RWXmlObjectOutputStreamImp

Module:  XML Streams   Package:  XML Streams

                                RWXMLObjectStreamCommon
RWXmlObjectOutputStreamImpRWObjectOutputStreamImp 
                                RWFilteredDataOutputStreamImp

• Local Index
• Header File
• Description
• Example
• Public Member Functions
• Static Public Member Functions
• Protected Constructors

Members

make() putChar() putCharacter() putDouble() putFloat() putInt() putLong()

putLongDouble() putLongLong() putShort() putSignedChar() putSizeT() putUCharacter() putUnsignedChar()

putUnsignedInt() putUnsignedLong() putUnsignedLongLong() putUnsignedShort() putUString() putWCharacter() putWchar_t()

putWString() RWXmlObjectOutputStreamImp() setNameForNextObject() writeObjectName()

#include <rw/xmlstreams/RWXmlObjectOutputStreamImp.h>

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.

// 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;

virtual void putChar(char value);
virtual void putCharacter(char value);
virtual void putDouble(double value);
virtual void putFloat(float value);
virtual void putInt(int value);
virtual void putLong(long value);
virtual void putLongLong(rwlonglong value);
virtual void putLongDouble(long double value);
virtual void putShort(short value);
virtual void putSignedChar(signed char value);
virtual void putSizeT(size_t value);
virtual void putUCharacter(RWUChar value);
virtual void putUnsignedChar(unsigned char value);
virtual void putUnsignedShort(unsigned short value);
virtual void putUnsignedInt(unsigned int value);
virtual void putUnsignedLong(unsigned long value);
virtual void putUnsignedLongLong(rwulonglong value);
virtual void putUString(const RWUString& value);
virtual void putWchar_t(wchar_t value);
virtual void putWString(const RWWString& value); 
virtual void putWCharacter(wchar_t value);

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.

virtual void          
writeObjectName();

Writes the object name to the stream.

virtual void          
setNameForNextObject(const RWCString& str);

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

static RWObjectOutputStream 
make(RW_SL_IO_STD(ostream)& sink,
     const RWCString& rootElementType=nestedObjectTag,
      bool escape = true);

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 std::ostream.

The parameter rootElementType must be one of the following:

• nestedObjectTag, if serializing an object by value

• objectTag, if serializing an object by pointer

• sequence, if serializing a sequential collection such as RWTPtrOrderedVector

• map, if serializing a mapping collection such as RWTPtrHashMap

• primitive, if serializing a built-in type such as int

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 
make(RWDataOutputStream& sink,
    const RWCString& rootElementType=nestedObjectTag,
    bool escape = true);

This function is like the one above, but is used when the required output stream is a derived class of RWDataOutputStream.

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

This function is the same as the first one described above, except that it 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

RWXmlObjectOutputStreamImp(RW_SL_IO_STD(ostream)& ostr, const RWCString& rootElementType, bool escape);

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 std::ostream and pass a reference to that stream as the ostr parameter.

The parameter rootElementType must be one of the following:

• nestedObjectTag, if serializing an object by value

• objectTag, if serializing an object by pointer

• sequence, if serializing a sequential collection such as RWTPtrOrderedVector

• map, if serializing a mapping collection such as RWTPtrHashMap

• primitive, if serializing a built-in type such as int

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(RWDataOutputStream& ostr,
    const RWCString& rootElementType, bool escape);

This constructor is like the one above, but is used when the required output stream is a derived class of RWDataOutputStream.

RWXmlObjectOutputStreamImp(RW_SL_IO_STD(ostream)& ostr,
    RW_SL_IO_STD(ios)*& formatter, 
    const RWCString& rootElementType, bool escape);

This constructor is the same as the first constructor described above, except that it 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 above for an example.

© 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.