| API Docs for SAX and DOM |

Main Page Class Hierarchy Alphabetical List Compound List File List Compound Members File Members

# TransService.hpp

Go to the documentation of this file.

    00001 /*
    00002  * The Apache Software License, Version 1.1
    00003  *
    00004  * Copyright (c) 1999-2001 The Apache Software Foundation.  All rights
    00005  * reserved.
    00006  *
    00007  * Redistribution and use in source and binary forms, with or without
    00008  * modification, are permitted provided that the following conditions
    00009  * are met:
    00010  *
    00011  * 1. Redistributions of source code must retain the above copyright
    00012  *    notice, this list of conditions and the following disclaimer.
    00013  *
    00014  * 2. Redistributions in binary form must reproduce the above copyright
    00015  *    notice, this list of conditions and the following disclaimer in
    00016  *    the documentation and/or other materials provided with the
    00017  *    distribution.
    00018  *
    00019  * 3. The end-user documentation included with the redistribution,
    00020  *    if any, must include the following acknowledgment:
    00021  *       "This product includes software developed by the
    00022  *        Apache Software Foundation (http://www.apache.org/)."
    00023  *    Alternately, this acknowledgment may appear in the software itself,
    00024  *    if and wherever such third-party acknowledgments normally appear.
    00025  *
    00026  * 4. The names "Xerces" and "Apache Software Foundation" must
    00027  *    not be used to endorse or promote products derived from this
    00028  *    software without prior written permission. For written
    00029  *    permission, please contact apache\@apache.org.
    00030  *
    00031  * 5. Products derived from this software may not be called "Apache",
    00032  *    nor may "Apache" appear in their name, without prior written
    00033  *    permission of the Apache Software Foundation.
    00034  *
    00035  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
    00036  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
    00037  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
    00038  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
    00039  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
    00040  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
    00041  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
    00042  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
    00043  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
    00044  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
    00045  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
    00046  * SUCH DAMAGE.
    00047  * ====================================================================
    00048  *
    00049  * This software consists of voluntary contributions made by many
    00050  * individuals on behalf of the Apache Software Foundation, and was
    00051  * originally based on software copyright (c) 1999, International
    00052  * Business Machines, Inc., http://www.ibm.com .  For more information
    00053  * on the Apache Software Foundation, please see
    00054  * <http://www.apache.org/>.
    00055  */
    00056
    00057 /*
    00058  * $Log: TransService.hpp,v $
    00059  * Revision 1.10  2003/11/24 19:52:06  neilg
    00060  * allow classes derived from XMLTransService to tailor the intrinsic maps to their taste.
    00061  *
    00062  * Revision 1.9  2003/06/03 18:12:29  knoaman
    00063  * Add default value for memory manager argument.
    00064  *
    00065  * Revision 1.8  2003/05/15 19:07:45  knoaman
    00066  * Partial implementation of the configurable memory manager.
    00067  *
    00068  * Revision 1.7  2003/03/07 18:11:55  tng
    00069  * Return a reference instead of void for operator=
    00070  *
    00071  * Revision 1.6  2003/02/04 22:11:52  peiyongz
    00072  * bug#16784: Obsolete documentation on XMLTranscoder -- reported by
    00073  * Colin Paul Adams, Preston Lancashire
    00074  *
    00075  * Revision 1.5  2002/11/25 21:27:52  tng
    00076  * Performance: use XMLRecognizer::Encodings enum to make new transcode, faster than comparing the encoding string every time.
    00077  *
    00078  * Revision 1.4  2002/11/04 15:22:04  tng
    00079  * C++ Namespace Support.
    00080  *
    00081  * Revision 1.3  2002/07/18 20:05:31  knoaman
    00082  * Add a new feature to control strict IANA encoding name.
    00083  *
    00084  * Revision 1.2  2002/04/09 15:44:00  knoaman
    00085  * Add lower case string support.
    00086  *
    00087  * Revision 1.1.1.1  2002/02/01 22:22:13  peiyongz
    00088  * sane_include
    00089  *
    00090  * Revision 1.14  2001/11/01 23:37:07  jasons
    00091  * 2001-11-01  Jason E. Stewart  <jason@openinformatics.com>
    00092  *
    00093  *  * src/util/TransService.hpp (Repository):
    00094  *  Updated Doxygen documentation for XMLTranscoder class
    00095  *
    00096  * Revision 1.13  2001/05/11 13:26:30  tng
    00097  * Copyright update.
    00098  *
    00099  * Revision 1.12  2001/01/25 19:19:32  tng
    00100  * Let user add their encoding to the intrinsic mapping table.  Added by Khaled Noaman.
    00101  *
    00102  * Revision 1.11  2000/04/12 22:57:45  roddey
    00103  * A couple of fixes to comments and parameter names to make them
    00104  * more correct.
    00105  *
    00106  * Revision 1.10  2000/03/28 19:43:19  roddey
    00107  * Fixes for signed/unsigned warnings. New work for two way transcoding
    00108  * stuff.
    00109  *
    00110  * Revision 1.9  2000/03/17 23:59:54  roddey
    00111  * Initial updates for two way transcoding support
    00112  *
    00113  * Revision 1.8  2000/03/02 19:54:46  roddey
    00114  * This checkin includes many changes done while waiting for the
    00115  * 1.1.0 code to be finished. I can't list them all here, but a list is
    00116  * available elsewhere.
    00117  *
    00118  * Revision 1.7  2000/02/24 20:05:25  abagchi
    00119  * Swat for removing Log from API docs
    00120  *
    00121  * Revision 1.6  2000/02/06 07:48:04  rahulj
    00122  * Year 2K copyright swat.
    00123  *
    00124  * Revision 1.5  2000/01/25 22:49:55  roddey
    00125  * Moved the supportsSrcOfs() method from the individual transcoder to the
    00126  * transcoding service, where it should have been to begin with.
    00127  *
    00128  * Revision 1.4  2000/01/25 19:19:07  roddey
    00129  * Simple addition of a getId() method to the xcode and netacess abstractions to
    00130  * allow each impl to give back an id string.
    00131  *
    00132  * Revision 1.3  1999/12/18 00:18:10  roddey
    00133  * More changes to support the new, completely orthagonal support for
    00134  * intrinsic encodings.
    00135  *
    00136  * Revision 1.2  1999/12/15 19:41:28  roddey
    00137  * Support for the new transcoder system, where even intrinsic encodings are
    00138  * done via the same transcoder abstraction as external ones.
    00139  *
    00140  * Revision 1.1.1.1  1999/11/09 01:05:16  twl
    00141  * Initial checkin
    00142  *
    00143  * Revision 1.2  1999/11/08 20:45:16  rahul
    00144  * Swat for adding in Product name and CVS comment log variable.
    00145  *
    00146  */
    00147
    00148 #ifndef TRANSSERVICE_HPP
    00149 #define TRANSSERVICE_HPP
    00150
    00151 #include <xercesc/util/XMemory.hpp>
    00152 #include <xercesc/util/PlatformUtils.hpp>
    00153 #include <xercesc/framework/XMLRecognizer.hpp>
    00154 #include <xercesc/util/RefHashTableOf.hpp>
    00155 #include <xercesc/util/RefVectorOf.hpp>
    00156
    00157 XERCES_CPP_NAMESPACE_BEGIN
    00158
    00159 // Forward references
    00160 //class XMLPlatformUtils;
    00161 class XMLLCPTranscoder;
    00162 class XMLTranscoder;
    00163 class ENameMap;
    00164
    00165
    00166 //
    00167 //  This class is an abstract base class which are used to abstract the
    00168 //  transcoding services that Xerces uses. The parser's actual transcoding
    00169 //  needs are small so it is desirable to allow different implementations
    00170 //  to be provided.
    00171 //
    00172 //  The transcoding service has to provide a couple of required string
    00173 //  and character operations, but its most important service is the creation
    00174 //  of transcoder objects. There are two types of transcoders, which are
    00175 //  discussed below in the XMLTranscoder class' description.
    00176 //
    00177 class  XMLTransService : public XMemory
    00178 {
    00179 public :
    00180     // -----------------------------------------------------------------------
    00181     //  Class specific types
    00182     // -----------------------------------------------------------------------
    00183     enum Codes
    00184     {
    00185         Ok
    00186         , UnsupportedEncoding
    00187         , InternalFailure
    00188         , SupportFilesNotFound
    00189     };
    00190
    00191     struct TransRec
    00192     {
    00193         XMLCh       intCh;
    00194         XMLByte     extCh;
    00195     };
    00196
    00197
    00198     // -----------------------------------------------------------------------
    00199     //  Public constructors and destructor
    00200     // -----------------------------------------------------------------------
    00201     virtual ~XMLTransService();
    00202
    00203
    00204     // -----------------------------------------------------------------------
    00205     //  Non-virtual API
    00206     // -----------------------------------------------------------------------
    00207     XMLTranscoder* makeNewTranscoderFor
    00208     (
    00209         const   XMLCh* const            encodingName
    00210         ,       XMLTransService::Codes& resValue
    00211         , const unsigned int            blockSize
    00212         , MemoryManager* const          manager = XMLPlatformUtils::fgMemoryManager
    00213     );
    00214
    00215     XMLTranscoder* makeNewTranscoderFor
    00216     (
    00217         const   char* const             encodingName
    00218         ,       XMLTransService::Codes& resValue
    00219         , const unsigned int            blockSize
    00220         , MemoryManager* const          manager = XMLPlatformUtils::fgMemoryManager
    00221     );
    00222
    00223     XMLTranscoder* makeNewTranscoderFor
    00224     (
    00225         XMLRecognizer::Encodings        encodingEnum
    00226         ,       XMLTransService::Codes& resValue
    00227         , const unsigned int            blockSize
    00228         , MemoryManager* const          manager = XMLPlatformUtils::fgMemoryManager
    00229     );
    00230
    00231
    00232     // -----------------------------------------------------------------------
    00233     //  The virtual transcoding service API
    00234     // -----------------------------------------------------------------------
    00235     virtual int compareIString
    00236     (
    00237         const   XMLCh* const    comp1
    00238         , const XMLCh* const    comp2
    00239     ) = 0;
    00240
    00241     virtual int compareNIString
    00242     (
    00243         const   XMLCh* const    comp1
    00244         , const XMLCh* const    comp2
    00245         , const unsigned int    maxChars
    00246     ) = 0;
    00247
    00248     virtual const XMLCh* getId() const = 0;
    00249
    00250     virtual bool isSpace(const XMLCh toCheck) const = 0;
    00251
    00252     virtual XMLLCPTranscoder* makeNewLCPTranscoder() = 0;
    00253
    00254     virtual bool supportsSrcOfs() const = 0;
    00255
    00256     virtual void upperCase(XMLCh* const toUpperCase) const = 0;
    00257     virtual void lowerCase(XMLCh* const toLowerCase) const = 0;
    00258
    00259     // -----------------------------------------------------------------------
    00260     //  Allow users to add their own encodings to the intrinsinc mapping
    00261     //  table
    00262     //  Usage:
    00263     //      XMLTransService::addEncoding (
    00264     //          gMyEncodingNameString
    00265     //          , new ENameMapFor<MyTransClassType>(gMyEncodingNameString)
    00266     //      );
    00267     // -----------------------------------------------------------------------
    00268     static void addEncoding(const XMLCh* const encoding, ENameMap* const ownMapping);
    00269
    00270
    00271 protected :
    00272     // -----------------------------------------------------------------------
    00273     //  Hidden constructors
    00274     // -----------------------------------------------------------------------
    00275     XMLTransService();
    00276
    00277
    00278     // -----------------------------------------------------------------------
    00279     //  Protected virtual methods.
    00280     // -----------------------------------------------------------------------
    00281     virtual XMLTranscoder* makeNewXMLTranscoder
    00282     (
    00283         const   XMLCh* const            encodingName
    00284         ,       XMLTransService::Codes& resValue
    00285         , const unsigned int            blockSize
    00286         , MemoryManager* const          manager
    00287     ) = 0;
    00288
    00289     // -----------------------------------------------------------------------
    00290     //  Protected init method for platform utils to call
    00291     // -----------------------------------------------------------------------
    00292     friend class XMLPlatformUtils;
    00293     virtual void initTransService();
    00294
    00295     // -----------------------------------------------------------------------
    00296     // protected static members
    00297     //  gMappings
    00298     //      This is a hash table of ENameMap objects. It is created and filled
    00299     //      in when the platform init calls our initTransService() method.
    00300     //
    00301     //  gMappingsRecognizer
    00302     //      This is an array of ENameMap objects, predefined for those
    00303     //      already recognized by XMLRecognizer::Encodings.
    00304     //
    00305
    00306     static RefHashTableOf<ENameMap>*    gMappings;
    00307     static RefVectorOf<ENameMap>*       gMappingsRecognizer;
    00308
    00309 private :
    00310     // -----------------------------------------------------------------------
    00311     //  Unimplemented constructors and operators
    00312     // -----------------------------------------------------------------------
    00313     XMLTransService(const XMLTransService&);
    00314     XMLTransService& operator=(const XMLTransService&);
    00315
    00316     // -----------------------------------------------------------------------
    00317     //  Hidden method to enable/disable strict IANA encoding check
    00318     //  Caller: XMLPlatformUtils
    00319     // -----------------------------------------------------------------------
    00320     void strictIANAEncoding(const bool newState);
    00321     bool isStrictIANAEncoding();
    00322     static void reinitMappings();
    00323     static void reinitMappingsRecognizer();
    00324
    00325 };
    00326
    00327
    00328
    00345 class  XMLTranscoder : public XMemory
    00346 {
    00347 public :
    00348
    00356     enum UnRepOpts
    00357     {
    00358         UnRep_Throw
    00359         , UnRep_RepChar
    00360     };
    00361
    00362
    00365
    00370     virtual ~XMLTranscoder();
    00372
    00373
    00374
    00377
    00397     virtual unsigned int transcodeFrom
    00398     (
    00399         const   XMLByte* const          srcData
    00400         , const unsigned int            srcCount
    00401         ,       XMLCh* const            toFill
    00402         , const unsigned int            maxChars
    00403         ,       unsigned int&           bytesEaten
    00404         ,       unsigned char* const    charSizes
    00405     ) = 0;
    00406
    00420     virtual unsigned int transcodeTo
    00421     (
    00422         const   XMLCh* const    srcData
    00423         , const unsigned int    srcCount
    00424         ,       XMLByte* const  toFill
    00425         , const unsigned int    maxBytes
    00426         ,       unsigned int&   charsEaten
    00427         , const UnRepOpts       options
    00428     ) = 0;
    00429
    00435     virtual bool canTranscodeTo
    00436     (
    00437         const   unsigned int    toCheck
    00438     )   const = 0;
    00439
    00441
    00444
    00449     unsigned int getBlockSize() const;
    00450
    00456     const XMLCh* getEncodingName() const;
    00458
    00461
    00469     MemoryManager* getMemoryManager() const;
    00470
    00472
    00473 protected :
    00474     // -----------------------------------------------------------------------
    00475     //  Hidden constructors
    00476     // -----------------------------------------------------------------------
    00477     XMLTranscoder
    00478     (
    00479         const   XMLCh* const    encodingName
    00480         , const unsigned int    blockSize
    00481         , MemoryManager* const  manager = XMLPlatformUtils::fgMemoryManager
    00482     );
    00483
    00484
    00485     // -----------------------------------------------------------------------
    00486     //  Protected helper methods
    00487     // -----------------------------------------------------------------------
    00488     void checkBlockSize(const unsigned int toCheck);
    00489
    00490
    00491 private :
    00492     // -----------------------------------------------------------------------
    00493     //  Unimplemented constructors and operators
    00494     // -----------------------------------------------------------------------
    00495     XMLTranscoder(const XMLTranscoder&);
    00496     XMLTranscoder& operator=(const XMLTranscoder&);
    00497
    00498     // -----------------------------------------------------------------------
    00499     //  Private data members
    00500     //
    00501     //  fBlockSize
    00502     //      This is the block size indicated in the constructor.
    00503     //
    00504     //  fEncodingName
    00505     //      This is the name of the encoding this encoder is for. All basic
    00506     //      XML transcoder's are for named encodings.
    00507     // -----------------------------------------------------------------------
    00508     unsigned int    fBlockSize;
    00509     XMLCh*          fEncodingName;
    00510     MemoryManager*  fMemoryManager;
    00511 };
    00512
    00513
    00514 //
    00515 //  This class is a specialized transcoder that only transcodes between
    00516 //  the internal XMLCh format and the local code page. It is specialized
    00517 //  for the very common job of translating data from the client app's
    00518 //  native code page to the internal format and vice versa.
    00519 //
    00520 class  XMLLCPTranscoder : public XMemory
    00521 {
    00522 public :
    00523     // -----------------------------------------------------------------------
    00524     //  Public constructors and destructor
    00525     // -----------------------------------------------------------------------
    00526     virtual ~XMLLCPTranscoder();
    00527
    00528
    00529     // -----------------------------------------------------------------------
    00530     //  The virtual transcoder API
    00531     //
    00532     //  NOTE:   All these APIs don't include null terminator characters in
    00533     //          their parameters. So calcRequiredSize() returns the number
    00534     //          of actual chars, not including the null. maxBytes and maxChars
    00535     //          parameters refer to actual chars, not including the null so
    00536     //          its assumed that the buffer is physically one char or byte
    00537     //          larger.
    00538     // -----------------------------------------------------------------------
    00539     virtual unsigned int calcRequiredSize(const char* const srcText) = 0;
    00540
    00541     virtual unsigned int calcRequiredSize(const XMLCh* const srcText) = 0;
    00542
    00543     virtual char* transcode(const XMLCh* const toTranscode) = 0;
    00544     virtual char* transcode(const XMLCh* const toTranscode,
    00545                             MemoryManager* const manager) = 0;
    00546
    00547     virtual XMLCh* transcode(const char* const toTranscode) = 0;
    00548     virtual XMLCh* transcode(const char* const toTranscode,
    00549                              MemoryManager* const manager) = 0;
    00550
    00551     virtual bool transcode
    00552     (
    00553         const   char* const     toTranscode
    00554         ,       XMLCh* const    toFill
    00555         , const unsigned int    maxChars
    00556     ) = 0;
    00557
    00558     virtual bool transcode
    00559     (
    00560         const   XMLCh* const    toTranscode
    00561         ,       char* const     toFill
    00562         , const unsigned int    maxBytes
    00563     ) = 0;
    00564
    00565
    00566 protected :
    00567     // -----------------------------------------------------------------------
    00568     //  Hidden constructors
    00569     // -----------------------------------------------------------------------
    00570     XMLLCPTranscoder();
    00571
    00572
    00573 private :
    00574     // -----------------------------------------------------------------------
    00575     //  Unimplemented constructors and operators
    00576     // -----------------------------------------------------------------------
    00577     XMLLCPTranscoder(const XMLLCPTranscoder&);
    00578     XMLLCPTranscoder& operator=(const XMLLCPTranscoder&);
    00579 };
    00580
    00581
    00582 // ---------------------------------------------------------------------------
    00583 //  XMLTranscoder: Getter methods
    00584 // ---------------------------------------------------------------------------
    00585 inline MemoryManager* XMLTranscoder::getMemoryManager() const
    00586 {
    00587     return fMemoryManager;
    00588 }
    00589
    00590 // ---------------------------------------------------------------------------
    00591 //  XMLTranscoder: Protected helper methods
    00592 // ---------------------------------------------------------------------------
    00593 inline unsigned int XMLTranscoder::getBlockSize() const
    00594 {
    00595     return fBlockSize;
    00596 }
    00597
    00598 inline const XMLCh* XMLTranscoder::getEncodingName() const
    00599 {
    00600     return fEncodingName;
    00601 }
    00602
    00603 XERCES_CPP_NAMESPACE_END
    00604
    00605 #endif

Copyright © 2003 The Apache Software Foundation. All Rights Reserved.