RWEnhancedXmlObjectOutputStreamImp Class Reference
[XML Streams]

Writes objects as XML into the supplied RWDataOutputStream. More...

#include <rw/xmlstreams/RWEnhancedXmlObjectOutputStreamImp.h>

Inheritance diagram for RWEnhancedXmlObjectOutputStreamImp:

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	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)
	RWEnhancedXmlObjectOutputStreamImp (std::ostream &ostr, const RWCString &rootElementType, bool escape)
	RWEnhancedXmlObjectOutputStreamImp (std::ostream &ostr, std::ios *&formatter, const RWCString &rootElementType, bool escape)
	RWEnhancedXmlObjectOutputStreamImp (const RWDataOutputStream &ostr, const RWCString &rootElementType, bool escape)
	~RWEnhancedXmlObjectOutputStreamImp ()
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 RWEnhancedXmlObjectOutputStreamImp writes objects as XML into the supplied RWDataOutputStream. Implements the body idiom from the handle/body pattern.

Examples

 // Create a strstream to serve as our sink
 ostrstream s;
 
 // Create an XML data stream using the strstream
 RWObjectOutputStream in = RWXmlbjectOutputStreamImp::make(s);
 
 // Write integer value '1' to XML data stream
 s << 1;

---

Constructor & Destructor Documentation

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

Constructs an RWEnhancedXmlObjectOutputStreamImp instance that takes an ostream to use as the destination.

The value rootElementType indicates the root element of the generated document. This value should be either objectTag, nestedObjectTag, sequenceTag, primitiveTag, or mapTag, depending on what sort of object is streamed into the document at the top level.

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.

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

Constructs an RWEnhancedXmlObjectOutputStreamImp instance that takes an ostream to use as the destination.

The value rootElementType indicates the root element of the generated document. This value should be either objectTag, nestedObjectTag, sequenceTag, primitiveTag, or mapTag, depending on what sort of object is streamed into the document at the top level.

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.

The parameter formatter will be returned with a reference to the formatting object.

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

Constructs an RWEnhancedXmlObjectOutputStreamImp instance that takes an RWDataOutputStream to use as the destination.

The value rootElementType indicates the root element of the generated document. This value should be either objectTag, nestedObjectTag, sequenceTag, primitiveTag, or mapTag, depending on what sort of object is streamed into the document at the top level.

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.

RWEnhancedXmlObjectOutputStreamImp::~RWEnhancedXmlObjectOutputStreamImp

(

)

[inline, protected]

Destructor. Delete the storeTable even if an exception is thrown.

---

Member Function Documentation

virtual void RWEnhancedXmlObjectOutputStreamImp::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 RWEnhancedXmlObjectOutputStreamImp::endAssoc

(

)

[virtual]

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

Reimplemented from RWObjectOutputStreamImp.

virtual void RWEnhancedXmlObjectOutputStreamImp::endBlock

(

)

[virtual]

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

Implements RWObjectOutputStreamImp.

virtual void RWEnhancedXmlObjectOutputStreamImp::endElement

(

)

[virtual]

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

Reimplemented from RWObjectOutputStreamImp.

virtual void RWEnhancedXmlObjectOutputStreamImp::endMap

(

)

[virtual]

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

Reimplemented from RWObjectOutputStreamImp.

virtual void RWEnhancedXmlObjectOutputStreamImp::endMember

(

const RWSymbol &

)

[virtual]

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

Reimplemented from RWObjectOutputStreamImp.

virtual void RWEnhancedXmlObjectOutputStreamImp::endSequence

(

)

[virtual]

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

Reimplemented from RWObjectOutputStreamImp.

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

Constructs an RWEnhancedXmlObjectOutputStreamImp instance that passes the serialized object data to the RWDataOutputStream sink, and returns a handle to it. Throws no exceptions.

The parameter sink is the ostream that is used as the sink of bytes.

The parameter rootElementType must be one of the following:

• nestedObjectTag, if serializing an object by value
• objectTag, if serializing an object by pointer
• sequenceTag, if serializing a sequential collection such as RWTPtrOrderedVector
• mapTag, if serializing a mapping collection such as RWTPtrHashMap
• primitiveTag, if serializing a built-in type such as int

The parameter escape sets whether to escape XML reserved characters in the data being serialized.

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

Constructs an RWEnhancedXmlObjectOutputStreamImp 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. Throws no exceptions.

The parameter sink is the ostream that is used as the sink of bytes.

The parameter rootElementType must be one of the following:

• nestedObjectTag, if serializing an object by value
• objectTag, if serializing an object by pointer
• sequenceTag, if serializing a sequential collection such as RWTPtrOrderedVector
• mapTag, if serializing a mapping collection such as RWTPtrHashMap
• primitiveTag, 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.

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 =
 RWEnhancedXmlObjectOutputStreamImp::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 

The parameter source is the istream that is used as the source of bytes.

The parameter formatter will be returned with a reference to the formatting object.

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

Constructs an RWEnhancedXmlObjectOutputStreamImp 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. Throws no exceptions.

The parameter sink is the ostream that is used as the sink of bytes.

The parameter rootElementType must be one of the following:

• nestedObjectTag, if serializing an object by value
• objectTag, if serializing an object by pointer
• sequenceTag, if serializing a sequential collection such as RWTPtrOrderedVector
• mapTag, if serializing a mapping collection such as RWTPtrHashMap
• primitiveTag, 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.

virtual bool RWEnhancedXmlObjectOutputStreamImp::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 RWEnhancedXmlObjectOutputStreamImp::newObjectMarker

(

)

[virtual]

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

Implements RWObjectOutputStreamImp.

virtual void RWEnhancedXmlObjectOutputStreamImp::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 RWEnhancedXmlObjectOutputStreamImp::putBool

(

bool

value

)

[virtual]

Puts a value into the stream, where the type of the value is defined by the first parameter.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWEnhancedXmlObjectOutputStreamImp::putChar

(

char

value

)

[virtual]

Puts a value into the stream, where the type of the value is defined by the first parameter.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWEnhancedXmlObjectOutputStreamImp::putCharacter

(

char

value

)

[virtual]

Puts a value into the stream, where the type of the value is defined by the first parameter.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWEnhancedXmlObjectOutputStreamImp::putDouble

(

double

value

)

[virtual]

Puts a value into the stream, where the type of the value is defined by the first parameter.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWEnhancedXmlObjectOutputStreamImp::putFloat

(

float

value

)

[virtual]

Puts a value into the stream, where the type of the value is defined by the first parameter.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWEnhancedXmlObjectOutputStreamImp::putInt

(

int

value

)

[virtual]

Puts a value into the stream, where the type of the value is defined by the first parameter.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWEnhancedXmlObjectOutputStreamImp::putLong

(

long

value

)

[virtual]

Puts a value into the stream, where the type of the value is defined by the first parameter.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWEnhancedXmlObjectOutputStreamImp::putLongDouble

(

long double

value

)

[virtual]

Puts a value into the stream, where the type of the value is defined by the first parameter.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWEnhancedXmlObjectOutputStreamImp::putLongLong

(

long long

value

)

[virtual]

Puts a value into the stream, where the type of the value is defined by the first parameter.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWEnhancedXmlObjectOutputStreamImp::putShort

(

short

value

)

[virtual]

Puts a value into the stream, where the type of the value is defined by the first parameter.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWEnhancedXmlObjectOutputStreamImp::putSignedChar

(

signed char

value

)

[virtual]

Puts a value into the stream, where the type of the value is defined by the first parameter.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWEnhancedXmlObjectOutputStreamImp::putSizeT

(

size_t

value

)

[virtual]

Puts a value into the stream, where the type of the value is defined by the first parameter.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWEnhancedXmlObjectOutputStreamImp::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 RWEnhancedXmlObjectOutputStreamImp::putString

(

const RWCString &

value

)

[virtual]

Puts a value into the stream, where the type of the value is defined by the first parameter.

Implements RWObjectOutputStreamImp.

virtual void RWEnhancedXmlObjectOutputStreamImp::putUCharacter

(

RWUChar

value

)

[virtual]

Puts a value into the stream, where the type of the value is defined by the first parameter.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWEnhancedXmlObjectOutputStreamImp::putUnsignedChar

(

unsigned char

value

)

[virtual]

Puts a value into the stream, where the type of the value is defined by the first parameter.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWEnhancedXmlObjectOutputStreamImp::putUnsignedInt

(

unsigned int

value

)

[virtual]

Puts a value into the stream, where the type of the value is defined by the first parameter.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWEnhancedXmlObjectOutputStreamImp::putUnsignedLong

(

unsigned long

value

)

[virtual]

Puts a value into the stream, where the type of the value is defined by the first parameter.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWEnhancedXmlObjectOutputStreamImp::putUnsignedLongLong

(

unsigned long long

value

)

[virtual]

Puts a value into the stream, where the type of the value is defined by the first parameter.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWEnhancedXmlObjectOutputStreamImp::putUnsignedShort

(

unsigned short

value

)

[virtual]

Puts a value into the stream, where the type of the value is defined by the first parameter.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWEnhancedXmlObjectOutputStreamImp::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 RWEnhancedXmlObjectOutputStreamImp::putUString

(

const RWBasicUString &

value

)

[virtual]

Puts a value into the stream, where the type of the value is defined by the first parameter.

Implements RWObjectOutputStreamImp.

virtual void RWEnhancedXmlObjectOutputStreamImp::putWchar_t

(

wchar_t

value

)

[virtual]

Puts a value into the stream, where the type of the value is defined by the first parameter.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWEnhancedXmlObjectOutputStreamImp::putWCharacter

(

wchar_t

value

)

[virtual]

Puts a value into the stream, where the type of the value is defined by the first parameter.

Reimplemented from RWFilteredDataOutputStreamImp.

virtual void RWEnhancedXmlObjectOutputStreamImp::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 RWEnhancedXmlObjectOutputStreamImp::putWString

(

const RWWString &

value

)

[virtual]

Puts a value into the stream, where the type of the value is defined by the first parameter.

Implements RWObjectOutputStreamImp.

virtual void RWEnhancedXmlObjectOutputStreamImp::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 RWEnhancedXmlObjectOutputStreamImp::setNameForNextObject

(

const RWCString &

str

)

[virtual]

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

Implements RWObjectOutputStreamImp.

virtual void RWEnhancedXmlObjectOutputStreamImp::startAssocKey

(

)

[virtual]

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

Reimplemented from RWObjectOutputStreamImp.

virtual void RWEnhancedXmlObjectOutputStreamImp::startAssocValue

(

)

[virtual]

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

Reimplemented from RWObjectOutputStreamImp.

virtual void RWEnhancedXmlObjectOutputStreamImp::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 RWEnhancedXmlObjectOutputStreamImp::startElement

(

int

)

[virtual]

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

Reimplemented from RWObjectOutputStreamImp.

virtual void RWEnhancedXmlObjectOutputStreamImp::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 RWEnhancedXmlObjectOutputStreamImp::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 RWEnhancedXmlObjectOutputStreamImp::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 RWEnhancedXmlObjectOutputStreamImp::writeNullPtr

(

)

[virtual]

Output is a token representing a null pointer.

Implements RWObjectOutputStreamImp.

virtual void RWEnhancedXmlObjectOutputStreamImp::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.