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.3  2002/07/18 20:05:31  knoaman
00060  * Add a new feature to control strict IANA encoding name.
00061  *
00062  * Revision 1.2  2002/04/09 15:44:00  knoaman
00063  * Add lower case string support.
00064  *
00065  * Revision 1.1.1.1  2002/02/01 22:22:13  peiyongz
00066  * sane_include
00067  *
00068  * Revision 1.14  2001/11/01 23:37:07  jasons
00069  * 2001-11-01  Jason E. Stewart  <jason@openinformatics.com>
00070  *
00071  *  * src/util/TransService.hpp (Repository):
00072  *  Updated Doxygen documentation for XMLTranscoder class
00073  *
00074  * Revision 1.13  2001/05/11 13:26:30  tng
00075  * Copyright update.
00076  *
00077  * Revision 1.12  2001/01/25 19:19:32  tng
00078  * Let user add their encoding to the intrinsic mapping table.  Added by Khaled Noaman.
00079  *
00080  * Revision 1.11  2000/04/12 22:57:45  roddey
00081  * A couple of fixes to comments and parameter names to make them
00082  * more correct.
00083  *
00084  * Revision 1.10  2000/03/28 19:43:19  roddey
00085  * Fixes for signed/unsigned warnings. New work for two way transcoding
00086  * stuff.
00087  *
00088  * Revision 1.9  2000/03/17 23:59:54  roddey
00089  * Initial updates for two way transcoding support
00090  *
00091  * Revision 1.8  2000/03/02 19:54:46  roddey
00092  * This checkin includes many changes done while waiting for the
00093  * 1.1.0 code to be finished. I can't list them all here, but a list is
00094  * available elsewhere.
00095  *
00096  * Revision 1.7  2000/02/24 20:05:25  abagchi
00097  * Swat for removing Log from API docs
00098  *
00099  * Revision 1.6  2000/02/06 07:48:04  rahulj
00100  * Year 2K copyright swat.
00101  *
00102  * Revision 1.5  2000/01/25 22:49:55  roddey
00103  * Moved the supportsSrcOfs() method from the individual transcoder to the
00104  * transcoding service, where it should have been to begin with.
00105  *
00106  * Revision 1.4  2000/01/25 19:19:07  roddey
00107  * Simple addition of a getId() method to the xcode and netacess abstractions to
00108  * allow each impl to give back an id string.
00109  *
00110  * Revision 1.3  1999/12/18 00:18:10  roddey
00111  * More changes to support the new, completely orthagonal support for
00112  * intrinsic encodings.
00113  *
00114  * Revision 1.2  1999/12/15 19:41:28  roddey
00115  * Support for the new transcoder system, where even intrinsic encodings are
00116  * done via the same transcoder abstraction as external ones.
00117  *
00118  * Revision 1.1.1.1  1999/11/09 01:05:16  twl
00119  * Initial checkin
00120  *
00121  * Revision 1.2  1999/11/08 20:45:16  rahul
00122  * Swat for adding in Product name and CVS comment log variable.
00123  *
00124  */
00125 
00126 #ifndef TRANSSERVICE_HPP
00127 #define TRANSSERVICE_HPP
00128 
00129 #include <xercesc/util/XercesDefs.hpp>
00130 
00131 
00132 // Forward references
00133 class XMLPlatformUtils;
00134 class XMLLCPTranscoder;
00135 class XMLTranscoder;
00136 class ENameMap;
00137 
00138 
00139 //
00140 //  This class is an abstract base class which are used to abstract the
00141 //  transcoding services that Xerces uses. The parser's actual transcoding
00142 //  needs are small so it is desirable to allow different implementations
00143 //  to be provided.
00144 //
00145 //  The transcoding service has to provide a couple of required string
00146 //  and character operations, but its most important service is the creation
00147 //  of transcoder objects. There are two types of transcoders, which are
00148 //  discussed below in the XMLTranscoder class' description.
00149 //
00150 class  XMLTransService
00151 {
00152 public :
00153     // -----------------------------------------------------------------------
00154     //  Class specific types
00155     // -----------------------------------------------------------------------
00156     enum Codes
00157     {
00158         Ok
00159         , UnsupportedEncoding
00160         , InternalFailure
00161         , SupportFilesNotFound
00162     };
00163 
00164     struct TransRec
00165     {
00166         XMLCh       intCh;
00167         XMLByte     extCh;
00168     };
00169 
00170 
00171     // -----------------------------------------------------------------------
00172     //  Public constructors and destructor
00173     // -----------------------------------------------------------------------
00174     virtual ~XMLTransService();
00175 
00176 
00177     // -----------------------------------------------------------------------
00178     //  Non-virtual API
00179     // -----------------------------------------------------------------------
00180     XMLTranscoder* makeNewTranscoderFor
00181     (
00182         const   XMLCh* const            encodingName
00183         ,       XMLTransService::Codes& resValue
00184         , const unsigned int            blockSize
00185     );
00186 
00187     XMLTranscoder* makeNewTranscoderFor
00188     (
00189         const   char* const             encodingName
00190         ,       XMLTransService::Codes& resValue
00191         , const unsigned int            blockSize
00192     );
00193 
00194 
00195     // -----------------------------------------------------------------------
00196     //  The virtual transcoding service API
00197     // -----------------------------------------------------------------------
00198     virtual int compareIString
00199     (
00200         const   XMLCh* const    comp1
00201         , const XMLCh* const    comp2
00202     ) = 0;
00203 
00204     virtual int compareNIString
00205     (
00206         const   XMLCh* const    comp1
00207         , const XMLCh* const    comp2
00208         , const unsigned int    maxChars
00209     ) = 0;
00210 
00211     virtual const XMLCh* getId() const = 0;
00212 
00213     virtual bool isSpace(const XMLCh toCheck) const = 0;
00214 
00215     virtual XMLLCPTranscoder* makeNewLCPTranscoder() = 0;
00216 
00217     virtual bool supportsSrcOfs() const = 0;
00218 
00219     virtual void upperCase(XMLCh* const toUpperCase) const = 0;
00220     virtual void lowerCase(XMLCh* const toLowerCase) const = 0;
00221 
00222     // -----------------------------------------------------------------------
00223     //  Allow users to add their own encodings to the intrinsinc mapping
00224     //  table
00225     //  Usage:
00226     //      XMLTransService::addEncoding (
00227     //          gMyEncodingNameString
00228     //          , new ENameMapFor<MyTransClassType>(gMyEncodingNameString)
00229     //      );
00230     // -----------------------------------------------------------------------
00231     static void addEncoding(const XMLCh* const encoding, ENameMap* const ownMapping);
00232 
00233 
00234 protected :
00235     // -----------------------------------------------------------------------
00236     //  Hidden constructors
00237     // -----------------------------------------------------------------------
00238     XMLTransService();
00239 
00240 
00241     // -----------------------------------------------------------------------
00242     //  Protected virtual methods.
00243     // -----------------------------------------------------------------------
00244     virtual XMLTranscoder* makeNewXMLTranscoder
00245     (
00246         const   XMLCh* const            encodingName
00247         ,       XMLTransService::Codes& resValue
00248         , const unsigned int            blockSize
00249     ) = 0;
00250 
00251 
00252 private :
00253     // -----------------------------------------------------------------------
00254     //  Unimplemented constructors and operators
00255     // -----------------------------------------------------------------------
00256     XMLTransService(const XMLTransService&);
00257     void operator=(const XMLTransService&);
00258 
00259     // -----------------------------------------------------------------------
00260     //  Hidden method to enable/disable strict IANA encoding check
00261     //  Caller: XMLPlatformUtils
00262     // -----------------------------------------------------------------------
00263     void strictIANAEncoding(const bool newState);
00264     bool isStrictIANAEncoding();
00265 
00266     // -----------------------------------------------------------------------
00267     //  Hidden init method for platform utils to call
00268     // -----------------------------------------------------------------------
00269     friend class XMLPlatformUtils;
00270     void initTransService();
00271 };
00272 
00273 
00274 
00282 
00291 class  XMLTranscoder
00292 {
00293 public :
00294 
00302     enum UnRepOpts
00303     {
00304         UnRep_Throw     
00305         , UnRep_RepChar     
00306     };
00307 
00308 
00311 
00316     virtual ~XMLTranscoder();
00318 
00319 
00320 
00323 
00341 
00342 
00343     virtual unsigned int transcodeFrom
00344     (
00345         const   XMLByte* const          srcData
00346         , const unsigned int            srcCount
00347         ,       XMLCh* const            toFill
00348         , const unsigned int            maxChars
00349         ,       unsigned int&           bytesEaten
00350         ,       unsigned char* const    charSizes
00351     ) = 0;
00352 
00365 
00366     virtual unsigned int transcodeTo
00367     (
00368         const   XMLCh* const    srcData
00369         , const unsigned int    srcCount
00370         ,       XMLByte* const  toFill
00371         , const unsigned int    maxBytes
00372         ,       unsigned int&   charsEaten
00373         , const UnRepOpts       options
00374     ) = 0;
00375 
00380 
00381     virtual bool canTranscodeTo
00382     (
00383         const   unsigned int    toCheck
00384     )   const = 0;
00385 
00387 
00390 
00399     unsigned int getBlockSize() const;
00400 
00406     const XMLCh* getEncodingName() const;
00408 
00409 protected :
00410     // -----------------------------------------------------------------------
00411     //  Hidden constructors
00412     // -----------------------------------------------------------------------
00413     XMLTranscoder
00414     (
00415         const   XMLCh* const    encodingName
00416         , const unsigned int    blockSize
00417     );
00418 
00419 
00420     // -----------------------------------------------------------------------
00421     //  Protected helper methods
00422     // -----------------------------------------------------------------------
00423     void checkBlockSize(const unsigned int toCheck);
00424 
00425 
00426 private :
00427     // -----------------------------------------------------------------------
00428     //  Unimplemented constructors and operators
00429     // -----------------------------------------------------------------------
00430     XMLTranscoder(const XMLTranscoder&);
00431     void operator=(const XMLTranscoder&);
00432 
00433 
00434     // -----------------------------------------------------------------------
00435     //  Private data members
00436     //
00437     //  fBlockSize
00438     //      This is the block size indicated in the constructor. This lets
00439     //      the derived class preallocate appopriately sized buffers. This
00440     //      sets the maximum number of characters which can be internalized
00441     //      per call to transcodeFrom() and transcodeTo().
00442     //
00443     //  fEncodingName
00444     //      This is the name of the encoding this encoder is for. All basic
00445     //      XML transcoder's are for named encodings.
00446     // -----------------------------------------------------------------------
00447     unsigned int    fBlockSize;
00448     XMLCh*          fEncodingName;
00449 };
00450 
00451 
00452 //
00453 //  This class is a specialized transcoder that only transcodes between
00454 //  the internal XMLCh format and the local code page. It is specialized
00455 //  for the very common job of translating data from the client app's
00456 //  native code page to the internal format and vice versa.
00457 //
00458 class  XMLLCPTranscoder
00459 {
00460 public :
00461     // -----------------------------------------------------------------------
00462     //  Public constructors and destructor
00463     // -----------------------------------------------------------------------
00464     virtual ~XMLLCPTranscoder();
00465 
00466 
00467     // -----------------------------------------------------------------------
00468     //  The virtual transcoder API
00469     //
00470     //  NOTE:   All these APIs don't include null terminator characters in
00471     //          their parameters. So calcRequiredSize() returns the number
00472     //          of actual chars, not including the null. maxBytes and maxChars
00473     //          parameters refer to actual chars, not including the null so
00474     //          its assumed that the buffer is physically one char or byte
00475     //          larger.
00476     // -----------------------------------------------------------------------
00477     virtual unsigned int calcRequiredSize(const char* const srcText) = 0;
00478 
00479     virtual unsigned int calcRequiredSize(const XMLCh* const srcText) = 0;
00480 
00481     virtual char* transcode(const XMLCh* const toTranscode) = 0;
00482 
00483     virtual XMLCh* transcode(const char* const toTranscode) = 0;
00484 
00485     virtual bool transcode
00486     (
00487         const   char* const     toTranscode
00488         ,       XMLCh* const    toFill
00489         , const unsigned int    maxChars
00490     ) = 0;
00491 
00492     virtual bool transcode
00493     (
00494         const   XMLCh* const    toTranscode
00495         ,       char* const     toFill
00496         , const unsigned int    maxBytes
00497     ) = 0;
00498 
00499 
00500 protected :
00501     // -----------------------------------------------------------------------
00502     //  Hidden constructors
00503     // -----------------------------------------------------------------------
00504     XMLLCPTranscoder();
00505 
00506 
00507 private :
00508     // -----------------------------------------------------------------------
00509     //  Unimplemented constructors and operators
00510     // -----------------------------------------------------------------------
00511     XMLLCPTranscoder(const XMLLCPTranscoder&);
00512     void operator=(const XMLLCPTranscoder&);
00513 };
00514 
00515 
00516 // ---------------------------------------------------------------------------
00517 //  XMLTranscoder: Protected helper methods
00518 // ---------------------------------------------------------------------------
00519 inline unsigned int XMLTranscoder::getBlockSize() const
00520 {
00521     return fBlockSize;
00522 }
00523 
00524 inline const XMLCh* XMLTranscoder::getEncodingName() const
00525 {
00526     return fEncodingName;
00527 }
00528 
00529 #endif


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