rwlogo
SourcePro C++ 12.0

SourcePro® C++ API Reference Guide



   SourcePro C++
Documentation Home

RWXmlObjectOutputStreamImp Class Reference
[XML Streams]

Serializes one or more objects as an XML-formatted data stream and passes the stream to a supplied RWDataOutputStream. More...

#include <rw/xmlstreams/RWXmlObjectOutputStreamImp.h>

Inheritance diagram for RWXmlObjectOutputStreamImp:
RWObjectOutputStreamImp RWXmlObjectStreamCommon RWFilteredDataOutputStreamImp RWDataOutputStreamImp RWOutputStreamImp RWStreamImp RWBodyBase RWTCountingBody< RWMutexLock > RWTMonitor< RWMutexLock > RWTParsedTransformObjectOutputStreamImp< Transform > RWTTransformObjectOutputStreamImp< Transform >

List of all members.

Public Member Functions

virtual void startBlock (const RWSymbol &)
virtual void endBlock ()
virtual bool needToWrite (const void *obj)
virtual void writeNullPtr ()
virtual void newObjectMarker ()
virtual void writeTypeInfo (const RWSymbol &typeInfo)
virtual void writeObjectName ()
virtual void rememberObject (const void *obj)
virtual void writeMemberInfo (const RWSymbol &memberName, RWStreamType memberType)
virtual void endMember (const RWSymbol &memberName)
virtual void startSequence (int count, RWStreamType elementType, const RWSymbol &)
virtual void startElement (int position)
virtual void endElement ()
virtual void endSequence ()
virtual void startMap (int count, RWStreamType keyType, RWStreamType valueType, const RWSymbol &)
virtual void startAssocKey ()
virtual void startAssocValue ()
virtual void endAssoc ()
virtual void endMap ()
virtual void putString (const RWCString &value)
virtual void putWString (const RWWString &value)
virtual void putUString (const RWBasicUString &value)
virtual void putBool (bool value)
virtual void putChar (char value)
virtual void putUnsignedChar (unsigned char value)
virtual void putSignedChar (signed char value)
virtual void putShort (short value)
virtual void putUnsignedShort (unsigned short value)
virtual void putInt (int value)
virtual void putUnsignedInt (unsigned int value)
virtual void putLong (long value)
virtual void putUnsignedLong (unsigned long value)
virtual void putFloat (float value)
virtual void putDouble (double value)
virtual void putWchar_t (wchar_t value)
virtual void putLongLong (long long value)
virtual void putUnsignedLongLong (unsigned long long value)
virtual void putLongDouble (long double value)
virtual void putCharacter (char value)
virtual void putWCharacter (wchar_t value)
virtual void putUCharacter (RWUChar value)
virtual void putSizeT (size_t value)
virtual void setNameForNextObject (const RWCString &str)

Static Public Member Functions

static RWObjectOutputStream make (std::ostream &sink, const RWCString &rootElementType=nestedObjectTag, bool escape=true)
static RWObjectOutputStream make (std::ostream &sink, std::ios *&formatter, const RWCString &rootElementType=nestedObjectTag, bool escape=true)
static RWObjectOutputStream make (RWDataOutputStream &sink, const RWCString &rootElementType=nestedObjectTag, bool escape=true)

Protected Member Functions

virtual void openOuterContext (bool writeContext)
virtual void closeOuterContext (bool writeContext)
 RWXmlObjectOutputStreamImp (std::ostream &ostr, const RWCString &rootElementType, bool escape)
 RWXmlObjectOutputStreamImp (std::ostream &ostr, std::ios *&formatter, const RWCString &rootElementType, bool escape)
 RWXmlObjectOutputStreamImp (const RWDataOutputStream &ostr, const RWCString &rootElementType, bool escape)
virtual void putString (const char *string, RWSize count)
virtual void putWString (const wchar_t *wstring, RWSize count)
virtual void putUString (const RWUChar *ustring, RWSize count)

Detailed Description

The class RWXmlObjectOutputStreamImp serializes one or more objects as an XML-formatted data stream and passes the stream to a supplied RWDataOutputStream.

The XML Streams Module integrates with the general Rogue Wave streams architecture defined by the streams and serialization packages of the Advanced Tools Module of SourcePro Core. This architecture allows an XML stream to be written out and read in using a wide variety of streaming configurations. For more information specific to the XML Streams Module, see the XML Streams Module User's Guide. For information on the general architecture, see the Advanced Tools Module User's Guide.

RWXmlObjectOutputStreamImp is the body class of a handle-body pattern. The corresponding handle class is RWObjectOutputStream.

The syntax of the XML formatting generated by this class is defined by the XML schema xmlstreams.xsd. This schema is located in buildspace\rw\xmlstreams.

Examples

 // Create a strstream as the output stream to receive
 // the XML-formatted object data
 ostrstream s;
 
 // Create an XML data stream using the strstream
 RWObjectOutputStream out = RWXmlObjectOutputStreamImp::make(s);
 
 // Write integer value `1' to XML data stream
 
 s << 1;

Constructor & Destructor Documentation

RWXmlObjectOutputStreamImp::RWXmlObjectOutputStreamImp ( std::ostream &  ostr,
const RWCString rootElementType,
bool  escape 
) [inline, protected]

Used by the make() function and potentially by derived classes to initialize an output stream to be used as the sink for the XML-formatted object serialization data. Use this constructor if the required output stream is a standard library ostream and pass a reference to that stream as the ostr parameter.

The parameter rootElementType must be one of the following:

The value passed indicates the root element of the generated document.

The parameter escape sets whether to escape XML reserved characters in the data being serialized. By setting this parameter to true, reserved characters in char and string values are escaped, allowing the data to include embedded XML.

The reserved characters are:

 <  >  &  "  '

You get slightly better performance if the escape parameter is set to false, but before doing so be certain that your data does not contain reserved characters.

RWXmlObjectOutputStreamImp::RWXmlObjectOutputStreamImp ( std::ostream &  ostr,
std::ios *&  formatter,
const RWCString rootElementType,
bool  escape 
) [inline, protected]

Used by the make() function and potentially by derived classes to initialize an output stream to be used as the sink for the XML-formatted object serialization data. Use this constructor if the required output stream is a standard library ostream and pass a reference to that stream as the ostr parameter.

The parameter rootElementType must be one of the following:

The value passed indicates the root element of the generated document.

The parameter escape sets whether to escape XML reserved characters in the data being serialized. By setting this parameter to true, reserved characters in char and string values are escaped, allowing the data to include embedded XML.

The reserved characters are:

 <  >  &  "  '
You get slightly better performance if the escape parameter is set to false, but before doing so be certain that your data does not contain reserved characters.

This constructor also takes a pointer reference to an std::ios formatting object. An empty formatting object pointer is created before the XML stream is created and is passed to this constructor through the make() function. This constructor, in creating the underlying character stream for the XML stream, creates a formatting object for the stream and places the address of that object in the pointer reference. The calling application can then use this formatting object to manipulate data formats in the XML stream. See the corresponding make() function description for an example.

RWXmlObjectOutputStreamImp::RWXmlObjectOutputStreamImp ( const RWDataOutputStream ostr,
const RWCString rootElementType,
bool  escape 
) [inline, protected]

Used by the make() function and potentially by derived classes to initialize an RWDataOutputStream stream to be used as the sink for the XML-formatted object serialization data. Use this constructor if the required output stream is a RWDataOutputStream stream and pass a reference to that stream as the ostr parameter.

The parameter rootElementType must be one of the following:

The value passed indicates the root element of the generated document.

The parameter escape sets whether to escape XML reserved characters in the data being serialized. By setting this parameter to true, reserved characters in char and string values are escaped, allowing the data to include embedded XML.

The reserved characters are:

 <  >  &  "  '

You get slightly better performance if the escape parameter is set to false, but before doing so be certain that your data does not contain reserved characters.


Member Function Documentation

virtual void RWXmlObjectOutputStreamImp::closeOuterContext ( bool  writeContext  )  [protected, virtual]

Really closes an open context. This function is called when the number of closeContext() calls matches the number of openContext() calls.

Implements RWObjectOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::endAssoc (  )  [virtual]

Called by the output operators for association types after each value.

Reimplemented from RWObjectOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::endBlock (  )  [virtual]

Causes tokens to be output that identify the end of an object.

Implements RWObjectOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::endElement (  )  [virtual]

Called by the output operators for collection types after each element in a sequence.

Reimplemented from RWObjectOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::endMap (  )  [virtual]

Called by the output operators for association types after all the pairs.

Reimplemented from RWObjectOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::endMember ( const RWSymbol  )  [virtual]

Called by streamContents() after each data member is written.

Reimplemented from RWObjectOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::endSequence (  )  [virtual]

Called by the output operators for collection types at the end of a sequence.

Reimplemented from RWObjectOutputStreamImp.

static RWObjectOutputStream RWXmlObjectOutputStreamImp::make ( RWDataOutputStream sink,
const RWCString rootElementType = nestedObjectTag,
bool  escape = true 
) [static]

Constructs an RWXmlObjectOutputStreamImp instance that passes the serialized object data to the RWDataOutputStream stream sink, and returns a handle to it. Use this method when the data output stream is a RWDataOutputStream stream.

The parameter rootElementType must be one of the following:

The value passed indicates the root element of the generated document. The default setting is nestedObjectTag.

The parameter escape sets whether to escape XML reserved characters in the data being serialized. By setting this parameter to true, reserved characters in char and string values are escaped, allowing the data to include embedded XML.

The reserved characters are:

 <  >  &  "  '

You get slightly better performance if the escape parameter is set to false, but before doing so be certain that your data does not contain reserved characters.

static RWObjectOutputStream RWXmlObjectOutputStreamImp::make ( std::ostream &  sink,
std::ios *&  formatter,
const RWCString rootElementType = nestedObjectTag,
bool  escape = true 
) [static]

Constructs an RWXmlObjectOutputStreamImp instance that passes the serialized object data to the output stream sink, and returns a handle to it. Use this method when the data output stream is a standard library ostream.The parameter rootElementType must be one of the following:

The value passed indicates the root element of the generated document. The default setting is nestedObjectTag.The parameter escape sets whether to escape XML reserved characters in the data being serialized. By setting this parameter to true, reserved characters in char and string values are escaped, allowing the data to include embedded XML.The reserved characters are:
 <  >  &  "  '
You get slightly better performance if the escape parameter is set to false, but before doing so be certain that your data does not contain reserved characters.

This function also takes a pointer reference to an std::ios formatting object. An empty formatting object pointer is created before the XML stream is created and is passed through this make() function to the constructor:

 std::ios* formatter;            // uninitialized pointer
 RWObjectOutputStream xostr =
 RWXmlObjectOutputStreamImp::make(outfile,formatter);

The constructor, in creating the underlying character stream for the XML stream, creates a formatting object for the stream and places the address of that object in the pointer reference. The calling application can then use this formatting object to manipulate data formats in the XML stream.

 formatter->precision(15);       // manipulate data format
static RWObjectOutputStream RWXmlObjectOutputStreamImp::make ( std::ostream &  sink,
const RWCString rootElementType = nestedObjectTag,
bool  escape = true 
) [static]

Constructs an RWXmlObjectOutputStreamImp instance that passes the serialized object data to the output stream sink, and returns a handle to it. Use this method when the data output stream is a standard library ostream.

The parameter rootElementType must be one of the following:

The value passed indicates the root element of the generated document. The default setting is nestedObjectTag.

The parameter escape sets whether to escape XML reserved characters in the data being serialized. By setting this parameter to true, reserved characters in char and string values are escaped, allowing the data to include embedded XML.

The reserved characters are:

 <  >  &  "  '

You get slightly better performance if the escape parameter is set to false, but before doing so be certain that your data does not contain reserved characters.

virtual bool RWXmlObjectOutputStreamImp::needToWrite ( const void *  obj  )  [virtual]

Returns true when the referenced object has not yet been written to the stream in the current context. Otherwise, tokens are output identifying this object as a previously streamed one, and the function returns false.

Implements RWObjectOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::newObjectMarker (  )  [virtual]

Output is a token indicating that an object will be created by the factory.

Implements RWObjectOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::openOuterContext ( bool  writeContext  )  [protected, virtual]

Really opens a new context. This function is called by openContext() when a context is not already open.

Implements RWObjectOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::putBool ( bool  value  )  [virtual]

Writes a value to the stream, where the type of the value is defined by the parameter. These functions are redefined from the parent class RWObjectOutputStream.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::putChar ( char  value  )  [virtual]

Writes a value to the stream, where the type of the value is defined by the parameter. These functions are redefined from the parent class RWObjectOutputStream.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::putCharacter ( char  value  )  [virtual]

Writes a value to the stream, where the type of the value is defined by the parameter. These functions are redefined from the parent class RWObjectOutputStream.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::putDouble ( double  value  )  [virtual]

Writes a value to the stream, where the type of the value is defined by the parameter. These functions are redefined from the parent class RWObjectOutputStream.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::putFloat ( float  value  )  [virtual]

Writes a value to the stream, where the type of the value is defined by the parameter. These functions are redefined from the parent class RWObjectOutputStream.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::putInt ( int  value  )  [virtual]

Writes a value to the stream, where the type of the value is defined by the parameter. These functions are redefined from the parent class RWObjectOutputStream.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::putLong ( long  value  )  [virtual]

Writes a value to the stream, where the type of the value is defined by the parameter. These functions are redefined from the parent class RWObjectOutputStream.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::putLongDouble ( long double  value  )  [virtual]

Writes a value to the stream, where the type of the value is defined by the parameter. These functions are redefined from the parent class RWObjectOutputStream.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::putLongLong ( long long  value  )  [virtual]

Writes a value to the stream, where the type of the value is defined by the parameter. These functions are redefined from the parent class RWObjectOutputStream.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::putShort ( short  value  )  [virtual]

Writes a value to the stream, where the type of the value is defined by the parameter. These functions are redefined from the parent class RWObjectOutputStream.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::putSignedChar ( signed char  value  )  [virtual]

Writes a value to the stream, where the type of the value is defined by the parameter. These functions are redefined from the parent class RWObjectOutputStream.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::putSizeT ( size_t  value  )  [virtual]

Writes a value to the stream, where the type of the value is defined by the parameter. These functions are redefined from the parent class RWObjectOutputStream.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::putString ( const char *  string,
RWSize  count 
) [inline, protected, virtual]

Forwards the writing of a narrow character string, including embedded nulls, starting at string to the next processing stream.

Parameters:
string A pointer to the narrow string's first character.
count The number of narrow character(s) to be written to the stream.

Reimplemented from RWObjectOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::putString ( const RWCString value  )  [virtual]

Writes a value to the stream, where the type of the value is defined by the parameter. These functions are redefined from the parent class RWObjectOutputStream.

Implements RWObjectOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::putUCharacter ( RWUChar  value  )  [virtual]

Writes a value to the stream, where the type of the value is defined by the parameter. These functions are redefined from the parent class RWObjectOutputStream.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::putUnsignedChar ( unsigned char  value  )  [virtual]

Writes a value to the stream, where the type of the value is defined by the parameter. These functions are redefined from the parent class RWObjectOutputStream.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::putUnsignedInt ( unsigned int  value  )  [virtual]

Writes a value to the stream, where the type of the value is defined by the parameter. These functions are redefined from the parent class RWObjectOutputStream.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::putUnsignedLong ( unsigned long  value  )  [virtual]

Writes a value to the stream, where the type of the value is defined by the parameter. These functions are redefined from the parent class RWObjectOutputStream.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::putUnsignedLongLong ( unsigned long long  value  )  [virtual]

Writes a value to the stream, where the type of the value is defined by the parameter. These functions are redefined from the parent class RWObjectOutputStream.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::putUnsignedShort ( unsigned short  value  )  [virtual]

Writes a value to the stream, where the type of the value is defined by the parameter. These functions are redefined from the parent class RWObjectOutputStream.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::putUString ( const RWUChar ustring,
RWSize  count 
) [inline, protected, virtual]

Forwards the writing of a UTF-16 character string, including embedded nulls, starting at ustring to the next processing stream.

Parameters:
ustring A pointer to the string's first unicode character.
count The number of unicode character(s) to be written to the stream.

Reimplemented from RWObjectOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::putUString ( const RWBasicUString value  )  [virtual]

Writes a value to the stream, where the type of the value is defined by the parameter. These functions are redefined from the parent class RWObjectOutputStream.

Implements RWObjectOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::putWchar_t ( wchar_t  value  )  [virtual]

Writes a value to the stream, where the type of the value is defined by the parameter. These functions are redefined from the parent class RWObjectOutputStream.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::putWCharacter ( wchar_t  value  )  [virtual]

Writes a value to the stream, where the type of the value is defined by the parameter. These functions are redefined from the parent class RWObjectOutputStream.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::putWString ( const wchar_t *  wstring,
RWSize  count 
) [inline, protected, virtual]

Forwards the writing of a wide character string, including embedded nulls, starting at wstring to the next processing stream.

Parameters:
wstring A pointer to the string's first wide character.
count The number of wide character(s) to be written to the stream.

Reimplemented from RWObjectOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::putWString ( const RWWString value  )  [virtual]

Writes a value to the stream, where the type of the value is defined by the parameter. These functions are redefined from the parent class RWObjectOutputStream.

Implements RWObjectOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::rememberObject ( const void *  obj  )  [virtual]

Called by streaming operators to record each instance streamed out, in case it is referenced again in the same context.

Parameters:
obj Holds the address of the instance.

Implements RWObjectOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::setNameForNextObject ( const RWCString str  )  [virtual]

Sets up the instance name for the next object to be written out.

Implements RWObjectOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::startAssocKey (  )  [virtual]

Called by the output operators for association types before each key.

Reimplemented from RWObjectOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::startAssocValue (  )  [virtual]

Called by the output operators for association types after each key and before each value.

Reimplemented from RWObjectOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::startBlock ( const RWSymbol typeInfo  )  [virtual]

Causes tokens to be output that identify the start of a new object.

Parameters:
typeInfo Identifies the type of the new object, if such information is available.

Implements RWObjectOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::startElement ( int   )  [virtual]

Called by the output operators for collection types before each element in a sequence.

Reimplemented from RWObjectOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::startMap ( int  count,
RWStreamType  keyType,
RWStreamType  valueType,
const RWSymbol typeInfo 
) [virtual]

Called by the output operators for association types (hash tables, etc.) at the start.

Parameters:
count Contains the number of items in the association.
keyType Contains the type of key in the association.
valueType Contains the type of value in the association.
typeInfo Contains the type of the association(collection) itself

Implements RWObjectOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::startSequence ( int  count,
RWStreamType  elementType,
const RWSymbol typeInfo 
) [virtual]

Called by the output operators for collection types at the start of a sequence.

Parameters:
count Contains the number of items in the collection.
elementType Contains the type of element in the collection.
typeInfo Contains the type of the collection itself.

Implements RWObjectOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::writeMemberInfo ( const RWSymbol memberName,
RWStreamType  memberType 
) [virtual]

Called for before each data member by the streamContents() function. Metadata about the field may or may not be written to the stream, depending on the implementation. This function returns true if data is actually written out. Otherwise, it returns false.

Parameters:
memberName Identifies the name of the member.
memberType Identifies the type of the member.

Implements RWObjectOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::writeNullPtr (  )  [virtual]

Output is a token representing a null pointer.

Implements RWObjectOutputStreamImp.

virtual void RWXmlObjectOutputStreamImp::writeObjectName (  )  [virtual]

Writes the object name to the stream.

virtual void RWXmlObjectOutputStreamImp::writeTypeInfo ( const RWSymbol typeInfo  )  [virtual]

Outputs the type information required to factory an object of the correct dynamic type (derived class) on input.

Parameters:
typeInfo Identifies the type of the new object, if such information is available.

Implements RWObjectOutputStreamImp.

 All Classes Functions Variables Typedefs Enumerations Enumerator Friends

© Copyright Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.