TransService.hpp

Go to the documentation of this file.
00001 /*
00002  * Licensed to the Apache Software Foundation (ASF) under one or more
00003  * contributor license agreements.  See the NOTICE file distributed with
00004  * this work for additional information regarding copyright ownership.
00005  * The ASF licenses this file to You under the Apache License, Version 2.0
00006  * (the "License"); you may not use this file except in compliance with
00007  * the License.  You may obtain a copy of the License at
00008  *
00009  *      http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 
00018 /*
00019  * $Id: TransService.hpp 698579 2008-09-24 14:13:08Z borisk $
00020  */
00021 
00022 #if !defined(XERCESC_INCLUDE_GUARD_TRANSSERVICE_HPP)
00023 #define XERCESC_INCLUDE_GUARD_TRANSSERVICE_HPP
00024 
00025 #include <xercesc/util/XMemory.hpp>
00026 #include <xercesc/util/PlatformUtils.hpp>
00027 #include <xercesc/framework/XMLRecognizer.hpp>
00028 #include <xercesc/util/RefHashTableOf.hpp>
00029 #include <xercesc/util/RefVectorOf.hpp>
00030 
00031 XERCES_CPP_NAMESPACE_BEGIN
00032 
00033 // Forward references
00034 //class XMLPlatformUtils;
00035 class XMLLCPTranscoder;
00036 class XMLTranscoder;
00037 class ENameMap;
00038 
00039 
00040 //
00041 //  This class is an abstract base class which are used to abstract the
00042 //  transcoding services that Xerces uses. The parser's actual transcoding
00043 //  needs are small so it is desirable to allow different implementations
00044 //  to be provided.
00045 //
00046 //  The transcoding service has to provide a couple of required string
00047 //  and character operations, but its most important service is the creation
00048 //  of transcoder objects. There are two types of transcoders, which are
00049 //  discussed below in the XMLTranscoder class' description.
00050 //
00051 class XMLUTIL_EXPORT XMLTransService : public XMemory
00052 {
00053 public :
00054     // -----------------------------------------------------------------------
00055     //  Class specific types
00056     // -----------------------------------------------------------------------
00057     enum Codes
00058     {
00059         Ok
00060         , UnsupportedEncoding
00061         , InternalFailure
00062         , SupportFilesNotFound
00063     };
00064 
00065     struct TransRec
00066     {
00067         XMLCh       intCh;
00068         XMLByte     extCh;
00069     };
00070 
00071 
00072     // -----------------------------------------------------------------------
00073     //  Public constructors and destructor
00074     // -----------------------------------------------------------------------
00075     virtual ~XMLTransService();
00076 
00077 
00078     // -----------------------------------------------------------------------
00079     //  Non-virtual API
00080     // -----------------------------------------------------------------------
00081     XMLTranscoder* makeNewTranscoderFor
00082     (
00083         const   XMLCh* const            encodingName
00084         ,       XMLTransService::Codes& resValue
00085         , const XMLSize_t               blockSize
00086         , MemoryManager* const          manager = XMLPlatformUtils::fgMemoryManager
00087     );
00088 
00089     XMLTranscoder* makeNewTranscoderFor
00090     (
00091         const   char* const             encodingName
00092         ,       XMLTransService::Codes& resValue
00093         , const XMLSize_t               blockSize
00094         , MemoryManager* const          manager = XMLPlatformUtils::fgMemoryManager
00095     );
00096 
00097     XMLTranscoder* makeNewTranscoderFor
00098     (
00099         XMLRecognizer::Encodings        encodingEnum
00100         ,       XMLTransService::Codes& resValue
00101         , const XMLSize_t               blockSize
00102         , MemoryManager* const          manager = XMLPlatformUtils::fgMemoryManager
00103     );
00104 
00105 
00106     // -----------------------------------------------------------------------
00107     //  The virtual transcoding service API
00108     // -----------------------------------------------------------------------
00109     virtual int compareIString
00110     (
00111         const   XMLCh* const    comp1
00112         , const XMLCh* const    comp2
00113     ) = 0;
00114 
00115     virtual int compareNIString
00116     (
00117         const   XMLCh* const    comp1
00118         , const XMLCh* const    comp2
00119         , const XMLSize_t       maxChars
00120     ) = 0;
00121 
00122     virtual const XMLCh* getId() const = 0;
00123 
00124     // -----------------------------------------------------------------------
00125     //  Create a new transcoder for the local code page.
00126     //
00127     //  @param manager The memory manager to use.
00128     // -----------------------------------------------------------------------
00129     virtual XMLLCPTranscoder* makeNewLCPTranscoder(MemoryManager* manager) = 0;
00130 
00131     virtual bool supportsSrcOfs() const = 0;
00132 
00133     virtual void upperCase(XMLCh* const toUpperCase) = 0;
00134     virtual void lowerCase(XMLCh* const toLowerCase) = 0;
00135 
00136     // -----------------------------------------------------------------------
00137     //  Allow users to add their own encodings to the intrinsinc mapping
00138     //  table
00139     //  Usage:
00140     //      XMLTransService::addEncoding (
00141     //          gMyEncodingNameString
00142     //          , new ENameMapFor<MyTransClassType>(gMyEncodingNameString)
00143     //      );
00144     // -----------------------------------------------------------------------
00145     static void addEncoding(const XMLCh* const encoding, ENameMap* const ownMapping);
00146 
00147 
00148 protected :
00149     // -----------------------------------------------------------------------
00150     //  Hidden constructors
00151     // -----------------------------------------------------------------------
00152     XMLTransService();
00153 
00154 
00155     // -----------------------------------------------------------------------
00156     //  Protected virtual methods.
00157     // -----------------------------------------------------------------------
00158 #ifdef OS390
00159     friend class Uniconv390TransService;
00160 #endif
00161     virtual XMLTranscoder* makeNewXMLTranscoder
00162     (
00163         const   XMLCh* const            encodingName
00164         ,       XMLTransService::Codes& resValue
00165         , const XMLSize_t               blockSize
00166         , MemoryManager* const          manager
00167     ) = 0;
00168 
00169     // -----------------------------------------------------------------------
00170     //  Protected init method for platform utils to call
00171     // -----------------------------------------------------------------------
00172     friend class XMLPlatformUtils;
00173     virtual void initTransService();
00174 
00175     // -----------------------------------------------------------------------
00176     // protected static members
00177     //  gMappings
00178     //      This is a hash table of ENameMap objects. It is created and filled
00179     //      in when the platform init calls our initTransService() method.
00180     //
00181     //  gMappingsRecognizer
00182     //      This is an array of ENameMap objects, predefined for those
00183     //      already recognized by XMLRecognizer::Encodings.
00184     //
00185 
00186     static RefHashTableOf<ENameMap>*    gMappings;
00187     static RefVectorOf<ENameMap>*       gMappingsRecognizer;
00188 
00189 private :
00190     // -----------------------------------------------------------------------
00191     //  Unimplemented constructors and operators
00192     // -----------------------------------------------------------------------
00193     XMLTransService(const XMLTransService&);
00194     XMLTransService& operator=(const XMLTransService&);
00195 
00196     // -----------------------------------------------------------------------
00197     //  Hidden method to enable/disable strict IANA encoding check
00198     //  Caller: XMLPlatformUtils
00199     // -----------------------------------------------------------------------
00200     void strictIANAEncoding(const bool newState);
00201     bool isStrictIANAEncoding();
00202 
00203     friend class XMLInitializer;
00204 };
00205 
00214 class XMLUTIL_EXPORT XMLTranscoder : public XMemory
00215 {
00216 public :
00217 
00225     enum UnRepOpts
00226     {
00227         UnRep_Throw     
00228         , UnRep_RepChar     
00229     };
00230 
00231 
00234 
00239     virtual ~XMLTranscoder();
00241 
00242 
00243 
00246 
00266     virtual XMLSize_t transcodeFrom
00267     (
00268         const   XMLByte* const          srcData
00269         , const XMLSize_t               srcCount
00270         ,       XMLCh* const            toFill
00271         , const XMLSize_t               maxChars
00272         ,       XMLSize_t&              bytesEaten
00273         ,       unsigned char* const    charSizes
00274     ) = 0;
00275 
00289     virtual XMLSize_t transcodeTo
00290     (
00291         const   XMLCh* const    srcData
00292         , const XMLSize_t       srcCount
00293         ,       XMLByte* const  toFill
00294         , const XMLSize_t       maxBytes
00295         ,       XMLSize_t&      charsEaten
00296         , const UnRepOpts       options
00297     ) = 0;
00298 
00304     virtual bool canTranscodeTo
00305     (
00306         const   unsigned int    toCheck
00307     ) = 0;
00308 
00310 
00313 
00318     XMLSize_t getBlockSize() const;
00319 
00325     const XMLCh* getEncodingName() const;
00327 
00330 
00338     MemoryManager* getMemoryManager() const;
00339 
00341 
00342 protected :
00343     // -----------------------------------------------------------------------
00344     //  Hidden constructors
00345     // -----------------------------------------------------------------------
00346     XMLTranscoder
00347     (
00348         const   XMLCh* const    encodingName
00349         , const XMLSize_t       blockSize
00350         , MemoryManager* const  manager = XMLPlatformUtils::fgMemoryManager
00351     );
00352 
00353 
00354     // -----------------------------------------------------------------------
00355     //  Protected helper methods
00356     // -----------------------------------------------------------------------
00357 
00358 private :
00359     // -----------------------------------------------------------------------
00360     //  Unimplemented constructors and operators
00361     // -----------------------------------------------------------------------
00362     XMLTranscoder(const XMLTranscoder&);
00363     XMLTranscoder& operator=(const XMLTranscoder&);
00364 
00365     // -----------------------------------------------------------------------
00366     //  Private data members
00367     //
00368     //  fBlockSize
00369     //      This is the block size indicated in the constructor.
00370     //
00371     //  fEncodingName
00372     //      This is the name of the encoding this encoder is for. All basic
00373     //      XML transcoder's are for named encodings.
00374     // -----------------------------------------------------------------------
00375     XMLSize_t       fBlockSize;
00376     XMLCh*          fEncodingName;
00377     MemoryManager*  fMemoryManager;
00378 };
00379 
00380 
00381 //
00382 //  This class is a specialized transcoder that only transcodes between
00383 //  the internal XMLCh format and the local code page. It is specialized
00384 //  for the very common job of translating data from the client app's
00385 //  native code page to the internal format and vice versa.
00386 //
00387 class XMLUTIL_EXPORT XMLLCPTranscoder : public XMemory
00388 {
00389 public :
00390     // -----------------------------------------------------------------------
00391     //  Public constructors and destructor
00392     // -----------------------------------------------------------------------
00393     virtual ~XMLLCPTranscoder();
00394 
00395 
00396     // -----------------------------------------------------------------------
00397     //  The virtual transcoder API
00398     //
00399     //  NOTE:   All these APIs don't include null terminator characters in
00400     //          their parameters. So calcRequiredSize() returns the number
00401     //          of actual chars, not including the null. maxBytes and maxChars
00402     //          parameters refer to actual chars, not including the null so
00403     //          its assumed that the buffer is physically one char or byte
00404     //          larger.
00405     // -----------------------------------------------------------------------
00406 
00407     // -----------------------------------------------------------------------
00408     //  The 'normal' way to transcode a XMLCh-string from/to local string
00409     //  representation
00410     //
00411     //  NOTE: Both methods return a string allocated via the MemoryManager.
00412     //        It is the responsibility of the calling environment to
00413     //        release this string after use.
00414     // -----------------------------------------------------------------------
00415     virtual char* transcode(const XMLCh* const toTranscode,
00416                             MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager) = 0;
00417 
00418     virtual XMLCh* transcode(const char* const toTranscode,
00419                              MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager) = 0;
00420 
00421 
00422     // -----------------------------------------------------------------------
00423     //  DEPRECATED old transcode interface
00424     // -----------------------------------------------------------------------
00425     virtual XMLSize_t calcRequiredSize(const char* const srcText
00426         , MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager) = 0;
00427 
00428     virtual XMLSize_t calcRequiredSize(const XMLCh* const srcText
00429         , MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager) = 0;
00430 
00431     virtual bool transcode
00432     (
00433         const   char* const     toTranscode
00434         ,       XMLCh* const    toFill
00435         , const XMLSize_t       maxChars
00436         , MemoryManager* const  manager = XMLPlatformUtils::fgMemoryManager
00437     ) = 0;
00438 
00439     virtual bool transcode
00440     (
00441         const   XMLCh* const    toTranscode
00442         ,       char* const     toFill
00443         , const XMLSize_t       maxBytes
00444         , MemoryManager* const  manager = XMLPlatformUtils::fgMemoryManager
00445     ) = 0;
00446 
00447 
00448 protected :
00449     // -----------------------------------------------------------------------
00450     //  Hidden constructors
00451     // -----------------------------------------------------------------------
00452     XMLLCPTranscoder();
00453 
00454 
00455 private :
00456     // -----------------------------------------------------------------------
00457     //  Unimplemented constructors and operators
00458     // -----------------------------------------------------------------------
00459     XMLLCPTranscoder(const XMLLCPTranscoder&);
00460     XMLLCPTranscoder& operator=(const XMLLCPTranscoder&);
00461 };
00462 
00463 //
00464 // This class can be used to transcode to a target encoding. It manages the
00465 // memory allocated for the transcode in an exception safe manner, automatically
00466 // deleting it when the class goes out of scope.
00467 //
00468 class XMLUTIL_EXPORT TranscodeToStr
00469 {
00470 public:
00471     // -----------------------------------------------------------------------
00472     //  Public constructors and destructor
00473     // -----------------------------------------------------------------------
00474 
00481     TranscodeToStr(const XMLCh *in, const char *encoding,
00482                    MemoryManager *manager = XMLPlatformUtils::fgMemoryManager);
00483 
00491     TranscodeToStr(const XMLCh *in, XMLSize_t length, const char *encoding,
00492                    MemoryManager *manager = XMLPlatformUtils::fgMemoryManager);
00493 
00500     TranscodeToStr(const XMLCh *in, XMLTranscoder* trans,
00501                    MemoryManager *manager = XMLPlatformUtils::fgMemoryManager);
00502 
00510     TranscodeToStr(const XMLCh *in, XMLSize_t length, XMLTranscoder* trans,
00511                    MemoryManager *manager = XMLPlatformUtils::fgMemoryManager);
00512 
00513     ~TranscodeToStr();
00514 
00517 
00521     const XMLByte *str() const;
00522 
00527     XMLByte *adopt();
00528 
00533     XMLSize_t length () const;
00534 
00536 
00537 private:
00538     // -----------------------------------------------------------------------
00539     //  Unimplemented constructors and operators
00540     // -----------------------------------------------------------------------
00541     TranscodeToStr(const TranscodeToStr &);
00542     TranscodeToStr &operator=(const TranscodeToStr &);
00543 
00544     // -----------------------------------------------------------------------
00545     //  Private helper methods
00546     // -----------------------------------------------------------------------
00547     void transcode(const XMLCh *in, XMLSize_t len, XMLTranscoder* trans);
00548 
00549     // -----------------------------------------------------------------------
00550     //  Private data members
00551     //
00552     //  fString
00553     //      The transcoded string
00554     //
00555     //  fBytesWritten
00556     //      The length of the transcoded string in bytes
00557     // -----------------------------------------------------------------------
00558     XMLByte *fString;
00559     XMLSize_t fBytesWritten;
00560     MemoryManager *fMemoryManager;
00561 };
00562 
00563 //
00564 // This class can be used to transcode from a source encoding. It manages the
00565 // memory allocated for the transcode in an exception safe manner, automatically
00566 // deleting it when the class goes out of scope.
00567 //
00568 class XMLUTIL_EXPORT TranscodeFromStr
00569 {
00570 public:
00571     // -----------------------------------------------------------------------
00572     //  Public constructors and destructor
00573     // -----------------------------------------------------------------------
00574 
00582     TranscodeFromStr(const XMLByte *data, XMLSize_t length, const char *encoding,
00583                      MemoryManager *manager = XMLPlatformUtils::fgMemoryManager);
00584 
00592     TranscodeFromStr(const XMLByte *data, XMLSize_t length, XMLTranscoder *trans,
00593                      MemoryManager *manager = XMLPlatformUtils::fgMemoryManager);
00594 
00595     ~TranscodeFromStr();
00596 
00599 
00603     const XMLCh *str() const;
00604 
00609     XMLCh *adopt();
00610 
00615     XMLSize_t length() const;
00616 
00618 
00619 private:
00620     // -----------------------------------------------------------------------
00621     //  Unimplemented constructors and operators
00622     // -----------------------------------------------------------------------
00623     TranscodeFromStr(const TranscodeFromStr &);
00624     TranscodeFromStr &operator=(const TranscodeFromStr &);
00625 
00626     // -----------------------------------------------------------------------
00627     //  Private helper methods
00628     // -----------------------------------------------------------------------
00629     void transcode(const XMLByte *in, XMLSize_t length, XMLTranscoder *trans);
00630 
00631     // -----------------------------------------------------------------------
00632     //  Private data members
00633     //
00634     //  fString
00635     //      The transcoded string
00636     //
00637     //  fBytesWritten
00638     //      The length of the transcoded string in characters
00639     // -----------------------------------------------------------------------
00640     XMLCh *fString;
00641     XMLSize_t fCharsWritten;
00642     MemoryManager *fMemoryManager;
00643 };
00644 
00645 // ---------------------------------------------------------------------------
00646 //  XMLTranscoder: Getter methods
00647 // ---------------------------------------------------------------------------
00648 inline MemoryManager* XMLTranscoder::getMemoryManager() const
00649 {
00650     return fMemoryManager;
00651 }
00652 
00653 // ---------------------------------------------------------------------------
00654 //  XMLTranscoder: Protected helper methods
00655 // ---------------------------------------------------------------------------
00656 inline XMLSize_t XMLTranscoder::getBlockSize() const
00657 {
00658     return fBlockSize;
00659 }
00660 
00661 inline const XMLCh* XMLTranscoder::getEncodingName() const
00662 {
00663     return fEncodingName;
00664 }
00665 
00666 // ---------------------------------------------------------------------------
00667 //  TranscodeToStr: Getter methods
00668 // ---------------------------------------------------------------------------
00669 inline const XMLByte *TranscodeToStr::str() const
00670 {
00671     return fString;
00672 }
00673 
00674 inline XMLByte *TranscodeToStr::adopt()
00675 {
00676     XMLByte *tmp = fString;
00677     fString = 0;
00678     return tmp;
00679 }
00680 
00681 inline XMLSize_t TranscodeToStr::length () const
00682 {
00683     return fBytesWritten;
00684 }
00685 
00686 // ---------------------------------------------------------------------------
00687 //  TranscodeFromStr: Getter methods
00688 // ---------------------------------------------------------------------------
00689 inline const XMLCh *TranscodeFromStr::str() const
00690 {
00691     return fString;
00692 }
00693 
00694 inline XMLCh *TranscodeFromStr::adopt()
00695 {
00696     XMLCh *tmp = fString;
00697     fString = 0;
00698     return tmp;
00699 }
00700 
00701 inline XMLSize_t TranscodeFromStr::length() const
00702 {
00703     return fCharsWritten;
00704 }
00705 
00706 XERCES_CPP_NAMESPACE_END
00707 
00708 #endif

Generated on Wed Sep 24 16:36:33 2008 for Xerces-C++ by  doxygen 1.5.4