Ceylan::Middleware::Marshaller Class Reference

Encodes and decodes informations so that they can be directly written and read from and to the stream that the marshaller encapsulates. More...

#include <CeylanMarshaller.h>

Inheritance diagram for Ceylan::Middleware::Marshaller:

[legend]

Collaboration diagram for Ceylan::Middleware::Marshaller:

[legend]

List of all members.

Public Types

enum TextOutputFormat { rawText, html }

Defines what text output formats for TextDisplayable instances are available. More...

Public Member Functions

Marshaller (System::InputOutputStream &lowerLevelStream, System::Size bufferedSize=0)

Constructs a new marshaller/demarshaller object.

virtual ~Marshaller () throw ()

Virtual destructor.

virtual System::Size retrieveData (System::Size requestedSize=0)

Requests this marshaller to read either a minimum size or as much data as possible, so that there may be enough data to read at least a full PDU.

virtual const std::string toString (Ceylan::VerbosityLevels level=Ceylan::high) const

Returns a user-friendly description of the state of this object.

Static Public Member Functions

static const std::string ToString (std::list< TextDisplayable * > displayables, Ceylan::VerbosityLevels level=Ceylan::high)

Returns a user-friendly description of this list of pointers to text displayable instances.

static TextOutputFormat GetOutputFormat ()

Returns the current overall text format to be used by TextDisplayable instances.

static void SetOutputFormat (TextOutputFormat newOutputFormat)

Sets the current overall text format to be used by TextDisplayable instances.

Protected Member Functions

bool isBuffered () const

Protected Attributes

System::InputOutputStream * _lowerLevelStream

The stream that will be used to exchange marshall/demarshall informations.

System::MemoryStream * _bufferStream

An in-memory buffered stream that may be used to cache read bytes until they form a full structure that has to be read as a whole (like a PDU) or not at all, for example by a protocol endpoint.

Static Protected Attributes

static TextOutputFormat _OutputFormat = rawText

The text format to be used currently by TextDisplayable instances.

Private Member Functions

Marshaller (const Marshaller &source)

Copy constructor made private to ensure that it will be never called.

Marshaller & operator= (const Marshaller &source)

Assignment operator made private to ensure that it will be never called.

Detailed Description

Encodes and decodes informations so that they can be directly written and read from and to the stream that the marshaller encapsulates.

These informations may be basic data types, for example a set of Ceylan::Uint32 numbers, or more complex data structures, such as full-fledged applicative PDU.

A marshaller is notably a building block of a protocol endpoint, as, for example, a protocol server must demarshall what the client sent, perform any corresponding action, and in turn it may marshall back an answer to the client. It is the task of the Marshaller to hide to the protocol endpoint the various operations necessary to convert higher-level informations, manipulated by the endpoint, into a bitstream, as needed by the underlying transport stream, and the other way round, from transport to endpoint.

Hence it is the place where the actual marshalling/demarshalling is taken care of.

Various encodings can be used, from basic home-made ones, which just handle endianness, to more powerful ones, including PER ASN.1 encodings.

Note:: The Marshaller abstract class does not enforce a specific interface (which for example would ensure that its child classes all implement readUint32), since, depending an the actual marshalling, this may or may not be make sense.

For example, ASN marshalling is PDU-based (it handles only full structures), hence fine-grain (ex: Uint32) encoding is meaningless with it.

Definition at line 163 of file CeylanMarshaller.h.

Member Enumeration Documentation

enum Ceylan::TextDisplayable::TextOutputFormat [inherited]

Defines what text output formats for TextDisplayable instances are available.

Enumerator:

rawText
html

Definition at line 124 of file CeylanTextDisplayable.h.

Constructor & Destructor Documentation

Marshaller::Marshaller	(	System::InputOutputStream &	lowerLevelStream,
		System::Size	bufferedSize = `0`
	)			`[explicit]`

Constructs a new marshaller/demarshaller object.

Parameters:

	lowerLevelStream	the stream that will be used by the marshaller to read/write the bistream to be transformed into higher level constructs.
	bufferedSize	the size in bytes of an internal buffered stream used so that only full PDU can be made available by the marshaller. A null size means no buffer wanted.

Note:: The marshaller does not take ownership of the stream, hence will not deallocate it.

Definition at line 99 of file CeylanMarshaller.cc.

References _bufferStream.

Marshaller::~Marshaller ( ) throw () [virtual]

Virtual destructor.

Definition at line 113 of file CeylanMarshaller.cc.

References _bufferStream, and isBuffered().

Ceylan::Middleware::Marshaller::Marshaller ( const Marshaller & source ) [private]

Copy constructor made private to ensure that it will be never called.

The compiler should complain whenever this undefined constructor is called, implicitly or not.

Member Function Documentation

TextDisplayable::TextOutputFormat TextDisplayable::GetOutputFormat ( ) [static, inherited]

Returns the current overall text format to be used by TextDisplayable instances.

Definition at line 63 of file CeylanTextDisplayable.cc.

References Ceylan::TextDisplayable::_OutputFormat.

Referenced by Ceylan::formatStringList(), Ceylan::formatStringMap(), Ceylan::XML::XMLMarkup::toString(), Ceylan::Maths::Linear::Vector3::toString(), Ceylan::Maths::Linear::Vector2::toString(), Ceylan::Maths::Linear::Tripoint::toString(), Ceylan::Module::toString(), Ceylan::Maths::Linear::Matrix3::toString(), Ceylan::Maths::Linear::Matrix2::toString(), Ceylan::Maths::Linear::HomogeneousMatrix3::toString(), and Ceylan::Maths::Linear::Bipoint::toString().

bool Ceylan::Middleware::Marshaller::isBuffered ( ) const [inline, protected]

Definition at line 275 of file CeylanMarshaller.h.

Referenced by retrieveData(), and ~Marshaller().

Marshaller& Ceylan::Middleware::Marshaller::operator= ( const Marshaller & source ) [private]

Assignment operator made private to ensure that it will be never called.

The compiler should complain whenever this undefined operator is called, implicitly or not.

System::Size Marshaller::retrieveData ( System::Size requestedSize = 0 ) [virtual]

Requests this marshaller to read either a minimum size or as much data as possible, so that there may be enough data to read at least a full PDU.

Parameters:

requestedSize

the contiguous size that is needed by the caller to store the bytes it is waiting for. If this needed size is greater than the buffer size, the condition will never be met and a DecodeException is thrown. If the needed size is smaller than the buffer size but bigger than the remaining size of next free chunk, as normally previous PDU should have been decoded, at the expense of an automatic move in buffer, the beginning of the PDU to decode will be set back to the beginning of the buffer so that the full PDU will be able to fit in buffer.

If the requested size is null, then this marshaller will try to read from its encapsulated lower level stream the full remaining free size between the current index of its internal buffer and the end of that buffer.

Returns:: the number of bytes available in the buffer for reading. This is not necessarily the exact number of bytes that were just read, insofar as there may already be some data in the buffer before this method was called.

The caller can use the returned information to figure out if it waits for more data or if there is already enough to be decoded in place.

Note:: Using this method only makes sense if the marshaller has an internal buffer.

Exceptions:

DecodeException

if the operation failed, including if there is no buffer available, or if there is not enough space in the buffer to fulfill requested size or to read more data.

Definition at line 125 of file CeylanMarshaller.cc.

References _bufferStream, _lowerLevelStream, dataUtils::e, Ceylan::System::MemoryStream::getAddressOfNextFreeChunk(), Ceylan::System::MemoryStream::getBlockLength(), Ceylan::System::MemoryStream::getSize(), Ceylan::System::MemoryStream::getSizeOfNextFreeChunk(), Ceylan::System::MemoryStream::increaseFilledBlockOf(), isBuffered(), Ceylan::System::MemoryStream::moveFilledBlockToBufferStart(), Ceylan::System::InputStream::read(), Ceylan::Exception::toString(), toString(), and Ceylan::toString().

void TextDisplayable::SetOutputFormat ( TextOutputFormat newOutputFormat ) [static, inherited]

Sets the current overall text format to be used by TextDisplayable instances.

Parameters:

newOutputFormat

the new output format.

Definition at line 72 of file CeylanTextDisplayable.cc.

References Ceylan::TextDisplayable::_OutputFormat.

Referenced by Ceylan::Log::LogHolder::LogHolder().

const std::string TextDisplayable::ToString	(	std::list< TextDisplayable * >	displayables,
		Ceylan::VerbosityLevels	level = `Ceylan::high`
	)			`[static, inherited]`

Returns a user-friendly description of this list of pointers to text displayable instances.

Parameters:

	displayables	a list of pointers to TextDisplayable instances/
	level	the requested verbosity level.

Note:: Text output format is determined from overall settings.

See also:: toString, Ceylan::VerbosityLevels

Definition at line 45 of file CeylanTextDisplayable.cc.

References Ceylan::formatStringList().

const string Marshaller::toString ( Ceylan::VerbosityLevels level = Ceylan::high ) const [virtual]

Returns a user-friendly description of the state of this object.

Parameters:

level

the requested verbosity level.

Note:: Text output format is determined from overall settings.

See also:: TextDisplayable

Implements Ceylan::TextDisplayable.

Reimplemented in Ceylan::Middleware::LightWeightMarshaller.

Definition at line 251 of file CeylanMarshaller.cc.

References _bufferStream, _lowerLevelStream, Ceylan::System::MemoryStream::toString(), and Ceylan::System::InputOutputStream::toString().

Referenced by retrieveData(), and Ceylan::Middleware::ProtocolEndpoint::toString().

Member Data Documentation

System::MemoryStream* Ceylan::Middleware::Marshaller::_bufferStream [protected]

An in-memory buffered stream that may be used to cache read bytes until they form a full structure that has to be read as a whole (like a PDU) or not at all, for example by a protocol endpoint.

Definition at line 291 of file CeylanMarshaller.h.

Referenced by Marshaller(), retrieveData(), toString(), and ~Marshaller().

System::InputOutputStream* Ceylan::Middleware::Marshaller::_lowerLevelStream [protected]

The stream that will be used to exchange marshall/demarshall informations.

Definition at line 271 of file CeylanMarshaller.h.

TextDisplayable::TextOutputFormat TextDisplayable::_OutputFormat = rawText [static, protected, inherited]

The text format to be used currently by TextDisplayable instances.

Note:: Defaults to raw text.

Definition at line 158 of file CeylanTextDisplayable.h.

Referenced by Ceylan::TextDisplayable::GetOutputFormat(), and Ceylan::TextDisplayable::SetOutputFormat().

The documentation for this class was generated from the following files:


Public Types
enum	TextOutputFormat { rawText, html }
	Defines what text output formats for TextDisplayable instances are available. More...
Public Member Functions
	Marshaller (System::InputOutputStream &lowerLevelStream, System::Size bufferedSize=0)
	Constructs a new marshaller/demarshaller object.
virtual	~Marshaller () throw ()
	Virtual destructor.
virtual System::Size	retrieveData (System::Size requestedSize=0)
	Requests this marshaller to read either a minimum size or as much data as possible, so that there may be enough data to read at least a full PDU.
virtual const std::string	toString (Ceylan::VerbosityLevels level=Ceylan::high) const
	Returns a user-friendly description of the state of this object.
Static Public Member Functions
static const std::string	ToString (std::list< TextDisplayable * > displayables, Ceylan::VerbosityLevels level=Ceylan::high)
	Returns a user-friendly description of this list of pointers to text displayable instances.
static TextOutputFormat	GetOutputFormat ()
	Returns the current overall text format to be used by TextDisplayable instances.
static void	SetOutputFormat (TextOutputFormat newOutputFormat)
	Sets the current overall text format to be used by TextDisplayable instances.
Protected Member Functions
bool	isBuffered () const
Protected Attributes
System::InputOutputStream *	_lowerLevelStream
	The stream that will be used to exchange marshall/demarshall informations.
System::MemoryStream *	_bufferStream
	An in-memory buffered stream that may be used to cache read bytes until they form a full structure that has to be read as a whole (like a PDU) or not at all, for example by a protocol endpoint.
Static Protected Attributes
static TextOutputFormat	_OutputFormat = rawText
	The text format to be used currently by TextDisplayable instances.
Private Member Functions
	Marshaller (const Marshaller &source)
	Copy constructor made private to ensure that it will be never called.
Marshaller &	operator= (const Marshaller &source)
	Assignment operator made private to ensure that it will be never called.