You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xerces.apache.org by el...@apache.org on 2004/01/23 20:41:31 UTC
cvs commit: xml-xerces/java/src/org/w3c/dom/ls LSException.java DOMImplementationLS.java LSInput.java LSLoadEvent.java LSOutput.java LSParser.java LSParserFilter.java LSProgressEvent.java LSResourceResolver.java LSSerializer.java LSSerializerFilter.java
elena 2004/01/23 11:41:31
Modified: java/src/org/w3c/dom/ls DOMImplementationLS.java
LSInput.java LSLoadEvent.java LSOutput.java
LSParser.java LSParserFilter.java
LSProgressEvent.java LSResourceResolver.java
LSSerializer.java LSSerializerFilter.java
Added: java/src/org/w3c/dom/ls LSException.java
Log:
Update following the latest changes to the draft
Revision Changes Path
1.9 +4 -6 xml-xerces/java/src/org/w3c/dom/ls/DOMImplementationLS.java
Index: DOMImplementationLS.java
===================================================================
RCS file: /home/cvs/xml-xerces/java/src/org/w3c/dom/ls/DOMImplementationLS.java,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- DOMImplementationLS.java 17 Nov 2003 13:45:26 -0000 1.8
+++ DOMImplementationLS.java 23 Jan 2004 19:41:30 -0000 1.9
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2003 World Wide Web Consortium,
+ * Copyright (c) 2004 World Wide Web Consortium,
*
* (Massachusetts Institute of Technology, European Research Consortium for
* Informatics and Mathematics, Keio University). All Rights Reserved. This
@@ -22,12 +22,10 @@
* 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/2003/CR-DOM-Level-3-Core-20031107'>DOM Level 3 Core</a>]
+ * defined in [DOM Level 3 Core]
* , 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/2003/CR-DOM-Level-3-LS-20031107'>Document Object Model (DOM) Level 3 Load
-and Save Specification</a>.
*/
public interface DOMImplementationLS {
// DOMImplementationLSMode
@@ -75,7 +73,7 @@
* 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 created <code>LSParser</code> contains a
+ * 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
@@ -94,7 +92,7 @@
* 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 created <code>LSSerializer</code> contains a
+ * parameter on the new <code>LSSerializer</code> object contains a
* reference to the default error handler.
*/
public LSSerializer createLSSerializer();
1.2 +13 -9 xml-xerces/java/src/org/w3c/dom/ls/LSInput.java
Index: LSInput.java
===================================================================
RCS file: /home/cvs/xml-xerces/java/src/org/w3c/dom/ls/LSInput.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- LSInput.java 17 Nov 2003 13:45:26 -0000 1.1
+++ LSInput.java 23 Jan 2004 19:41:30 -0000 1.2
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2003 World Wide Web Consortium,
+ * Copyright (c) 2004 World Wide Web Consortium,
*
* (Massachusetts Institute of Technology, European Research Consortium for
* Informatics and Mathematics, Keio University). All Rights Reserved. This
@@ -44,11 +44,13 @@
* <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/2003/CR-DOM-Level-3-LS-20031107'>Document Object Model (DOM) Level 3 Load
-and Save Specification</a>.
*/
public interface LSInput {
/**
@@ -101,12 +103,13 @@
* provide one, since the application will use it to resolve any
* relative URIs and can include it in error messages and warnings (the
* <code>LSParser</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).
+ * 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 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
+ * <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.
@@ -119,12 +122,13 @@
* provide one, since the application will use it to resolve any
* relative URIs and can include it in error messages and warnings (the
* <code>LSParser</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).
+ * 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 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
+ * <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.
1.8 +2 -2 xml-xerces/java/src/org/w3c/dom/ls/LSLoadEvent.java
Index: LSLoadEvent.java
===================================================================
RCS file: /home/cvs/xml-xerces/java/src/org/w3c/dom/ls/LSLoadEvent.java,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- LSLoadEvent.java 17 Nov 2003 13:45:26 -0000 1.7
+++ LSLoadEvent.java 23 Jan 2004 19:41:30 -0000 1.8
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2003 World Wide Web Consortium,
+ * Copyright (c) 2004 World Wide Web Consortium,
*
* (Massachusetts Institute of Technology, European Research Consortium for
* Informatics and Mathematics, Keio University). All Rights Reserved. This
@@ -18,7 +18,7 @@
/**
* 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/2003/CR-DOM-Level-3-LS-20031107'>Document Object Model (DOM) Level 3 Load
+ * <p>See also the <a href='http://www.w3.org/2004/01/PR-DOM-Level-3-LS-20040112'>Document Object Model (DOM) Level 3 Load
and Save Specification</a>.
*/
public interface LSLoadEvent extends Event {
1.2 +2 -6 xml-xerces/java/src/org/w3c/dom/ls/LSOutput.java
Index: LSOutput.java
===================================================================
RCS file: /home/cvs/xml-xerces/java/src/org/w3c/dom/ls/LSOutput.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- LSOutput.java 17 Nov 2003 13:45:26 -0000 1.1
+++ LSOutput.java 23 Jan 2004 19:41:30 -0000 1.2
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2003 World Wide Web Consortium,
+ * Copyright (c) 2004 World Wide Web Consortium,
*
* (Massachusetts Institute of Technology, European Research Consortium for
* Informatics and Mathematics, Keio University). All Rights Reserved. This
@@ -43,7 +43,7 @@
* <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/2003/CR-DOM-Level-3-LS-20031107'>Document Object Model (DOM) Level 3 Load
+ * <p>See also the <a href='http://www.w3.org/2004/01/PR-DOM-Level-3-LS-20040112'>Document Object Model (DOM) Level 3 Load
and Save Specification</a>.
*/
public interface LSOutput {
@@ -91,8 +91,6 @@
* 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.
- * <br> This attribute has no effect when outputting to a character
- * stream.
*/
public String getEncoding();
/**
@@ -102,8 +100,6 @@
* 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.
- * <br> This attribute has no effect when outputting to a character
- * stream.
*/
public void setEncoding(String encoding);
1.2 +53 -26 xml-xerces/java/src/org/w3c/dom/ls/LSParser.java
Index: LSParser.java
===================================================================
RCS file: /home/cvs/xml-xerces/java/src/org/w3c/dom/ls/LSParser.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- LSParser.java 17 Nov 2003 13:45:26 -0000 1.1
+++ LSParser.java 23 Jan 2004 19:41:30 -0000 1.2
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2003 World Wide Web Consortium,
+ * Copyright (c) 2004 World Wide Web Consortium,
*
* (Massachusetts Institute of Technology, European Research Consortium for
* Informatics and Mathematics, Keio University). All Rights Reserved. This
@@ -24,7 +24,7 @@
* 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/2003/CR-DOM-Level-3-Core-20031107'>DOM Level 3 Core</a>]
+ * <p> As specified in DOM Level 3 Core
* , when a document is first made available via the LSParser:
* <ul>
* <li> there will
@@ -61,7 +61,7 @@
* <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
- * depenedent, but here is one example of how an application might dispatch
+ * dependent, but 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, then from there on, a
* progress event is dispatched for every 4096 bytes of data that is
@@ -73,7 +73,7 @@
* <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.config</code>'s "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler'>
+ * 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
@@ -83,16 +83,20 @@
* <code>"check-character-normalization-failure" [error]</code> </dt>
* <dd> Raised if
* the paramter "<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 encoutered that fails 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 encoutered in a location where the base URI of the
+ * 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:
@@ -131,8 +135,6 @@
* 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/CR-DOM-Level-3-LS-20031107'>Document Object Model (DOM) Level 3 Load
-and Save Specification</a>.
*/
public interface LSParser {
/**
@@ -146,7 +148,8 @@
* <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/CR-DOM-Level-3-Core-20031107'>DOM Level 3 Core</a>]
+ * <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 DOM Level 3 Core
* , the <code>DOMConfiguration</code> objects for <code>LSParser</code>
* add or modify the following parameters:
* <dl>
@@ -155,7 +158,7 @@
* <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
+ * <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,
@@ -196,7 +199,7 @@
* <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/CR-DOM-Level-3-Core-20031107'>DOM Level 3 Core</a>]
+ * this parameter. Unlike in [DOM Level 3 Core]
* , this parameter will default to <code>true</code> for
* <code>LSParser</code>. </dd>
* <dt><code>"namespaces"</code></dt>
@@ -233,7 +236,7 @@
* <br> The parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-well-formed'>
* well-formed</a>" cannot be set to <code>false</code>.
*/
- public DOMConfiguration getConfig();
+ public DOMConfiguration getDomConfig();
/**
* When a filter is provided, the implementation will call out to the
@@ -285,9 +288,14 @@
* @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;
+ 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
@@ -297,15 +305,21 @@
* @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. 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.
+ * <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;
+ throws DOMException, LSException;
// ACTION_TYPES
/**
@@ -360,14 +374,13 @@
* 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>actualEncoding</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> If the <code>LSParser</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> 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>.
@@ -399,17 +412,31 @@
* the result is more than one top-level node, the first one is
* returned.
* @exception DOMException
- * NOT_SUPPORTED_ERR: Raised if the <code>LSParser</code> doesn't
- * support this method.
+ * 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 [DOM Level 3 Core]
+ * ).
+ * <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.
+ * 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;
+ throws DOMException, LSException;
/**
* Abort the loading of the document that is currently being loaded by
1.2 +19 -11 xml-xerces/java/src/org/w3c/dom/ls/LSParserFilter.java
Index: LSParserFilter.java
===================================================================
RCS file: /home/cvs/xml-xerces/java/src/org/w3c/dom/ls/LSParserFilter.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- LSParserFilter.java 17 Nov 2003 13:45:26 -0000 1.1
+++ LSParserFilter.java 23 Jan 2004 19:41:30 -0000 1.2
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2003 World Wide Web Consortium,
+ * Copyright (c) 2004 World Wide Web Consortium,
*
* (Massachusetts Institute of Technology, European Research Consortium for
* Informatics and Mathematics, Keio University). All Rights Reserved. This
@@ -26,7 +26,14 @@
* 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.
+ * <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>, or if the <code>EntityReference</code>
+ * node is skipped by the method <code>LSParserFilter.acceptNode()</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>", entity reference nodes to non-defined entities 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
@@ -35,9 +42,8 @@
* <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> The <code>LSParser</code> ignores any exception raised in the filter.
- * <p>See also the <a href='http://www.w3.org/TR/2003/CR-DOM-Level-3-LS-20031107'>Document Object Model (DOM) Level 3 Load
-and Save Specification</a>.
+ * <p> DOM applications must not raise exceptions in a filter. The effect of
+ * throwing exceptions from a filter is DOM implementation dependent.
*/
public interface LSParserFilter {
// Constants returned by startElement and acceptNode
@@ -154,12 +160,14 @@
/**
* Tells the <code>LSParser</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>LSParserFilter</code>.
+ * 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>]
* .
*/
1.8 +7 -5 xml-xerces/java/src/org/w3c/dom/ls/LSProgressEvent.java
Index: LSProgressEvent.java
===================================================================
RCS file: /home/cvs/xml-xerces/java/src/org/w3c/dom/ls/LSProgressEvent.java,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- LSProgressEvent.java 17 Nov 2003 13:45:26 -0000 1.7
+++ LSProgressEvent.java 23 Jan 2004 19:41:30 -0000 1.8
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2003 World Wide Web Consortium,
+ * Copyright (c) 2004 World Wide Web Consortium,
*
* (Massachusetts Institute of Technology, European Research Consortium for
* Informatics and Mathematics, Keio University). All Rights Reserved. This
@@ -18,9 +18,10 @@
* 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>See also the <a href='http://www.w3.org/TR/2003/CR-DOM-Level-3-LS-20031107'>Document Object Model (DOM) Level 3 Load
-and Save Specification</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.
*/
public interface LSProgressEvent extends Event {
/**
@@ -37,7 +38,8 @@
/**
* 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.
+ * 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();
1.2 +21 -19 xml-xerces/java/src/org/w3c/dom/ls/LSResourceResolver.java
Index: LSResourceResolver.java
===================================================================
RCS file: /home/cvs/xml-xerces/java/src/org/w3c/dom/ls/LSResourceResolver.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- LSResourceResolver.java 17 Nov 2003 13:45:26 -0000 1.1
+++ LSResourceResolver.java 23 Jan 2004 19:41:30 -0000 1.2
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2003 World Wide Web Consortium,
+ * Copyright (c) 2004 World Wide Web Consortium,
*
* (Massachusetts Institute of Technology, European Research Consortium for
* Informatics and Mathematics, Keio University). All Rights Reserved. This
@@ -17,36 +17,37 @@
* 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>LSParser</code>.
+ * 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.
+ * 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 URN's.
* <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/2003/CR-DOM-Level-3-LS-20031107'>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 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>LSParser</code> resolve the
- * resource itself, that it use an alternative URI, or that it use an
- * entirely different input source.
+ * 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's, to look up public
+ * 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).
- * <br> If the system identifier is a URI, the <code>LSParser</code> must
- * resolve it fully before calling this method.
* @param type The type of the resource being resolved. For XML [<a href='http://www.w3.org/TR/2000/REC-xml-20001006'>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>]
@@ -55,18 +56,19 @@
* 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,
- * i.e. the namespace of the XML Schema [<a href='http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/'>XML Schema Part 1</a>]
+ * 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.
+ * 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 system identifier.
+ * regular URI connection to the resource.
*/
public LSInput resolveResource(String type,
String namespaceURI,
1.2 +123 -117 xml-xerces/java/src/org/w3c/dom/ls/LSSerializer.java
Index: LSSerializer.java
===================================================================
RCS file: /home/cvs/xml-xerces/java/src/org/w3c/dom/ls/LSSerializer.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- LSSerializer.java 17 Nov 2003 13:45:26 -0000 1.1
+++ LSSerializer.java 23 Jan 2004 19:41:30 -0000 1.2
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2003 World Wide Web Consortium,
+ * Copyright (c) 2004 World Wide Web Consortium,
*
* (Massachusetts Institute of Technology, European Research Consortium for
* Informatics and Mathematics, Keio University). All Rights Reserved. This
@@ -19,8 +19,10 @@
/**
* 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.
- * <p> During serialization of XML data, namespace fixup is done as defined in [<a href='http://www.w3.org/TR/2003/CR-DOM-Level-3-Core-20031107'>DOM Level 3 Core</a>]
+ * 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 [DOM Level 3 Core]
* , 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
@@ -49,29 +51,37 @@
* 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> 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>
- * 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/DOM-Level-3-Core/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.
+ * <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-wellformed'>
+ * 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> <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> 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
@@ -96,8 +106,11 @@
* 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 fatal error. An example would be serializing the element
- * <LaCa\u00f1ada/> with <code>encoding="us-ascii"</code>.
+ * 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 rules defined in [<a href='http://www.w3.org/TR/2003/WD-charmod-20030822/'>CharModel</a>] on
@@ -110,37 +123,25 @@
* 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
+ * 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/2003/CR-DOM-Level-3-Core-20031107'>DOM Level 3 Core</a>]
+ * "Namespace normalization", of [DOM Level 3 Core]
* .
- * <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 and warnings are reported to the application
- * through the error handler (<code>LSSerializer.config</code>'s "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler'>
+ * 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>"invalid-data-in-cdata-section" [fatal]</code></dt>
- * <dd>
- * Raised if the configuration parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/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>"no-output-specified" [fatal]</code></dt>
- * <dd> Raised when writing
- * to a <code>LSOutput</code> if no output is specified in the
+ * <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>
@@ -158,14 +159,13 @@
* 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/CR-DOM-Level-3-LS-20031107'>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 in the [<a href='http://www.w3.org/TR/2003/CR-DOM-Level-3-Core-20031107'>DOM Level 3 Core</a>]
+ * <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 [DOM Level 3 Core]
* , the <code>DOMConfiguration</code> objects for
* <code>LSSerializer</code> adds, or modifies, the following
* parameters:
@@ -174,9 +174,15 @@
* <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>
+ * <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>" [DOM Level 3 Core]
+ * , 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>
@@ -203,10 +209,9 @@
* 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/DOM-Level-3-Core/core.html#parameter-canonical-form'>
- * canonical-form</a>" to <code>false</code>. </dd>
- * <dt><code>false</code></dt>
+ * 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>
@@ -220,17 +225,16 @@
* 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
+ * 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/2003/CR-DOM-Level-3-Core-20031107'>DOM Level 3 Core</a>]
+ * the one defined by <code>DOMConfiguration</code> in [DOM Level 3 Core]
* . 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
@@ -258,67 +262,49 @@
* 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/DOM-Level-3-Core/core.html#parameter-well-formed'>
- * well-formed</a>", "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-namespaces'>
- * namespaces</a>", and "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-namespace-declarations'>
- * namespace-declarations</a>" cannot be set to <code>false</code>.
*/
- public DOMConfiguration getConfig();
+ public DOMConfiguration getDomConfig();
/**
* 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
+ * 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/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/2003/PR-xml11-20031105/'>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>.
+ * 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 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
+ * 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/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/2003/PR-xml11-20031105/'>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>.
+ * 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);
@@ -357,7 +343,7 @@
* <li> <code>LSOutput.encoding</code>,
* </li>
* <li>
- * <code>Document.actualEncoding</code>,
+ * <code>Document.inputEncoding</code>,
* </li>
* <li>
* <code>Document.xmlEncoding</code>.
@@ -380,11 +366,19 @@
* @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 and <code>false</code> in case the node
- * couldn't be serialized.
+ * 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);
+ LSOutput destination)
+ throws LSException;
/**
* A convenience method that acts as if <code>LSSerializer.write</code>
@@ -394,11 +388,19 @@
* @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 and <code>false</code> in case the node
- * couldn't be serialized.
+ * 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);
+ String uri)
+ throws LSException;
/**
* Serialize the specified node as described above in the general
@@ -407,13 +409,17 @@
* (this method completely ignores all the encoding information
* available).
* @param nodeArg The node to serialize.
- * @return Returns the serialized data, or <code>null</code> in case the
- * node couldn't be serialized.
+ * @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;
+ throws DOMException, LSException;
}
1.2 +12 -8 xml-xerces/java/src/org/w3c/dom/ls/LSSerializerFilter.java
Index: LSSerializerFilter.java
===================================================================
RCS file: /home/cvs/xml-xerces/java/src/org/w3c/dom/ls/LSSerializerFilter.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- LSSerializerFilter.java 17 Nov 2003 13:45:26 -0000 1.1
+++ LSSerializerFilter.java 23 Jan 2004 19:41:30 -0000 1.2
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2003 World Wide Web Consortium,
+ * Copyright (c) 2004 World Wide Web Consortium,
*
* (Massachusetts Institute of Technology, European Research Consortium for
* Informatics and Mathematics, Keio University). All Rights Reserved. This
@@ -22,7 +22,10 @@
* .
* <p> <code>Document</code>, <code>DocumentType</code>,
* <code>DocumentFragment</code>, <code>Notation</code>, and
- * <code>Entity</code> nodes are not passed to the filter.
+ * <code>Entity</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 "
@@ -30,16 +33,17 @@
* to the filter.
* <p> The result of any attempt to modify a node passed to a
* <code>LSSerializerFilter</code> is implementation dependent.
- * <p>See also the <a href='http://www.w3.org/TR/2003/CR-DOM-Level-3-LS-20031107'>Document Object Model (DOM) Level 3 Load
-and Save Specification</a>.
+ * <p> DOM applications must not raise exceptions in a filter. The effect of
+ * throwing exceptions from a filter is DOM implementation dependent.
*/
public interface LSSerializerFilter extends NodeFilter {
/**
* Tells the <code>LSSerializer</code> what types of nodes to show to the
- * filter. 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
+ * 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> 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>]
1.1 xml-xerces/java/src/org/w3c/dom/ls/LSException.java
Index: LSException.java
===================================================================
/*
* 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.
*/
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;
}
---------------------------------------------------------------------
To unsubscribe, e-mail: xerces-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: xerces-cvs-help@xml.apache.org