A package for streaming C++ objects
04aug00 1000
Code version 0.03.25
Objstream provides classes for writing and reading back C++ objects.
Simple output formatting may be accomplished with ObjectFormat.
Programmers add the following objects to their streams:
- begin_object - mark the beginning of an object
- end_object - mark the end of an object
- new_line - start a new line (with appropriate indentation)
An object of type ObjectFormat may also be added to the stream. It
controls the formatting of these objects. It defines strings for
delimiting objects and for indentation. The indentation string
is repeated once for each level of object nesting.
Some standard formats as well as the above delimiters are defined
in the ObjectFormat header.
The remaining classes provide a system for input, output and management
of a collection of objects which may hold non-managing or shared management
pointers to one another. These objects must all inherit from ObjType.
Each object of this type provides a method to write its named data to
an object of type ObjData and provides a free function (the creator)
to construct a new instance of itself from such a data object.
Objects are named and managed in a global table ObjTable. When
constructing its data object, if an object contains a pointer to
another object, that pointer is replaced with name of the referenced
object. This name is obtained from the table. When an object is
created from object data, reference names are used to extract the
corresponding object pointers from the table.
In both cases the referenced object must already exist and must be
registered in the table.
Object input streams read in object data which is passed to a creator
which creates the corresponding object and returns a pointer to this
object. This pointer is then stored in the table. The user is returned
the object name which can be used to fetch the pointer.
A unique name is specified when an object is output. Objects may be
written by reference or as shared management pointers. In the latter
case, the object is registered with the table if needed. In the former
case the object may not be referenced by other streamed objects unless
it is sparately registered in the table. The user is responsible for
guaranteeing that the same name is used in the stream and the table.
The stream classes inherit from the base ObjStream with each implementation
defining the format of the data. A simple implementation StdObjStream
is provided as part of this package. Another implementation based on
XML is envisioned but not implemented.
Links to code
The description below includes links to the code contained in this
package. This
version
of the code may not be the most recent.
Description
TRF++ package trfbase defines the base classes for manipulating
tracks.
The physical components include:
- ObjectFormat (
header,
source,
test )
- ObjType (
header,
source,
test )
- ObjData (
header,
source,
test )
- ObjTable (
header,
source,
test,
test header )
- ObjStream (
header,
source,
test,
test header )
- StdObjStream (
header,
source,
test )
This package depends on the no external packages:
The classes defined in the above components are described below.
Unless otherwise indicated, each class is described in the component of
the same name. The descriptions here are brief. See the heaser files
for details.
ObjectFormat
Defines the the format for an object. An object of this type is
inserted in a an ordinary out put stream (ostream) stream and its
formatting is applied until another such object is inserted.
ObjectType
The base type for objects to used with object streams. Subclasses are
required to implement a method which converts the object into an object
of type ObjData. They are also expected to provide a free function
which creates an object of the full type from a data object. This function
must be registered with the global object table ObjTable.
ObjPtr
This is not a class. It is a typedef for
Ptr<const ObjType,SharedDeletePolicy>.
This object behaves like const ObjType* but has shared management.
The object is deleted when the last referencing pointer is deleted.
The object table holds pointers of this type guaranteeing that any
registered object will be held for the life of the program.
ObjData
A fixed format for holding the type and attributes associated with an
object. The attributes must be one of the following types (names are
those used in the enum ObjData::Type:
- INT - int
- DOUBLE - double (double precision float)
- BOOL - bool
- STRING - string
- BARE_PTR - bare C++ pointer (const ObjType*) in ObjTable
- SHARE_PTR - shared management pointer (ObjPtr) to a registerd object
Each attribute has a unique name.
ObjTable
This singleton provides the association between object names and pointers.
It also maintains the association between type names and creators.
It provides management of registered objects by holding them with shared
management pointers. Care should be taken to ensure that all registered
objects are created on the free store and not deleted elsewhere.
The typedef ObjTable::ObjType is a pointer to a creator, i.e. it
defines the signature required for a creator. An example of a creator
and its registration may be found the test header for this class.
ObjStream
The base class for streaming objects. It is constructed from a standard
input stream (istream) when used as an object input stream and from an
ostream when used as a standard output stream.
StdObjStream
This is a simple implementation of ObjStream.
The syntax is described on a separate page.
Questions or comments to dladams@.fnal.gov.