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


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