/* * Copyright 1999-2000,2004 The Apache Software Foundation. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ /* * $Log: XMLEntityResolver.hpp,v $ * Revision 1.3 2004/09/26 01:06:31 cargilld * Fix documentation generation problem. Replace
 with .  Patch from James Littlejohn.
 *
 * Revision 1.2  2004/09/08 13:56:24  peiyongz
 * Apache License Version 2.0
 *
 * Revision 1.1  2003/10/30 21:37:32  knoaman
 * Enhanced Entity Resolver Support. Thanks to David Cargill.
 *
 *
 * Revision 1.1    1999/11/09 01:07:44  twl
 * Initial checkin
 *
 */

#ifndef XMLENTITYRESOLVER_HPP
#define XMLENTITYRESOLVER_HPP

#include 
#include 
#include 

XERCES_CPP_NAMESPACE_BEGIN

class InputSource;

/**
  * Revised interface for resolving entities.
  *
  * 

If an application needs to implement customized handling * for external entities, it can implement this interface and * register an instance with the parser using the parser's * setXMLEntityResolver method or it can use the basic SAX interface * (EntityResolver). The difference between the two interfaces is * the arguments to the resolveEntity() method. With the SAX * EntityResolve the arguments are systemId and publicId. With this * interface the argument is a XMLResourceIdentifier object. Only * one EntityResolver can be set using setEntityResolver() or * setXMLEntityResolver, if both are set the last one set is * used.

* *

The parser will then allow the application to intercept any * external entities (including the external DTD subset and external * parameter entities, if any) before including them.

* *

Many applications will not need to implement this interface, * but it will be especially useful for applications that build * XML documents from databases or other specialised input sources, * or for applications that use URI types other than URLs.

* *

The following resolver would provide the application * with a special character stream for the entity with the system * identifier "http://www.myhost.com/today":

* * * #include
* #include
*
* class MyResolver : public XMLEntityResolver {
*  public:
*   InputSource resolveEntity (XMLResourceIdentifier* xmlri);
*   ...
*  };
*
* MyResolver::resolveEntity(XMLResourceIdentifier* xmlri) {
*  switch(xmlri->getResourceIdentifierType()) {
*   case XMLResourceIdentifier::SystemId:
*    if (XMLString::compareString(xmlri->getSystemId(), "http://www.myhost.com/today")) {
*     MyReader* reader = new MyReader();
*     return new InputSource(reader);
*    } else {
*     return null;
*    }
*    break;
*   default:
*    return null;
*  }
* }
* *

The application can also use this interface to redirect system * identifiers to local URIs or to look up replacements in a catalog * (possibly by using the public identifier).

* *

The HandlerBase class implements the default behaviour for * this interface, which is simply always to return null (to request * that the parser use the default system identifier).

* * @see XMLResourceIdentifier * @see Parser#setXMLEntityResolver * @see InputSource#InputSource * @see HandlerBase#HandlerBase */ class XMLUTIL_EXPORT XMLEntityResolver { public: /** @name Constructors and Destructor */ //@{ /** Destructor */ virtual ~XMLEntityResolver() { } //@} /** @name The XMLEntityResolver interface */ //@{ /** * Allow the application to resolve external entities. * *

The Parser will call this method before opening any external * entity except the top-level document entity (including the * external DTD subset, external entities referenced within the * DTD, and external entities referenced within the document * element): the application may request that the parser resolve * the entity itself, that it use an alternative URI, or that it * use an entirely different input source.

* *

Application writers can use this method to redirect external * system identifiers to secure and/or local URIs, to look up * public identifiers in a catalogue, or to read an entity from a * database or other input source (including, for example, a dialog * box).

* *

If the system identifier is a URL, the SAX parser must * resolve it fully before reporting it to the application.

* * @param resourceIdentifier An object containing the type of * resource to be resolved and the associated data members * corresponding to this type. * @return An InputSource object describing the new input source, * or null to request that the parser open a regular * URI connection to the system identifier. * The returned InputSource is owned by the parser which is * responsible to clean up the memory. * @exception SAXException Any SAX exception, possibly * wrapping another exception. * @exception IOException An IO exception, * possibly the result of creating a new InputStream * or Reader for the InputSource. * * @see InputSource#InputSource * @see XMLResourceIdentifier */ virtual InputSource* resolveEntity ( XMLResourceIdentifier* resourceIdentifier ) = 0; //@} protected: /** Default Constructor */ XMLEntityResolver() { } private : /* Unimplemented constructors and operators */ /* Copy constructor */ XMLEntityResolver(const XMLEntityResolver&); /* Assignment operator */ XMLEntityResolver& operator=(const XMLEntityResolver&); }; XERCES_CPP_NAMESPACE_END #endif