/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/*
* $Id: XSerializeEngine.hpp 679296 2008-07-24 08:13:42Z borisk $
*/
#if !defined(XERCESC_INCLUDE_GUARD_XSERIALIZE_ENGINE_HPP)
#define XERCESC_INCLUDE_GUARD_XSERIALIZE_ENGINE_HPP
#include <xercesc/util/RefHashTableOf.hpp>
#include <xercesc/util/ValueVectorOf.hpp>
#include <xercesc/util/XMLExceptMsgs.hpp>
#include <xercesc/internal/XSerializationException.hpp>
XERCES_CPP_NAMESPACE_BEGIN
class XSerializable;
class XProtoType;
class MemoryManager;
class XSerializedObjectId;
class BinOutputStream;
class BinInputStream;
class XMLGrammarPool;
class XMLGrammarPoolImpl;
class XMLStringPool;
class XMLUTIL_EXPORT XSerializeEngine
{
public:
enum { mode_Store
, mode_Load
};
static const bool toReadBufferLen;
typedef unsigned int XSerializedObjectId_t;
/***
*
* Destructor
*
***/
~XSerializeEngine();
/***
*
* Constructor for de-serialization(loading)
*
* Application needs to make sure that the instance of
* BinInputStream, persists beyond the life of this
* SerializeEngine.
*
* Param
* inStream input stream
* gramPool Grammar Pool
* bufSize the size of the internal buffer
*
***/
XSerializeEngine(BinInputStream* inStream
, XMLGrammarPool* const gramPool
, XMLSize_t bufSize = 8192 );
/***
*
* Constructor for serialization(storing)
*
* Application needs to make sure that the instance of
* BinOutputStream, persists beyond the life of this
* SerializeEngine.
*
* Param
* outStream output stream
* gramPool Grammar Pool
* bufSize the size of the internal buffer
*
***/
XSerializeEngine(BinOutputStream* outStream
, XMLGrammarPool* const gramPool
, XMLSize_t bufSize = 8192 );
/***
*
* When serialization, flush out the internal buffer
*
* Return:
*
***/
void flush();
/***
*
* Checking if the serialize engine is doing serialization(storing)
*
* Return: true, if it is
* false, otherwise
*
***/
inline bool isStoring() const;
/***
*
* Checking if the serialize engine is doing de-serialization(loading)
*
* Return: true, if it is
* false, otherwise
*
***/
inline bool isLoading() const;
/***
*
* Get the GrammarPool
*
* Return: XMLGrammarPool
*
***/
XMLGrammarPool* getGrammarPool() const;
/***
*
* Get the StringPool
*
* Return: XMLStringPool
*
***/
XMLStringPool* getStringPool() const;
/***
*
* Get the embeded Memory Manager
*
* Return: MemoryManager
*
***/
MemoryManager* getMemoryManager() const;
/***
*
* Get the storer level (the level of the serialize engine
* which created the binary stream that this serialize engine
* is loading).
*
* The level returned is meaningful only when
* the engine isLoading.
*
* Return: level
*
***/
inline unsigned int getStorerLevel() const;
/***
*
* Write object to the internal buffer.
*
* Param
* objectToWrite: the object to be serialized
*
* Return:
*
***/
void write(XSerializable* const objectToWrite);
/***
*
* Write prototype info to the internal buffer.
*
* Param
* protoType: instance of prototype
*
* Return:
*
***/
void write(XProtoType* const protoType);
/***
*
* Write a stream of XMLByte to the internal buffer.
*
* Param
* toWrite: the stream of XMLByte to write
* writeLen: the length of the stream
*
* Return:
*
***/
void write(const XMLByte* const toWrite
, XMLSize_t writeLen);
/***
*
* Write a stream of XMLCh to the internal buffer.
*
* Param
* toWrite: the stream of XMLCh to write
* writeLen: the length of the stream
*
* Return:
*
***/
void write(const XMLCh* const toWrite
, XMLSize_t writeLen);
/***
*
* Write a stream of XMLCh to the internal buffer.
*
* Write the bufferLen first if requested, then the length
* of the stream followed by the stream.
*
* Param
* toWrite: the stream of XMLCh to write
* bufferLen: the maximum size of the buffer
* toWriteBufLen: specify if the bufferLen need to be written or not
*
* Return:
*
***/
void writeString(const XMLCh* const toWrite
, const XMLSize_t bufferLen = 0
, bool toWriteBufLen = false);
/***
*
* Write a stream of XMLByte to the internal buffer.
*
* Write the bufferLen first if requested, then the length
* of the stream followed by the stream.
*
* Param
* toWrite: the stream of XMLByte to write
* bufferLen: the maximum size of the buffer
* toWriteBufLen: specify if the bufferLen need to be written or not
*
* Return:
*
***/
void writeString(const XMLByte* const toWrite
, const XMLSize_t bufferLen = 0
, bool toWriteBufLen = false);
static const bool toWriteBufferLen;
/***
*
* Read/Create object from the internal buffer.
*
* Param
* protoType: an instance of prototype of the object anticipated
*
* Return: to object read/created
*
***/
XSerializable* read(XProtoType* const protoType);
/***
*
* Read prototype object from the internal buffer.
* Verify if the same prototype object found in buffer.
*
* Param
* protoType: an instance of prototype of the object anticipated
* objTag: the object Tag to an existing object
*
* Return: true : if matching found
* false : otherwise
*
***/
bool read(XProtoType* const protoType
, XSerializedObjectId_t* objTag);
/***
*
* Read XMLByte stream from the internal buffer.
*
* Param
* toRead: the buffer to hold the XMLByte stream
* readLen: the length of the XMLByte to read in
*
* Return:
*
***/
void read(XMLByte* const toRead
, XMLSize_t readLen);
/***
*
* Read XMLCh stream from the internal buffer.
*
* Param
* toRead: the buffer to hold the XMLCh stream
* readLen: the length of the XMLCh to read in
*
* Return:
*
***/
void read(XMLCh* const toRead
, XMLSize_t readLen);
/***
*
* Read a stream of XMLCh from the internal buffer.
*
* Read the bufferLen first if requested, then the length
* of the stream followed by the stream.
*
* Param
* toRead: the pointer to the buffer to hold the XMLCh stream
* bufferLen: the size of the buffer created
* dataLen: the length of the stream
* toReadBufLen: specify if the bufferLen need to be read or not
*
* Return:
*
***/
void readString(XMLCh*& toRead
, XMLSize_t& bufferLen
, XMLSize_t& dataLen
, bool toReadBufLen = false);
/***
*
* Read a stream of XMLCh from the internal buffer.
*
* Read the bufferLen first if requested, then the length
* of the stream followed by the stream.
*
* Param
* toRead: the pointer to the buffer to hold the XMLCh stream
* bufferLen: the size of the buffer created
*
* Return:
*
***/
inline void readString(XMLCh*& toRead
, XMLSize_t& bufferLen);
/***
*
* Read a stream of XMLCh from the internal buffer.
*
* Param
* toRead: the pointer to the buffer to hold the XMLCh stream
*
* Return:
*
***/
inline void readString(XMLCh*& toRead);
/***
*
* Read a stream of XMLByte from the internal buffer.
*
* Read the bufferLen first if requested, then the length
* of the stream followed by the stream.
*
* Param
* toRead: the pointer to the buffer to hold the XMLByte stream
* bufferLen: the size of the buffer created
* dataLen: the length of the stream
* toReadBufLen: specify if the bufferLen need to be read or not
*
* Return:
*
***/
void readString(XMLByte*& toRead
, XMLSize_t& bufferLen
, XMLSize_t& dataLen
, bool toReadBufLen = false);
/***
*
* Read a stream of XMLByte from the internal buffer.
*
* Read the bufferLen first if requested, then the length
* of the stream followed by the stream.
*
* Param
* toRead: the pointer to the buffer to hold the XMLByte stream
* bufferLen: the size of the buffer created
*
* Return:
*
***/
inline void readString(XMLByte*& toRead
, XMLSize_t& bufferLen);
/***
*
* Read a stream of XMLByte from the internal buffer.
*
* Read the bufferLen first if requested, then the length
* of the stream followed by the stream.
*
* Param
* toRead: the pointer to the buffer to hold the XMLByte stream
* bufferLen: the size of the buffer created
* dataLen: the length of the stream
* toReadBufLen: specify if the bufferLen need to be read or not
*
* Return:
*
***/
inline void readString(XMLByte*& toRead);
/***
*
* Check if the template object has been stored or not
*
* Param
* objectPtr: the template object pointer
*
* Return: true : the object has NOT been stored yet
* false : otherwise
*
***/
bool needToStoreObject(void* const templateObjectToWrite);
/***
*
* Check if the template object has been loaded or not
*
* Param
* objectPtr: the address of the template object pointer
*
* Return: true : the object has NOT been loaded yet
* false : otherwise
*
***/
bool needToLoadObject(void** templateObjectToRead);
/***
*
* In the case of needToLoadObject() return true, the client
* application needs to instantiate an expected template object, and
* register the address to the engine.
*
* Param
* objectPtr: the template object pointer newly instantiated
*
* Return:
*
***/
void registerObject(void* const templateObjectToRegister);
/***
*
* Insertion operator for serializable classes
*
***/
friend XSerializeEngine& operator<<(XSerializeEngine&
, XSerializable* const );
/***
*
* Insertion operators for
* . basic Xerces data types
* . built-in types
*
***/
XSerializeEngine& operator<<(XMLByte);
XSerializeEngine& operator<<(XMLCh);
XSerializeEngine& operator<<(char);
XSerializeEngine& operator<<(short);
XSerializeEngine& operator<<(int);
XSerializeEngine& operator<<(unsigned int);
XSerializeEngine& operator<<(long);
XSerializeEngine& operator<<(unsigned long);
XSerializeEngine& operator<<(float);
XSerializeEngine& operator<<(double);
XSerializeEngine& operator<<(bool);
// These cannot be done as operators since on some platforms they
// may collide with int/long types.
//
void writeSize (XMLSize_t);
void writeInt64 (XMLInt64);
void writeUInt64 (XMLUInt64);
/***
*
* Extraction operators for
* . basic Xerces data types
* . built-in types
*
***/
XSerializeEngine& operator>>(XMLByte&);
XSerializeEngine& operator>>(XMLCh&);
XSerializeEngine& operator>>(char&);
XSerializeEngine& operator>>(short&);
XSerializeEngine& operator>>(int&);
XSerializeEngine& operator>>(unsigned int&);
XSerializeEngine& operator>>(long&);
XSerializeEngine& operator>>(unsigned long&);
XSerializeEngine& operator>>(float&);
XSerializeEngine& operator>>(double&);
XSerializeEngine& operator>>(bool&);
void readSize (XMLSize_t&);
void readInt64 (XMLInt64&);
void readUInt64 (XMLUInt64&);
/***
*
* Getters
*
***/
inline
XMLSize_t getBufSize() const;
inline
XMLSize_t getBufCur() const;
inline
XMLSize_t getBufCurAccumulated() const;
inline
unsigned long getBufCount() const;
void trace(char*) const;
private:
// -----------------------------------------------------------------------
// Unimplemented constructors and operators
// -----------------------------------------------------------------------
XSerializeEngine();
XSerializeEngine(const XSerializeEngine&);
XSerializeEngine& operator=(const XSerializeEngine&);
/***
*
* Store Pool Opertions
*
***/
XSerializedObjectId_t lookupStorePool(void* const objectPtr) const;
void addStorePool(void* const objectPtr);
/***
*
* Load Pool Opertions
*
***/
XSerializable* lookupLoadPool(XSerializedObjectId_t objectTag) const;
void addLoadPool(void* const objectPtr);
/***
*
* Intenal Buffer Operations
*
***/
inline void checkAndFillBuffer(XMLSize_t bytesNeedToRead);
inline void checkAndFlushBuffer(XMLSize_t bytesNeedToWrite);
void fillBuffer();
void flushBuffer();
void pumpCount();
inline void resetBuffer();
/***
*
* Helper
*
***/
inline void ensureStoring() const;
inline void ensureLoading() const;
inline void ensureStoreBuffer() const;
inline void ensureLoadBuffer() const;
inline void ensurePointer(void* const) const;
inline void Assert(bool toEval
, const XMLExcepts::Codes toThrow) const;
inline XMLSize_t calBytesNeeded(XMLSize_t) const;
inline XMLSize_t alignAdjust(XMLSize_t) const;
inline void alignBufCur(XMLSize_t);
// Make XTemplateSerializer friend of XSerializeEngine so that
// we can call lookupStorePool and lookupLoadPool in the case of
// annotations.
friend class XTemplateSerializer;
// -------------------------------------------------------------------------------
// data
//
// fStoreLoad:
// Indicator: storing(serialization) or loading(de-serialization)
//
// fStorerLevel:
// The level of the serialize engine which created the binary
// stream that this serialize engine is loading
//
// It is set by GrammarPool when loading
//
// fGrammarPool:
// Thw owning GrammarPool which instantiate this SerializeEngine
// instance
//
// fInputStream:
// Binary stream to read from (de-serialization), provided
// by client application, not owned.
//
// fOutputStream:
// Binary stream to write to (serialization), provided
// by client application, not owned.
//
// fBufSize:
// The size of the internal buffer
//
// fBufStart/fBufEnd:
//
// The internal buffer.
// fBufEnd:
// one beyond the last valid cell
// fBufEnd === (fBufStart + fBufSize)
//
// fBufCur:
// The cursor of the buffer
//
// fBufLoadMax:
// Indicating the end of the valid content in the buffer
//
// fStorePool:
// Object collection for storing
//
// fLoadPool:
// Object collection for loading
//
// fMapCount:
// -------------------------------------------------------------------------------
const short fStoreLoad;
unsigned int fStorerLevel;
XMLGrammarPool* const fGrammarPool;
BinInputStream* const fInputStream;
BinOutputStream* const fOutputStream;
unsigned long fBufCount;
//buffer
const XMLSize_t fBufSize;
XMLByte* const fBufStart;
XMLByte* const fBufEnd;
XMLByte* fBufCur;
XMLByte* fBufLoadMax;
/***
* Map for storing object
*
* key: XSerializable*
* XProtoType*
*
* value: XMLInteger*, owned
*
***/
RefHashTableOf<XSerializedObjectId, PtrHasher>* fStorePool;
/***
* Vector for loading object, objects are NOT owned
*
* data: XSerializable*
* XProtoType*
*
***/
ValueVectorOf<void*>* fLoadPool;
/***
* object counter
***/
XSerializedObjectId_t fObjectCount;
//to allow grammar pool to set storer level when loading
friend class XMLGrammarPoolImpl;
};
inline bool XSerializeEngine::isStoring() const
{
return (fStoreLoad == mode_Store);
}
inline bool XSerializeEngine::isLoading() const
{
return (fStoreLoad == mode_Load);
}
inline XSerializeEngine& operator<<(XSerializeEngine& serEng
, XSerializable* const serObj)
{
serEng.write(serObj);
return serEng;
}
inline void XSerializeEngine::ensureStoring() const
{
Assert(isStoring(), XMLExcepts::XSer_Storing_Violation);
}
inline void XSerializeEngine::ensureLoading() const
{
Assert(isLoading(), XMLExcepts::XSer_Loading_Violation);
}
inline void XSerializeEngine::Assert(bool toEval
, const XMLExcepts::Codes toThrow) const
{
if (!toEval)
{
ThrowXMLwithMemMgr(XSerializationException, toThrow, getMemoryManager());
}
}
inline void XSerializeEngine::readString(XMLCh*& toRead
, XMLSize_t& bufferLen)
{
XMLSize_t dummyDataLen;
readString(toRead, bufferLen, dummyDataLen);
}
inline void XSerializeEngine::readString(XMLCh*& toRead)
{
XMLSize_t dummyBufferLen;
XMLSize_t dummyDataLen;
readString(toRead, dummyBufferLen, dummyDataLen);
}
inline void XSerializeEngine::readString(XMLByte*& toRead
, XMLSize_t& bufferLen)
{
XMLSize_t dummyDataLen;
readString(toRead, bufferLen, dummyDataLen);
}
inline void XSerializeEngine::readString(XMLByte*& toRead)
{
XMLSize_t dummyBufferLen;
XMLSize_t dummyDataLen;
readString(toRead, dummyBufferLen, dummyDataLen);
}
inline
XMLSize_t XSerializeEngine::getBufSize() const
{
return fBufSize;
}
inline
XMLSize_t XSerializeEngine::getBufCur() const
{
return (fBufCur-fBufStart);
}
inline
XMLSize_t XSerializeEngine::getBufCurAccumulated() const
{
return (fBufCount - (isStoring() ? 0: 1)) * fBufSize + (fBufCur-fBufStart);
}
inline
unsigned long XSerializeEngine::getBufCount() const
{
return fBufCount;
}
inline
unsigned int XSerializeEngine::getStorerLevel() const
{
return fStorerLevel;
}
/***
* Ought to be nested class
***/
class XSerializedObjectId : public XMemory
{
public:
~XSerializedObjectId(){};
private:
inline XSerializedObjectId(XSerializeEngine::XSerializedObjectId_t val):
fData(val) { };
inline XSerializeEngine::XSerializedObjectId_t getValue() const {return fData; };
friend class XSerializeEngine;
private:
// -----------------------------------------------------------------------
// Unimplemented constructors and operators
// -----------------------------------------------------------------------
XSerializedObjectId();
XSerializedObjectId(const XSerializedObjectId&);
XSerializedObjectId& operator=(const XSerializedObjectId&);
XSerializeEngine::XSerializedObjectId_t fData;
};
XERCES_CPP_NAMESPACE_END
#endif