# 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