RELEASE NOTES for SSLIB31596

Summary:

Functionality:

    All we were shooting for has been implemented, minus:

    - EANode
    - TZ switch

    I plan on implementing them both early this week. The testing of
    the EANode and TZ stuff may be left to the user, since my time is
    limited.

Testing:

    All that has been implemented has been basically tested, minus:

    - PackedLogExtentList - tests currently FAIL.
    - LELSpaceResource    - tests currently FAIL.
    - TableSpaceResource  - tests currently FAIL.

    At Charley Bay's earliest opportunity, these will be turned on. I
    expect this to go well, but his time is in extremely short
    supply. Hopefully, you can work around them for the time being. If
    you want to be able to handle files with preallocation, you may
    want to alter the Node to present the tail as a LogExtentList,
    rather than as an LELSpaceResource. If you would like to use the
    PackedLogExtentList (which offers the benefit of concatenating
    physically adjacent extents and thus saving space on the disk),
    you may turn this code on if you would like. The earliest that
    I'll possibly be able to look into these is in May some time.

    A few of the regression tests currently fail, but this appears to
    be solely because of problems with the above classes.

    srTest   fails
    ntfTest  fails
    nodeTest fails

    All other regression tests pass, except lelTest, which has not
    been turned on to even integrate with the regression test
    infrastructure.

Goals for release:

1. Clean up SingleSurfaceVolume

   - Divorce it from SpaceResource

     The divorce is complete. While the SRs are still allocated and
     freed by the SingleSurfaceVolume, this is done entirely outside
     of the Partition object. See the documentation of the
     TableSpaceResource for more details on what its lifecycle is to
     be.

   - Miscellaneous internal cleaning, including enhanced error
     handling.

     Basic infrastructure was inspected for robustness and cleaned up
     significantly. A list of items to be changed when it changes to
     support full UDF receivership and/or disk initialization has been
     generated. NOTE that it has been tested to properly read in all
     the structures on the SAI-formatted cartridge supplied to HP, as
     well as to the ones written by our multi-surface implementation.

2. Provide TableSpaceResource, making room for BitmapSpaceResource

   - CLOSED Final interfaces

     The MasterSpaceResource, TableSpaceResource, and
     BitmapSpaceResource, all derivatives of the ISOSpaceResource, are
     reasonably documented in the source code, found in
     udfCore/ss/nsrSpace.h and udfCore/ss/nsrSpace.cpp.

3. Provide ExtendedAttribute support

   - CLOSED Provide all required EAs for Mac, DOS platforms

     They are all implemented and basically tested out in
     udfAncil/descrTst/descrTst.cpp. Please notify me if you have ANY
     problems or questions about them.
   
   - CLOSED Provide EAInspector

     This ties into the Registry via the methods we discussed last
     week, and is totally separate from the SearchEA. Class-level
     documentation is provided in the source code, which is found in
     udfCore/descr/nsrEA.h. This has been tested on all of the
     implemented EAs, to verify that it identifies them correctly,
     etc.

   - OPEN Provide an EANode

     I thought Charley had implemented this, but upon closer
     inspection, found that he has not. I will therefore provide this
     later this week.

4. Opportunistically provide enhancements

   - CLOSED Construct ByteArrayRef from char *, vs. from ByteArray.

     Jon Hirota did this for you. I expect it to meet your
     requirements. Essentially, the ByteArrayRef now holds a BYTE_PTR
     and a buffer length in the place of a reference to a
     ByteArray. This means that the same ByteArrayRef will support
     construction from a ByteArray as well as a CHAR_PTR and length,
     generated by any other buffer scheme.
     
   - OPEN Port timezone code to support platforms with no time zone
     capability.

     This is next on my list, to be pursued this week if possible. I
     expect this to impact ONLY the udfCore/descr/nsrTypes.* files.

   - OPEN Provide LightweightNode to NOT parse through extent lists.

     I did not have time for this. I expect most UDF disks to have
     reasonably short ExtentLists, so it should not be a big
     issue. However, this DOES make sense for us to ultimately include
     in the toolkit, and I expect it to planned into the toolkit
     schedule in the May timeframe.

   - OPEN Provide special TagRewriter object, to make it simple to
     update the TagLocation field.

     I did not make it to this item, but if the issue lies in where
     the EAHeaderDesc is used, the EAHeaderDesc may be used to rewrite
     with the proper location. Note that on the first toISO(), the
     supplied location may be 0, which will generate an error on the
     fromISO(), so fromISOBlind() should be used. This may be followed
     by another toISO() with the proper tagLocation supplied.
     
   - OPEN Encapsulate LVID.

     We will likely be able to make the LVID somewhat friendlier and
     easier to use, but for now, it is simply a descriptor with
     to/fromISO() methods to call. An enhancement should be considered
     in the May/June timeframe.

5. Fix bugs uncovered in porting process

   - CLOSED Provide access to LogVolumep and Partitionp from SSVolume.

     > The inline functions
     > NSR::SingleSurfaceVolume::getPartitionPtr() and
     > NSR::SingleSurfaceVolume::getLogVolumePtr() seem to have been
     > removed in this release, and they are needed by our library
     > layer.  They are trivial functions that return member
     > variables.

     Added partitionp() and logVolumep() methods back in.

   - CLOSED Make sure all operator=() methods return references, not
     values.

     > There seems to be a problem with the way the assignment
     > operator is defined for certain objects.  Specifically
     > NSR::String, NSR::ByteArray, NSR::SmallByteArray, and
     > NSR::Dchars.  The assignment operators in these classes return
     > by value, rather than by reference (i.e. Class operator=()
     > rather than Class& operator=()).  This causes it to create a
     > temporary return object and call the copy constructor.  Under
     > certain conditions, this seems to create a recursive "spiral of
     > death" situation.  I think this occurs when there are
     > dependencies between the assigment operator and copy
     > constructor.  Simply making all assignment operators return by
     > reference seems to fix the problem.  You might want to check
     > for other classes in which the assignment operator was defined
     > this way.

     I fixed a slew of these problems -- Most of the low-level field
     types were guilty of this as well.

   - CLOSED Make sure a 'debug' variable is declared.

     > nsrFile.cpp - line 1360
     > nsrVol.cpp - line 122
     >    "debug" undefined.  "debug" is created as a global static
     > object in nsrDebug.cpp but an external reference is not
     > provided in nsrDebug.h.  Adding a line "extern NSR::Debug
     > debug" to nsrDebug.h will probably fix it.

     This has been fixed, and in the process, I cleaned up a memory
     leak, and changed it to hold a ByteArray, rather than a char *.

   - CLOSED Merge in fixes to OLD_STRING version of String.

     > Finally, there is still the issue of the Rogue Wave strings.  I
     > have attached repaired definitions of the original NSR::String
     > class, which seems to work for us.  Please incorporate this
     > class into your sources so we can enable it using the
     > OLD_STRING preprocessor flag.

     We have integrated your changes, but have not compiled with
     -DOLD_STRING to verify that all is well. The testing will, I
     guess, be up to you guys.

   - CLOSED Fix validateSpaceExtents() to return appropriate value.

     > nsrVol.cpp - line 127
     >    Function should return a value. The function
     > NSR::Partition::validateSpaceExtents() does not have a return
     > statement.  Adding "return error" at then end will resolve this
     > problem.

   - CLOSED Fix old bug in LogExtentList::logBlockNo():

     > There is an old bug in module ss/nsrExt.cp that has fallen
     > through the cracks:
     > In NSR::LogExtentList::logBlockNo(), the code:
     >    for (i = 0; i < elist_.entries(); i++) {
     >            if ((len + elist_.at(i)->infoLen()) >= offset) {
     > should be:
     >    for (i = 0; i < elist_.entries(); i++) {
     >            if ((len + elist_.at(i)->infoLen()) > offset) {
     > We had some really really obscure problems, that Shuching
     > traced back to  this.

   - CLOSED Bug in LogExtentList::copy()

     > There is another problem in ss/nsrExt.cp: In method
     > NSR::LogExtentList::copy_(), the Logical Volume Pointer
     > logicalVolume_ does not get copied.  I'm not sure what the
     > intent was here, but it seems that it should be copied.

   - CLOSED Implement a validateLength() method in LogExtents, for use
     by SpaceResource objects.

     Per my discussions with Gary Glenn, both a validateLength() and a
     maxInfoLen() method are now supported.

   - CLOSED Implement explicit copy constructors and assignment
     operators for SR objects.

     These have been implemented and made private, so that users will
     not be able to simply instantiate and pass around SRs, which
     would be a hazard to disk space closure.

   - CLOSED Attempt to provide default LogExtent constructor.

     This has been there for some time. Essentially, a LogExtent
     without a LogicalVolume or partition pointer passed in is
     "Imaginary", and of zero length at address 0. It has some natural
     hazards associated with it, in that the user could then attempt
     to dereference the partition pointer, and cause a core
     dump. However, all of the device methods (e.g., read(), write(),
     etc.) check for this condition, and I modified some other methods
     to check for this as well.


   - CLOSED (Borland problem) Remove explicit operator=() calls.

     > nsrNode.h - line 226
     >    The assignment of the form x.operator=(y) is not valid for
     > an object of type Attributes.  This is because there is not
     > assignment operator explicitly defined for this type, so the
     > default behavior is implicilty used.  Substituting the form,
     > "x = y" will resolve the problem.

     This has been fixed.

   - CLOSED (Borland problem) change ISOSpaceResource::syncToDisk()
     signatures.

     The new names are:
     - syncToDiskUsingSR(sr,err) - allows control over which SR to use
                                   in allocating space for the SR
                                   metadata. 
     - syncToDisk(err)           - uses "this" SR for any metadata
                                   space needs.

6. Support BitmapSpaceResource and EASpace development at SAI.

   - CLOSED Change nsrLib.h to include the extra rwtool header files
     required by your bitmap and/or EA classes.

     > Module nsrLib.h changed to add two #include statements in
     > the "#ifdef _INCL_SSOBJS_" section:
     >    #include <rw/collect.h>
     >    #include <rw/ordcltn.h>

     This has been fixed.

   - CLOSED Review EASpace design and interfaces

     I have reviewed this down to a reasonable level of detail with
     Cary Boyd, and am convinced that the architecture and
     implementation approach is good. Essentially, the design review
     was focusing on the interfaces, and less on the internal
     algorithms.

     While I do not consider that it has undergone a true in-depth
     design review, its interface has undergone intense and repeated
     scrutiny, and appears to be very strong and robust.

   - CLOSED Review BitmapSpaceResource design.

     I reviewed this in reasonable detail with Gary Glenn, and am
     convinced that Gary has implemented with optimization in mind,
     and with very thorough consideration of the
     constraints. Therefore, I expect no trouble here.

     NOTE that the released interface was revised dramatically in
     order to properly address all of the issues Gary found.
     
   - CLOSED Implement revised TableSpaceResource interface, to work
     with BitmapSpaceResource as well.

     The MasterSpaceResource interface has been defined and
     implemented, the ISOSpaceResource virtual interface has been
     implemented, and the TableSpaceResource has been
     implemented. Using all three of these, the BitmapSpaceResource
     and TableSpaceResource may both be used with no regard to their
     differences, and are automatically recognized and instantiated
     based upon what is found on the disk.

7. Miscellaneous cleanup and robustness issues

   - OPEN Integrate Charley's "check" program into build process.

     We did not do this, so you MAY find cases where we used a char *
     instead of a CHAR_PTR, etc. I do not expect that there will be
     difficulty with it, but if you do, you should have no trouble
     working around it.

   - OPEN Resolve ambiguities in NSR_VERIFY and NSR_COMPARE compile
     flags.

     This was for our own tidiness' sake, so was left out.

   - OPEN Run Purify on all code.

     I wish we had gotten to this, but we did not.
