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

Home

Readme
Download
Installation
Build

API Docs
Samples
Schema

FAQs
Programming
Migration

Releases
Bug-Reporting
Feedback

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


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