http://xml.apache.org/http://www.apache.org/http://www.w3.org/

Home

Readme
Release Info

Installation
Download
Build

FAQs
Samples
API Docs

DOM C++ Binding
Programming
Migration Guide

Feedback
Bug-Reporting
PDF Document

CVS Repository
Mail Archive

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.8  2003/05/15 19:07:45  knoaman
00060  * Partial implementation of the configurable memory manager.
00061  *
00062  * Revision 1.7  2003/03/07 18:11:55  tng
00063  * Return a reference instead of void for operator=
00064  *
00065  * Revision 1.6  2003/02/04 22:11:52  peiyongz
00066  * bug#16784: Obsolete documentation on XMLTranscoder -- reported by
00067  * Colin Paul Adams, Preston Lancashire
00068  *
00069  * Revision 1.5  2002/11/25 21:27:52  tng
00070  * Performance: use XMLRecognizer::Encodings enum to make new transcode, faster than comparing the encoding string every time.
00071  *
00072  * Revision 1.4  2002/11/04 15:22:04  tng
00073  * C++ Namespace Support.
00074  *
00075  * Revision 1.3  2002/07/18 20:05:31  knoaman
00076  * Add a new feature to control strict IANA encoding name.
00077  *
00078  * Revision 1.2  2002/04/09 15:44:00  knoaman
00079  * Add lower case string support.
00080  *
00081  * Revision 1.1.1.1  2002/02/01 22:22:13  peiyongz
00082  * sane_include
00083  *
00084  * Revision 1.14  2001/11/01 23:37:07  jasons
00085  * 2001-11-01  Jason E. Stewart  <jason@openinformatics.com>
00086  *
00087  *  * src/util/TransService.hpp (Repository):
00088  *  Updated Doxygen documentation for XMLTranscoder class
00089  *
00090  * Revision 1.13  2001/05/11 13:26:30  tng
00091  * Copyright update.
00092  *
00093  * Revision 1.12  2001/01/25 19:19:32  tng
00094  * Let user add their encoding to the intrinsic mapping table.  Added by Khaled Noaman.
00095  *
00096  * Revision 1.11  2000/04/12 22:57:45  roddey
00097  * A couple of fixes to comments and parameter names to make them
00098  * more correct.
00099  *
00100  * Revision 1.10  2000/03/28 19:43:19  roddey
00101  * Fixes for signed/unsigned warnings. New work for two way transcoding
00102  * stuff.
00103  *
00104  * Revision 1.9  2000/03/17 23:59:54  roddey
00105  * Initial updates for two way transcoding support
00106  *
00107  * Revision 1.8  2000/03/02 19:54:46  roddey
00108  * This checkin includes many changes done while waiting for the
00109  * 1.1.0 code to be finished. I can't list them all here, but a list is
00110  * available elsewhere.
00111  *
00112  * Revision 1.7  2000/02/24 20:05:25  abagchi
00113  * Swat for removing Log from API docs
00114  *
00115  * Revision 1.6  2000/02/06 07:48:04  rahulj
00116  * Year 2K copyright swat.
00117  *
00118  * Revision 1.5  2000/01/25 22:49:55  roddey
00119  * Moved the supportsSrcOfs() method from the individual transcoder to the
00120  * transcoding service, where it should have been to begin with.
00121  *
00122  * Revision 1.4  2000/01/25 19:19:07  roddey
00123  * Simple addition of a getId() method to the xcode and netacess abstractions to
00124  * allow each impl to give back an id string.
00125  *
00126  * Revision 1.3  1999/12/18 00:18:10  roddey
00127  * More changes to support the new, completely orthagonal support for
00128  * intrinsic encodings.
00129  *
00130  * Revision 1.2  1999/12/15 19:41:28  roddey
00131  * Support for the new transcoder system, where even intrinsic encodings are
00132  * done via the same transcoder abstraction as external ones.
00133  *
00134  * Revision 1.1.1.1  1999/11/09 01:05:16  twl
00135  * Initial checkin
00136  *
00137  * Revision 1.2  1999/11/08 20:45:16  rahul
00138  * Swat for adding in Product name and CVS comment log variable.
00139  *
00140  */
00141 
00142 #ifndef TRANSSERVICE_HPP
00143 #define TRANSSERVICE_HPP
00144 
00145 #include <xercesc/util/XMemory.hpp>
00146 #include <xercesc/util/PlatformUtils.hpp>
00147 #include <xercesc/framework/XMLRecognizer.hpp>
00148 
00149 XERCES_CPP_NAMESPACE_BEGIN
00150 
00151 // Forward references
00152 //class XMLPlatformUtils;
00153 class XMLLCPTranscoder;
00154 class XMLTranscoder;
00155 class ENameMap;
00156 
00157 
00158 //
00159 //  This class is an abstract base class which are used to abstract the
00160 //  transcoding services that Xerces uses. The parser's actual transcoding
00161 //  needs are small so it is desirable to allow different implementations
00162 //  to be provided.
00163 //
00164 //  The transcoding service has to provide a couple of required string
00165 //  and character operations, but its most important service is the creation
00166 //  of transcoder objects. There are two types of transcoders, which are
00167 //  discussed below in the XMLTranscoder class' description.
00168 //
00169 class  XMLTransService : public XMemory
00170 {
00171 public :
00172     // -----------------------------------------------------------------------
00173     //  Class specific types
00174     // -----------------------------------------------------------------------
00175     enum Codes
00176     {
00177         Ok
00178         , UnsupportedEncoding
00179         , InternalFailure
00180         , SupportFilesNotFound
00181     };
00182 
00183     struct TransRec
00184     {
00185         XMLCh       intCh;
00186         XMLByte     extCh;
00187     };
00188 
00189 
00190     // -----------------------------------------------------------------------
00191     //  Public constructors and destructor
00192     // -----------------------------------------------------------------------
00193     virtual ~XMLTransService();
00194 
00195 
00196     // -----------------------------------------------------------------------
00197     //  Non-virtual API
00198     // -----------------------------------------------------------------------
00199     XMLTranscoder* makeNewTranscoderFor
00200     (
00201         const   XMLCh* const            encodingName
00202         ,       XMLTransService::Codes& resValue
00203         , const unsigned int            blockSize
00204         , MemoryManager* const          manager
00205     );
00206 
00207     XMLTranscoder* makeNewTranscoderFor
00208     (
00209         const   char* const             encodingName
00210         ,       XMLTransService::Codes& resValue
00211         , const unsigned int            blockSize
00212         , MemoryManager* const          manager
00213     );
00214 
00215     XMLTranscoder* makeNewTranscoderFor
00216     (
00217         XMLRecognizer::Encodings        encodingEnum
00218         ,       XMLTransService::Codes& resValue
00219         , const unsigned int            blockSize
00220         , MemoryManager* const          manager
00221     );
00222 
00223 
00224     // -----------------------------------------------------------------------
00225     //  The virtual transcoding service API
00226     // -----------------------------------------------------------------------
00227     virtual int compareIString
00228     (
00229         const   XMLCh* const    comp1
00230         , const XMLCh* const    comp2
00231     ) = 0;
00232 
00233     virtual int compareNIString
00234     (
00235         const   XMLCh* const    comp1
00236         , const XMLCh* const    comp2
00237         , const unsigned int    maxChars
00238     ) = 0;
00239 
00240     virtual const XMLCh* getId() const = 0;
00241 
00242     virtual bool isSpace(const XMLCh toCheck) const = 0;
00243 
00244     virtual XMLLCPTranscoder* makeNewLCPTranscoder() = 0;
00245 
00246     virtual bool supportsSrcOfs() const = 0;
00247 
00248     virtual void upperCase(XMLCh* const toUpperCase) const = 0;
00249     virtual void lowerCase(XMLCh* const toLowerCase) const = 0;
00250 
00251     // -----------------------------------------------------------------------
00252     //  Allow users to add their own encodings to the intrinsinc mapping
00253     //  table
00254     //  Usage:
00255     //      XMLTransService::addEncoding (
00256     //          gMyEncodingNameString
00257     //          , new ENameMapFor<MyTransClassType>(gMyEncodingNameString)
00258     //      );
00259     // -----------------------------------------------------------------------
00260     static void addEncoding(const XMLCh* const encoding, ENameMap* const ownMapping);
00261 
00262 
00263 protected :
00264     // -----------------------------------------------------------------------
00265     //  Hidden constructors
00266     // -----------------------------------------------------------------------
00267     XMLTransService();
00268 
00269 
00270     // -----------------------------------------------------------------------
00271     //  Protected virtual methods.
00272     // -----------------------------------------------------------------------
00273     virtual XMLTranscoder* makeNewXMLTranscoder
00274     (
00275         const   XMLCh* const            encodingName
00276         ,       XMLTransService::Codes& resValue
00277         , const unsigned int            blockSize
00278         , MemoryManager* const          manager
00279     ) = 0;
00280 
00281 
00282 private :
00283     // -----------------------------------------------------------------------
00284     //  Unimplemented constructors and operators
00285     // -----------------------------------------------------------------------
00286     XMLTransService(const XMLTransService&);
00287     XMLTransService& operator=(const XMLTransService&);
00288 
00289     // -----------------------------------------------------------------------
00290     //  Hidden method to enable/disable strict IANA encoding check
00291     //  Caller: XMLPlatformUtils
00292     // -----------------------------------------------------------------------
00293     void strictIANAEncoding(const bool newState);
00294     bool isStrictIANAEncoding();
00295 
00296     // -----------------------------------------------------------------------
00297     //  Hidden init method for platform utils to call
00298     // -----------------------------------------------------------------------
00299     friend class XMLPlatformUtils;
00300     void initTransService();
00301 };
00302 
00303 
00304 
00321 class  XMLTranscoder : public XMemory
00322 {
00323 public :
00324 
00332     enum UnRepOpts
00333     {
00334         UnRep_Throw     
00335         , UnRep_RepChar     
00336     };
00337 
00338 
00341 
00346     virtual ~XMLTranscoder();
00348 
00349 
00350 
00353 
00373     virtual unsigned int transcodeFrom
00374     (
00375         const   XMLByte* const          srcData
00376         , const unsigned int            srcCount
00377         ,       XMLCh* const            toFill
00378         , const unsigned int            maxChars
00379         ,       unsigned int&           bytesEaten
00380         ,       unsigned char* const    charSizes
00381     ) = 0;
00382 
00396     virtual unsigned int transcodeTo
00397     (
00398         const   XMLCh* const    srcData
00399         , const unsigned int    srcCount
00400         ,       XMLByte* const  toFill
00401         , const unsigned int    maxBytes
00402         ,       unsigned int&   charsEaten
00403         , const UnRepOpts       options
00404     ) = 0;
00405 
00411     virtual bool canTranscodeTo
00412     (
00413         const   unsigned int    toCheck
00414     )   const = 0;
00415 
00417 
00420 
00425     unsigned int getBlockSize() const;
00426 
00432     const XMLCh* getEncodingName() const;
00434 
00437 
00445     MemoryManager* getMemoryManager() const;
00446 
00448 
00449 protected :
00450     // -----------------------------------------------------------------------
00451     //  Hidden constructors
00452     // -----------------------------------------------------------------------
00453     XMLTranscoder
00454     (
00455         const   XMLCh* const    encodingName
00456         , const unsigned int    blockSize
00457         , MemoryManager* const  manager = XMLPlatformUtils::fgMemoryManager
00458     );
00459 
00460 
00461     // -----------------------------------------------------------------------
00462     //  Protected helper methods
00463     // -----------------------------------------------------------------------
00464     void checkBlockSize(const unsigned int toCheck);
00465 
00466 
00467 private :
00468     // -----------------------------------------------------------------------
00469     //  Unimplemented constructors and operators
00470     // -----------------------------------------------------------------------
00471     XMLTranscoder(const XMLTranscoder&);
00472     XMLTranscoder& operator=(const XMLTranscoder&);
00473 
00474 
00475     // -----------------------------------------------------------------------
00476     //  Private data members
00477     //
00478     //  fBlockSize
00479     //      This is the block size indicated in the constructor.
00480     //
00481     //  fEncodingName
00482     //      This is the name of the encoding this encoder is for. All basic
00483     //      XML transcoder's are for named encodings.
00484     // -----------------------------------------------------------------------
00485     unsigned int    fBlockSize;
00486     XMLCh*          fEncodingName;
00487     MemoryManager*  fMemoryManager;
00488 };
00489 
00490 
00491 //
00492 //  This class is a specialized transcoder that only transcodes between
00493 //  the internal XMLCh format and the local code page. It is specialized
00494 //  for the very common job of translating data from the client app's
00495 //  native code page to the internal format and vice versa.
00496 //
00497 class  XMLLCPTranscoder : public XMemory
00498 {
00499 public :
00500     // -----------------------------------------------------------------------
00501     //  Public constructors and destructor
00502     // -----------------------------------------------------------------------
00503     virtual ~XMLLCPTranscoder();
00504 
00505 
00506     // -----------------------------------------------------------------------
00507     //  The virtual transcoder API
00508     //
00509     //  NOTE:   All these APIs don't include null terminator characters in
00510     //          their parameters. So calcRequiredSize() returns the number
00511     //          of actual chars, not including the null. maxBytes and maxChars
00512     //          parameters refer to actual chars, not including the null so
00513     //          its assumed that the buffer is physically one char or byte
00514     //          larger.
00515     // -----------------------------------------------------------------------
00516     virtual unsigned int calcRequiredSize(const char* const srcText) = 0;
00517 
00518     virtual unsigned int calcRequiredSize(const XMLCh* const srcText) = 0;
00519 
00520     virtual char* transcode(const XMLCh* const toTranscode) = 0;
00521     virtual char* transcode(const XMLCh* const toTranscode,
00522                             MemoryManager* const manager) = 0;
00523 
00524     virtual XMLCh* transcode(const char* const toTranscode) = 0;
00525     virtual XMLCh* transcode(const char* const toTranscode,
00526                              MemoryManager* const manager) = 0;
00527 
00528     virtual bool transcode
00529     (
00530         const   char* const     toTranscode
00531         ,       XMLCh* const    toFill
00532         , const unsigned int    maxChars
00533     ) = 0;
00534 
00535     virtual bool transcode
00536     (
00537         const   XMLCh* const    toTranscode
00538         ,       char* const     toFill
00539         , const unsigned int    maxBytes
00540     ) = 0;
00541 
00542 
00543 protected :
00544     // -----------------------------------------------------------------------
00545     //  Hidden constructors
00546     // -----------------------------------------------------------------------
00547     XMLLCPTranscoder();
00548 
00549 
00550 private :
00551     // -----------------------------------------------------------------------
00552     //  Unimplemented constructors and operators
00553     // -----------------------------------------------------------------------
00554     XMLLCPTranscoder(const XMLLCPTranscoder&);
00555     XMLLCPTranscoder& operator=(const XMLLCPTranscoder&);
00556 };
00557 
00558 
00559 // ---------------------------------------------------------------------------
00560 //  XMLTranscoder: Getter methods
00561 // ---------------------------------------------------------------------------
00562 inline MemoryManager* XMLTranscoder::getMemoryManager() const
00563 {
00564     return fMemoryManager;
00565 }
00566 
00567 // ---------------------------------------------------------------------------
00568 //  XMLTranscoder: Protected helper methods
00569 // ---------------------------------------------------------------------------
00570 inline unsigned int XMLTranscoder::getBlockSize() const
00571 {
00572     return fBlockSize;
00573 }
00574 
00575 inline const XMLCh* XMLTranscoder::getEncodingName() const
00576 {
00577     return fEncodingName;
00578 }
00579 
00580 XERCES_CPP_NAMESPACE_END
00581 
00582 #endif


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