[Ssrformat] API: Object Creation/Conversion

[Knight, James]

Here is the piece of the API focusing on SrfRead object creation,
destruction and its interface with the ZTR format and the
encoding/decoding
of blocks for the SRF file format.  The method calls are given below,
with
the following additional notes about this part of the API:

   * The three constructor methods and the three toZtr methods support
the
     ways in which we've discussed processing SRF files (how they hook
into
     the SrfFileReader and SrfFileWriter objects will be a later email,
once
     I write that part of the API down) 
   * The methods refer to a ZtrBlob object, which hasn't been
implemented
     yet, but which will encapsulate the creation of ZTR blocks
      - Think of it as the buffer object for a block of ZTR elements
      - Either it or a set of support classes will encapsulate the
specific
        ZTR format conversion functions
   * The SrfFieldList object is the method that I was thinking about to
     handle how to define what information goes where (such as into the
SRF
     file):
      - Think of it as a set of Enumeration values, but the actual
        implementation might require more (so, for now, I'm using this
        instead of "set<SrfFieldEnum>")
      - Each manufacturer defines a list of fields that a read of their
type
        could contain, and defines the enumeration constants for each of
        those fields (so there would be an Srf454FieldList,
        SrfSangerFieldList, ...)
      - The implementation is required to support getting/setting of
each of
        those fields
      - However, it is the file writer's decision about which fields
will
        or will not be written to a specific file (the SrfRead
        implementation cannot mandate that certain fields either must or
        must not be written).
      - These object and the methods below, then, make it easy to create

        data header and data body blocks for reads without hard-coding
what
        goes where.

Also, more general comments that will hold going forward:

    * I'm not including any notion of virtual/non-virtual methods so
that
      I can focus on the calls themselves, but my current design view is
      that all of the base classes are really going to be pure virtual
      classes (i.e., interfaces in Java) that mandate the
implementations
      of the concrete classes.
    * I'll include the methods I see as general methods inside the base
      SrfRead class, then include additional functions inside platform
      specific objects (of which there are none for these methods).
    * You may have seen in the example the use of pointers to objects
and
      the use of "new" to do the dynamic creation.  (And, if you really
      read the code, have seen the memory leak in the example code.)
For
      the next several API method emails, I'm going to skip the use or
      or notion about what objects should be passed as objects, as
pointers
      or as references.  Any suggestions (for a cross-C++/Java/Perl
      standard) would be helpful.

-------------------------

class SrfRead
{
public:
    // The basic constructor for the read object, typically used when
    // creating a new read object from scratch (using the set* methods
    // to store the read's information).
    SrfRead();
    
    // The simple SRF file constructor for a read object, typically used
    // when constructing a read object during the streaming of SRF files
    // through pipes (i.e., where random access to the file is not
    // available.
    SrfRead(ZtrBlob blob);
    
    // The standard SRF file constructor for a read object, used when
    // constructing an object from the data header and data body blocks
    // in the SRF file.
    SrfRead(ZtrBlob headerBlob, ZtrBlob dataBlob);
    
    // The full SRF file constructor, where XML information can be used
    // to supply read information.
    SrfRead(ZtrBlob headerBlob,
            ZtrBlob dataBlob,
            string xmlString);

    // The destructor for an object.                        
    ~SrfRead();
    
    // These set methods allow for the setting of read information by
the
    // processing of a ZtrBlob or XML string.  An additional
SrfFieldList
    // object can be used to restrict the set of fields that are set
using
    // the passed in information.
    //
    // If information for specific fields exists in the object, these
    // methods overwrite that information.
    void set(ZtrBlob blob);
    void set(ZtrBlob blob, SrfFieldList fieldsToSet);
    void set(string xmlString, SrfFieldList fieldsToSet);
    
    // The simple toZtr method, converting all of the read information
    // in the object into a ZtrBlob.
    ZtrBlob toZtr();
    
    // A toZtr method to convert only a specific list of fields into a
    // ZtrBlob.  The method only does the conversion for data actually
    // stored in the object, and by default throws no errors if data for
    // a field does not exist.
    //
    // The optional throwError flag can be set to true to have the
method
    // throw an Srf::SrfNoDataException if data for a specified field
    // does not exist.
    ZtrBlob toZtr(SrfFieldList fields, bool throwError = false);
    
    // A toZtr method to convert all of the other fields, other than
those
    // in a given list, into a ZtrBlob.  This will typically be used by
    // the SrfFileWriter which will call 
    // read->toZtr(SrfRead::getDefaultHeaderFields()) to get the data
header
    // block, then use this to get the data body block.
    ZtrBlob toZtrOther(SrfFieldList fields);
    
    // A method to return the set of fields that, with the default
    // information provided by a manufacturer's data, can be stored
    // in a common data header block shared by a set of reads.
    static SrfFieldList getDefaultHeaderFields();
}