org.w3c.dom.ls
Interface DocumentLS


public interface DocumentLS

DOM Level 3 WD Experimental: The DOM Level 3 specification is at the stage of Working Draft, which represents work in progress and thus may be updated, replaced, or obsoleted by other documents at any time. The DocumentLS interface provides a mechanism by which the content of a document can be serialized, or replaced with the DOM tree produced when loading a URI, or parsing a string.

If the DocumentLS interface is supported, the expectation is that an instance of the DocumentLS interface can be obtained by using binding-specific casting methods on an instance of the Document interface, or by using the method Node.getFeature with parameter values "LS-Load" and "3.0" (respectively) on an Document, if the Document supports the feature "Core" version "3.0" defined in [DOM Level 3 Core]

This interface is optional. If supported, implementations are must support version "3.0" of the feature "LS-DocumentLS".

See also the Document Object Model (DOM) Level 3 Load and Save Specification.


Method Summary
 void abort()
          If the document is currently being loaded as a result of the method load being invoked the loading and parsing is immediately aborted.
 boolean getAsync()
          Indicates whether the method DocumentLS.load() should be synchronous or asynchronous.
 boolean load(java.lang.String uri)
          Replaces the content of the document with the result of parsing the given URI.
 boolean loadXML(java.lang.String source)
          Replace the content of the document with the result of parsing the input string, this method is always synchronous.
 java.lang.String saveXML(org.w3c.dom.Node snode)
          Save the document or the given node and all its descendants to a string (i.e.
 void setAsync(boolean async)
          Indicates whether the method DocumentLS.load() should be synchronous or asynchronous.
 

Method Detail

getAsync

public boolean getAsync()
Indicates whether the method DocumentLS.load() should be synchronous or asynchronous. When the async attribute is set to true the load method returns control to the caller before the document has completed loading. The default value of this attribute is true. Should the DOM spec define the default value of this attribute? What if implementing both async and sync IO is impractical in some systems? 2001-09-14. default is false but we need to check with Mozilla and IE. 2003-01-24. Checked with IE and Mozilla, default is true .


setAsync

public void setAsync(boolean async)
              throws org.w3c.dom.DOMException
Indicates whether the method DocumentLS.load() should be synchronous or asynchronous. When the async attribute is set to true the load method returns control to the caller before the document has completed loading. The default value of this attribute is true. Should the DOM spec define the default value of this attribute? What if implementing both async and sync IO is impractical in some systems? 2001-09-14. default is false but we need to check with Mozilla and IE. 2003-01-24. Checked with IE and Mozilla, default is true .

Throws:
org.w3c.dom.DOMException - NOT_SUPPORTED_ERR: Raised if the implementation doesn't support the mode the attribute is being set to.

abort

public void abort()
If the document is currently being loaded as a result of the method load being invoked the loading and parsing is immediately aborted. The possibly partial result of parsing the document is discarded and the document is cleared.


load

public boolean load(java.lang.String uri)
Replaces the content of the document with the result of parsing the given URI. Invoking this method will either block the caller or return to the caller immediately depending on the value of the async attribute. Once the document is fully loaded the document will fire a "load" event that the caller can register as a listener for. If an error occurs the document will fire an "error" event so that the caller knows that the load failed (see ParseErrorEvent). If this method is called on a document that is currently loading, the current load is interrupted and the new URI load is initiated.
When invoking this method the features used in the DOMBuilder interface are assumed to have their default values with the exception that the feature "entities" is "false".

Parameters:
uri - The URI reference for the XML file to be loaded. If this is a relative URI, the base URI used by the implementation is implementation dependent.
Returns:
If async is set to true load returns true if the document load was successfully initiated. If an error occurred when initiating the document load load returns false.If async is set to false load returns true if the document was successfully loaded and parsed. If an error occurred when either loading or parsing the URI load returns false.

loadXML

public boolean loadXML(java.lang.String source)
Replace the content of the document with the result of parsing the input string, this method is always synchronous. This method always parses from a DOMString, which means the data is always UTF16. All other encoding information is ignored.
The features used in the DOMBuilder interface are assumed to have their default values when invoking this method.

Parameters:
source - A string containing an XML document.
Returns:
true if parsing the input string succeeded without errors, otherwise false.

saveXML

public java.lang.String saveXML(org.w3c.dom.Node snode)
                         throws org.w3c.dom.DOMException
Save the document or the given node and all its descendants to a string (i.e. serialize the document or node).
The features used in the DOMWriter interface are assumed to have their default values when invoking this method.

Parameters:
snode - Specifies what to serialize, if this parameter is null the whole document is serialized, if it's non-null the given node is serialized.
Returns:
The serialized document or null in case an error occured.
Throws:
org.w3c.dom.DOMException - WRONG_DOCUMENT_ERR: Raised if the node passed in as the node parameter is from an other document.


Copyright ? 1999-2003 Apache XML Project. All Rights Reserved.