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: XMLEntityResolver.hpp 568078 2007-08-21 11:43:25Z amassari $

    36  */

    37 

    38 #ifndef XMLENTITYRESOLVER_HPP

    39 #define XMLENTITYRESOLVER_HPP

    40 

    41 #include <xercesc/util/XercesDefs.hpp>

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

    43 #include <xercesc/util/XMLResourceIdentifier.hpp>

    44 

    45 XERCES_CPP_NAMESPACE_BEGIN

    46 

    47 class InputSource;

    48 

    49 /**

    50   * Revised interface for resolving entities.

    51   *

    52   * <p>If an application needs to implement customized handling

    53   * for external entities, it can implement this interface and

    54   * register an instance with the parser using the parser's

    55   * setXMLEntityResolver method or it can use the basic SAX interface 

    56   * (EntityResolver).  The difference between the two interfaces is

    57   * the arguments to the resolveEntity() method.  With the SAX

    58   * EntityResolve the arguments are systemId and publicId.  With this

    59   * interface the argument is a XMLResourceIdentifier object.  <i>Only

    60   * one EntityResolver can be set using setEntityResolver() or 

    61   * setXMLEntityResolver, if both are set the last one set is 

    62   * used.</i></p>

    63   *

    64   * <p>The parser will then allow the application to intercept any

    65   * external entities (including the external DTD subset and external

    66   * parameter entities, if any) before including them.</p>

    67   *

    68   * <p>Many applications will not need to implement this interface,

    69   * but it will be especially useful for applications that build

    70   * XML documents from databases or other specialised input sources,

    71   * or for applications that use URI types other than URLs.</p>

    72   *

    73   * <p>The following resolver would provide the application

    74   * with a special character stream for the entity with the system

    75   * identifier "http://www.myhost.com/today":</p>

    76   *

    77   *<code>

    78   * #include <xercesc/util/XMLEntityResolver.hpp><br>

    79   * #include <xercesc/sax/InputSource.hpp><br>

    80   *<br>

    81   *&nbsp;class MyResolver : public XMLEntityResolver {<br>

    82   *&nbsp;&nbsp;public:<br>

    83   *&nbsp;&nbsp;&nbsp;InputSource resolveEntity (XMLResourceIdentifier* xmlri);<br>

    84   *&nbsp;&nbsp;&nbsp;...<br>

    85   *&nbsp;&nbsp;};<br>

    86   *<br>

    87   *&nbsp;MyResolver::resolveEntity(XMLResourceIdentifier* xmlri) {<br>

    88   *&nbsp;&nbsp;switch(xmlri->getResourceIdentifierType()) {<br>

    89   *&nbsp;&nbsp;&nbsp;case XMLResourceIdentifier::SystemId:<br>

    90   *&nbsp;&nbsp;&nbsp;&nbsp;if (XMLString::compareString(xmlri->getSystemId(), "http://www.myhost.com/today")) {<br>

    91   *&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;MyReader* reader = new MyReader();<br>

    92   *&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return new InputSource(reader);<br>

    93   *&nbsp;&nbsp;&nbsp;&nbsp;} else {<br>

    94   *&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return null;<br>

    95   *&nbsp;&nbsp;&nbsp;&nbsp;}<br>

    96   *&nbsp;&nbsp;&nbsp;&nbsp;break;<br>

    97   *&nbsp;&nbsp;&nbsp;default:<br>

    98   *&nbsp;&nbsp;&nbsp;&nbsp;return null;<br>

    99   *&nbsp;&nbsp;}<br>

   100   *&nbsp;}</code>

   101   *

   102   * <p>The application can also use this interface to redirect system

   103   * identifiers to local URIs or to look up replacements in a catalog

   104   * (possibly by using the public identifier).</p>

   105   *

   106   * <p>The HandlerBase class implements the default behaviour for

   107   * this interface, which is simply always to return null (to request

   108   * that the parser use the default system identifier).</p>

   109   *

   110   * @see XMLResourceIdentifier

   111   * @see Parser#setXMLEntityResolver

   112   * @see InputSource#InputSource

   113   * @see HandlerBase#HandlerBase

   114   */

   115 class XMLUTIL_EXPORT XMLEntityResolver

   116 {

   117 public:

   118     /** @name Constructors and Destructor */

   119     //@{

   120 

   121 

   122     /** Destructor */

   123     virtual ~XMLEntityResolver()

   124     {

   125     }

   126 

   127     //@}

   128 

   129     /** @name The XMLEntityResolver interface */

   130     //@{

   131 

   132   /**

   133     * Allow the application to resolve external entities.

   134     *

   135     * <p>The Parser will call this method before opening any external

   136     * entity except the top-level document entity (including the

   137     * external DTD subset, external entities referenced within the

   138     * DTD, and external entities referenced within the document

   139     * element): the application may request that the parser resolve

   140     * the entity itself, that it use an alternative URI, or that it

   141     * use an entirely different input source.</p>

   142     *

   143     * <p>Application writers can use this method to redirect external

   144     * system identifiers to secure and/or local URIs, to look up

   145     * public identifiers in a catalogue, or to read an entity from a

   146     * database or other input source (including, for example, a dialog

   147     * box).</p>

   148     *

   149     * <p>If the system identifier is a URL, the SAX parser must

   150     * resolve it fully before reporting it to the application.</p>

   151     *

   152     * @param resourceIdentifier An object containing the type of

   153     *        resource to be resolved and the associated data members

   154     *        corresponding to this type.

   155     * @return An InputSource object describing the new input source,

   156     *         or null to request that the parser open a regular

   157     *         URI connection to the system identifier.

   158     *         The returned InputSource is owned by the parser which is

   159     *         responsible to clean up the memory.

   160     * @exception SAXException Any SAX exception, possibly

   161     *            wrapping another exception.

   162     * @exception IOException An IO exception,

   163     *            possibly the result of creating a new InputStream

   164     *            or Reader for the InputSource.

   165     *

   166     * @see InputSource#InputSource

   167     * @see XMLResourceIdentifier

   168     */

   169     virtual InputSource* resolveEntity

   170     (

   171         XMLResourceIdentifier* resourceIdentifier

   172     ) = 0;

   173 

   174     //@}

   175 protected: 

   176     /** Default Constructor */

   177     XMLEntityResolver()

   178     {

   179     }

   180 

   181 private :

   182     /* Unimplemented constructors and operators */

   183 

   184     /* Copy constructor */

   185     XMLEntityResolver(const XMLEntityResolver&);

   186 

   187     /* Assignment operator */

   188     XMLEntityResolver& operator=(const XMLEntityResolver&);

   189 

   190 };

   191 

   192 XERCES_CPP_NAMESPACE_END

   193 

   194 #endif