XMLGrammarPool.hpp
Go to the documentation of this file.
/*
* 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$
*/
#if !defined(XERCESC_INCLUDE_GUARD_XMLGRAMMARPOOL_HPP)
#define XERCESC_INCLUDE_GUARD_XMLGRAMMARPOOL_HPP
#include <xercesc/util/PlatformUtils.hpp>
#include <xercesc/util/RefHashTableOf.hpp>
#include <xercesc/util/XMemory.hpp>
#include <xercesc/framework/psvi/XSModel.hpp>
XERCES_CPP_NAMESPACE_BEGIN
class Grammar;
class XMLGrammarDescription;
class DTDGrammar;
class SchemaGrammar;
class XMLDTDDescription;
class XMLSchemaDescription;
class XMLStringPool;
class BinInputStream;
class BinOutputStream;
class XMLPARSER_EXPORT XMLGrammarPool : public XMemory
{
public :
// -----------------------------------------------------------------------
// -----------------------------------------------------------------------
virtual ~XMLGrammarPool(){};
// -----------------------------------------------------------------------
// -----------------------------------------------------------------------
virtual bool cacheGrammar(Grammar* const gramToCache) = 0;
virtual Grammar* retrieveGrammar(XMLGrammarDescription* const gramDesc) = 0;
virtual Grammar* orphanGrammar(const XMLCh* const nameSpaceKey) = 0;
virtual RefHashTableOfEnumerator<Grammar> getGrammarEnumerator() const = 0;
virtual bool clear() = 0;
virtual void lockPool() = 0;
virtual void unlockPool() = 0;
// -----------------------------------------------------------------------
// -----------------------------------------------------------------------
virtual DTDGrammar* createDTDGrammar() = 0;
virtual SchemaGrammar* createSchemaGrammar() = 0;
virtual XMLDTDDescription* createDTDDescription(const XMLCh* const systemId) = 0;
virtual XMLSchemaDescription* createSchemaDescription(const XMLCh* const targetNamespace) = 0;
// -----------------------------------------------------------------------
// -----------------------------------------------------------------------
/***
* Return an XSModel derived from the components of all SchemaGrammars
* in the grammar pool. If the pool is locked, this should
* be a thread-safe operation.
*
* NOTE: The function should NEVER return NULL. If there are no grammars in
* the pool it should return an XSModel containing the Schema for Schema.
*
* Calling getXSModel() on an unlocked grammar pool may result in the
* creation of a new XSModel with the old XSModel being deleted.
* The bool parameter will indicate if the XSModel was changed.
*
*/
virtual XSModel *getXSModel(bool& XSModelWasChanged) = 0;
// @}
// -----------------------------------------------------------------------
// -----------------------------------------------------------------------
inline MemoryManager* getMemoryManager()
{
return fMemMgr;
}
virtual XMLStringPool *getURIStringPool() = 0;
// -----------------------------------------------------------------------
// -----------------------------------------------------------------------
/***
*
* 1. Context: Serialize/Deserialize All Grammars In One Session
*
* Since it is common that a declaration in one grammar may reference
* to definitions in other grammars, it is required to serialize those
* related (or interdependent) grammars in to one persistent data store
* in one serialization session (storing), and deserialize them from the
* persistent data store in one deserialization session (loading) back
* to the grammar pool.
*
* 2. Multiple serializations
*
* It is acceptable that client application requests more than one
* grammar serialization on a particular grammar pool, to track the
* different grammars cached, or for whatever reasons that client
* application is interested in.
*
* 3. Multiple deserializations
*
* Request for grammar deserialization either after the grammar pool has
* its own cached grammars, or request for more than one grammar
* deserialization, may cause undesired and unpredictable consequence
* and therefore client application shall be aware that individual
* implementationis may NOT support this.
*
* However it is strongly recommended that the client application requests
* no more than one grammar deserialization even a particular implementation
* may allow multiple deserializations.
*
* 4. Locking
*
* Both serialization and deserialization requires to lock the grammar pool
* before operation and unlock after operation. In the case the grammar pool
* is locked by a third party, the request for serialization/deserialization
* will NOT be entertained.
*
* 5. Versioning
*
* The Persistent data store has a version tag to be verified during
* deserialization, thus a grammar pool may decide if it supports
* a binary data created by a different release of Xerces.
*
* 6. Clean up
*
* The client application shall be aware that in the event of an exception
* thrown due to a corrupted data store during deserialization, implementation
* may not be able to clean up all resources allocated, and therefore it is
* client application's responsibility to clean up those unreleased resources.
*
*
*/
virtual void serializeGrammars(BinOutputStream* const) = 0;
virtual void deserializeGrammars(BinInputStream* const) = 0;
/*
* Set/get a flag to not create XSAnnotations when deserializing the grammar.
* Defaults to false (create XSAnnotations when deserializing the grammar).
*/
inline void setIgnoreSerializedAnnotations(const bool flag)
{
fIgnoreSerializedAnnotations = flag;
};
inline bool getIgnoreSerializedAnnotations() const
{
return fIgnoreSerializedAnnotations;
};
protected :
// -----------------------------------------------------------------------
// -----------------------------------------------------------------------
XMLGrammarPool(MemoryManager* const memMgr = XMLPlatformUtils::fgMemoryManager)
:fMemMgr(memMgr)
,fIgnoreSerializedAnnotations(false)
{
};
private :
// -----------------------------------------------------------------------
// -----------------------------------------------------------------------
XMLGrammarPool(const XMLGrammarPool& );
XMLGrammarPool& operator=(const XMLGrammarPool& );
// -----------------------------------------------------------------------
//
// fMemMgr: plugged-in (or defaulted-in) memory manager
// not owned
// no reset after initialization
//
// -----------------------------------------------------------------------
MemoryManager* const fMemMgr;
bool fIgnoreSerializedAnnotations;
};
XERCES_CPP_NAMESPACE_END
#endif
PlatformUtils.hpp
XMemory.hpp
XSModel.hpp
XMLPARSER_EXPORT
#define XMLPARSER_EXPORT
Definition XercesDefs.hpp:163
XERCES_CPP_NAMESPACE_BEGIN
#define XERCES_CPP_NAMESPACE_BEGIN
Definition XercesDefs.hpp:112
XERCES_CPP_NAMESPACE_END
#define XERCES_CPP_NAMESPACE_END
Definition XercesDefs.hpp:113
XMLCh
char16_t XMLCh
Definition Xerces_autoconf_config.hpp:120
BinInputStream
Definition BinInputStream.hpp:30
BinOutputStream
Definition BinOutputStream.hpp:30
MemoryManager
Configurable memory manager.
Definition MemoryManager.hpp:40
XMLDTDDescription
Definition XMLDTDDescription.hpp:30
XMLGrammarDescription
Definition XMLGrammarDescription.hpp:33
XMLGrammarPool
Definition XMLGrammarPool.hpp:44
XMLGrammarPool::cacheGrammar
virtual bool cacheGrammar(Grammar *const gramToCache)=0
cacheGrammar
XMLGrammarPool::XMLGrammarPool
XMLGrammarPool(MemoryManager *const memMgr=XMLPlatformUtils::fgMemoryManager)
Hidden Constructors.
Definition XMLGrammarPool.hpp:291
XMLGrammarPool::getURIStringPool
virtual XMLStringPool * getURIStringPool()=0
Return an XMLStringPool for use by validation routines.
XMLGrammarPool::lockPool
virtual void lockPool()=0
lockPool
XMLGrammarPool::getIgnoreSerializedAnnotations
bool getIgnoreSerializedAnnotations() const
Definition XMLGrammarPool.hpp:281
XMLGrammarPool::createDTDDescription
virtual XMLDTDDescription * createDTDDescription(const XMLCh *const systemId)=0
createDTDDescription
XMLGrammarPool::deserializeGrammars
virtual void deserializeGrammars(BinInputStream *const)=0
XMLGrammarPool::createSchemaDescription
virtual XMLSchemaDescription * createSchemaDescription(const XMLCh *const targetNamespace)=0
createSchemaDescription
XMLGrammarPool::retrieveGrammar
virtual Grammar * retrieveGrammar(XMLGrammarDescription *const gramDesc)=0
retrieveGrammar
XMLGrammarPool::unlockPool
virtual void unlockPool()=0
unlockPool
XMLGrammarPool::~XMLGrammarPool
virtual ~XMLGrammarPool()
virtual destructor
Definition XMLGrammarPool.hpp:55
XMLGrammarPool::orphanGrammar
virtual Grammar * orphanGrammar(const XMLCh *const nameSpaceKey)=0
orphanGrammar
XMLGrammarPool::serializeGrammars
virtual void serializeGrammars(BinOutputStream *const)=0
serialization and deserialization support
XMLGrammarPool::getMemoryManager
MemoryManager * getMemoryManager()
getMemoryManager
Definition XMLGrammarPool.hpp:200
XMLGrammarPool::clear
virtual bool clear()=0
clear
XMLGrammarPool::createSchemaGrammar
virtual SchemaGrammar * createSchemaGrammar()=0
createSchemaGrammar
XMLGrammarPool::getGrammarEnumerator
virtual RefHashTableOfEnumerator< Grammar > getGrammarEnumerator() const =0
Get an enumeration of the cached Grammars in the Grammar pool.
XMLGrammarPool::createDTDGrammar
virtual DTDGrammar * createDTDGrammar()=0
createDTDGrammar
XMLGrammarPool::setIgnoreSerializedAnnotations
void setIgnoreSerializedAnnotations(const bool flag)
Definition XMLGrammarPool.hpp:277
XMLGrammarPool::getXSModel
virtual XSModel * getXSModel(bool &XSModelWasChanged)=0
XMLPlatformUtils::fgMemoryManager
static MemoryManager * fgMemoryManager
The configurable memory manager.
Definition PlatformUtils.hpp:121
XMLSchemaDescription
Definition XMLSchemaDescription.hpp:33
XMemory::XMemory
XMemory()
Protected default constructor.
Definition XMemory.hpp:130
XSModel
Definition XSModel.hpp:60