Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.w3c.dom.ls
Interface DOMBuilder

public interface DOMBuilder

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.

A interface to an object that is able to build a DOM tree from various input sources.

`DOMBuilder` provides an API for parsing XML documents and building the corresponding DOM document tree. A `DOMBuilder` instance is obtained from the `DOMImplementationLS` interface by invoking its `createDOMBuilder`method.

As specified in , when a document is first made available via the DOMBuilder: there is only one `Text` node for each block of text. The `Text` nodes are into "normal" form: only structure (e.g., elements, comments, processing instructions, CDATA sections, and entity references) separates `Text` nodes, i.e., there are neither adjacent `Text` nodes nor empty `Text` nodes. it is expected that the `value` and `nodeValue` attributes of an `Attr` node initially return the XML 1.0 normalized value. However, if the features `validate-if-schema` and `datatype-normalization` are set to `true`, depending on the attribute normalization used, the attribute values may differ from the ones obtained by the XML 1.0 attribute normalization. If the feature `datatype-normalization` is not set to `true`, the XML 1.0 attribute normalization is guaranteed to occur, and if attributes list does not contain namespace declarations, the `attributes` attribute on `Element` node represents the property [attributes] defined in . XML Schemas does not modify the XML attribute normalization but represents their normalized value in an other information item property: [schema normalized value]XML Schema normalization only occurs if `datatype-normalization` is set to `true`.

Asynchronous `DOMBuilder` objects are expected to also implement the `events::EventTarget` interface so that event listeners can be registered on asynchronous `DOMBuilder` objects.

Events supported by asynchronous `DOMBuilder` are: load: The document that's being loaded is completely parsed, see the definition of `LSLoadEvent`progress: Progress notification, see the definition of `LSProgressEvent` All events defined in this specification use the namespace URI `"http://www.w3.org/2002/DOMLS"`.

`DOMBuilder`s have a number of named features that can be queried or set. The name of `DOMBuilder` features must be valid XML names. Implementation specific features (extensions) should choose a implementation specific prefix to avoid name collisions.

Even if all features must be recognized by all implementations, being able to set a state (`true` or `false`) is not always required. The following list of recognized features indicates the definitions of each feature state, if setting the state to `true` or `false` must be supported or is optional and, which state is the default one:

`"canonical-form"`
  This feature is equivalent to the one provided on `Document.setNormalizationFeature` in .
`"cdata-sections"`
  This feature is equivalent to the one provided on `Document.setNormalizationFeature` in .
`"certified"`
  `true`
    [optional] Assume, when XML 1.1 is supported, that the input is certified (see section 2.13 in ).
  `false`
    [required] (default) Don't assume that the input is certified (see section 2.13 in ).
`"charset-overrides-xml-encoding"`
  `true`
    [required] ( default) If a higher level protocol such as HTTP 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 4.3.3 "Character Encoding in Entities"). Explicitly setting an encoding in the `DOMInputSource` overrides encodings from the protocol.
  `false`
    [required] Any character set encoding information from higher level protocols is ignored by the parser.
`"comments"`
  This feature is equivalent to the one provided on `Document.setNormalizationFeature` in .
`"datatype-normalization"`
  This feature is equivalent to the one provided on `Document.setNormalizationFeature` in .
`"entities"`
  This feature is equivalent to the one provided on `Document.setNormalizationFeature` in .
`"infoset"`
  This feature is equivalent to the one provided on `Document.setNormalizationFeature` in . Setting this feature to `true` will also force the feature `namespaces` to `true`.
`"namespaces"`
  `true`
    [required ] (default) Perform the namespace processing as defined in .
  `false`
    [optional] Do not perform the namespace processing.
`"namespace-declarations"`
  This feature is equivalent to the one provided on `Document.setNormalizationFeature` in .
`"supported-mediatypes-only"`
  `true`
    [optional] Check that the media type of the parsed resource is a supported media type and call the error handler if an unsupported media type is encountered. The media types defined in must be accepted.
  `false`
    [required] ( default) Don't check the media type, accept any type of data.
`"unknown-characters"`
  `true`
    [required] (default) If, while verifying full normalization when XML 1.1 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.
  `false`
    [optional] Report an fatal error if a character is encountered for which the processor can not determine the normalization properties.
`"validate"`
  This feature is equivalent to the one provided on `Document.setNormalizationFeature` in .
`"validate-if-schema"`
  This feature is equivalent to the one provided on `Document.setNormalizationFeature` in .
`"whitespace-in-element-content"`
  This feature is equivalent to the one provided on `Document.setNormalizationFeature` in .

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

Field Summary
`static short` | `ACTION_APPEND_AS_CHILDREN` Append the result of the input source as children of the context node.
`static short` | `ACTION_INSERT_AFTER` Insert the result of parsing the input source after the context node.
`static short` | `ACTION_INSERT_BEFORE` Insert the result of parsing the input source before the context node.
`static short` | `ACTION_REPLACE` Replace the context node with the result of parsing the input source.

Method Summary
`org.apache.xerces.dom3.DOMConfiguration` | `getConfig()` The configuration used when a document is loaded.
`DOMBuilderFilter` | `getFilter()` When the application provides a filter, the parser will call out to the filter at the completion of the construction of each `Element` node.
`Document` | `parse(DOMInputSource is)` Parse an XML document from a resource identified by a `DOMInputSource`.
`Document` | `parseURI(java.lang.String uri)` Parse an XML document from a location identified by a URI reference .
`void` | `parseWithContext(DOMInputSource is, Node cnode, short action)` Parse an XML fragment from a resource identified by a `DOMInputSource` and insert the content into an existing document at the position specified with the `contextNode` and `action` arguments.
`void` | `setFilter(DOMBuilderFilter filter)` When the application provides a filter, the parser will call out to the filter at the completion of the construction of each `Element` node.

Field Detail

### ACTION_REPLACE

    public static final short ACTION_REPLACE

  Replace the context node with the result of parsing the input source. For this action to work the context node must have a parent and the context node must be an `Element`, `Text`, `CDATASection`, `Comment`, `ProcessingInstruction`, or `EntityReference` node.

### ACTION_APPEND_AS_CHILDREN

    public static final short ACTION_APPEND_AS_CHILDREN

  Append the result of the input source as children of the context node. For this action to work, the context node must be an `Element` or a `DocumentFragment`.

### ACTION_INSERT_AFTER

    public static final short ACTION_INSERT_AFTER

  Insert the result of parsing the input source after the context node. For this action to work the context nodes parent must be an `Element`.

### ACTION_INSERT_BEFORE

    public static final short ACTION_INSERT_BEFORE

  Insert the result of parsing the input source before the context node. For this action to work the context nodes parent must be an `Element`.

Method Detail

### getConfig

    public org.apache.xerces.dom3.DOMConfiguration getConfig()

  The configuration used when a document is loaded. The values of parameters used to load a document are not passed automatically to the `DOMConfiguration` object used by the `Document` nodes. The DOM application is responsible for passing the parameters values from the `DOMConfiguration` object referenced from `DOMBuilder` to the `DOMConfiguration` object referenced from `Document`.
  In addition to the boolean parameters and parameters recognized in the Core module, the `DOMConfiguration` objects for `DOMBuider` adds the following boolean parameters:
  `"entity-resolver"`
    [required] A `DOMEntityResolver` object. If this parameter has been specified, each time a reference to an external entity is encountered the implementation will pass the public and system IDs to the entity resolver, which can then specify the actual source of the entity. If this parameter is not set, the resolution of entities in the document is implementation dependent. When the features "LS-Load" or "LS-Save" are supported, this parameter may also be supported by the `DOMConfiguration` object referenced from the `Document` node.
  `"certified"`
    `true`
      [ optional] Assume, when XML 1.1 is supported, that the input is certified (see section 2.13 in [XML 1.1]).
    `false`
      [required] ( default) Don't assume that the input is certified (see section 2.13 in [XML 1.1]).
  `"charset-overrides-xml-encoding"`
    `true`
      [ required] (default) If a higher level protocol such as HTTP [IETF RFC 2616] 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 [XML 1.0] 4.3.3 "Character Encoding in Entities"). Explicitly setting an encoding in the `DOMInputSource` overrides encodings from the protocol.
    `false`
      [required] Any character set encoding information from higher level protocols is ignored by the parser.
  `"supported-mediatypes-only"`
    `true`
      [optional] Check that the media type of the parsed resource is a supported media type and call the error handler if an unsupported media type is encountered. The media types defined in [IETF RFC 3023] must be accepted.
    `false`
      [required] (default) Don't check the media type, accept any type of data.
  `"unknown-characters"`
    `true`
      [required] (default) If, while verifying full normalization when [XML 1.1] 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.
    `false`
      [optional] Report an fatal error if a character is encountered for which the processor can not determine the normalization properties.

### getFilter

    public DOMBuilderFilter getFilter()

  When the application provides a filter, the parser will call out to the filter at the completion of the construction of each `Element` node. The filter implementation can choose to remove the element from the document being constructed (unless the element is the document element) or to terminate the parse early. If the document is being validated when it's loaded the validation happens before the filter is called.

### setFilter

    public void setFilter(DOMBuilderFilter filter)

  When the application provides a filter, the parser will call out to the filter at the completion of the construction of each `Element` node. The filter implementation can choose to remove the element from the document being constructed (unless the element is the document element) or to terminate the parse early. If the document is being validated when it's loaded the validation happens before the filter is called.

### parseURI

    public Document parseURI(java.lang.String uri)

  Parse an XML document from a location identified by a URI reference . If the URI contains a fragment identifier (see section 4.1 in ), the behavior is not defined by this specification, but future versions of this specification might define the behavior.
  Parameters:
    `uri` - The location of the XML document to be read.
  Returns:
    If the `DOMBuilder` is a synchronous `DOMBuilder` the newly created and populated `Document` is returned. If the `DOMBuilder` is asynchronous then `null` is returned since the document object is not yet parsed when this method returns.

### parse

    public Document parse(DOMInputSource is)

  Parse an XML document from a resource identified by a `DOMInputSource`.
  Parameters:
    `is` - The `DOMInputSource` from which the source document is to be read.
  Returns:
    If the `DOMBuilder` is a synchronous `DOMBuilder` the newly created and populated `Document` is returned. If the `DOMBuilder` is asynchronous then `null` is returned since the document object is not yet parsed when this method returns.

### parseWithContext

    public void parseWithContext(DOMInputSource is,
                                 Node cnode,
                                 short action)
                          throws DOMException

  Parse an XML fragment from a resource identified by a `DOMInputSource` and insert the content into an existing document at the position specified with the `contextNode` and `action` arguments. When parsing the input stream the context node is used for resolving unbound namespace prefixes. The `Document` node, attached to the context node, is used to resolved default attributes and entity references.
  As the new data is inserted into the document at least one mutation event is fired per immediate child (or sibling) of context node.
  If an error occurs while parsing, the caller is notified through the error handler.
  Parameters:
    `is` - The `DOMInputSource` from which the source document is to be read. The source document must be an XML fragment, i.e. anything except an XML Document, a DOCTYPE, entities declarations, notations declarations, or XML or text declarations.
    `cnode` - The node that is used as the context for the data that is being parsed. This node must be a `Document` node, a `DocumentFragment` node, or a node of a type that is allowed as a child of an element, e.g. it can not be an attribute node.
    `action` - This parameter describes which action should be taken between the new set of node being inserted and the existing children of the context node. The set of possible actions is defined above.
  Throws:
    `DOMException` - NOT_SUPPORTED_ERR: Raised when the `DOMBuilder` doesn't support this method.
    NO_MODIFICATION_ALLOWED_ERR: Raised if the context node is readonly.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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