/src/xerces-c/src/xercesc/dom/DOMLSResourceResolver.hpp

Source
/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You 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.
 */

/*
 * $Id: DOMLSResourceResolver.hpp 527149 2007-04-10 14:56:39Z amassari $
 */

#if !defined(XERCESC_INCLUDE_GUARD_DOMLSRESOURCERESOLVER_HPP)
#define XERCESC_INCLUDE_GUARD_DOMLSRESOURCERESOLVER_HPP

#include <xercesc/util/XercesDefs.hpp>

XERCES_CPP_NAMESPACE_BEGIN


class DOMLSInput;

/**
  * DOMLSResourceResolver provides a way for applications to redirect references
  * to external entities.
  *
  * <p>Applications needing to implement customized handling for external
  * entities must implement this interface and register their implementation
  * by setting the entityResolver attribute of the DOMLSParser.</p>
  *
  * <p>The DOMLSParser will then allow the application to intercept any
  * external entities (including the external DTD subset and external parameter
  * entities) before including them.</p>
  *
  * <p>Many DOM applications will not need to implement this interface, but it
  * will be especially useful for applications that build XML documents from
  * databases or other specialized input sources, or for applications that use
  * URNs.</p>
  *
  * @see DOMLSParser#getDomConfig
  * @see DOMLSInput#DOMLSInput
  * @since DOM Level 3
  */
class CDOM_EXPORT DOMLSResourceResolver
{
protected:
    // -----------------------------------------------------------------------
    //  Hidden constructors
    // -----------------------------------------------------------------------
    /** @name Hidden constructors */
    //@{    
    DOMLSResourceResolver() {};
    //@}

private:
    // -----------------------------------------------------------------------
    // Unimplemented constructors and operators
    // -----------------------------------------------------------------------
    /** @name Unimplemented constructors and operators */
    //@{
    DOMLSResourceResolver(const DOMLSResourceResolver &);
    DOMLSResourceResolver & operator = (const DOMLSResourceResolver &);
    //@}

public:
    // -----------------------------------------------------------------------
    //  All constructors are hidden, just the destructor is available
    // -----------------------------------------------------------------------
    /** @name Destructor */
    //@{
    /**
     * Destructor
     *
     */
    virtual ~DOMLSResourceResolver() {};
    //@}

    // -----------------------------------------------------------------------
    //  Virtual DOMLSResourceResolver interface
    // -----------------------------------------------------------------------
    /** @name Functions introduced in DOM Level 3 */
    //@{
    /**
     * Allow the application to resolve external resources.
     *
     * The <code>DOMLSParser</code> will call this method before opening any external resource, 
     * including the external DTD subset, external entities referenced within the DTD, and 
     * external entities referenced within the document element (however, the top-level 
     * document entity is not passed to this method). The application may then request that 
     * the <code>DOMLSParser</code> resolve the external resource 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 URI, 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).
     *
     * The returned DOMLSInput is owned by the DOMLSParser which is
     * responsible to clean up the memory.
     *
     * @param resourceType The type of the resource being resolved. For XML [XML 1.0] resources 
     *                     (i.e. entities), applications must use the value "http://www.w3.org/TR/REC-xml". 
     *                     For XML Schema [XML Schema Part 1], applications must use the value 
     *                     "http://www.w3.org/2001/XMLSchema". Other types of resources are outside 
     *                     the scope of this specification and therefore should recommend an absolute 
     *                     URI in order to use this method.
     * @param namespaceUri The namespace of the resource being resolved, e.g. the target namespace 
     *                     of the XML Schema [XML Schema Part 1] when resolving XML Schema resources.
     * @param publicId     The public identifier of the external entity being referenced, or <code>null</code> 
     *                     if no public identifier was supplied or if the resource is not an entity.
     * @param systemId     The system identifier, a URI reference [IETF RFC 2396], of the external 
     *                     resource being referenced, or <code>null</code> if no system identifier was supplied.
     * @param baseURI      The absolute base URI of the resource being parsed, or <code>null</code> if 
     *                     there is no base URI.
     * @return A DOMLSInput object describing the new input source,
     *         or <code>null</code> to request that the parser open a regular
     *         URI connection to the resource.
     *         The returned DOMLSInput is owned by the DOMLSParser which is
     *         responsible to clean up the memory.
     * @see DOMLSInput#DOMLSInput
     * @since DOM Level 3
     */
    virtual DOMLSInput* resolveResource(  const XMLCh* const    resourceType
                                        , const XMLCh* const    namespaceUri
                                        , const XMLCh* const    publicId
                                        , const XMLCh* const    systemId
                                        , const XMLCh* const    baseURI) = 0;

    //@}

};

XERCES_CPP_NAMESPACE_END

#endif

Coverage Report

Created: 2026-04-01 06:57

Line	Count	Source
1		/*
2		* Licensed to the Apache Software Foundation (ASF) under one or more
3		* contributor license agreements. See the NOTICE file distributed with
4		* this work for additional information regarding copyright ownership.
5		* The ASF licenses this file to You under the Apache License, Version 2.0
6		* (the "License"); you may not use this file except in compliance with
7		* the License. You may obtain a copy of the License at
8		*
9		* http://www.apache.org/licenses/LICENSE-2.0
10		*
11		* Unless required by applicable law or agreed to in writing, software
12		* distributed under the License is distributed on an "AS IS" BASIS,
13		* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14		* See the License for the specific language governing permissions and
15		* limitations under the License.
16		*/
17
18		/*
19		* $Id: DOMLSResourceResolver.hpp 527149 2007-04-10 14:56:39Z amassari $
20		*/
21
22		#if !defined(XERCESC_INCLUDE_GUARD_DOMLSRESOURCERESOLVER_HPP)
23		#define XERCESC_INCLUDE_GUARD_DOMLSRESOURCERESOLVER_HPP
24
25		#include <xercesc/util/XercesDefs.hpp>
26
27		XERCES_CPP_NAMESPACE_BEGIN
28
29
30		class DOMLSInput;
31
32		/**
33		* DOMLSResourceResolver provides a way for applications to redirect references
34		* to external entities.
35		*
36		* <p>Applications needing to implement customized handling for external
37		* entities must implement this interface and register their implementation
38		* by setting the entityResolver attribute of the DOMLSParser.</p>
39		*
40		* <p>The DOMLSParser will then allow the application to intercept any
41		* external entities (including the external DTD subset and external parameter
42		* entities) before including them.</p>
43		*
44		* <p>Many DOM applications will not need to implement this interface, but it
45		* will be especially useful for applications that build XML documents from
46		* databases or other specialized input sources, or for applications that use
47		* URNs.</p>
48		*
49		* @see DOMLSParser#getDomConfig
50		* @see DOMLSInput#DOMLSInput
51		* @since DOM Level 3
52		*/
53		class CDOM_EXPORT DOMLSResourceResolver
54		{
55		protected:
56		// -----------------------------------------------------------------------
57		// Hidden constructors
58		// -----------------------------------------------------------------------
59		/** @name Hidden constructors */
60		//@{
61	0	DOMLSResourceResolver() {};
62		//@}
63
64		private:
65		// -----------------------------------------------------------------------
66		// Unimplemented constructors and operators
67		// -----------------------------------------------------------------------
68		/** @name Unimplemented constructors and operators */
69		//@{
70		DOMLSResourceResolver(const DOMLSResourceResolver &);
71		DOMLSResourceResolver & operator = (const DOMLSResourceResolver &);
72		//@}
73
74		public:
75		// -----------------------------------------------------------------------
76		// All constructors are hidden, just the destructor is available
77		// -----------------------------------------------------------------------
78		/** @name Destructor */
79		//@{
80		/**
81		* Destructor
82		*
83		*/
84	0	virtual ~DOMLSResourceResolver() {};
85		//@}
86
87		// -----------------------------------------------------------------------
88		// Virtual DOMLSResourceResolver interface
89		// -----------------------------------------------------------------------
90		/** @name Functions introduced in DOM Level 3 */
91		//@{
92		/**
93		* Allow the application to resolve external resources.
94		*
95		* The <code>DOMLSParser</code> will call this method before opening any external resource,
96		* including the external DTD subset, external entities referenced within the DTD, and
97		* external entities referenced within the document element (however, the top-level
98		* document entity is not passed to this method). The application may then request that
99		* the <code>DOMLSParser</code> resolve the external resource itself, that it use an
100		* alternative URI, or that it use an entirely different input source.
101		*
102		* Application writers can use this method to redirect external system identifiers to
103		* secure and/or local URI, to look up public identifiers in a catalogue, or to read
104		* an entity from a database or other input source (including, for example, a dialog box).
105		*
106		* The returned DOMLSInput is owned by the DOMLSParser which is
107		* responsible to clean up the memory.
108		*
109		* @param resourceType The type of the resource being resolved. For XML [XML 1.0] resources
110		* (i.e. entities), applications must use the value "http://www.w3.org/TR/REC-xml".
111		* For XML Schema [XML Schema Part 1], applications must use the value
112		* "http://www.w3.org/2001/XMLSchema". Other types of resources are outside
113		* the scope of this specification and therefore should recommend an absolute
114		* URI in order to use this method.
115		* @param namespaceUri The namespace of the resource being resolved, e.g. the target namespace
116		* of the XML Schema [XML Schema Part 1] when resolving XML Schema resources.
117		* @param publicId The public identifier of the external entity being referenced, or <code>null</code>
118		* if no public identifier was supplied or if the resource is not an entity.
119		* @param systemId The system identifier, a URI reference [IETF RFC 2396], of the external
120		* resource being referenced, or <code>null</code> if no system identifier was supplied.
121		* @param baseURI The absolute base URI of the resource being parsed, or <code>null</code> if
122		* there is no base URI.
123		* @return A DOMLSInput object describing the new input source,
124		* or <code>null</code> to request that the parser open a regular
125		* URI connection to the resource.
126		* The returned DOMLSInput is owned by the DOMLSParser which is
127		* responsible to clean up the memory.
128		* @see DOMLSInput#DOMLSInput
129		* @since DOM Level 3
130		*/
131		virtual DOMLSInput* resolveResource( const XMLCh* const resourceType
132		, const XMLCh* const namespaceUri
133		, const XMLCh* const publicId
134		, const XMLCh* const systemId
135		, const XMLCh* const baseURI) = 0;
136
137		//@}
138
139		};
140
141		XERCES_CPP_NAMESPACE_END
142
143		#endif