1//
2// EntityResolver.h
3//
4// Library: XML
5// Package: SAX
6// Module: SAX
7//
8// SAX EntityResolver Interface.
9//
10// Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH.
11// and Contributors.
12//
13// SPDX-License-Identifier: BSL-1.0
14//
15
16
17#ifndef SAX_EntityResolver_INCLUDED
18#define SAX_EntityResolver_INCLUDED
19
20
21#include "Poco/XML/XML.h"
22#include "Poco/XML/XMLString.h"
23
24
25namespace Poco {
26namespace XML {
27
28
29class InputSource;
30
31
32class XML_API EntityResolver
33 /// If a SAX application needs to implement customized handling for external entities,
34 /// it must implement this interface and register an instance with the SAX driver using
35 /// the setEntityResolver method.
36 ///
37 /// The XML reader will then allow the application to intercept any external entities
38 /// (including the external DTD subset and external parameter entities, if any) before
39 /// including them.
40 ///
41 /// Many SAX applications will not need to implement this interface, but it will be
42 /// especially useful for applications that build XML documents from databases or other
43 /// specialised input sources, or for applications that use URI types other than URLs.
44 ///
45 /// The application can also use this interface to redirect system identifiers to local
46 /// URIs or to look up replacements in a catalog (possibly by using the public identifier).
47{
48public:
49 virtual InputSource* resolveEntity(const XMLString* publicId, const XMLString& systemId) = 0;
50 /// Allow the application to resolve external entities.
51 ///
52 /// The parser will call this method before opening any external entity except the
53 /// top-level document entity. Such entities include the external DTD subset and
54 /// external parameter entities referenced within the DTD (in either case, only
55 /// if the parser reads external parameter entities), and external general entities
56 /// referenced within the document element (if the parser reads external general entities).
57 /// The application may request that the parser locate the entity itself, that it use an
58 /// alternative URI, or that it use data provided by the application (as a character or
59 /// byte input stream).
60 ///
61 /// Application writers can use this method to redirect external system identifiers to
62 /// secure and/or local URIs, to look up public identifiers in a catalogue, or to read an
63 /// entity from a database or other input source (including, for example, a dialog box).
64 /// Neither XML nor SAX specifies a preferred policy for using public or system IDs to resolve
65 /// resources. However, SAX specifies how to interpret any InputSource returned by this method,
66 /// and that if none is returned, then the system ID will be dereferenced as a URL.
67 ///
68 /// If the system identifier is a URL, the SAX parser must resolve it fully before reporting it to
69 /// the application.
70 ///
71 /// Note that publicId maybe null, therefore we pass a pointer rather than a reference.
72
73 virtual void releaseInputSource(InputSource* pSource) = 0;
74 /// This is a non-standard extension to SAX!
75 /// Called by the parser when the input source returned by ResolveEntity is
76 /// no longer needed. Should free any resources used by the input source.
77
78protected:
79 virtual ~EntityResolver();
80};
81
82
83} } // namespace Poco::XML
84
85
86#endif // SAX_EntityResolver_INCLUDED
87