neeraj 2003/07/30 03:54:45
Added: java/src/org/w3c/dom/ls DOMInput.java DOMOutput.java
DOMParser.java DOMParserFilter.java
DOMResourceResolver.java DOMSerializer.java
DOMSerializerFilter.java
Removed: java/src/org/w3c/dom/ls DOMBuilder.java
DOMBuilderFilter.java DOMEntityResolver.java
DOMInputSource.java DOMWriter.java
DOMWriterFilter.java
Log:
Applying patches to upgrade to latest DOM L3 LS draft. Thanks Gopal.
Revision Changes Path
1.1 xml-xerces/java/src/org/w3c/dom/ls/DOMInput.java
Index: DOMInput.java
===================================================================
/*
* Copyright (c) 2003 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.createDOMInput()</code>
* to create objects that implement this interface.
* <p> The <code>DOMParser</code> will use the <code>DOMInput</code> object to
* determine how to read data. The <code>DOMParser</code> will look at the
* different inputs specified in the <code>DOMInput</code> in the following
* order to know which one to read from, the first one through which data is
* available will be used:
* <ol>
* <li> <code>DOMInput.characterStream</code>
* </li>
* <li>
* <code>DOMInput.byteStream</code>
* </li>
* <li> <code>DOMInput.stringData</code>
* </li>
* <li>
* <code>DOMInput.systemId</code>
* </li>
* <li> <code>DOMInput.publicId</code>
* </li>
* </ol>
* <p> <code>DOMInput</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/2003/WD-DOM-Level-3-LS-20030619'>Document Object Model
(DOM) Level 3 Load
and Save Specification</a>.
*/
public interface DOMInput {
/**
* 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 Amendment 1 of [ISO/IEC 10646]).
*/
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 Amendment 1 of [ISO/IEC 10646]).
*/
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).
*/
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).
*/
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, but it is still useful to
* provide one, since the application will use it to resolve any
* relative URI's and can include it in error messages and warnings (the
* <code>DOMParser</code> will only attempt to fetch the resource
* identified by the URI reference only 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 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, but it is still useful to
* provide one, since the application will use it to resolve any
* relative URI's and can include it in error messages and warnings (the
* <code>DOMParser</code> will only attempt to fetch the resource
* identified by the URI reference only 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 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 character encoding, if known. The encoding must be a string
* acceptable for an XML encoding declaration ([<a
href='http://www.w3.org/TR/2000/REC-xml-20001006'>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/2000/REC-xml-20001006'>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);
/**
* 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);
/**
* If set to true, assume that the input is certified (see section 2.13
* in [<a href='http://www.w3.org/TR/2002/CR-xml11-20021015/'>XML 1.1</a>]) when
* parsing [<a href='http://www.w3.org/TR/2002/CR-xml11-20021015/'>XML 1.1</a>].
*/
public boolean getCertified();
/**
* If set to true, assume that the input is certified (see section 2.13
* in [<a href='http://www.w3.org/TR/2002/CR-xml11-20021015/'>XML 1.1</a>]) when
* parsing [<a href='http://www.w3.org/TR/2002/CR-xml11-20021015/'>XML 1.1</a>].
*/
public void setCertified(boolean certified);
}
1.1 xml-xerces/java/src/org/w3c/dom/ls/DOMOutput.java
Index: DOMOutput.java
===================================================================
/*
* Copyright (c) 2003 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.createDOMOutput()</code>
* to create objects that implement this interface.
* <p> The <code>DOMSerializer</code> will use the <code>DOMOutput</code>
* object to determine where to serialize the output to. The
* <code>DOMSerializer</code> will look at the different outputs specified
* in the <code>DOMOutput</code> in the following order to know which one to
* output to, the first one that data can be output to will be used:
* <ol>
* <li>
* <code>DOMOutput.characterStream</code>
* </li>
* <li> <code>DOMOutput.byteStream</code>
* </li>
* <li>
* <code>DOMOutput.systemId</code>
* </li>
* </ol>
* <p> <code>DOMOutput</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/2003/WD-DOM-Level-3-LS-20030619'>Document Object Model
(DOM) Level 3 Load
and Save Specification</a>.
*/
public interface DOMOutput {
/**
* An attribute of a language and binding dependent type that represents
* a writable stream to which 16-bit units can be output. The
* application must encode the stream using UTF-16 (defined in [Unicode] and
Amendment 1 of [ISO/IEC 10646]).
*/
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. The
* application must encode the stream using UTF-16 (defined in [Unicode] and
Amendment 1 of [ISO/IEC 10646]).
*/
public void setCharacterStream(java.io.Writer characterStream);
/**
* An attribute of a language and binding dependent type that represents
* a writable 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.OutputStream getByteStream();
/**
* An attribute of a language and binding dependent type that represents
* a writable 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.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 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 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 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 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, if known. The encoding must be a string
* acceptable for an XML encoding declaration ([<a
href='http://www.w3.org/TR/2000/REC-xml-20001006'>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/2000/REC-xml-20001006'>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);
}
1.1 xml-xerces/java/src/org/w3c/dom/ls/DOMParser.java
Index: DOMParser.java
===================================================================
/*
* Copyright (c) 2003 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>DOMParser</code> provides an API for parsing XML and building the
* corresponding DOM document structure. A <code>DOMParser</code> instance
* can be obtained by invoking the
* <code>DOMImplementationLS.createDOMParser()</code> method.
* <p> As specified in [<a
href='http://www.w3.org/TR/2003/WD-DOM-Level-3-Core-20030609'>DOM Level 3 Core</a>]
* , when a document is first made available via the DOMParser:
* <ul>
* <li> there is
* only one <code>Text</code> node for each block of text. The
* <code>Text</code> nodes are in "normal" form: only structure (e.g.
* elements, comments, processing instructions, CDATA sections, and entity
* references) separates <code>Text</code> nodes, i.e., there are neither
* adjacent nor empty <code>Text</code> 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/2000/REC-xml-20001006#AVNormalize'>XML 1.0
* normalized value</a>. However, if the parameters "<a
href='http://www.w3.org/TR/2003/WD-DOM-Level-3-Core-20030609/core.html#parameter-validate-if-schema'>
* validate-if-schema</a>" and "<a
href='http://www.w3.org/TR/2003/WD-DOM-Level-3-Core-20030609/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
* <code>data-type-normalization</code> 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/2001/REC-xml-infoset-20011024/'>XML Information set</a>]
* .
* </li>
* </ul>
* <p> Asynchronous <code>DOMParser</code> objects are expected to also
* implement the <code>events::EventTarget</code> interface so that event
* listeners can be registered on asynchronous <code>DOMParser</code>
* objects.
* <p> Events supported by asynchronous <code>DOMParser</code> objects are:
* <dl>
* <dt>
* load</dt>
* <dd> The <code>DOMParser</code> finishes to load the document. See also
* the definition of the <code>LSLoadEvent</code> interface. </dd>
* <dt>progress</dt>
* <dd> The
* <code>DOMParser</code> signals a progress as a document is parsed. 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>DOMParser.config</code>'s "<a
href='http://www.w3.org/TR/2003/WD-DOM-Level-3-Core-20030609/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>"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>
* <dt>
* <code>"unsupported-encoding" [fatal]</code></dt>
* <dd> Raised if an unsupported
* encoding is encountered. </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>"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>"unbound-namespace-in-entity" [warning]</code></dt>
* <dd> Raised if the
* configuration parameter "<a
href='http://www.w3.org/TR/2003/WD-DOM-Level-3-Core-20030609/core.html#parameter-entities'>
* entities</a>" is set to <code>true</code> and an unbound namespace prefix is
* encounterd in an entity declaration. </dd>
* <dt>
* <code>"pi-base-uri-not-preserved" [warning]</code></dt>
* <dd> Raised if a processing
* instruction is encoutered 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/2003/WD-DOM-Level-3-Core-20030609/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>
* looks like this:
* <pre><one> <two/> </one> <?pi
* 3.14159?> <more/></pre>
* </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/2003/WD-DOM-Level-3-LS-20030619'>Document Object Model
(DOM) Level 3 Load
and Save Specification</a>.
*/
public interface DOMParser {
/**
* The <code>DOMConfiguration</code> object used when parsing an input
* source. This <code>DOMConfiguration</code> is specific to the parse
* operation and 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 [<a
href='http://www.w3.org/TR/2003/WD-DOM-Level-3-Core-20030609'>DOM Level 3 Core</a>]
* , the <code>DOMConfiguration</code> objects for <code>DOMParser</code>
* adds or modifies the following parameters:
* <dl>
* <dt>
* <code>"charset-overrides-xml-encoding"</code></dt>
* <dd>
* <dl>
* <dt><code>true</code></dt>
* <dd>[<em>required</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/2000/REC-xml-20001006'>XML 1.0</a>]).
* Explicitly setting an encoding in the <code>DOMInput</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/2002/CR-xml11-20021015/'>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/2000/REC-xml-20001006'>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/2003/WD-DOM-Level-3-Core-20030609'>DOM Level 3 Core</a>]
* , this parameter will default to <code>true</code> for
* <code>DOMParser</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>]
* . </dd>
* <dt><code>false</code></dt>
* <dd>[<em>optional</em>] Do not perform the namespace processing. </dd>
* </dl></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>
* </dl>
* <br> The parameter "<a
href='http://www.w3.org/TR/2003/WD-DOM-Level-3-Core-20030609/core.html#parameter-well-formed'>
* well-formed</a>" cannot be set to <code>false</code>.
*/
public DOMConfiguration getConfig();
/**
* 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/2003/WD-DOM-Level-3-Core-20030609/core.html#parameter-validate'>
* validate</a>" is set to <code>true</code>, the validation is done before
invoking the
* filter.
*/
public DOMParserFilter 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/2003/WD-DOM-Level-3-Core-20030609/core.html#parameter-validate'>
* validate</a>" is set to <code>true</code>, the validation is done before
invoking the
* filter.
*/
public void setFilter(DOMParserFilter filter);
/**
* <code>true</code> if the <code>DOMParser</code> is asynchronous,
* <code>false</code> if it is synchronous.
*/
public boolean getAsync();
/**
* <code>true</code> if the <code>DOMParser</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>DOMInput</code>.
* @param is The <code>DOMInput</code> from which the source of the
* document is to be read.
* @return If the <code>DOMParser</code> is a synchronous
* <code>DOMParser</code>, the newly created and populated
* <code>Document</code> is returned. If the <code>DOMParser</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>DOMParser</code>'s
* <code>DOMParser.busy</code> attribute is <code>true</code>.
*/
public Document parse(DOMInput is)
throws DOMException;
/**
* 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>DOMParser</code> is a synchronous
* <code>DOMParser</code>, the newly created and populated
* <code>Document</code> is returned. If the <code>DOMParser</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>DOMParser.busy</code>
* attribute is <code>true</code>.
*/
public Document parseURI(String uri)
throws DOMException;
// 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>DOMInput</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 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 it's
* <code>xmlEncoding</code>, <code>documentURI</code>,
* <code>xmlVersion</code>, <code>actualEncoding</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>DOMParser.parse()</code>.
* <br> If the <code>DOMParser</code> is asynchronous then the insertion
* of the resulting DOM structure is atomic, e.g. the whole structure is
* inserted only once the whole input stream is completely parsed
* without errors.
* <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/2003/WD-DOM-Level-3-Core-20030609/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/2003/WD-DOM-Level-3-Core-20030609/core.html#parameter-validate'>
* validate</a>", "<a
href='http://www.w3.org/TR/2003/WD-DOM-Level-3-Core-20030609/core.html#parameter-validate-if-schema'>
* validate-if-schema</a>", and "<a
href='http://www.w3.org/TR/2003/WD-DOM-Level-3-Core-20030609/core.html#parameter-whitespace-in-element-content'>
* whitespace-in-element-content</a>".
* @param input The <code>DOMInput</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 context 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
* NOT_SUPPORTED_ERR: Raised if the <code>DOMParser</code> doesn't
* support this method.
* <br> NO_MODIFICATION_ALLOWED_ERR: Raised if the context node is a
* read only node.
* <br> INVALID_STATE_ERR: Raised if the <code>DOMParser.busy</code>
* attribute is <code>true</code>.
*/
public Node parseWithContext(DOMInput input,
Node context,
short action)
throws DOMException;
/**
* Abort the loading of the document that is currently being loaded by
* the <code>DOMParser</code>. If the <code>DOMParser</code> is
* currently not busy, a call to this method does nothing.
*/
public void abort();
}
1.1 xml-xerces/java/src/org/w3c/dom/ls/DOMParserFilter.java
Index: DOMParserFilter.java
===================================================================
/*
* Copyright (c) 2003 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>DOMParserFilter</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>DOMParserFilter</code>
* methods, i.e. it is not possible to filter out the document element. The
* <code>Document</code>, <code>DocumentType</code>, <code>Notation</code>,
* and <code>Entity</code> nodes are not passed to the
* <code>acceptNode</code> method on the filter.
* <p>All validity checking while reading 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 content, including default attributes, must be passed to
* the filter methods.
* <p> The <code>DOMParser</code> ignores any exception raised in the filter.
* <p>See also the <a
href='http://www.w3.org/TR/2003/WD-DOM-Level-3-LS-20030619'>Document Object Model
(DOM) Level 3 Load
and Save Specification</a>.
*/
public interface DOMParserFilter {
// 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 element 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 this <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. This return value will be ignored
* if <code>element</code> is the documentElement, the documentElement
* cannot be rejected.
* </li>
* <li> <code>FILTER_SKIP</code> if the
* <code>Element</code> should be rejected. All of its children are
* inserted in place of the rejected <code>Element</code> node. This
* return value will be ignored if <code>element</code> is the
* documentElement, the documentElement cannot be rejected nor
* skipped.
* </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 entire is XML well-formed
* .
* </li>
* </ul> Returning any other values will result in unspecified behavior.
*/
public short startElement(Element element);
/**
* 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
* or any of its descendants.
* @param node 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 entire is XML well-formed
* .
* </li>
* </ul>
*/
public short acceptNode(Node node);
/**
* Tells the <code>DOMParser</code> what types of nodes to show to the
* filter. 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 a
* <code>DOMParserFilter</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();
}
1.1 xml-xerces/java/src/org/w3c/dom/ls/DOMResourceResolver.java
Index: DOMResourceResolver.java
===================================================================
/*
* Copyright (c) 2003 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>DOMResourceResolver</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 <code>resourceResolver</code> attribute of the
* <code>DOMParser</code>.
* <p> The <code>DOMParser</code> will then allow the application to intercept
* any external entities (including the external DTD subset and external
* parameter entities) before including them.
* <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 URN's.
* <p ><b>Note:</b> <code>DOMResourceResolver</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/2003/WD-DOM-Level-3-LS-20030619'>Document Object Model
(DOM) Level 3 Load
and Save Specification</a>.
*/
public interface DOMResourceResolver {
/**
* Allow the application to resolve external resources.
* <br> The <code>DOMParser</code> will call this method before opening
* any external resource except the top-level document entity (including
* the external DTD subset, external entities referenced within the DTD,
* and external entities referenced within the document element); the
* application may request that the <code>DOMParser</code> resolve the
* 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's, 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).
* <br> If the system identifier is a URI, the <code>DOMParser</code> must
* resolve it fully before calling this method.
* @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.
* @param baseURI The absolute base URI of the resource being parsed, or
* <code>null</code> if there is no base URI.
* @return A <code>DOMInput</code> object describing the new input
* source, or <code>null</code> to request that the parser open a
* regular URI connection to the system identifier.
*/
public DOMInput resolveResource(String publicId,
String systemId,
String baseURI);
}
1.1 xml-xerces/java/src/org/w3c/dom/ls/DOMSerializer.java
Index: DOMSerializer.java
===================================================================
/*
* Copyright (c) 2003 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;
/**
* <code>DOMSerializer</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.
* <p> During serialization of XML data, namespace fixup is done as defined in [<a
href='http://www.w3.org/TR/2003/WD-DOM-Level-3-Core-20030609'>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>DOMSerializer</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 not specified, but should be something useful to a human for debugging
* or diagnostic purposes.
* <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>DOMSerializer.write</code>, outputs the entity expansion but no
* namespace fixup is done. The resulting output will be valid as an
* external entity.
* </li>
* <li> <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.
* </li>
* <li>
* CDATA sections containing content characters that cannot be represented
* in the specified output encoding are handled according to the "<a
href='http://www.w3.org/TR/2003/WD-DOM-Level-3-Core-20030609/core.html#parameter-split-cdata-sections'>
* split-cdata-sections</a>" parameter. If the parameter is set to
<code>true</code>, CDATA sections
* 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 CDATA section are reported as
* <code>"invalid-data-in-cdata-section"</code> errors. 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>DOMParser</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.
* <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 an error. An example would be serializing the element
* <LaCa\u00f1ada/> with <code>encoding="us-ascii"</code>.
* <p> When requested by setting the parameter "<a
href='http://www.w3.org/TR/2003/WD-DOM-Level-3-Core-20030609/core.html#parameter-normalize-characters'>
* normalize-characters</a>" on <code>DOMSerializer</code> to true, character
normalization is
* performed according to the rules defined in [<a
href='http://www.w3.org/TR/2002/WD-charmod-20020430'>CharModel</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> When outputting unicode data, whether or not a byte order mark is
* serialized, or if the output is big-endian or little-endian, is
* implementation dependent.
* <p> Namespaces are fixed up during serialization, the serialization process
* will verify that namespace declarations, namespace prefixes and the
* namespace URI's 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/2003/WD-DOM-Level-3-Core-20030609'>DOM Level 3 Core</a>]
* .
* <p> Any changes made affect only the namespace prefixes and declarations
* appearing in the serialized data. The DOM's view of the document is not
* altered by the serialization operation, and does not reflect any changes
* made to namespace declarations or prefixes in the serialized output. We
* may take back what we say in the above paragraph depending on feedback
* from implementors, but for now the belief is that the DOM's view of the
* document is not changed during serialization.
* <p> While serializing a document, the parameter "discard-default-content"
* controls whether or not non-specified data is serialized.
* <p> While serializing, errors are reported to the application through the
* error handler (<code>DOMSerializer.config</code>'s "<a
href='http://www.w3.org/TR/2003/WD-DOM-Level-3-Core-20030609/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 serializing a DOM node, 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>"invalid-data-in-cdata-section" [fatal]</code></dt>
* <dd> Raised if the
* configuration parameter "<a
href='http://www.w3.org/TR/2003/WD-DOM-Level-3-Core-20030609/core.html#parameter-split-cdata-sections'>
* split-cdata-sections</a>" is set to <code>false</code> and invalid data is
encountered in a CDATA
* section. </dd>
* <dt><code>"unsupported-encoding" [fatal]</code></dt>
* <dd> Raised if an
* unsupported encoding is encountered. </dd>
* <dt>
* <code>"unbound-namespace-in-entity" [warning]</code></dt>
* <dd> Raised if the
* configuration parameter "<a
href='http://www.w3.org/TR/2003/WD-DOM-Level-3-Core-20030609/core.html#parameter-entities'>
* entities</a>" is set to <code>true</code> and an unbound namespace prefix is
* encounterd in a referenced entity. </dd>
* <dt>
* <code>"no-output-specified" [fatal]</code></dt>
* <dd> Raised when writing to a
* <code>DOMOutput</code> if no output is specified in the
* <code>DOMOutput</code>. </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/2003/WD-DOM-Level-3-LS-20030619'>Document Object Model
(DOM) Level 3 Load
and Save Specification</a>.
*/
public interface DOMSerializer {
/**
* The <code>DOMConfiguration</code> object used by the
* <code>DOMSerializer</code> when serializing a DOM node.
* <br> In addition to the parameters recognized in the [<a
href='http://www.w3.org/TR/2003/WD-DOM-Level-3-Core-20030609'>DOM Level 3 Core</a>]
* , the <code>DOMConfiguration</code> objects for
* <code>DOMSerializer</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>] This formatting writes the document according to the
rules specified in [<a
href='http://www.w3.org/TR/2001/REC-xml-c14n-20010315'>Canonical XML</a>].
* Setting this parameter to <code>true</code> will set the parameter "
* format-pretty-print" to <code>false</code>. </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. Setting this
* parameter to <code>true</code> will set the parameter "<a
href='http://www.w3.org/TR/2003/WD-DOM-Level-3-Core-20030609/core.html#parameter-canonical-form'>
* canonical-form</a>" to <code>false</code>. </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/2002/CR-xml11-20021015/'>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. IMO it would
* make sense to move this parameter into the DOM Level 3 Core spec, and
* the error/warning should be defined there. </dd>
* <dt><code>false</code></dt>
* <dd>[<em>optional</em>] Report an 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/2003/WD-DOM-Level-3-Core-20030609'>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 fully normalizing the characters in the document according to
* the rules defined in [<a
href='http://www.w3.org/TR/2002/WD-charmod-20020430'>CharModel</a>]
* supplemented by the definitions of relevant constructs from Section
* 2.13 of [<a href='http://www.w3.org/TR/2002/CR-xml11-20021015/'>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 possibly an encoding (
* <code>DOMSerializer.encoding</code>, or
* <code>Document.actualEncoding</code> or
* <code>Document.xmlEncoding</code> if the document is a Level 3
* document) is 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/2000/REC-xml-20001006'>XML 1.0</a>], or an
* encoding would be needed to be able to re-parse the serialized data). </dd>
* </dl></dd>
* </dl>
* <br> The parameters "<a
href='http://www.w3.org/TR/2003/WD-DOM-Level-3-Core-20030609/core.html#parameter-well-formed'>
* well-formed</a>", "<a
href='http://www.w3.org/TR/2003/WD-DOM-Level-3-Core-20030609/core.html#parameter-namespaces'>
* namespaces</a>", and "<a
href='http://www.w3.org/TR/2003/WD-DOM-Level-3-Core-20030609/core.html#parameter-namespace-declarations'>
* namespace-declarations</a>" cannot be set to <code>false</code>.
*/
public DOMConfiguration getConfig();
/**
* The end-of-line sequence of characters to be used in the XML being
* written out. Any string is supported, but these are the recommended
* end-of-line sequences (using other character sequences than these
* recommended ones can result in a document that is either not
* serializable or not well-formed):
* <dl>
* <dt><code>null</code></dt>
* <dd> Use a 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 section 2.11, "End-of-Line Handling" in [<a
href='http://www.w3.org/TR/2000/REC-xml-20001006'>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/2002/CR-xml11-20021015/'>XML 1.1</a>], if
the
* serialized content is XML 1.1. </dd>
* <dt>CR</dt>
* <dd>The carriage-return character (#xD).</dd>
* <dt>
* CR-LF</dt>
* <dd> The carriage-return and line-feed characters (#xD #xA). </dd>
* <dt>LF</dt>
* <dd> The
* line-feed character (#xA). </dd>
* </dl>
* <br>The default value for this attribute is <code>null</code>.
*/
public String getNewLine();
/**
* The end-of-line sequence of characters to be used in the XML being
* written out. Any string is supported, but these are the recommended
* end-of-line sequences (using other character sequences than these
* recommended ones can result in a document that is either not
* serializable or not well-formed):
* <dl>
* <dt><code>null</code></dt>
* <dd> Use a 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 section 2.11, "End-of-Line Handling" in [<a
href='http://www.w3.org/TR/2000/REC-xml-20001006'>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/2002/CR-xml11-20021015/'>XML 1.1</a>], if
the
* serialized content is XML 1.1. </dd>
* <dt>CR</dt>
* <dd>The carriage-return character (#xD).</dd>
* <dt>
* CR-LF</dt>
* <dd> The carriage-return and line-feed characters (#xD #xA). </dd>
* <dt>LF</dt>
* <dd> The
* line-feed character (#xA). </dd>
* </dl>
* <br>The default value for this attribute is <code>null</code>.
*/
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 before the operations requested by the
* <code>DOMConfiguration</code> parameters have been applied. For
* example, CDATA sections are passed to the filter even if "<a
href='http://www.w3.org/TR/2003/WD-DOM-Level-3-Core-20030609/core.html#parameter-cdata-sections'>
* cdata-sections</a>" is set to <code>false</code>.
*/
public DOMSerializerFilter 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 before the operations requested by the
* <code>DOMConfiguration</code> parameters have been applied. For
* example, CDATA sections are passed to the filter even if "<a
href='http://www.w3.org/TR/2003/WD-DOM-Level-3-Core-20030609/core.html#parameter-cdata-sections'>
* cdata-sections</a>" is set to <code>false</code>.
*/
public void setFilter(DOMSerializerFilter filter);
/**
* Serialize the specified node as described above in the general
* description of the <code>DOMSerializer</code> interface. The output
* is written to the supplied <code>DOMOutput</code>.
* <br> When writing to a <code>DOMOutput</code>, the encoding is found by
* looking at the encoding information that is reachable through the
* <code>DOMOutput</code> and the item to be written (or its owner
* document) in this order:
* <ol>
* <li> <code>DOMOutput.encoding</code>,
* </li>
* <li>
* <code>Document.actualEncoding</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.
* <br> If the specified encoding is not supported an
* "unsupported-encoding" error is raised.
* <br> If no output is specified in the <code>DOMOutput</code>, a
* "no-output-specified" error is raised.
* @param node The node to serialize.
* @param destination The destination for the serialized DOM.
* @return Returns <code>true</code> if <code>node</code> was
* successfully serialized and <code>false</code> in case the node
* couldn't be serialized.
*/
public boolean write(Node node,
DOMOutput destination);
/**
* Serialize the specified node as described above in the general
* description of the <code>DOMSerializer</code> interface. The output
* is written to the supplied URI.
* <br> When writing to a URI, the encoding is found by looking at the
* encoding information that is reachable through the item to be written
* (or its owner document) in this order:
* <ol>
* <li>
* <code>Document.actualEncoding</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.
* <br> If the specified encoding is not supported an
* "unsupported-encoding" error is raised.
* @param node The node to serialize.
* @param URI The URI to write to.
* @return Returns <code>true</code> if <code>node</code> was
* successfully serialized and <code>false</code> in case the node
* couldn't be serialized.
*/
public boolean writeURI(Node node,
String URI);
/**
* Serialize the specified node as described above in the general
* description of the <code>DOMSerializer</code> interface. The output
* is written to a <code>DOMString</code> that is returned to the caller
* (this method completely ignores all the encoding information
* available).
* @param node The node to serialize.
* @return Returns the serialized data, or <code>null</code> in case the
* node couldn't be serialized.
* @exception DOMException
* DOMSTRING_SIZE_ERR: Raised if the resulting string is too long to
* fit in a <code>DOMString</code>.
*/
public String writeToString(Node node)
throws DOMException;
}
1.1 xml-xerces/java/src/org/w3c/dom/ls/DOMSerializerFilter.java
Index: DOMSerializerFilter.java
===================================================================
/*
* Copyright (c) 2003 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>DOMSerializerFilter</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>DOMSerializerFilter</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> The <code>Document</code>, <code>DocumentType</code>,
* <code>DocumentFragment</code>, <code>Attr</code>, <code>Notation</code>,
* and <code>Entity</code> nodes are not passed to the filter.
* <p> The result of any attempt to modify a node passed to a
* <code>DOMSerializerFilter</code> is implementation dependent.
* <p>See also the <a
href='http://www.w3.org/TR/2003/WD-DOM-Level-3-LS-20030619'>Document Object Model
(DOM) Level 3 Load
and Save Specification</a>.
*/
public interface DOMSerializerFilter extends NodeFilter {
/**
* Tells the <code>DOMSerializer</code> what types of nodes to show to
* the filter. 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_ATTRIBUTE</code>, and
* <code>SHOW_DOCUMENT_FRAGMENT</code> are meaningless here, those nodes
* will never be passed to a <code>DOMSerializerFilter</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();
}
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
