diff options
Diffstat (limited to 'libjava/classpath/external/w3c_dom/org/w3c/dom/ls')
11 files changed, 1794 insertions, 0 deletions
diff --git a/libjava/classpath/external/w3c_dom/org/w3c/dom/ls/DOMImplementationLS.java b/libjava/classpath/external/w3c_dom/org/w3c/dom/ls/DOMImplementationLS.java new file mode 100644 index 000000000..4d1b0971d --- /dev/null +++ b/libjava/classpath/external/w3c_dom/org/w3c/dom/ls/DOMImplementationLS.java @@ -0,0 +1,122 @@ +/* + * Copyright (c) 2004 World Wide Web Consortium, + * + * (Massachusetts Institute of Technology, European Research Consortium for + * Informatics and Mathematics, Keio University). All Rights Reserved. This + * work is distributed under the W3C(r) Software License [1] in the hope that + * it will be useful, but WITHOUT ANY WARRANTY; without even the implied + * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + * + * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231 + */ + +package org.w3c.dom.ls; + +import org.w3c.dom.DOMException; + +/** + * <code>DOMImplementationLS</code> contains the factory methods for creating + * Load and Save objects. + * <p> The expectation is that an instance of the + * <code>DOMImplementationLS</code> interface can be obtained by using + * binding-specific casting methods on an instance of the + * <code>DOMImplementation</code> interface or, if the <code>Document</code> + * supports the feature <code>"Core"</code> version <code>"3.0"</code> + * defined in [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>] + * , by using the method <code>DOMImplementation.getFeature</code> with + * parameter values <code>"LS"</code> (or <code>"LS-Async"</code>) and + * <code>"3.0"</code> (respectively). + * <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 +and Save Specification</a>. + */ +public interface DOMImplementationLS { + // DOMImplementationLSMode + /** + * Create a synchronous <code>LSParser</code>. + */ + public static final short MODE_SYNCHRONOUS = 1; + /** + * Create an asynchronous <code>LSParser</code>. + */ + public static final short MODE_ASYNCHRONOUS = 2; + + /** + * Create a new <code>LSParser</code>. The newly constructed parser may + * then be configured by means of its <code>DOMConfiguration</code> + * object, and used to parse documents by means of its <code>parse</code> + * method. + * @param mode The <code>mode</code> argument is either + * <code>MODE_SYNCHRONOUS</code> or <code>MODE_ASYNCHRONOUS</code>, if + * <code>mode</code> is <code>MODE_SYNCHRONOUS</code> then the + * <code>LSParser</code> that is created will operate in synchronous + * mode, if it's <code>MODE_ASYNCHRONOUS</code> then the + * <code>LSParser</code> that is created will operate in asynchronous + * mode. + * @param schemaType An absolute URI representing the type of the schema + * language used during the load of a <code>Document</code> using the + * newly created <code>LSParser</code>. Note that no lexical checking + * is done on the absolute URI. In order to create a + * <code>LSParser</code> for any kind of schema types (i.e. the + * LSParser will be free to use any schema found), use the value + * <code>null</code>. + * <p ><b>Note:</b> For W3C XML Schema [<a href='http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/'>XML Schema Part 1</a>] + * , applications must use the value + * <code>"http://www.w3.org/2001/XMLSchema"</code>. For XML DTD [<a href='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0</a>], + * applications must use the value + * <code>"http://www.w3.org/TR/REC-xml"</code>. Other Schema languages + * are outside the scope of the W3C and therefore should recommend an + * absolute URI in order to use this method. + * @return The newly created <code>LSParser</code> object. This + * <code>LSParser</code> is either synchronous or asynchronous + * depending on the value of the <code>mode</code> argument. + * <p ><b>Note:</b> By default, the newly created <code>LSParser</code> + * does not contain a <code>DOMErrorHandler</code>, i.e. the value of + * the "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler'> + * error-handler</a>" configuration parameter is <code>null</code>. However, implementations + * may provide a default error handler at creation time. In that case, + * the initial value of the <code>"error-handler"</code> configuration + * parameter on the new <code>LSParser</code> object contains a + * reference to the default error handler. + * @exception DOMException + * NOT_SUPPORTED_ERR: Raised if the requested mode or schema type is + * not supported. + */ + public LSParser createLSParser(short mode, + String schemaType) + throws DOMException; + + /** + * Create a new <code>LSSerializer</code> object. + * @return The newly created <code>LSSerializer</code> object. + * <p ><b>Note:</b> By default, the newly created + * <code>LSSerializer</code> has no <code>DOMErrorHandler</code>, i.e. + * the value of the <code>"error-handler"</code> configuration + * parameter is <code>null</code>. However, implementations may + * provide a default error handler at creation time. In that case, the + * initial value of the <code>"error-handler"</code> configuration + * parameter on the new <code>LSSerializer</code> object contains a + * reference to the default error handler. + */ + public LSSerializer createLSSerializer(); + + /** + * Create a new empty input source object where + * <code>LSInput.characterStream</code>, <code>LSInput.byteStream</code> + * , <code>LSInput.stringData</code> <code>LSInput.systemId</code>, + * <code>LSInput.publicId</code>, <code>LSInput.baseURI</code>, and + * <code>LSInput.encoding</code> are null, and + * <code>LSInput.certifiedText</code> is false. + * @return The newly created input object. + */ + public LSInput createLSInput(); + + /** + * Create a new empty output destination object where + * <code>LSOutput.characterStream</code>, + * <code>LSOutput.byteStream</code>, <code>LSOutput.systemId</code>, + * <code>LSOutput.encoding</code> are null. + * @return The newly created output object. + */ + public LSOutput createLSOutput(); + +} diff --git a/libjava/classpath/external/w3c_dom/org/w3c/dom/ls/LSException.java b/libjava/classpath/external/w3c_dom/org/w3c/dom/ls/LSException.java new file mode 100644 index 000000000..677ad385c --- /dev/null +++ b/libjava/classpath/external/w3c_dom/org/w3c/dom/ls/LSException.java @@ -0,0 +1,47 @@ +/* + * Copyright (c) 2004 World Wide Web Consortium, + * + * (Massachusetts Institute of Technology, European Research Consortium for + * Informatics and Mathematics, Keio University). All Rights Reserved. This + * work is distributed under the W3C(r) Software License [1] in the hope that + * it will be useful, but WITHOUT ANY WARRANTY; without even the implied + * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + * + * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231 + */ + +package org.w3c.dom.ls; + +/** + * Parser or write operations may throw an <code>LSException</code> if the + * processing is stopped. The processing can be stopped due to a + * <code>DOMError</code> with a severity of + * <code>DOMError.SEVERITY_FATAL_ERROR</code> or a non recovered + * <code>DOMError.SEVERITY_ERROR</code>, or if + * <code>DOMErrorHandler.handleError()</code> returned <code>false</code>. + * <p ><b>Note:</b> As suggested in the definition of the constants in the + * <code>DOMError</code> interface, a DOM implementation may choose to + * continue after a fatal error, but the resulting DOM tree is then + * implementation dependent. + * <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 +and Save Specification</a>. + */ +public class LSException extends RuntimeException { + public LSException(short code, String message) { + super(message); + this.code = code; + } + public short code; + // LSExceptionCode + /** + * If an attempt was made to load a document, or an XML Fragment, using + * <code>LSParser</code> and the processing has been stopped. + */ + public static final short PARSE_ERR = 81; + /** + * If an attempt was made to serialize a <code>Node</code> using + * <code>LSSerializer</code> and the processing has been stopped. + */ + public static final short SERIALIZE_ERR = 82; + +} diff --git a/libjava/classpath/external/w3c_dom/org/w3c/dom/ls/LSInput.java b/libjava/classpath/external/w3c_dom/org/w3c/dom/ls/LSInput.java new file mode 100644 index 000000000..bba1792cd --- /dev/null +++ b/libjava/classpath/external/w3c_dom/org/w3c/dom/ls/LSInput.java @@ -0,0 +1,218 @@ +/* + * Copyright (c) 2004 World Wide Web Consortium, + * + * (Massachusetts Institute of Technology, European Research Consortium for + * Informatics and Mathematics, Keio University). All Rights Reserved. This + * work is distributed under the W3C(r) Software License [1] in the hope that + * it will be useful, but WITHOUT ANY WARRANTY; without even the implied + * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + * + * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231 + */ + +package org.w3c.dom.ls; + +/** + * This interface represents an input source for data. + * <p> This interface allows an application to encapsulate information about + * an input source in a single object, which may include a public + * identifier, a system identifier, a byte stream (possibly with a specified + * encoding), a base URI, and/or a character stream. + * <p> The exact definitions of a byte stream and a character stream are + * binding dependent. + * <p> The application is expected to provide objects that implement this + * interface whenever such objects are needed. The application can either + * provide its own objects that implement this interface, or it can use the + * generic factory method <code>DOMImplementationLS.createLSInput()</code> + * to create objects that implement this interface. + * <p> The <code>LSParser</code> will use the <code>LSInput</code> object to + * determine how to read data. The <code>LSParser</code> will look at the + * different inputs specified in the <code>LSInput</code> in the following + * order to know which one to read from, the first one that is not null and + * not an empty string will be used: + * <ol> + * <li> <code>LSInput.characterStream</code> + * </li> + * <li> + * <code>LSInput.byteStream</code> + * </li> + * <li> <code>LSInput.stringData</code> + * </li> + * <li> + * <code>LSInput.systemId</code> + * </li> + * <li> <code>LSInput.publicId</code> + * </li> + * </ol> + * <p> If all inputs are null, the <code>LSParser</code> will report a + * <code>DOMError</code> with its <code>DOMError.type</code> set to + * <code>"no-input-specified"</code> and its <code>DOMError.severity</code> + * set to <code>DOMError.SEVERITY_FATAL_ERROR</code>. + * <p> <code>LSInput</code> objects belong to the application. The DOM + * implementation will never modify them (though it may make copies and + * modify the copies, if necessary). + * <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 +and Save Specification</a>. + */ +public interface LSInput { + /** + * An attribute of a language and binding dependent type that represents + * a stream of 16-bit units. The application must encode the stream + * using UTF-16 (defined in [Unicode] and in [ISO/IEC 10646]). It is not a requirement to have an XML declaration when + * using character streams. If an XML declaration is present, the value + * of the encoding attribute will be ignored. + */ + public java.io.Reader getCharacterStream(); + /** + * An attribute of a language and binding dependent type that represents + * a stream of 16-bit units. The application must encode the stream + * using UTF-16 (defined in [Unicode] and in [ISO/IEC 10646]). It is not a requirement to have an XML declaration when + * using character streams. If an XML declaration is present, the value + * of the encoding attribute will be ignored. + */ + public void setCharacterStream(java.io.Reader characterStream); + + /** + * An attribute of a language and binding dependent type that represents + * a stream of bytes. + * <br> If the application knows the character encoding of the byte + * stream, it should set the encoding attribute. Setting the encoding in + * this way will override any encoding specified in an XML declaration + * in the data. + */ + public java.io.InputStream getByteStream(); + /** + * An attribute of a language and binding dependent type that represents + * a stream of bytes. + * <br> If the application knows the character encoding of the byte + * stream, it should set the encoding attribute. Setting the encoding in + * this way will override any encoding specified in an XML declaration + * in the data. + */ + public void setByteStream(java.io.InputStream byteStream); + + /** + * String data to parse. If provided, this will always be treated as a + * sequence of 16-bit units (UTF-16 encoded characters). It is not a + * requirement to have an XML declaration when using + * <code>stringData</code>. If an XML declaration is present, the value + * of the encoding attribute will be ignored. + */ + public String getStringData(); + /** + * String data to parse. If provided, this will always be treated as a + * sequence of 16-bit units (UTF-16 encoded characters). It is not a + * requirement to have an XML declaration when using + * <code>stringData</code>. If an XML declaration is present, the value + * of the encoding attribute will be ignored. + */ + public void setStringData(String stringData); + + /** + * The system identifier, a URI reference [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>], for this + * input source. The system identifier is optional if there is a byte + * stream, a character stream, or string data. It is still useful to + * provide one, since the application will use it to resolve any + * relative URIs and can include it in error messages and warnings. (The + * LSParser will only attempt to fetch the resource identified by the + * URI reference if there is no other input available in the input + * source.) + * <br> If the application knows the character encoding of the object + * pointed to by the system identifier, it can set the encoding using + * the <code>encoding</code> attribute. + * <br> If the specified system ID is a relative URI reference (see + * section 5 in [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>]), the DOM + * implementation will attempt to resolve the relative URI with the + * <code>baseURI</code> as the base, if that fails, the behavior is + * implementation dependent. + */ + public String getSystemId(); + /** + * The system identifier, a URI reference [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>], for this + * input source. The system identifier is optional if there is a byte + * stream, a character stream, or string data. It is still useful to + * provide one, since the application will use it to resolve any + * relative URIs and can include it in error messages and warnings. (The + * LSParser will only attempt to fetch the resource identified by the + * URI reference if there is no other input available in the input + * source.) + * <br> If the application knows the character encoding of the object + * pointed to by the system identifier, it can set the encoding using + * the <code>encoding</code> attribute. + * <br> If the specified system ID is a relative URI reference (see + * section 5 in [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>]), the DOM + * implementation will attempt to resolve the relative URI with the + * <code>baseURI</code> as the base, if that fails, the behavior is + * implementation dependent. + */ + public void setSystemId(String systemId); + + /** + * The public identifier for this input source. This may be mapped to an + * input source using an implementation dependent mechanism (such as + * catalogues or other mappings). The public identifier, if specified, + * may also be reported as part of the location information when errors + * are reported. + */ + public String getPublicId(); + /** + * The public identifier for this input source. This may be mapped to an + * input source using an implementation dependent mechanism (such as + * catalogues or other mappings). The public identifier, if specified, + * may also be reported as part of the location information when errors + * are reported. + */ + public void setPublicId(String publicId); + + /** + * The base URI to be used (see section 5.1.4 in [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>]) for + * resolving a relative <code>systemId</code> to an absolute URI. + * <br> If, when used, the base URI is itself a relative URI, an empty + * string, or null, the behavior is implementation dependent. + */ + public String getBaseURI(); + /** + * The base URI to be used (see section 5.1.4 in [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>]) for + * resolving a relative <code>systemId</code> to an absolute URI. + * <br> If, when used, the base URI is itself a relative URI, an empty + * string, or null, the behavior is implementation dependent. + */ + public void setBaseURI(String baseURI); + + /** + * The character encoding, if known. The encoding must be a string + * acceptable for an XML encoding declaration ([<a href='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0</a>] section + * 4.3.3 "Character Encoding in Entities"). + * <br> This attribute has no effect when the application provides a + * character stream or string data. For other sources of input, an + * encoding specified by means of this attribute will override any + * encoding specified in the XML declaration or the Text declaration, or + * an encoding obtained from a higher level protocol, such as HTTP [<a href='http://www.ietf.org/rfc/rfc2616.txt'>IETF RFC 2616</a>]. + */ + public String getEncoding(); + /** + * The character encoding, if known. The encoding must be a string + * acceptable for an XML encoding declaration ([<a href='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0</a>] section + * 4.3.3 "Character Encoding in Entities"). + * <br> This attribute has no effect when the application provides a + * character stream or string data. For other sources of input, an + * encoding specified by means of this attribute will override any + * encoding specified in the XML declaration or the Text declaration, or + * an encoding obtained from a higher level protocol, such as HTTP [<a href='http://www.ietf.org/rfc/rfc2616.txt'>IETF RFC 2616</a>]. + */ + public void setEncoding(String encoding); + + /** + * If set to true, assume that the input is certified (see section 2.13 + * in [<a href='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>]) when + * parsing [<a href='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>]. + */ + public boolean getCertifiedText(); + /** + * If set to true, assume that the input is certified (see section 2.13 + * in [<a href='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>]) when + * parsing [<a href='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>]. + */ + public void setCertifiedText(boolean certifiedText); + +} diff --git a/libjava/classpath/external/w3c_dom/org/w3c/dom/ls/LSLoadEvent.java b/libjava/classpath/external/w3c_dom/org/w3c/dom/ls/LSLoadEvent.java new file mode 100644 index 000000000..0140b4123 --- /dev/null +++ b/libjava/classpath/external/w3c_dom/org/w3c/dom/ls/LSLoadEvent.java @@ -0,0 +1,35 @@ +/* + * Copyright (c) 2004 World Wide Web Consortium, + * + * (Massachusetts Institute of Technology, European Research Consortium for + * Informatics and Mathematics, Keio University). All Rights Reserved. This + * work is distributed under the W3C(r) Software License [1] in the hope that + * it will be useful, but WITHOUT ANY WARRANTY; without even the implied + * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + * + * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231 + */ + +package org.w3c.dom.ls; + +import org.w3c.dom.Document; +import org.w3c.dom.events.Event; + +/** + * This interface represents a load event object that signals the completion + * of a document load. + * <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 +and Save Specification</a>. + */ +public interface LSLoadEvent extends Event { + /** + * The document that finished loading. + */ + public Document getNewDocument(); + + /** + * The input source that was parsed. + */ + public LSInput getInput(); + +} diff --git a/libjava/classpath/external/w3c_dom/org/w3c/dom/ls/LSOutput.java b/libjava/classpath/external/w3c_dom/org/w3c/dom/ls/LSOutput.java new file mode 100644 index 000000000..789b95a93 --- /dev/null +++ b/libjava/classpath/external/w3c_dom/org/w3c/dom/ls/LSOutput.java @@ -0,0 +1,106 @@ +/* + * Copyright (c) 2004 World Wide Web Consortium, + * + * (Massachusetts Institute of Technology, European Research Consortium for + * Informatics and Mathematics, Keio University). All Rights Reserved. This + * work is distributed under the W3C(r) Software License [1] in the hope that + * it will be useful, but WITHOUT ANY WARRANTY; without even the implied + * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + * + * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231 + */ + +package org.w3c.dom.ls; + +/** + * This interface represents an output destination for data. + * <p> This interface allows an application to encapsulate information about + * an output destination in a single object, which may include a URI, a byte + * stream (possibly with a specified encoding), a base URI, and/or a + * character stream. + * <p> The exact definitions of a byte stream and a character stream are + * binding dependent. + * <p> The application is expected to provide objects that implement this + * interface whenever such objects are needed. The application can either + * provide its own objects that implement this interface, or it can use the + * generic factory method <code>DOMImplementationLS.createLSOutput()</code> + * to create objects that implement this interface. + * <p> The <code>LSSerializer</code> will use the <code>LSOutput</code> object + * to determine where to serialize the output to. The + * <code>LSSerializer</code> will look at the different outputs specified in + * the <code>LSOutput</code> in the following order to know which one to + * output to, the first one that is not null and not an empty string will be + * used: + * <ol> + * <li> <code>LSOutput.characterStream</code> + * </li> + * <li> + * <code>LSOutput.byteStream</code> + * </li> + * <li> <code>LSOutput.systemId</code> + * </li> + * </ol> + * <p> <code>LSOutput</code> objects belong to the application. The DOM + * implementation will never modify them (though it may make copies and + * modify the copies, if necessary). + * <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 +and Save Specification</a>. + */ +public interface LSOutput { + /** + * An attribute of a language and binding dependent type that represents + * a writable stream to which 16-bit units can be output. + */ + public java.io.Writer getCharacterStream(); + /** + * An attribute of a language and binding dependent type that represents + * a writable stream to which 16-bit units can be output. + */ + public void setCharacterStream(java.io.Writer characterStream); + + /** + * An attribute of a language and binding dependent type that represents + * a writable stream of bytes. + */ + public java.io.OutputStream getByteStream(); + /** + * An attribute of a language and binding dependent type that represents + * a writable stream of bytes. + */ + public void setByteStream(java.io.OutputStream byteStream); + + /** + * The system identifier, a URI reference [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>], for this + * output destination. + * <br> If the system ID is a relative URI reference (see section 5 in [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>]), the + * behavior is implementation dependent. + */ + public String getSystemId(); + /** + * The system identifier, a URI reference [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>], for this + * output destination. + * <br> If the system ID is a relative URI reference (see section 5 in [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>]), the + * behavior is implementation dependent. + */ + public void setSystemId(String systemId); + + /** + * The character encoding to use for the output. The encoding must be a + * string acceptable for an XML encoding declaration ([<a href='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0</a>] section + * 4.3.3 "Character Encoding in Entities"), it is recommended that + * character encodings registered (as charsets) with the Internet + * Assigned Numbers Authority [<a href='ftp://ftp.isi.edu/in-notes/iana/assignments/character-sets'>IANA-CHARSETS</a>] + * should be referred to using their registered names. + */ + public String getEncoding(); + /** + * The character encoding to use for the output. The encoding must be a + * string acceptable for an XML encoding declaration ([<a href='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0</a>] section + * 4.3.3 "Character Encoding in Entities"), it is recommended that + * character encodings registered (as charsets) with the Internet + * Assigned Numbers Authority [<a href='ftp://ftp.isi.edu/in-notes/iana/assignments/character-sets'>IANA-CHARSETS</a>] + * should be referred to using their registered names. + */ + public void setEncoding(String encoding); + +} diff --git a/libjava/classpath/external/w3c_dom/org/w3c/dom/ls/LSParser.java b/libjava/classpath/external/w3c_dom/org/w3c/dom/ls/LSParser.java new file mode 100644 index 000000000..41781fa33 --- /dev/null +++ b/libjava/classpath/external/w3c_dom/org/w3c/dom/ls/LSParser.java @@ -0,0 +1,466 @@ +/* + * Copyright (c) 2004 World Wide Web Consortium, + * + * (Massachusetts Institute of Technology, European Research Consortium for + * Informatics and Mathematics, Keio University). All Rights Reserved. This + * work is distributed under the W3C(r) Software License [1] in the hope that + * it will be useful, but WITHOUT ANY WARRANTY; without even the implied + * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + * + * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231 + */ + +package org.w3c.dom.ls; + +import org.w3c.dom.Document; +import org.w3c.dom.DOMConfiguration; +import org.w3c.dom.Node; +import org.w3c.dom.DOMException; + +/** + * An interface to an object that is able to build, or augment, a DOM tree + * from various input sources. + * <p> <code>LSParser</code> provides an API for parsing XML and building the + * corresponding DOM document structure. A <code>LSParser</code> instance + * can be obtained by invoking the + * <code>DOMImplementationLS.createLSParser()</code> method. + * <p> As specified in [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>] + * , when a document is first made available via the LSParser: + * <ul> + * <li> there will + * never be two adjacent nodes of type NODE_TEXT, and there will never be + * empty text nodes. + * </li> + * <li> it is expected that the <code>value</code> and + * <code>nodeValue</code> attributes of an <code>Attr</code> node initially + * return the <a href='http://www.w3.org/TR/2004/REC-xml-20040204#AVNormalize'>XML 1.0 + * normalized value</a>. However, if the parameters "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-validate-if-schema'> + * validate-if-schema</a>" and "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-datatype-normalization'> + * datatype-normalization</a>" are set to <code>true</code>, depending on the attribute normalization + * used, the attribute values may differ from the ones obtained by the XML + * 1.0 attribute normalization. If the parameters "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-datatype-normalization'> + * datatype-normalization</a>" is set to <code>false</code>, the XML 1.0 attribute normalization is + * guaranteed to occur, and if the attributes list does not contain + * namespace declarations, the <code>attributes</code> attribute on + * <code>Element</code> node represents the property <b>[attributes]</b> defined in [<a href='http://www.w3.org/TR/2004/REC-xml-infoset-20040204/'>XML Information Set</a>] + * . + * </li> + * </ul> + * <p> Asynchronous <code>LSParser</code> objects are expected to also + * implement the <code>events::EventTarget</code> interface so that event + * listeners can be registered on asynchronous <code>LSParser</code> + * objects. + * <p> Events supported by asynchronous <code>LSParser</code> objects are: + * <dl> + * <dt>load</dt> + * <dd> + * The <code>LSParser</code> finishes to load the document. See also the + * definition of the <code>LSLoadEvent</code> interface. </dd> + * <dt>progress</dt> + * <dd> The + * <code>LSParser</code> signals progress as data is parsed. This + * specification does not attempt to define exactly when progress events + * should be dispatched. That is intentionally left as + * implementation-dependent. Here is one example of how an application might + * dispatch progress events: Once the parser starts receiving data, a + * progress event is dispatched to indicate that the parsing starts. From + * there on, a progress event is dispatched for every 4096 bytes of data + * that is received and processed. This is only one example, though, and + * implementations can choose to dispatch progress events at any time while + * parsing, or not dispatch them at all. See also the definition of the + * <code>LSProgressEvent</code> interface. </dd> + * </dl> + * <p ><b>Note:</b> All events defined in this specification use the + * namespace URI <code>"http://www.w3.org/2002/DOMLS"</code>. + * <p> While parsing an input source, errors are reported to the application + * through the error handler (<code>LSParser.domConfig</code>'s "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler'> + * error-handler</a>" parameter). This specification does in no way try to define all possible + * errors that can occur while parsing XML, or any other markup, but some + * common error cases are defined. The types (<code>DOMError.type</code>) of + * errors and warnings defined by this specification are: + * <dl> + * <dt> + * <code>"check-character-normalization-failure" [error]</code> </dt> + * <dd> Raised if + * the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-check-character-normalization'> + * check-character-normalization</a>" is set to true and a string is encountered that fails normalization + * checking. </dd> + * <dt><code>"doctype-not-allowed" [fatal]</code></dt> + * <dd> Raised if the + * configuration parameter "disallow-doctype" is set to <code>true</code> + * and a doctype is encountered. </dd> + * <dt><code>"no-input-specified" [fatal]</code></dt> + * <dd> + * Raised when loading a document and no input is specified in the + * <code>LSInput</code> object. </dd> + * <dt> + * <code>"pi-base-uri-not-preserved" [warning]</code></dt> + * <dd> Raised if a processing + * instruction is encountered in a location where the base URI of the + * processing instruction can not be preserved. One example of a case where + * this warning will be raised is if the configuration parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-entities'> + * entities</a>" is set to <code>false</code> and the following XML file is parsed: + * <pre> + * <!DOCTYPE root [ <!ENTITY e SYSTEM 'subdir/myentity.ent' ]> + * <root> &e; </root></pre> + * And <code>subdir/myentity.ent</code> + * contains: + * <pre><one> <two/> </one> <?pi 3.14159?> + * <more/></pre> + * </dd> + * <dt><code>"unbound-prefix-in-entity" [warning]</code></dt> + * <dd> An + * implementation dependent warning that may be raised if the configuration + * parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-namespaces'> + * namespaces</a>" is set to <code>true</code> and an unbound namespace prefix is + * encountered in an entity's replacement text. Raising this warning is not + * enforced since some existing parsers may not recognize unbound namespace + * prefixes in the replacement text of entities. </dd> + * <dt> + * <code>"unknown-character-denormalization" [fatal]</code></dt> + * <dd> Raised if the + * configuration parameter "ignore-unknown-character-denormalizations" is + * set to <code>false</code> and a character is encountered for which the + * processor cannot determine the normalization properties. </dd> + * <dt> + * <code>"unsupported-encoding" [fatal]</code></dt> + * <dd> Raised if an unsupported + * encoding is encountered. </dd> + * <dt><code>"unsupported-media-type" [fatal]</code></dt> + * <dd> + * Raised if the configuration parameter "supported-media-types-only" is set + * to <code>true</code> and an unsupported media type is encountered. </dd> + * </dl> + * <p> In addition to raising the defined errors and warnings, implementations + * are expected to raise implementation specific errors and warnings for any + * other error and warning cases such as IO errors (file not found, + * permission denied,...), XML well-formedness errors, and so on. + * <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 +and Save Specification</a>. + */ +public interface LSParser { + /** + * The <code>DOMConfiguration</code> object used when parsing an input + * source. This <code>DOMConfiguration</code> is specific to the parse + * operation. No parameter values from this <code>DOMConfiguration</code> + * object are passed automatically to the <code>DOMConfiguration</code> + * object on the <code>Document</code> that is created, or used, by the + * parse operation. The DOM application is responsible for passing any + * needed parameter values from this <code>DOMConfiguration</code> + * object to the <code>DOMConfiguration</code> object referenced by the + * <code>Document</code> object. + * <br> In addition to the parameters recognized in on the <a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#DOMConfiguration'> + * DOMConfiguration</a> interface defined in [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>] + * , the <code>DOMConfiguration</code> objects for <code>LSParser</code> + * add or modify the following parameters: + * <dl> + * <dt> + * <code>"charset-overrides-xml-encoding"</code></dt> + * <dd> + * <dl> + * <dt><code>true</code></dt> + * <dd>[<em>optional</em>] (<em>default</em>) If a higher level protocol such as HTTP [<a href='http://www.ietf.org/rfc/rfc2616.txt'>IETF RFC 2616</a>] provides an + * indication of the character encoding of the input stream being + * processed, that will override any encoding specified in the XML + * declaration or the Text declaration (see also section 4.3.3, + * "Character Encoding in Entities", in [<a href='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0</a>]). + * Explicitly setting an encoding in the <code>LSInput</code> overrides + * any encoding from the protocol. </dd> + * <dt><code>false</code></dt> + * <dd>[<em>required</em>] The parser ignores any character set encoding information from + * higher-level protocols. </dd> + * </dl></dd> + * <dt><code>"disallow-doctype"</code></dt> + * <dd> + * <dl> + * <dt> + * <code>true</code></dt> + * <dd>[<em>optional</em>] Throw a fatal <b>"doctype-not-allowed"</b> error if a doctype node is found while parsing the document. This is + * useful when dealing with things like SOAP envelopes where doctype + * nodes are not allowed. </dd> + * <dt><code>false</code></dt> + * <dd>[<em>required</em>] (<em>default</em>) Allow doctype nodes in the document. </dd> + * </dl></dd> + * <dt> + * <code>"ignore-unknown-character-denormalizations"</code></dt> + * <dd> + * <dl> + * <dt> + * <code>true</code></dt> + * <dd>[<em>required</em>] (<em>default</em>) If, while verifying full normalization when [<a href='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>] is + * supported, a processor encounters characters for which it cannot + * determine the normalization properties, then the processor will + * ignore any possible denormalizations caused by these characters. + * This parameter is ignored for [<a href='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0</a>]. </dd> + * <dt> + * <code>false</code></dt> + * <dd>[<em>optional</em>] Report an fatal <b>"unknown-character-denormalization"</b> error if a character is encountered for which the processor cannot + * determine the normalization properties. </dd> + * </dl></dd> + * <dt><code>"infoset"</code></dt> + * <dd> See + * the definition of <code>DOMConfiguration</code> for a description of + * this parameter. Unlike in [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>] + * , this parameter will default to <code>true</code> for + * <code>LSParser</code>. </dd> + * <dt><code>"namespaces"</code></dt> + * <dd> + * <dl> + * <dt><code>true</code></dt> + * <dd>[<em>required</em>] (<em>default</em>) Perform the namespace processing as defined in [<a href='http://www.w3.org/TR/1999/REC-xml-names-19990114/'>XML Namespaces</a>] + * and [<a href='http://www.w3.org/TR/2004/REC-xml-names11-20040204/'>XML Namespaces 1.1</a>] + * . </dd> + * <dt><code>false</code></dt> + * <dd>[<em>optional</em>] Do not perform the namespace processing. </dd> + * </dl></dd> + * <dt> + * <code>"resource-resolver"</code></dt> + * <dd>[<em>required</em>] A reference to a <code>LSResourceResolver</code> object, or null. If + * the value of this parameter is not null when an external resource + * (such as an external XML entity or an XML schema location) is + * encountered, the implementation will request that the + * <code>LSResourceResolver</code> referenced in this parameter resolves + * the resource. </dd> + * <dt><code>"supported-media-types-only"</code></dt> + * <dd> + * <dl> + * <dt> + * <code>true</code></dt> + * <dd>[<em>optional</em>] Check that the media type of the parsed resource is a supported media + * type. If an unsupported media type is encountered, a fatal error of + * type <b>"unsupported-media-type"</b> will be raised. The media types defined in [<a href='http://www.ietf.org/rfc/rfc3023.txt'>IETF RFC 3023</a>] must always + * be accepted. </dd> + * <dt><code>false</code></dt> + * <dd>[<em>required</em>] (<em>default</em>) Accept any media type. </dd> + * </dl></dd> + * <dt><code>"validate"</code></dt> + * <dd> See the definition of + * <code>DOMConfiguration</code> for a description of this parameter. + * Unlike in [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>] + * , the processing of the internal subset is always accomplished, even + * if this parameter is set to <code>false</code>. </dd> + * <dt> + * <code>"validate-if-schema"</code></dt> + * <dd> See the definition of + * <code>DOMConfiguration</code> for a description of this parameter. + * Unlike in [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>] + * , the processing of the internal subset is always accomplished, even + * if this parameter is set to <code>false</code>. </dd> + * <dt> + * <code>"well-formed"</code></dt> + * <dd> See the definition of + * <code>DOMConfiguration</code> for a description of this parameter. + * Unlike in [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>] + * , this parameter cannot be set to <code>false</code>. </dd> + * </dl> + */ + public DOMConfiguration getDomConfig(); + + /** + * When a filter is provided, the implementation will call out to the + * filter as it is constructing the DOM tree structure. The filter can + * choose to remove elements from the document being constructed, or to + * terminate the parsing early. + * <br> The filter is invoked after the operations requested by the + * <code>DOMConfiguration</code> parameters have been applied. For + * example, if "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-validate'> + * validate</a>" is set to <code>true</code>, the validation is done before invoking the + * filter. + */ + public LSParserFilter getFilter(); + /** + * When a filter is provided, the implementation will call out to the + * filter as it is constructing the DOM tree structure. The filter can + * choose to remove elements from the document being constructed, or to + * terminate the parsing early. + * <br> The filter is invoked after the operations requested by the + * <code>DOMConfiguration</code> parameters have been applied. For + * example, if "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-validate'> + * validate</a>" is set to <code>true</code>, the validation is done before invoking the + * filter. + */ + public void setFilter(LSParserFilter filter); + + /** + * <code>true</code> if the <code>LSParser</code> is asynchronous, + * <code>false</code> if it is synchronous. + */ + public boolean getAsync(); + + /** + * <code>true</code> if the <code>LSParser</code> is currently busy + * loading a document, otherwise <code>false</code>. + */ + public boolean getBusy(); + + /** + * Parse an XML document from a resource identified by a + * <code>LSInput</code>. + * @param input The <code>LSInput</code> from which the source of the + * document is to be read. + * @return If the <code>LSParser</code> is a synchronous + * <code>LSParser</code>, the newly created and populated + * <code>Document</code> is returned. If the <code>LSParser</code> is + * asynchronous, <code>null</code> is returned since the document + * object may not yet be constructed when this method returns. + * @exception DOMException + * INVALID_STATE_ERR: Raised if the <code>LSParser</code>'s + * <code>LSParser.busy</code> attribute is <code>true</code>. + * @exception LSException + * PARSE_ERR: Raised if the <code>LSParser</code> was unable to load + * the XML document. DOM applications should attach a + * <code>DOMErrorHandler</code> using the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler'> + * error-handler</a>" if they wish to get details on the error. + */ + public Document parse(LSInput input) + throws DOMException, LSException; + + /** + * Parse an XML document from a location identified by a URI reference [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>]. If the URI + * contains a fragment identifier (see section 4.1 in [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>]), the + * behavior is not defined by this specification, future versions of + * this specification may define the behavior. + * @param uri The location of the XML document to be read. + * @return If the <code>LSParser</code> is a synchronous + * <code>LSParser</code>, the newly created and populated + * <code>Document</code> is returned, or <code>null</code> if an error + * occured. If the <code>LSParser</code> is asynchronous, + * <code>null</code> is returned since the document object may not yet + * be constructed when this method returns. + * @exception DOMException + * INVALID_STATE_ERR: Raised if the <code>LSParser.busy</code> + * attribute is <code>true</code>. + * @exception LSException + * PARSE_ERR: Raised if the <code>LSParser</code> was unable to load + * the XML document. DOM applications should attach a + * <code>DOMErrorHandler</code> using the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler'> + * error-handler</a>" if they wish to get details on the error. + */ + public Document parseURI(String uri) + throws DOMException, LSException; + + // ACTION_TYPES + /** + * Append the result of the parse operation as children of the context + * node. For this action to work, the context node must be an + * <code>Element</code> or a <code>DocumentFragment</code>. + */ + public static final short ACTION_APPEND_AS_CHILDREN = 1; + /** + * Replace all the children of the context node with the result of the + * parse operation. For this action to work, the context node must be an + * <code>Element</code>, a <code>Document</code>, or a + * <code>DocumentFragment</code>. + */ + public static final short ACTION_REPLACE_CHILDREN = 2; + /** + * Insert the result of the parse operation as the immediately preceding + * sibling of the context node. For this action to work the context + * node's parent must be an <code>Element</code> or a + * <code>DocumentFragment</code>. + */ + public static final short ACTION_INSERT_BEFORE = 3; + /** + * Insert the result of the parse operation as the immediately following + * sibling of the context node. For this action to work the context + * node's parent must be an <code>Element</code> or a + * <code>DocumentFragment</code>. + */ + public static final short ACTION_INSERT_AFTER = 4; + /** + * Replace the context node with the result of the parse operation. For + * this action to work, the context node must have a parent, and the + * parent must be an <code>Element</code> or a + * <code>DocumentFragment</code>. + */ + public static final short ACTION_REPLACE = 5; + + /** + * Parse an XML fragment from a resource identified by a + * <code>LSInput</code> and insert the content into an existing document + * at the position specified with the <code>context</code> and + * <code>action</code> arguments. When parsing the input stream, the + * context node (or its parent, depending on where the result will be + * inserted) is used for resolving unbound namespace prefixes. The + * context node's <code>ownerDocument</code> node (or the node itself if + * the node of type <code>DOCUMENT_NODE</code>) is used to resolve + * default attributes and entity references. + * <br> As the new data is inserted into the document, at least one + * mutation event is fired per new immediate child or sibling of the + * context node. + * <br> If the context node is a <code>Document</code> node and the action + * is <code>ACTION_REPLACE_CHILDREN</code>, then the document that is + * passed as the context node will be changed such that its + * <code>xmlEncoding</code>, <code>documentURI</code>, + * <code>xmlVersion</code>, <code>inputEncoding</code>, + * <code>xmlStandalone</code>, and all other such attributes are set to + * what they would be set to if the input source was parsed using + * <code>LSParser.parse()</code>. + * <br> This method is always synchronous, even if the + * <code>LSParser</code> is asynchronous (<code>LSParser.async</code> is + * <code>true</code>). + * <br> If an error occurs while parsing, the caller is notified through + * the <code>ErrorHandler</code> instance associated with the "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler'> + * error-handler</a>" parameter of the <code>DOMConfiguration</code>. + * <br> When calling <code>parseWithContext</code>, the values of the + * following configuration parameters will be ignored and their default + * values will always be used instead: "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-validate'> + * validate</a>", "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-validate-if-schema'> + * validate-if-schema</a>", and "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-element-content-whitespace'> + * element-content-whitespace</a>". Other parameters will be treated normally, and the parser is expected + * to call the <code>LSParserFilter</code> just as if a whole document + * was parsed. + * @param input The <code>LSInput</code> from which the source document + * is to be read. The source document must be an XML fragment, i.e. + * anything except a complete XML document (except in the case where + * the context node of type <code>DOCUMENT_NODE</code>, and the action + * is <code>ACTION_REPLACE_CHILDREN</code>), a DOCTYPE (internal + * subset), entity declaration(s), notation declaration(s), or XML or + * text declaration(s). + * @param contextArg The node that is used as the context for the data + * that is being parsed. This node must be a <code>Document</code> + * node, a <code>DocumentFragment</code> node, or a node of a type + * that is allowed as a child of an <code>Element</code> node, e.g. it + * cannot be an <code>Attribute</code> node. + * @param action This parameter describes which action should be taken + * between the new set of nodes being inserted and the existing + * children of the context node. The set of possible actions is + * defined in <code>ACTION_TYPES</code> above. + * @return Return the node that is the result of the parse operation. If + * the result is more than one top-level node, the first one is + * returned. + * @exception DOMException + * HIERARCHY_REQUEST_ERR: Raised if the content cannot replace, be + * inserted before, after, or as a child of the context node (see also + * <code>Node.insertBefore</code> or <code>Node.replaceChild</code> in [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>] + * ). + * <br> NOT_SUPPORTED_ERR: Raised if the <code>LSParser</code> doesn't + * support this method, or if the context node is of type + * <code>Document</code> and the DOM implementation doesn't support + * the replacement of the <code>DocumentType</code> child or + * <code>Element</code> child. + * <br> NO_MODIFICATION_ALLOWED_ERR: Raised if the context node is a + * read only node and the content is being appended to its child list, + * or if the parent node of the context node is read only node and the + * content is being inserted in its child list. + * <br> INVALID_STATE_ERR: Raised if the <code>LSParser.busy</code> + * attribute is <code>true</code>. + * @exception LSException + * PARSE_ERR: Raised if the <code>LSParser</code> was unable to load + * the XML fragment. DOM applications should attach a + * <code>DOMErrorHandler</code> using the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler'> + * error-handler</a>" if they wish to get details on the error. + */ + public Node parseWithContext(LSInput input, + Node contextArg, + short action) + throws DOMException, LSException; + + /** + * Abort the loading of the document that is currently being loaded by + * the <code>LSParser</code>. If the <code>LSParser</code> is currently + * not busy, a call to this method does nothing. + */ + public void abort(); + +} diff --git a/libjava/classpath/external/w3c_dom/org/w3c/dom/ls/LSParserFilter.java b/libjava/classpath/external/w3c_dom/org/w3c/dom/ls/LSParserFilter.java new file mode 100644 index 000000000..00db4d3c2 --- /dev/null +++ b/libjava/classpath/external/w3c_dom/org/w3c/dom/ls/LSParserFilter.java @@ -0,0 +1,172 @@ +/* + * Copyright (c) 2004 World Wide Web Consortium, + * + * (Massachusetts Institute of Technology, European Research Consortium for + * Informatics and Mathematics, Keio University). All Rights Reserved. This + * work is distributed under the W3C(r) Software License [1] in the hope that + * it will be useful, but WITHOUT ANY WARRANTY; without even the implied + * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + * + * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231 + */ + +package org.w3c.dom.ls; + +import org.w3c.dom.Node; +import org.w3c.dom.Element; + +/** + * <code>LSParserFilter</code>s provide applications the ability to examine + * nodes as they are being constructed while parsing. As each node is + * examined, it may be modified or removed, or the entire parse may be + * terminated early. + * <p> At the time any of the filter methods are called by the parser, the + * owner Document and DOMImplementation objects exist and are accessible. + * The document element is never passed to the <code>LSParserFilter</code> + * methods, i.e. it is not possible to filter out the document element. + * <code>Document</code>, <code>DocumentType</code>, <code>Notation</code>, + * <code>Entity</code>, and <code>Attr</code> nodes are never passed to the + * <code>acceptNode</code> method on the filter. The child nodes of an + * <code>EntityReference</code> node are passed to the filter if the + * parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-entities'> + * entities</a>" is set to <code>false</code>. Note that, as described by the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-entities'> + * entities</a>", unexpanded entity reference nodes are never discarded and are always + * passed to the filter. + * <p> All validity checking while parsing a document occurs on the source + * document as it appears on the input stream, not on the DOM document as it + * is built in memory. With filters, the document in memory may be a subset + * of the document on the stream, and its validity may have been affected by + * the filtering. + * <p> All default attributes must be present on elements when the elements + * are passed to the filter methods. All other default content must be + * passed to the filter methods. + * <p> DOM applications must not raise exceptions in a filter. The effect of + * throwing exceptions from a filter is DOM implementation dependent. + * <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 +and Save Specification</a>. + */ +public interface LSParserFilter { + // Constants returned by startElement and acceptNode + /** + * Accept the node. + */ + public static final short FILTER_ACCEPT = 1; + /** + * Reject the node and its children. + */ + public static final short FILTER_REJECT = 2; + /** + * Skip this single node. The children of this node will still be + * considered. + */ + public static final short FILTER_SKIP = 3; + /** + * Interrupt the normal processing of the document. + */ + public static final short FILTER_INTERRUPT = 4; + + /** + * The parser will call this method after each <code>Element</code> start + * tag has been scanned, but before the remainder of the + * <code>Element</code> is processed. The intent is to allow the + * element, including any children, to be efficiently skipped. Note that + * only element nodes are passed to the <code>startElement</code> + * function. + * <br>The element node passed to <code>startElement</code> for filtering + * will include all of the Element's attributes, but none of the + * children nodes. The Element may not yet be in place in the document + * being constructed (it may not have a parent node.) + * <br>A <code>startElement</code> filter function may access or change + * the attributes for the Element. Changing Namespace declarations will + * have no effect on namespace resolution by the parser. + * <br>For efficiency, the Element node passed to the filter may not be + * the same one as is actually placed in the tree if the node is + * accepted. And the actual node (node object identity) may be reused + * during the process of reading in and filtering a document. + * @param elementArg The newly encountered element. At the time this + * method is called, the element is incomplete - it will have its + * attributes, but no children. + * @return + * <ul> + * <li> <code>FILTER_ACCEPT</code> if the <code>Element</code> should + * be included in the DOM document being built. + * </li> + * <li> + * <code>FILTER_REJECT</code> if the <code>Element</code> and all of + * its children should be rejected. + * </li> + * <li> <code>FILTER_SKIP</code> if the + * <code>Element</code> should be skipped. All of its children are + * inserted in place of the skipped <code>Element</code> node. + * </li> + * <li> + * <code>FILTER_INTERRUPT</code> if the filter wants to stop the + * processing of the document. Interrupting the processing of the + * document does no longer guarantee that the resulting DOM tree is + * XML well-formed. The <code>Element</code> is rejected. + * </li> + * </ul> Returning + * any other values will result in unspecified behavior. + */ + public short startElement(Element elementArg); + + /** + * This method will be called by the parser at the completion of the + * parsing of each node. The node and all of its descendants will exist + * and be complete. The parent node will also exist, although it may be + * incomplete, i.e. it may have additional children that have not yet + * been parsed. Attribute nodes are never passed to this function. + * <br>From within this method, the new node may be freely modified - + * children may be added or removed, text nodes modified, etc. The state + * of the rest of the document outside this node is not defined, and the + * affect of any attempt to navigate to, or to modify any other part of + * the document is undefined. + * <br>For validating parsers, the checks are made on the original + * document, before any modification by the filter. No validity checks + * are made on any document modifications made by the filter. + * <br>If this new node is rejected, the parser might reuse the new node + * and any of its descendants. + * @param nodeArg The newly constructed element. At the time this method + * is called, the element is complete - it has all of its children + * (and their children, recursively) and attributes, and is attached + * as a child to its parent. + * @return + * <ul> + * <li> <code>FILTER_ACCEPT</code> if this <code>Node</code> should + * be included in the DOM document being built. + * </li> + * <li> + * <code>FILTER_REJECT</code> if the <code>Node</code> and all of its + * children should be rejected. + * </li> + * <li> <code>FILTER_SKIP</code> if the + * <code>Node</code> should be skipped and the <code>Node</code> + * should be replaced by all the children of the <code>Node</code>. + * </li> + * <li> + * <code>FILTER_INTERRUPT</code> if the filter wants to stop the + * processing of the document. Interrupting the processing of the + * document does no longer guarantee that the resulting DOM tree is + * XML well-formed. The <code>Node</code> is accepted and will be the + * last completely parsed node. + * </li> + * </ul> + */ + public short acceptNode(Node nodeArg); + + /** + * Tells the <code>LSParser</code> what types of nodes to show to the + * method <code>LSParserFilter.acceptNode</code>. If a node is not shown + * to the filter using this attribute, it is automatically included in + * the DOM document being built. See <code>NodeFilter</code> for + * definition of the constants. The constants <code>SHOW_ATTRIBUTE</code> + * , <code>SHOW_DOCUMENT</code>, <code>SHOW_DOCUMENT_TYPE</code>, + * <code>SHOW_NOTATION</code>, <code>SHOW_ENTITY</code>, and + * <code>SHOW_DOCUMENT_FRAGMENT</code> are meaningless here. Those nodes + * will never be passed to <code>LSParserFilter.acceptNode</code>. + * <br> The constants used here are defined in [<a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113'>DOM Level 2 Traversal and Range</a>] + * . + */ + public int getWhatToShow(); + +} diff --git a/libjava/classpath/external/w3c_dom/org/w3c/dom/ls/LSProgressEvent.java b/libjava/classpath/external/w3c_dom/org/w3c/dom/ls/LSProgressEvent.java new file mode 100644 index 000000000..adf7b098c --- /dev/null +++ b/libjava/classpath/external/w3c_dom/org/w3c/dom/ls/LSProgressEvent.java @@ -0,0 +1,48 @@ +/* + * Copyright (c) 2004 World Wide Web Consortium, + * + * (Massachusetts Institute of Technology, European Research Consortium for + * Informatics and Mathematics, Keio University). All Rights Reserved. This + * work is distributed under the W3C(r) Software License [1] in the hope that + * it will be useful, but WITHOUT ANY WARRANTY; without even the implied + * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + * + * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231 + */ + +package org.w3c.dom.ls; + +import org.w3c.dom.events.Event; + +/** + * This interface represents a progress event object that notifies the + * application about progress as a document is parsed. It extends the + * <code>Event</code> interface defined in [<a href='http://www.w3.org/TR/2003/NOTE-DOM-Level-3-Events-20031107'>DOM Level 3 Events</a>] + * . + * <p> The units used for the attributes <code>position</code> and + * <code>totalSize</code> are not specified and can be implementation and + * input dependent. + * <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 +and Save Specification</a>. + */ +public interface LSProgressEvent extends Event { + /** + * The input source that is being parsed. + */ + public LSInput getInput(); + + /** + * The current position in the input source, including all external + * entities and other resources that have been read. + */ + public int getPosition(); + + /** + * The total size of the document including all external resources, this + * number might change as a document is being parsed if references to + * more external resources are seen. A value of <code>0</code> is + * returned if the total size cannot be determined or estimated. + */ + public int getTotalSize(); + +} diff --git a/libjava/classpath/external/w3c_dom/org/w3c/dom/ls/LSResourceResolver.java b/libjava/classpath/external/w3c_dom/org/w3c/dom/ls/LSResourceResolver.java new file mode 100644 index 000000000..5301beb8f --- /dev/null +++ b/libjava/classpath/external/w3c_dom/org/w3c/dom/ls/LSResourceResolver.java @@ -0,0 +1,81 @@ +/* + * Copyright (c) 2004 World Wide Web Consortium, + * + * (Massachusetts Institute of Technology, European Research Consortium for + * Informatics and Mathematics, Keio University). All Rights Reserved. This + * work is distributed under the W3C(r) Software License [1] in the hope that + * it will be useful, but WITHOUT ANY WARRANTY; without even the implied + * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + * + * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231 + */ + +package org.w3c.dom.ls; + +/** + * <code>LSResourceResolver</code> provides a way for applications to + * redirect references to external resources. + * <p> Applications needing to implement custom handling for external + * resources can implement this interface and register their implementation + * by setting the "resource-resolver" parameter of + * <code>DOMConfiguration</code> objects attached to <code>LSParser</code> + * and <code>LSSerializer</code>. It can also be register on + * <code>DOMConfiguration</code> objects attached to <code>Document</code> + * if the "LS" feature is supported. + * <p> The <code>LSParser</code> will then allow the application to intercept + * any external entities, including the external DTD subset and external + * parameter entities, before including them. The top-level document entity + * is never passed to the <code>resolveResource</code> method. + * <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 ><b>Note:</b> <code>LSResourceResolver</code> is based on the SAX2 [<a href='http://www.saxproject.org/'>SAX</a>] <code>EntityResolver</code> + * interface. + * <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 +and Save Specification</a>. + */ +public interface LSResourceResolver { + /** + * Allow the application to resolve external resources. + * <br> The <code>LSParser</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>LSParser</code> resolve the external resource itself, that + * it use an alternative URI, or that it use an entirely different input + * source. + * <br> 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). + * @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 + * (i.e. entities), applications must use the value + * <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>] + * , applications must use the value + * <code>"http://www.w3.org/2001/XMLSchema"</code>. 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 [<a href='http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/'>XML Schema Part 1</a>] + * 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 [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>], 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 <code>LSInput</code> object describing the new input + * source, or <code>null</code> to request that the parser open a + * regular URI connection to the resource. + */ + public LSInput resolveResource(String type, + String namespaceURI, + String publicId, + String systemId, + String baseURI); + +} diff --git a/libjava/classpath/external/w3c_dom/org/w3c/dom/ls/LSSerializer.java b/libjava/classpath/external/w3c_dom/org/w3c/dom/ls/LSSerializer.java new file mode 100644 index 000000000..2a6fb6ff4 --- /dev/null +++ b/libjava/classpath/external/w3c_dom/org/w3c/dom/ls/LSSerializer.java @@ -0,0 +1,436 @@ +/* + * Copyright (c) 2004 World Wide Web Consortium, + * + * (Massachusetts Institute of Technology, European Research Consortium for + * Informatics and Mathematics, Keio University). All Rights Reserved. This + * work is distributed under the W3C(r) Software License [1] in the hope that + * it will be useful, but WITHOUT ANY WARRANTY; without even the implied + * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + * + * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231 + */ + +package org.w3c.dom.ls; + +import org.w3c.dom.DOMConfiguration; +import org.w3c.dom.Node; +import org.w3c.dom.DOMException; + +/** + * A <code>LSSerializer</code> provides an API for serializing (writing) a + * DOM document out into XML. The XML data is written to a string or an + * output stream. Any changes or fixups made during the serialization affect + * only the serialized data. The <code>Document</code> object and its + * children are never altered by the serialization operation. + * <p> During serialization of XML data, namespace fixup is done as defined in [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>] + * , Appendix B. [<a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113'>DOM Level 2 Core</a>] + * allows empty strings as a real namespace URI. If the + * <code>namespaceURI</code> of a <code>Node</code> is empty string, the + * serialization will treat them as <code>null</code>, ignoring the prefix + * if any. + * <p> <code>LSSerializer</code> accepts any node type for serialization. For + * nodes of type <code>Document</code> or <code>Entity</code>, well-formed + * XML will be created when possible (well-formedness is guaranteed if the + * document or entity comes from a parse operation and is unchanged since it + * was created). The serialized output for these node types is either as a + * XML document or an External XML Entity, respectively, and is acceptable + * input for an XML parser. For all other types of nodes the serialized form + * is implementation dependent. + * <p>Within a <code>Document</code>, <code>DocumentFragment</code>, or + * <code>Entity</code> being serialized, <code>Nodes</code> are processed as + * follows + * <ul> + * <li> <code>Document</code> nodes are written, including the XML + * declaration (unless the parameter "xml-declaration" is set to + * <code>false</code>) and a DTD subset, if one exists in the DOM. Writing a + * <code>Document</code> node serializes the entire document. + * </li> + * <li> + * <code>Entity</code> nodes, when written directly by + * <code>LSSerializer.write</code>, outputs the entity expansion but no + * namespace fixup is done. The resulting output will be valid as an + * external entity. + * </li> + * <li> If the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-entities'> + * entities</a>" is set to <code>true</code>, <code>EntityReference</code> nodes are + * serialized as an entity reference of the form " + * <code>&entityName;</code>" in the output. Child nodes (the expansion) + * of the entity reference are ignored. If the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-entities'> + * entities</a>" is set to <code>false</code>, only the children of the entity reference + * are serialized. <code>EntityReference</code> nodes with no children (no + * corresponding <code>Entity</code> node or the corresponding + * <code>Entity</code> nodes have no children) are always serialized. + * </li> + * <li> + * <code>CDATAsections</code> containing content characters that cannot be + * represented in the specified output encoding are handled according to the + * "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-split-cdata-sections'> + * split-cdata-sections</a>" parameter. If the parameter is set to <code>true</code>, + * <code>CDATAsections</code> are split, and the unrepresentable characters + * are serialized as numeric character references in ordinary content. The + * exact position and number of splits is not specified. If the parameter + * is set to <code>false</code>, unrepresentable characters in a + * <code>CDATAsection</code> are reported as + * <code>"wf-invalid-character"</code> errors if the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-well-formed'> + * well-formed</a>" is set to <code>true</code>. The error is not recoverable - there is no + * mechanism for supplying alternative characters and continuing with the + * serialization. + * </li> + * <li> <code>DocumentFragment</code> nodes are serialized by + * serializing the children of the document fragment in the order they + * appear in the document fragment. + * </li> + * <li> All other node types (Element, Text, + * etc.) are serialized to their corresponding XML source form. + * </li> + * </ul> + * <p ><b>Note:</b> The serialization of a <code>Node</code> does not always + * generate a well-formed XML document, i.e. a <code>LSParser</code> might + * throw fatal errors when parsing the resulting serialization. + * <p> Within the character data of a document (outside of markup), any + * characters that cannot be represented directly are replaced with + * character references. Occurrences of '<' and '&' are replaced by + * the predefined entities &lt; and &amp;. The other predefined + * entities (&gt;, &apos;, and &quot;) might not be used, except + * where needed (e.g. using &gt; in cases such as ']]>'). Any + * characters that cannot be represented directly in the output character + * encoding are serialized as numeric character references (and since + * character encoding standards commonly use hexadecimal representations of + * characters, using the hexadecimal representation when serializing + * character references is encouraged). + * <p> To allow attribute values to contain both single and double quotes, the + * apostrophe or single-quote character (') may be represented as + * "&apos;", and the double-quote character (") as "&quot;". New + * line characters and other characters that cannot be represented directly + * in attribute values in the output character encoding are serialized as a + * numeric character reference. + * <p> Within markup, but outside of attributes, any occurrence of a character + * that cannot be represented in the output character encoding is reported + * as a <code>DOMError</code> fatal error. An example would be serializing + * the element <LaCa\u00f1ada/> with <code>encoding="us-ascii"</code>. + * This will result with a generation of a <code>DOMError</code> + * "wf-invalid-character-in-node-name" (as proposed in "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-well-formed'> + * well-formed</a>"). + * <p> When requested by setting the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-normalize-characters'> + * normalize-characters</a>" on <code>LSSerializer</code> to true, character normalization is + * performed according to the definition of <a href='http://www.w3.org/TR/2004/REC-xml11-20040204/#dt-fullnorm'>fully + * normalized</a> characters included in appendix E of [<a href='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>] on all + * data to be serialized, both markup and character data. The character + * normalization process affects only the data as it is being written; it + * does not alter the DOM's view of the document after serialization has + * completed. + * <p> Implementations are required to support the encodings "UTF-8", + * "UTF-16", "UTF-16BE", and "UTF-16LE" to guarantee that data is + * serializable in all encodings that are required to be supported by all + * XML parsers. When the encoding is UTF-8, whether or not a byte order mark + * is serialized, or if the output is big-endian or little-endian, is + * implementation dependent. When the encoding is UTF-16, whether or not the + * output is big-endian or little-endian is implementation dependent, but a + * Byte Order Mark must be generated for non-character outputs, such as + * <code>LSOutput.byteStream</code> or <code>LSOutput.systemId</code>. If + * the Byte Order Mark is not generated, a "byte-order-mark-needed" warning + * is reported. When the encoding is UTF-16LE or UTF-16BE, the output is + * big-endian (UTF-16BE) or little-endian (UTF-16LE) and the Byte Order Mark + * is not be generated. In all cases, the encoding declaration, if + * generated, will correspond to the encoding used during the serialization + * (e.g. <code>encoding="UTF-16"</code> will appear if UTF-16 was + * requested). + * <p> Namespaces are fixed up during serialization, the serialization process + * will verify that namespace declarations, namespace prefixes and the + * namespace URI associated with elements and attributes are consistent. If + * inconsistencies are found, the serialized form of the document will be + * altered to remove them. The method used for doing the namespace fixup + * while serializing a document is the algorithm defined in Appendix B.1, + * "Namespace normalization", of [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>] + * . + * <p> While serializing a document, the parameter "discard-default-content" + * controls whether or not non-specified data is serialized. + * <p> While serializing, errors and warnings are reported to the application + * through the error handler (<code>LSSerializer.domConfig</code>'s "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler'> + * error-handler</a>" parameter). This specification does in no way try to define all possible + * errors and warnings that can occur while serializing a DOM node, but some + * common error and warning cases are defined. The types ( + * <code>DOMError.type</code>) of errors and warnings defined by this + * specification are: + * <dl> + * <dt><code>"no-output-specified" [fatal]</code></dt> + * <dd> Raised when + * writing to a <code>LSOutput</code> if no output is specified in the + * <code>LSOutput</code>. </dd> + * <dt> + * <code>"unbound-prefix-in-entity-reference" [fatal]</code> </dt> + * <dd> Raised if the + * configuration parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-namespaces'> + * namespaces</a>" is set to <code>true</code> and an entity whose replacement text + * contains unbound namespace prefixes is referenced in a location where + * there are no bindings for the namespace prefixes. </dd> + * <dt> + * <code>"unsupported-encoding" [fatal]</code></dt> + * <dd> Raised if an unsupported + * encoding is encountered. </dd> + * </dl> + * <p> In addition to raising the defined errors and warnings, implementations + * are expected to raise implementation specific errors and warnings for any + * other error and warning cases such as IO errors (file not found, + * permission denied,...) and so on. + * <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 +and Save Specification</a>. + */ +public interface LSSerializer { + /** + * The <code>DOMConfiguration</code> object used by the + * <code>LSSerializer</code> when serializing a DOM node. + * <br> In addition to the parameters recognized by the <a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#DOMConfiguration'> + * DOMConfiguration</a> interface defined in [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>] + * , the <code>DOMConfiguration</code> objects for + * <code>LSSerializer</code> adds, or modifies, the following + * parameters: + * <dl> + * <dt><code>"canonical-form"</code></dt> + * <dd> + * <dl> + * <dt><code>true</code></dt> + * <dd>[<em>optional</em>] Writes the document according to the rules specified in [<a href='http://www.w3.org/TR/2001/REC-xml-c14n-20010315'>Canonical XML</a>]. + * In addition to the behavior described in "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-canonical-form'> + * canonical-form</a>" [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>] + * , setting this parameter to <code>true</code> will set the parameters + * "format-pretty-print", "discard-default-content", and "xml-declaration + * ", to <code>false</code>. Setting one of those parameters to + * <code>true</code> will set this parameter to <code>false</code>. + * Serializing an XML 1.1 document when "canonical-form" is + * <code>true</code> will generate a fatal error. </dd> + * <dt><code>false</code></dt> + * <dd>[<em>required</em>] (<em>default</em>) Do not canonicalize the output. </dd> + * </dl></dd> + * <dt><code>"discard-default-content"</code></dt> + * <dd> + * <dl> + * <dt> + * <code>true</code></dt> + * <dd>[<em>required</em>] (<em>default</em>) Use the <code>Attr.specified</code> attribute to decide what attributes + * should be discarded. Note that some implementations might use + * whatever information available to the implementation (i.e. XML + * schema, DTD, the <code>Attr.specified</code> attribute, and so on) to + * determine what attributes and content to discard if this parameter is + * set to <code>true</code>. </dd> + * <dt><code>false</code></dt> + * <dd>[<em>required</em>]Keep all attributes and all content.</dd> + * </dl></dd> + * <dt><code>"format-pretty-print"</code></dt> + * <dd> + * <dl> + * <dt> + * <code>true</code></dt> + * <dd>[<em>optional</em>] Formatting the output by adding whitespace to produce a pretty-printed, + * indented, human-readable form. The exact form of the transformations + * is not specified by this specification. Pretty-printing changes the + * content of the document and may affect the validity of the document, + * validating implementations should preserve validity. </dd> + * <dt> + * <code>false</code></dt> + * <dd>[<em>required</em>] (<em>default</em>) Don't pretty-print the result. </dd> + * </dl></dd> + * <dt> + * <code>"ignore-unknown-character-denormalizations"</code> </dt> + * <dd> + * <dl> + * <dt> + * <code>true</code></dt> + * <dd>[<em>required</em>] (<em>default</em>) If, while verifying full normalization when [<a href='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>] is + * supported, a character is encountered for which the normalization + * properties cannot be determined, then raise a + * <code>"unknown-character-denormalization"</code> warning (instead of + * raising an error, if this parameter is not set) and ignore any + * possible denormalizations caused by these characters. </dd> + * <dt> + * <code>false</code></dt> + * <dd>[<em>optional</em>] Report a fatal error if a character is encountered for which the + * processor cannot determine the normalization properties. </dd> + * </dl></dd> + * <dt> + * <code>"normalize-characters"</code></dt> + * <dd> This parameter is equivalent to + * the one defined by <code>DOMConfiguration</code> in [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>] + * . Unlike in the Core, the default value for this parameter is + * <code>true</code>. While DOM implementations are not required to + * support <a href='http://www.w3.org/TR/2004/REC-xml11-20040204/#dt-fullnorm'>fully + * normalizing</a> the characters in the document according to appendix E of [<a href='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>], this + * parameter must be activated by default if supported. </dd> + * <dt> + * <code>"xml-declaration"</code></dt> + * <dd> + * <dl> + * <dt><code>true</code></dt> + * <dd>[<em>required</em>] (<em>default</em>) If a <code>Document</code>, <code>Element</code>, or <code>Entity</code> + * node is serialized, the XML declaration, or text declaration, should + * be included. The version (<code>Document.xmlVersion</code> if the + * document is a Level 3 document and the version is non-null, otherwise + * use the value "1.0"), and the output encoding (see + * <code>LSSerializer.write</code> for details on how to find the output + * encoding) are specified in the serialized XML declaration. </dd> + * <dt> + * <code>false</code></dt> + * <dd>[<em>required</em>] Do not serialize the XML and text declarations. Report a + * <code>"xml-declaration-needed"</code> warning if this will cause + * problems (i.e. the serialized data is of an XML version other than [<a href='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0</a>], or an + * encoding would be needed to be able to re-parse the serialized data). </dd> + * </dl></dd> + * </dl> + */ + public DOMConfiguration getDomConfig(); + + /** + * The end-of-line sequence of characters to be used in the XML being + * written out. Any string is supported, but XML treats only a certain + * set of characters sequence as end-of-line (See section 2.11, + * "End-of-Line Handling" in [<a href='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0</a>], if the + * serialized content is XML 1.0 or section 2.11, "End-of-Line Handling" + * in [<a href='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>], if the + * serialized content is XML 1.1). Using other character sequences than + * the recommended ones can result in a document that is either not + * serializable or not well-formed). + * <br> On retrieval, the default value of this attribute is the + * implementation specific default end-of-line sequence. DOM + * implementations should choose the default to match the usual + * convention for text files in the environment being used. + * Implementations must choose a default sequence that matches one of + * those allowed by XML 1.0 or XML 1.1, depending on the serialized + * content. Setting this attribute to <code>null</code> will reset its + * value to the default value. + * <br> + */ + public String getNewLine(); + /** + * The end-of-line sequence of characters to be used in the XML being + * written out. Any string is supported, but XML treats only a certain + * set of characters sequence as end-of-line (See section 2.11, + * "End-of-Line Handling" in [<a href='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0</a>], if the + * serialized content is XML 1.0 or section 2.11, "End-of-Line Handling" + * in [<a href='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>], if the + * serialized content is XML 1.1). Using other character sequences than + * the recommended ones can result in a document that is either not + * serializable or not well-formed). + * <br> On retrieval, the default value of this attribute is the + * implementation specific default end-of-line sequence. DOM + * implementations should choose the default to match the usual + * convention for text files in the environment being used. + * Implementations must choose a default sequence that matches one of + * those allowed by XML 1.0 or XML 1.1, depending on the serialized + * content. Setting this attribute to <code>null</code> will reset its + * value to the default value. + * <br> + */ + public void setNewLine(String newLine); + + /** + * When the application provides a filter, the serializer will call out + * to the filter before serializing each Node. The filter implementation + * can choose to remove the node from the stream or to terminate the + * serialization early. + * <br> The filter is invoked after the operations requested by the + * <code>DOMConfiguration</code> parameters have been applied. For + * example, CDATA sections won't be passed to the filter if "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-cdata-sections'> + * cdata-sections</a>" is set to <code>false</code>. + */ + public LSSerializerFilter getFilter(); + /** + * When the application provides a filter, the serializer will call out + * to the filter before serializing each Node. The filter implementation + * can choose to remove the node from the stream or to terminate the + * serialization early. + * <br> The filter is invoked after the operations requested by the + * <code>DOMConfiguration</code> parameters have been applied. For + * example, CDATA sections won't be passed to the filter if "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-cdata-sections'> + * cdata-sections</a>" is set to <code>false</code>. + */ + public void setFilter(LSSerializerFilter filter); + + /** + * Serialize the specified node as described above in the general + * description of the <code>LSSerializer</code> interface. The output is + * written to the supplied <code>LSOutput</code>. + * <br> When writing to a <code>LSOutput</code>, the encoding is found by + * looking at the encoding information that is reachable through the + * <code>LSOutput</code> and the item to be written (or its owner + * document) in this order: + * <ol> + * <li> <code>LSOutput.encoding</code>, + * </li> + * <li> + * <code>Document.inputEncoding</code>, + * </li> + * <li> + * <code>Document.xmlEncoding</code>. + * </li> + * </ol> + * <br> If no encoding is reachable through the above properties, a + * default encoding of "UTF-8" will be used. If the specified encoding + * is not supported an "unsupported-encoding" fatal error is raised. + * <br> If no output is specified in the <code>LSOutput</code>, a + * "no-output-specified" fatal error is raised. + * <br> The implementation is responsible of associating the appropriate + * media type with the serialized data. + * <br> When writing to a HTTP URI, a HTTP PUT is performed. When writing + * to other types of URIs, the mechanism for writing the data to the URI + * is implementation dependent. + * @param nodeArg The node to serialize. + * @param destination The destination for the serialized DOM. + * @return Returns <code>true</code> if <code>node</code> was + * successfully serialized. Return <code>false</code> in case the + * normal processing stopped but the implementation kept serializing + * the document; the result of the serialization being implementation + * dependent then. + * @exception LSException + * SERIALIZE_ERR: Raised if the <code>LSSerializer</code> was unable to + * serialize the node. DOM applications should attach a + * <code>DOMErrorHandler</code> using the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler'> + * error-handler</a>" if they wish to get details on the error. + */ + public boolean write(Node nodeArg, + LSOutput destination) + throws LSException; + + /** + * A convenience method that acts as if <code>LSSerializer.write</code> + * was called with a <code>LSOutput</code> with no encoding specified + * and <code>LSOutput.systemId</code> set to the <code>uri</code> + * argument. + * @param nodeArg The node to serialize. + * @param uri The URI to write to. + * @return Returns <code>true</code> if <code>node</code> was + * successfully serialized. Return <code>false</code> in case the + * normal processing stopped but the implementation kept serializing + * the document; the result of the serialization being implementation + * dependent then. + * @exception LSException + * SERIALIZE_ERR: Raised if the <code>LSSerializer</code> was unable to + * serialize the node. DOM applications should attach a + * <code>DOMErrorHandler</code> using the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler'> + * error-handler</a>" if they wish to get details on the error. + */ + public boolean writeToURI(Node nodeArg, + String uri) + throws LSException; + + /** + * Serialize the specified node as described above in the general + * description of the <code>LSSerializer</code> interface. The output is + * written to a <code>DOMString</code> that is returned to the caller. + * The encoding used is the encoding of the <code>DOMString</code> type, + * i.e. UTF-16. Note that no Byte Order Mark is generated in a + * <code>DOMString</code> object. + * @param nodeArg The node to serialize. + * @return Returns the serialized data. + * @exception DOMException + * DOMSTRING_SIZE_ERR: Raised if the resulting string is too long to + * fit in a <code>DOMString</code>. + * @exception LSException + * SERIALIZE_ERR: Raised if the <code>LSSerializer</code> was unable to + * serialize the node. DOM applications should attach a + * <code>DOMErrorHandler</code> using the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler'> + * error-handler</a>" if they wish to get details on the error. + */ + public String writeToString(Node nodeArg) + throws DOMException, LSException; + +} diff --git a/libjava/classpath/external/w3c_dom/org/w3c/dom/ls/LSSerializerFilter.java b/libjava/classpath/external/w3c_dom/org/w3c/dom/ls/LSSerializerFilter.java new file mode 100644 index 000000000..b04655677 --- /dev/null +++ b/libjava/classpath/external/w3c_dom/org/w3c/dom/ls/LSSerializerFilter.java @@ -0,0 +1,63 @@ +/* + * Copyright (c) 2004 World Wide Web Consortium, + * + * (Massachusetts Institute of Technology, European Research Consortium for + * Informatics and Mathematics, Keio University). All Rights Reserved. This + * work is distributed under the W3C(r) Software License [1] in the hope that + * it will be useful, but WITHOUT ANY WARRANTY; without even the implied + * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + * + * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231 + */ + +package org.w3c.dom.ls; + +import org.w3c.dom.traversal.NodeFilter; + +/** + * <code>LSSerializerFilter</code>s provide applications the ability to + * examine nodes as they are being serialized and decide what nodes should + * be serialized or not. The <code>LSSerializerFilter</code> interface is + * based on the <code>NodeFilter</code> interface defined in [<a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113'>DOM Level 2 Traversal and Range</a>] + * . + * <p> <code>Document</code>, <code>DocumentType</code>, + * <code>DocumentFragment</code>, <code>Notation</code>, <code>Entity</code> + * , and children of <code>Attr</code> nodes are not passed to the filter. + * The child nodes of an <code>EntityReference</code> node are only passed + * to the filter if the <code>EntityReference</code> node is skipped by the + * method <code>LSParserFilter.acceptNode()</code>. + * <p> When serializing an <code>Element</code>, the element is passed to the + * filter before any of its attributes are passed to the filter. Namespace + * declaration attributes, and default attributes (except in the case when " + * discard-default-content" is set to <code>false</code>), are never passed + * to the filter. + * <p> The result of any attempt to modify a node passed to a + * <code>LSSerializerFilter</code> is implementation dependent. + * <p> DOM applications must not raise exceptions in a filter. The effect of + * throwing exceptions from a filter is DOM implementation dependent. + * <p> For efficiency, a node passed to the filter may not be the same as the + * one that is actually in the tree. And the actual node (node object + * identity) may be reused during the process of filtering and serializing a + * document. + * <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 +and Save Specification</a>. + */ +public interface LSSerializerFilter extends NodeFilter { + /** + * Tells the <code>LSSerializer</code> what types of nodes to show to the + * filter. If a node is not shown to the filter using this attribute, it + * is automatically serialized. See <code>NodeFilter</code> for + * definition of the constants. The constants <code>SHOW_DOCUMENT</code> + * , <code>SHOW_DOCUMENT_TYPE</code>, <code>SHOW_DOCUMENT_FRAGMENT</code> + * , <code>SHOW_NOTATION</code>, and <code>SHOW_ENTITY</code> are + * meaningless here, such nodes will never be passed to a + * <code>LSSerializerFilter</code>. + * <br> Unlike [<a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113'>DOM Level 2 Traversal and Range</a>] + * , the <code>SHOW_ATTRIBUTE</code> constant indicates that the + * <code>Attr</code> nodes are shown and passed to the filter. + * <br> The constants used here are defined in [<a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113'>DOM Level 2 Traversal and Range</a>] + * . + */ + public int getWhatToShow(); + +} |