1320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson/* 2320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Copyright (c) 2004 World Wide Web Consortium, 3320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 4320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * (Massachusetts Institute of Technology, European Research Consortium for 5320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Informatics and Mathematics, Keio University). All Rights Reserved. This 6320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * work is distributed under the W3C(r) Software License [1] in the hope that 7320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * it will be useful, but WITHOUT ANY WARRANTY; without even the implied 8320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 9320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 10320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231 11320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 12320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 13320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilsonpackage org.w3c.dom.ls; 14320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 15320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson/** 16f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>LSResourceResolver</code> provides a way for applications to 17f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * redirect references to external resources. 18f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <p> Applications needing to implement custom handling for external 19f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * resources can implement this interface and register their implementation 20f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * by setting the "resource-resolver" parameter of 21f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>DOMConfiguration</code> objects attached to <code>LSParser</code> 22f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * and <code>LSSerializer</code>. It can also be register on 23f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>DOMConfiguration</code> objects attached to <code>Document</code> 24f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * if the "LS" feature is supported. 25f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <p> The <code>LSParser</code> will then allow the application to intercept 26f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * any external entities, including the external DTD subset and external 27f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * parameter entities, before including them. The top-level document entity 28f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * is never passed to the <code>resolveResource</code> method. 29f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <p> Many DOM applications will not need to implement this interface, but it 30f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * will be especially useful for applications that build XML documents from 31f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * databases or other specialized input sources, or for applications that 32f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * use URNs. 33f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <p ><b>Note:</b> <code>LSResourceResolver</code> is based on the SAX2 [<a href='http://www.saxproject.org/'>SAX</a>] <code>EntityResolver</code> 34f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * interface. 35320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>See also the <a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-LS-20040407'>Document Object Model (DOM) Level 3 Load 36320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilsonand Save Specification</a>. 37320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 38320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilsonpublic interface LSResourceResolver { 39320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 40f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * Allow the application to resolve external resources. 41f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <br> The <code>LSParser</code> will call this method before opening any 42f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * external resource, including the external DTD subset, external 43f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * entities referenced within the DTD, and external entities referenced 44f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * within the document element (however, the top-level document entity 45f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * is not passed to this method). The application may then request that 46f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * the <code>LSParser</code> resolve the external resource itself, that 47f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * it use an alternative URI, or that it use an entirely different input 48f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * source. 49f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <br> Application writers can use this method to redirect external 50f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * system identifiers to secure and/or local URI, to look up public 51f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * identifiers in a catalogue, or to read an entity from a database or 52f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * other input source (including, for example, a dialog box). 53f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * @param type The type of the resource being resolved. For XML [<a href='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0</a>] resources 54f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * (i.e. entities), applications must use the value 55320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>"http://www.w3.org/TR/REC-xml"</code>. For XML Schema [<a href='http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/'>XML Schema Part 1</a>] 56f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * , applications must use the value 57f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>"http://www.w3.org/2001/XMLSchema"</code>. Other types of 58f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * resources are outside the scope of this specification and therefore 59f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * should recommend an absolute URI in order to use this method. 60f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * @param namespaceURI The namespace of the resource being resolved, 61320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * e.g. the target namespace of the XML Schema [<a href='http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/'>XML Schema Part 1</a>] 62f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * when resolving XML Schema resources. 63f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * @param publicId The public identifier of the external entity being 64f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * referenced, or <code>null</code> if no public identifier was 65f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * supplied or if the resource is not an entity. 66f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * @param systemId The system identifier, a URI reference [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>], of the 67f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * external resource being referenced, or <code>null</code> if no 68f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * system identifier was supplied. 69f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * @param baseURI The absolute base URI of the resource being parsed, or 70f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>null</code> if there is no base URI. 71f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * @return A <code>LSInput</code> object describing the new input 72f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * source, or <code>null</code> to request that the parser open a 73f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * regular URI connection to the resource. 74320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 75f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes public LSInput resolveResource(String type, 76f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes String namespaceURI, 77f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes String publicId, 78f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes String systemId, 79320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson String baseURI); 80320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 81320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson} 82