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

    36  */

    37 

    38 

    39 #ifndef ENTITYRESOLVER_HPP

    40 #define ENTITYRESOLVER_HPP

    41 

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

    43 

    44 XERCES_CPP_NAMESPACE_BEGIN

    45 

    46 class InputSource;

    47 

    48 /**

    49   * Basic interface for resolving entities.

    50   *

    51   * <p>If a SAX application needs to implement customized handling

    52   * for external entities, it must implement this interface and

    53   * register an instance with the SAX parser using the parser's

    54   * setEntityResolver method.</p>

    55   *

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

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

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

    59   *

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

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

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

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

    64   *

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

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

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

    68   *

    69   *<code>

    70   *#include <xercesc/sax/EntityResolver.hpp><br>

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

    72   *<br>

    73   *class MyResolver : public EntityResolver {<br>

    74   *  public:<br>&nbsp;

    75   *    InputSource resolveEntity (const XMLCh* const publicId, const XMLCh* const systemId);<br>&nbsp;&nbsp;

    76   *    <br>

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

    78   *   };<br>&nbsp;

    79   *<br>

    80   *&nbsp;MyResolver::resolveEntity {<br>

    81   *&nbsp;&nbsp;if (XMLString::compareString(systemId, "http://www.myhost.com/today")) {<br>

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

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

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

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

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

    87   *&nbsp;}<br>

    88   *<br>

    89   *</code>

    90   *

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

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

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

    94   *

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

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

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

    98   *

    99   * @see Parser#setEntityResolver

   100   * @see InputSource#InputSource

   101   * @see HandlerBase#HandlerBase

   102   */

   103 class SAX_EXPORT EntityResolver

   104 {

   105 public:

   106     /** @name Constructors and Destructor */

   107     //@{

   108 

   109     /** Default Constructor */

   110     EntityResolver()

   111     {

   112     }

   113 

   114     /** Destructor */

   115     virtual ~EntityResolver()

   116     {

   117     }

   118 

   119     //@}

   120 

   121     /** @name The EntityResolver interface */

   122     //@{

   123 

   124   /**

   125     * Allow the application to resolve external entities.

   126     *

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

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

   129     * external DTD subset, external entities referenced within the

   130     * DTD, and external entities referenced within the document

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

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

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

   134     *

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

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

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

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

   139     * box).</p>

   140     *

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

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

   143     *

   144     * @param publicId The public identifier of the external entity

   145     *        being referenced, or null if none was supplied.

   146     * @param systemId The system identifier of the external entity

   147     *        being referenced.

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

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

   150     *         URI connection to the system identifier.

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

   152     *         responsible to clean up the memory.

   153     * @exception SAXException Any SAX exception, possibly

   154     *            wrapping another exception.

   155     * @exception IOException An IO exception,

   156     *            possibly the result of creating a new InputStream

   157     *            or Reader for the InputSource.

   158     * @see InputSource#InputSource

   159     */

   160     virtual InputSource* resolveEntity

   161     (

   162         const   XMLCh* const    publicId

   163         , const XMLCh* const    systemId

   164     ) = 0;

   165 

   166     //@}

   167 

   168 private :

   169     /* Unimplemented constructors and operators */

   170 

   171 

   172     /* Copy constructor */

   173     EntityResolver(const EntityResolver&);

   174 

   175     /* Assignment operator */

   176     EntityResolver& operator=(const EntityResolver&);

   177 

   178 };

   179 

   180 XERCES_CPP_NAMESPACE_END

   181 

   182 #endif