org.w3c.dom.ls
Interface DocumentLS

public interface DocumentLS

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 "DocumentLS" 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 must support version "3.0" of the feature "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(Node node) 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.

setAsync

public void setAsync(boolean async)
              throws 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.

Throws:

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 a "load" event (as defined in [DOM Level 3 Events] , except that the Event.targetNode will be the document, not an element) will be dispatched on the document. If an error occurs, an implementation dependent "error" event will be dispatched on the document. 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 parameters used in the DOMParser interface are assumed to have their default values with the exception that the parameters "entities" , "normalize-characters", "check-character-normalization" are set to "false".
The result of a call to this method is the same the result of a call to DOMParser.parseWithContext with an input stream referencing the URI that was passed to this call, the document as the context node, and the action ACTION_REPLACE_CHILDREN.

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 UTF-16. All other encoding information is ignored.
The parameters used in the DOMParser interface are assumed to have their default values when invoking this method.
The result of a call to this method is the same the result of a call to DOMParser.parseWithContext with an input stream containing the string passed to this call, the document as the context node, and the action ACTION_REPLACE_CHILDREN.

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(Node node)
                         throws DOMException

Save the document or the given node and all its descendants to a string (i.e. serialize the document or node).
The parameters used in the DOMSerializer interface are assumed to have their default values when invoking this method.
The result of a call to this method is the same the result of a call to DOMSerializer.writeToString with the document as the node to write.

Parameters:

node - 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 occurred.

Throws:

DOMException - WRONG_DOCUMENT_ERR: Raised if the node passed in as the node parameter is from an other document.