1 /*

     2 * Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: 

    15 *

    16 */

    17 /*

    18  * Licensed to the Apache Software Foundation (ASF) under one or more

    19  * contributor license agreements.  See the NOTICE file distributed with

    20  * this work for additional information regarding copyright ownership.

    21  * The ASF licenses this file to You under the Apache License, Version 2.0

    22  * (the "License"); you may not use this file except in compliance with

    23  * the License.  You may obtain a copy of the License at

    24  * 

    25  *      http://www.apache.org/licenses/LICENSE-2.0

    26  * 

    27  * Unless required by applicable law or agreed to in writing, software

    28  * distributed under the License is distributed on an "AS IS" BASIS,

    29  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

    30  * See the License for the specific language governing permissions and

    31  * limitations under the License.

    32  */

    33 

    34 /*

    35  * $Id: InputSource.hpp 568078 2007-08-21 11:43:25Z amassari $

    36  */

    37 

    38 

    39 #ifndef INPUTSOURCE_HPP

    40 #define INPUTSOURCE_HPP

    41 

    42 #include <xercesc/util/PlatformUtils.hpp>

    43 

    44 XERCES_CPP_NAMESPACE_BEGIN

    45 

    46 class BinInputStream;

    47 

    48 

    49 /**

    50   * A single input source for an XML entity.

    51   *

    52   * <p>This class encapsulates information about an input source in a

    53   * single object, which may include a public identifier or a system

    54   * identifier</p>

    55   *

    56   * <p>There are two places that the application will deliver this input

    57   * source to the parser: as the argument to the Parser::parse method, or as

    58   * the return value of the EntityResolver::resolveEntity method.</p>

    59   *

    60   * <p>InputSource is never used directly, but is the base class for a number

    61   * of derived classes for particular types of input sources. Derivatives are

    62   * provided (in the framework/ directory) for URL input sources, memory buffer

    63   * input sources, and so on.</p>

    64   *

    65   * <p>When it is time to parse the input described by an input source, it

    66   * will be asked to create a binary stream for that source. That stream will

    67   * be used to input the data of the source. The derived class provides the

    68   * implementation of the makeStream() method, and provides a type of stream

    69   * of the correct type for the input source it represents.

    70   *

    71   * <p>An InputSource object belongs to the application: the parser never

    72   * modifies them in any way. They are always passed by const reference so

    73   * the parser will make a copy of any input sources that it must keep

    74   * around beyond the call.</p>

    75   *

    76   * @see Parser#parse

    77   * @see EntityResolver#resolveEntity

    78   */

    79 class SAX_EXPORT InputSource : public XMemory

    80 {

    81 public:

    82     // -----------------------------------------------------------------------

    83     //  All constructors are hidden, just the destructor is available

    84     // -----------------------------------------------------------------------

    85     /** @name Destructor */

    86     //@{

    87   /**

    88     * Destructor

    89     *

    90     */

    91     virtual ~InputSource();

    92     //@}

    93 

    94 

    95     // -----------------------------------------------------------------------

    96     /** @name Virtual input source interface */

    97     //@{

    98   /**

    99     * Makes the byte stream for this input source.

   100     *

   101     * <p>The derived class must create and return a binary input stream of an

   102     * appropriate type for its kind of data source. The returned stream must

   103     * be dynamically allocated and becomes the parser's property.

   104     * </p>

   105     *

   106     * @see BinInputStream

   107     */

   108     virtual BinInputStream* makeStream() const = 0;

   109 

   110     //@}

   111 

   112 

   113     // -----------------------------------------------------------------------

   114     /** @name Getter methods */

   115     //@{

   116   /**

   117     * An input source can be set to force the parser to assume a particular

   118     * encoding for the data that input source reprsents, via the setEncoding()

   119     * method. This method returns name of the encoding that is to be forced.

   120     * If the encoding has never been forced, it returns a null pointer.

   121     *

   122     * @return The forced encoding, or null if none was supplied.

   123     * @see #setEncoding

   124     */

   125     virtual const XMLCh* getEncoding() const;

   126 

   127 

   128   /**

   129     * Get the public identifier for this input source.

   130     *

   131     * @return The public identifier, or null if none was supplied.

   132     * @see #setPublicId

   133     */

   134     virtual const XMLCh* getPublicId() const;

   135 

   136 

   137   /**

   138     * Get the system identifier for this input source.

   139     *

   140     * <p>If the system ID is a URL, it will be fully resolved.</p>

   141     *

   142     * @return The system identifier.

   143     * @see #setSystemId

   144     */

   145     virtual const XMLCh* getSystemId() const;

   146 

   147   /**

   148     * Get the flag that indicates if the parser should issue fatal error if this input source

   149     * is not found.

   150     *

   151     * @return True if the parser should issue fatal error if this input source is not found.

   152     *         False if the parser issue warning message instead.

   153     * @see #setIssueFatalErrorIfNotFound

   154     */

   155     virtual bool getIssueFatalErrorIfNotFound() const;

   156 

   157     MemoryManager* getMemoryManager() const;

   158 

   159     //@}

   160 

   161 

   162     // -----------------------------------------------------------------------

   163     /** @name Setter methods */

   164     //@{

   165 

   166   /**

   167     * Set the encoding which will be required for use with the XML text read

   168     * via a stream opened by this input source.

   169     *

   170     * <p>This is usually not set, allowing the encoding to be sensed in the

   171     * usual XML way. However, in some cases, the encoding in the file is known

   172     * to be incorrect because of intermediate transcoding, for instance

   173     * encapsulation within a MIME document.

   174     *

   175     * @param encodingStr The name of the encoding to force.

   176     */

   177     virtual void setEncoding(const XMLCh* const encodingStr);

   178 

   179 

   180   /**

   181     * Set the public identifier for this input source.

   182     *

   183     * <p>The public identifier is always optional: if the application writer

   184     * includes one, it will be provided as part of the location information.</p>

   185     *

   186     * @param publicId The public identifier as a string.

   187     * @see Locator#getPublicId

   188     * @see SAXParseException#getPublicId

   189     * @see #getPublicId

   190     */

   191     virtual void setPublicId(const XMLCh* const publicId);

   192 

   193   /**

   194     * Set the system identifier for this input source.

   195     *

   196     * <p>Set the system identifier for this input source.

   197     *

   198     * </p>The system id is always required. The public id may be used to map

   199     * to another system id, but the system id must always be present as a fall

   200     * back.

   201     *

   202     * <p>If the system ID is a URL, it must be fully resolved.</p>

   203     *

   204     * @param systemId The system identifier as a string.

   205     * @see #getSystemId

   206     * @see Locator#getSystemId

   207     * @see SAXParseException#getSystemId

   208     */

   209     virtual void setSystemId(const XMLCh* const systemId);

   210 

   211   /**

   212     * Indicates if the parser should issue fatal error if this input source

   213     * is not found.  If set to false, the parser issue warning message instead.

   214     *

   215     * @param  flag True if the parser should issue fatal error if this input source is not found.

   216     *               If set to false, the parser issue warning message instead.  (Default: true)

   217     *

   218     * @see #getIssueFatalErrorIfNotFound

   219     */

   220     virtual void setIssueFatalErrorIfNotFound(const bool flag);

   221 

   222     //@}

   223 

   224 

   225 protected :

   226     // -----------------------------------------------------------------------

   227     //  Hidden constructors

   228     // -----------------------------------------------------------------------

   229     /** @name Constructors and Destructor */

   230     //@{

   231     /** Default constructor */

   232     InputSource(MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager);

   233 

   234     /** Constructor with a system identifier as XMLCh type.

   235       * @param systemId The system identifier (URI).

   236       * @param manager    Pointer to the memory manager to be used to

   237       *                   allocate objects.

   238       */

   239     InputSource(const XMLCh* const systemId,

   240                 MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager);

   241 

   242     /** Constructor with a system and public identifiers

   243       * @param systemId The system identifier (URI).

   244       * @param publicId The public identifier as in the entity definition.

   245       * @param manager    Pointer to the memory manager to be used to

   246       *                   allocate objects.

   247       */

   248     InputSource

   249     (

   250         const   XMLCh* const   systemId

   251         , const XMLCh* const   publicId

   252         , MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager

   253     );

   254 

   255     /** Constructor witha system identifier as string

   256       * @param systemId The system identifier (URI).

   257       * @param manager    Pointer to the memory manager to be used to

   258       *                   allocate objects.

   259       */

   260     InputSource(const char* const systemId,

   261                 MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager);

   262 

   263     /** Constructor witha system and public identifiers. Both as string

   264       * @param systemId The system identifier (URI).

   265       * @param publicId The public identifier as in the entity definition.

   266       * @param manager    Pointer to the memory manager to be used to

   267       *                   allocate objects.

   268       */

   269     InputSource

   270     (

   271         const   char* const systemId

   272         , const char* const publicId

   273         , MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager

   274     );

   275 

   276     //@}

   277 

   278 

   279 

   280 

   281 

   282 private:

   283     // -----------------------------------------------------------------------

   284     //  Unimplemented constructors and operators

   285     // -----------------------------------------------------------------------

   286     InputSource(const InputSource&);

   287     InputSource& operator=(const InputSource&);

   288 

   289 

   290     // -----------------------------------------------------------------------

   291     //  Private data members

   292     //

   293     //  fEncoding

   294     //      This is the encoding to use. Usually this is null, which means

   295     //      to use the information found in the file itself. But, if set,

   296     //      this encoding will be used without question.

   297     //

   298     //  fPublicId

   299     //      This is the optional public id for the input source. It can be

   300     //      null if none is desired.

   301     //

   302     //  fSystemId

   303     //      This is the system id for the input source. This is what is

   304     //      actually used to open the source.

   305     //

   306     //  fFatalErrorIfNotFound

   307     // -----------------------------------------------------------------------

   308     MemoryManager* const fMemoryManager;

   309     XMLCh*         fEncoding;

   310     XMLCh*         fPublicId;

   311     XMLCh*         fSystemId;

   312     bool           fFatalErrorIfNotFound;

   313 };

   314 

   315 

   316 // ---------------------------------------------------------------------------

   317 //  InputSource: Getter methods

   318 // ---------------------------------------------------------------------------

   319 inline const XMLCh* InputSource::getEncoding() const

   320 {

   321     return fEncoding;

   322 }

   323 

   324 inline const XMLCh* InputSource::getPublicId() const

   325 {

   326     return fPublicId;

   327 }

   328 

   329 inline const XMLCh* InputSource::getSystemId() const

   330 {

   331     return fSystemId;

   332 }

   333 

   334 inline bool InputSource::getIssueFatalErrorIfNotFound() const

   335 {

   336     return fFatalErrorIfNotFound;

   337 }

   338 

   339 inline MemoryManager* InputSource::getMemoryManager() const

   340 {

   341     return fMemoryManager;

   342 }

   343 

   344 // ---------------------------------------------------------------------------

   345 //  InputSource: Setter methods

   346 // ---------------------------------------------------------------------------

   347 inline void InputSource::setIssueFatalErrorIfNotFound(const bool flag)

   348 {

   349     fFatalErrorIfNotFound = flag;

   350 }

   351 

   352 XERCES_CPP_NAMESPACE_END

   353 

   354 #endif