TransService.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: TransService.hpp 1224891 2011-12-27 10:59:21Z amassari $
*/
#if !defined(XERCESC_INCLUDE_GUARD_TRANSSERVICE_HPP)
#define XERCESC_INCLUDE_GUARD_TRANSSERVICE_HPP
#include <xercesc/util/XMemory.hpp>
#include <xercesc/util/PlatformUtils.hpp>
#include <xercesc/framework/XMLRecognizer.hpp>
#include <xercesc/util/RefHashTableOf.hpp>
#include <xercesc/util/RefVectorOf.hpp>
#include <xercesc/util/Janitor.hpp>
XERCES_CPP_NAMESPACE_BEGIN
// Forward references
//class XMLPlatformUtils;
class XMLLCPTranscoder;
class XMLTranscoder;
class ENameMap;
//
// This class is an abstract base class which are used to abstract the
// transcoding services that Xerces uses. The parser's actual transcoding
// needs are small so it is desirable to allow different implementations
// to be provided.
//
// The transcoding service has to provide a couple of required string
// and character operations, but its most important service is the creation
// of transcoder objects. There are two types of transcoders, which are
// discussed below in the XMLTranscoder class' description.
//
class XMLUTIL_EXPORT XMLTransService : public XMemory
{
public :
// -----------------------------------------------------------------------
// Class specific types
// -----------------------------------------------------------------------
enum Codes
{
Ok
, UnsupportedEncoding
, InternalFailure
, SupportFilesNotFound
};
struct TransRec
{
XMLCh intCh;
XMLByte extCh;
};
// -----------------------------------------------------------------------
// Public constructors and destructor
// -----------------------------------------------------------------------
virtual ~XMLTransService();
// -----------------------------------------------------------------------
// Non-virtual API
// -----------------------------------------------------------------------
XMLTranscoder* makeNewTranscoderFor
(
const XMLCh* const encodingName
, XMLTransService::Codes& resValue
, const XMLSize_t blockSize
, MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager
);
XMLTranscoder* makeNewTranscoderFor
(
const char* const encodingName
, XMLTransService::Codes& resValue
, const XMLSize_t blockSize
, MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager
);
XMLTranscoder* makeNewTranscoderFor
(
XMLRecognizer::Encodings encodingEnum
, XMLTransService::Codes& resValue
, const XMLSize_t blockSize
, MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager
);
// -----------------------------------------------------------------------
// The virtual transcoding service API
// -----------------------------------------------------------------------
virtual int compareIString
(
const XMLCh* const comp1
, const XMLCh* const comp2
) = 0;
virtual int compareNIString
(
const XMLCh* const comp1
, const XMLCh* const comp2
, const XMLSize_t maxChars
) = 0;
virtual const XMLCh* getId() const = 0;
// -----------------------------------------------------------------------
// Create a new transcoder for the local code page.
//
// @param manager The memory manager to use.
// -----------------------------------------------------------------------
virtual XMLLCPTranscoder* makeNewLCPTranscoder(MemoryManager* manager) = 0;
virtual bool supportsSrcOfs() const = 0;
virtual void upperCase(XMLCh* const toUpperCase) = 0;
virtual void lowerCase(XMLCh* const toLowerCase) = 0;
// -----------------------------------------------------------------------
// Allow users to add their own encodings to the intrinsic mapping
// table
// Usage:
// XMLTransService::addEncoding (
// gMyEncodingNameString
// , new ENameMapFor<MyTransClassType>(gMyEncodingNameString)
// );
// -----------------------------------------------------------------------
static void addEncoding(const XMLCh* const encoding, ENameMap* const ownMapping);
protected :
// -----------------------------------------------------------------------
// Hidden constructors
// -----------------------------------------------------------------------
XMLTransService();
// -----------------------------------------------------------------------
// Protected virtual methods.
// -----------------------------------------------------------------------
#ifdef OS390
friend class Uniconv390TransService;
#endif
virtual XMLTranscoder* makeNewXMLTranscoder
(
const XMLCh* const encodingName
, XMLTransService::Codes& resValue
, const XMLSize_t blockSize
, MemoryManager* const manager
) = 0;
// -----------------------------------------------------------------------
// Protected init method for platform utils to call
// -----------------------------------------------------------------------
friend class XMLPlatformUtils;
virtual void initTransService();
// -----------------------------------------------------------------------
// protected static members
// gMappings
// This is a hash table of ENameMap objects. It is created and filled
// in when the platform init calls our initTransService() method.
//
// gMappingsRecognizer
// This is an array of ENameMap objects, predefined for those
// already recognized by XMLRecognizer::Encodings.
//
static RefHashTableOf<ENameMap>* gMappings;
static RefVectorOf<ENameMap>* gMappingsRecognizer;
private :
// -----------------------------------------------------------------------
// Unimplemented constructors and operators
// -----------------------------------------------------------------------
XMLTransService(const XMLTransService&);
XMLTransService& operator=(const XMLTransService&);
// -----------------------------------------------------------------------
// Hidden method to enable/disable strict IANA encoding check
// Caller: XMLPlatformUtils
// -----------------------------------------------------------------------
void strictIANAEncoding(const bool newState);
bool isStrictIANAEncoding();
friend class XMLInitializer;
};
class XMLUTIL_EXPORT XMLTranscoder : public XMemory
{
public :
enum UnRepOpts
{
UnRep_Throw
, UnRep_RepChar
};
virtual ~XMLTranscoder();
virtual XMLSize_t transcodeFrom
(
const XMLByte* const srcData
, const XMLSize_t srcCount
, XMLCh* const toFill
, const XMLSize_t maxChars
, XMLSize_t& bytesEaten
, unsigned char* const charSizes
) = 0;
virtual XMLSize_t transcodeTo
(
const XMLCh* const srcData
, const XMLSize_t srcCount
, XMLByte* const toFill
, const XMLSize_t maxBytes
, XMLSize_t& charsEaten
, const UnRepOpts options
) = 0;
virtual bool canTranscodeTo
(
const unsigned int toCheck
) = 0;
XMLSize_t getBlockSize() const;
const XMLCh* getEncodingName() const;
MemoryManager* getMemoryManager() const;
protected :
// -----------------------------------------------------------------------
// Hidden constructors
// -----------------------------------------------------------------------
XMLTranscoder
(
const XMLCh* const encodingName
, const XMLSize_t blockSize
, MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager
);
// -----------------------------------------------------------------------
// Protected helper methods
// -----------------------------------------------------------------------
private :
// -----------------------------------------------------------------------
// Unimplemented constructors and operators
// -----------------------------------------------------------------------
XMLTranscoder(const XMLTranscoder&);
XMLTranscoder& operator=(const XMLTranscoder&);
// -----------------------------------------------------------------------
// Private data members
//
// fBlockSize
// This is the block size indicated in the constructor.
//
// fEncodingName
// This is the name of the encoding this encoder is for. All basic
// XML transcoder's are for named encodings.
// -----------------------------------------------------------------------
XMLSize_t fBlockSize;
XMLCh* fEncodingName;
MemoryManager* fMemoryManager;
};
//
// This class is a specialized transcoder that only transcodes between
// the internal XMLCh format and the local code page. It is specialized
// for the very common job of translating data from the client app's
// native code page to the internal format and vice versa.
//
class XMLUTIL_EXPORT XMLLCPTranscoder : public XMemory
{
public :
// -----------------------------------------------------------------------
// Public constructors and destructor
// -----------------------------------------------------------------------
virtual ~XMLLCPTranscoder();
// -----------------------------------------------------------------------
// The virtual transcoder API
//
// NOTE: All these APIs don't include null terminator characters in
// their parameters. So calcRequiredSize() returns the number
// of actual chars, not including the null. maxBytes and maxChars
// parameters refer to actual chars, not including the null so
// its assumed that the buffer is physically one char or byte
// larger.
// -----------------------------------------------------------------------
// -----------------------------------------------------------------------
// The 'normal' way to transcode a XMLCh-string from/to local string
// representation
//
// NOTE: Both methods return a string allocated via the MemoryManager.
// It is the responsibility of the calling environment to
// release this string after use.
// -----------------------------------------------------------------------
virtual char* transcode(const XMLCh* const toTranscode,
MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager) = 0;
virtual XMLCh* transcode(const char* const toTranscode,
MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager) = 0;
// -----------------------------------------------------------------------
// DEPRECATED old transcode interface
// -----------------------------------------------------------------------
virtual XMLSize_t calcRequiredSize(const char* const srcText
, MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager) = 0;
virtual XMLSize_t calcRequiredSize(const XMLCh* const srcText
, MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager) = 0;
virtual bool transcode
(
const char* const toTranscode
, XMLCh* const toFill
, const XMLSize_t maxChars
, MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager
) = 0;
virtual bool transcode
(
const XMLCh* const toTranscode
, char* const toFill
, const XMLSize_t maxBytes
, MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager
) = 0;
protected :
// -----------------------------------------------------------------------
// Hidden constructors
// -----------------------------------------------------------------------
XMLLCPTranscoder();
private :
// -----------------------------------------------------------------------
// Unimplemented constructors and operators
// -----------------------------------------------------------------------
XMLLCPTranscoder(const XMLLCPTranscoder&);
XMLLCPTranscoder& operator=(const XMLLCPTranscoder&);
};
//
// This class can be used to transcode to a target encoding. It manages the
// memory allocated for the transcode in an exception safe manner, automatically
// deleting it when the class goes out of scope.
//
class XMLUTIL_EXPORT TranscodeToStr
{
public:
// -----------------------------------------------------------------------
// Public constructors and destructor
// -----------------------------------------------------------------------
TranscodeToStr(const XMLCh *in, const char *encoding,
MemoryManager *manager = XMLPlatformUtils::fgMemoryManager);
TranscodeToStr(const XMLCh *in, XMLSize_t length, const char *encoding,
MemoryManager *manager = XMLPlatformUtils::fgMemoryManager);
TranscodeToStr(const XMLCh *in, XMLTranscoder* trans,
MemoryManager *manager = XMLPlatformUtils::fgMemoryManager);
TranscodeToStr(const XMLCh *in, XMLSize_t length, XMLTranscoder* trans,
MemoryManager *manager = XMLPlatformUtils::fgMemoryManager);
~TranscodeToStr();
const XMLByte *str() const;
XMLByte *adopt();
XMLSize_t length () const;
private:
// -----------------------------------------------------------------------
// Unimplemented constructors and operators
// -----------------------------------------------------------------------
TranscodeToStr(const TranscodeToStr &);
TranscodeToStr &operator=(const TranscodeToStr &);
// -----------------------------------------------------------------------
// Private helper methods
// -----------------------------------------------------------------------
void transcode(const XMLCh *in, XMLSize_t len, XMLTranscoder* trans);
// -----------------------------------------------------------------------
// Private data members
//
// fString
// The transcoded string
//
// fBytesWritten
// The length of the transcoded string in bytes
// -----------------------------------------------------------------------
ArrayJanitor<XMLByte> fString;
XMLSize_t fBytesWritten;
MemoryManager *fMemoryManager;
};
//
// This class can be used to transcode from a source encoding. It manages the
// memory allocated for the transcode in an exception safe manner, automatically
// deleting it when the class goes out of scope.
//
class XMLUTIL_EXPORT TranscodeFromStr
{
public:
// -----------------------------------------------------------------------
// Public constructors and destructor
// -----------------------------------------------------------------------
TranscodeFromStr(const XMLByte *data, XMLSize_t length, const char *encoding,
MemoryManager *manager = XMLPlatformUtils::fgMemoryManager);
TranscodeFromStr(const XMLByte *data, XMLSize_t length, XMLTranscoder *trans,
MemoryManager *manager = XMLPlatformUtils::fgMemoryManager);
~TranscodeFromStr();
const XMLCh *str() const;
XMLCh *adopt();
XMLSize_t length() const;
private:
// -----------------------------------------------------------------------
// Unimplemented constructors and operators
// -----------------------------------------------------------------------
TranscodeFromStr(const TranscodeFromStr &);
TranscodeFromStr &operator=(const TranscodeFromStr &);
// -----------------------------------------------------------------------
// Private helper methods
// -----------------------------------------------------------------------
void transcode(const XMLByte *in, XMLSize_t length, XMLTranscoder *trans);
// -----------------------------------------------------------------------
// Private data members
//
// fString
// The transcoded string
//
// fCharsWritten
// The length of the transcoded string in characters
// -----------------------------------------------------------------------
ArrayJanitor<XMLCh> fString;
XMLSize_t fCharsWritten;
MemoryManager *fMemoryManager;
};
// ---------------------------------------------------------------------------
// XMLTranscoder: Getter methods
// ---------------------------------------------------------------------------
inline MemoryManager* XMLTranscoder::getMemoryManager() const
{
return fMemoryManager;
}
// ---------------------------------------------------------------------------
// XMLTranscoder: Protected helper methods
// ---------------------------------------------------------------------------
inline XMLSize_t XMLTranscoder::getBlockSize() const
{
return fBlockSize;
}
inline const XMLCh* XMLTranscoder::getEncodingName() const
{
return fEncodingName;
}
// ---------------------------------------------------------------------------
// TranscodeToStr: Getter methods
// ---------------------------------------------------------------------------
inline const XMLByte *TranscodeToStr::str() const
{
return fString.get();
}
inline XMLByte *TranscodeToStr::adopt()
{
fBytesWritten = 0;
return fString.release();
}
inline XMLSize_t TranscodeToStr::length () const
{
return fBytesWritten;
}
// ---------------------------------------------------------------------------
// TranscodeFromStr: Getter methods
// ---------------------------------------------------------------------------
inline const XMLCh *TranscodeFromStr::str() const
{
return fString.get();
}
inline XMLCh *TranscodeFromStr::adopt()
{
fCharsWritten = 0;
return fString.release();
}
inline XMLSize_t TranscodeFromStr::length() const
{
return fCharsWritten;
}
XERCES_CPP_NAMESPACE_END
#endif
TranscodeToStr::str
const XMLByte * str() const
Returns the transcoded, null terminated string.
Definition: TransService.hpp:670
XMemory
This class makes it possible to override the C++ memory management by adding new/delete operators to ...
Definition: XMemory.hpp:40
XMLTransService::TransRec::extCh
XMLByte extCh
Definition: TransService.hpp:69
XMLPlatformUtils::fgMemoryManager
static MemoryManager * fgMemoryManager
The configurable memory manager.
Definition: PlatformUtils.hpp:121
TranscodeFromStr::length
XMLSize_t length() const
Returns the length of the transcoded string in characters.
Definition: TransService.hpp:700
XMLTranscoder::UnRepOpts
UnRepOpts
This enum is used by the transcodeTo() method to indicate how to react to unrepresentable characters...
Definition: TransService.hpp:226
TranscodeFromStr::adopt
XMLCh * adopt()
Returns the transcoded, null terminated string - adopting the memory allocated to it from the Transco...
Definition: TransService.hpp:694
XMLInitializer
Utilities that must be implemented in a class-specific way.
Definition: XMLInitializer.hpp:37
TranscodeFromStr
Definition: TransService.hpp:569
XMLTransService::Codes
Codes
Definition: TransService.hpp:58
TranscodeToStr
Definition: TransService.hpp:469
XMLPlatformUtils::isStrictIANAEncoding
static bool isStrictIANAEncoding()
Returns whether a strict IANA encoding name check is enabled or disabled.
XMLTranscoder
XMLTranscoder is for transcoding non-local code page encodings, i.e.
Definition: TransService.hpp:215
XMLTransService::TransRec::intCh
XMLCh intCh
Definition: TransService.hpp:68
XMLPlatformUtils::strictIANAEncoding
static void strictIANAEncoding(const bool state)
This function enables/disables strict IANA encoding names checking.
PlatformUtils.hpp
MemoryManager
Configurable memory manager.
Definition: MemoryManager.hpp:39
XMLCh
uint16_t XMLCh
Definition: Xerces_autoconf_config.hpp:118
XERCES_CPP_NAMESPACE_BEGIN
#define XERCES_CPP_NAMESPACE_BEGIN
Definition: XercesDefs.hpp:112
XMLPlatformUtils
Utilities that must be implemented in a platform-specific way.
Definition: PlatformUtils.hpp:68
TranscodeToStr::length
XMLSize_t length() const
Returns the length of the transcoded string in bytes.
Definition: TransService.hpp:681
XMLTransService
Definition: TransService.hpp:52
XMLByte
unsigned char XMLByte
Definition: XercesDefs.hpp:65
TranscodeFromStr::str
const XMLCh * str() const
Returns the transcoded, null terminated string.
Definition: TransService.hpp:689
XMLSize_t
size_t XMLSize_t
Definition: Xerces_autoconf_config.hpp:110
TranscodeToStr::adopt
XMLByte * adopt()
Returns the transcoded, null terminated string - adopting the memory allocated to it from the Transco...
Definition: TransService.hpp:675
XMLUTIL_EXPORT
#define XMLUTIL_EXPORT
Definition: XercesDefs.hpp:162
XMLTransService::TransRec
Definition: TransService.hpp:66
XERCES_CPP_NAMESPACE_END
#define XERCES_CPP_NAMESPACE_END
Definition: XercesDefs.hpp:113
XMLLCPTranscoder
Definition: TransService.hpp:388
XMLTranscoder::getMemoryManager
MemoryManager * getMemoryManager() const
Get the plugged-in memory manager.
Definition: TransService.hpp:649
XMLTranscoder::getBlockSize
XMLSize_t getBlockSize() const
Get the internal block size.
Definition: TransService.hpp:657
XMemory.hpp
XMLTransService::gMappingsRecognizer
static RefVectorOf< ENameMap > * gMappingsRecognizer
Definition: TransService.hpp:188
XMLTransService::gMappings
static RefHashTableOf< ENameMap > * gMappings
Definition: TransService.hpp:187
XMLTranscoder::getEncodingName
const XMLCh * getEncodingName() const
Get the encoding name.
Definition: TransService.hpp:662