Skip navigation links

Oracle® Database XML Java API Reference 11g Release 2 (11.2) E10769-01

## oracle.xml.parser.v2
Class DocumentBuilder

`java.lang.Object
org.xml.sax.HandlerBase
oracle.xml.parser.v2.DefaultXMLDocumentHandler
oracle.xml.parser.v2.DocumentBuilder`

All Implemented Interfaces:
  XMLDocumentHandler, ContentHandler, DocumentHandler, DTDHandler, EntityResolver, ErrorHandler, DeclHandler, LexicalHandler

      public class DocumentBuilder

extends DefaultXMLDocumentHandler
implements ContentHandler, LexicalHandler, DeclHandler

This class implements XMLDocumentHandler (deprecated) and ContentHandler to build a DOM Tree from SAX 2.0 events. XMLDocumentHandler events are supported for backward compatibility

Field Summary
`protected XMLNode` `root`

Constructor Summary
`DocumentBuilder()` Default Constructor.

Method Summary
`void` `attributeDecl(java.lang.String eName, java.lang.String aName, java.lang.String type, java.lang.String valueDefault, java.lang.String value)` Report an attribute type declaration.
`void` `cDATASection(char[] ch, int start, int length)` Receive notification of CDATA Section data inside an element.
`void` `characters(char[] ch, int start, int length)` Receive notification of character data inside an element.
`void` `comment(char[] ch, int start, int length)` Report an XML comment anywhere in the document.
`void` `comment(java.lang.String data)` Receive notification of a comment.
`void` `elementDecl(java.lang.String name, java.lang.String model)` Report an element type declaration.
`void` `endCDATA()` Report the end of a CDATA section.
`void` `endDoctype()` Receive notification of end of the DTD.
`void` `endDocument()` Receive notification of the end of the document.
`void` `endDTD()` Report the end of DTD declarations.
`void` `endElement(NSName elem)` Receive notification of the end of an element.
`void` `endElement(java.lang.String namespaceURI, java.lang.String localName, java.lang.String qName)` Receive notification of the end of an element.
`void` `endEntity(java.lang.String name)` Report the end of an entity.
`void` `externalEntityDecl(java.lang.String name, java.lang.String publicId, java.lang.String systemId)` Report a parsed external entity declaration.
`XMLDocument` `getDocument()` Get the document being build
`Locator` `getLocator()` Get the locator reported by the Reader using setDocumentLocator
`XMLNode` `getRoot()` Get the root of tree being built
`void` `ignorableWhitespace(char[] ch, int start, int length)` Receive notification of ignorable whitespace in element content.
`void` `internalEntityDecl(java.lang.String name, java.lang.String value)` Report an internal entity declaration.
`void` `processingInstruction(java.lang.String target, java.lang.String data)` Receive notification of a processing instruction.
`void` `reset()` Resets the document builder state
`void` `resetNodeFactory()` Reset the NodeFactory and go back to the original behaviour.
`void` `retainCDATASection(boolean flag)` Sets a flag to retain CDATA sections
`void` `setAttribute(java.lang.String name, java.lang.Object value)` Allows the user to set specific attributes on the underlying implementation.
`void` `setDebugMode(boolean flag)` Sets a flag to turn on debug information in the document
`void` `setDoctype(DTD dtd)` Receive notification of DTD Sets the DTD
`void` `setDocumentLocator(Locator locator)` Receive a Locator object for document events.
`void` `setNodeFactory(NodeFactory f)` Set a optional NodeFactory to be used for creating custom DOM trees
`void` `setNodeFactory(XMLDocument doc)` Set document as the factory to create nodes
`void` `setTextDecl(java.lang.String version, java.lang.String encoding)` Receive notification of a Text XML Declaration.
`void` `setXMLDecl(java.lang.String version, java.lang.String standalone, java.lang.String encoding)` Receive notification of a XML Declaration.
`void` `startCDATA()` Report the start of a CDATA section.
`void` `startDocument()` Receive notification of the beginning of the document.
`void` `startDTD(java.lang.String name, java.lang.String publicId, java.lang.String systemId)` Report the start of DTD declarations, if any.
`void` `startElement(NSName elem, SAXAttrList attrlist)` Receive notification of the beginning of an element.
`void` `startElement(java.lang.String namespaceURI, java.lang.String localName, java.lang.String qName, Attributes atts)` Receive notification of the beginning of an element.
`void` `startEntity(java.lang.String name)` Report the beginning of some internal and external XML entities.

Methods inherited from class oracle.xml.parser.v2.DefaultXMLDocumentHandler
`endPrefixMapping, getHandler, setError, setHandler, setXMLSchema, skippedEntity, startPrefixMapping`

Methods inherited from class org.xml.sax.HandlerBase
`endElement, error, fatalError, notationDecl, resolveEntity, startElement, unparsedEntityDecl, warning`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Methods inherited from interface org.xml.sax.ContentHandler
`endPrefixMapping, skippedEntity, startPrefixMapping`

Methods inherited from interface org.xml.sax.DocumentHandler
`endElement, startElement`

Field Detail

### root

    protected XMLNode root

Constructor Detail

### DocumentBuilder

    public DocumentBuilder()

  Default Constructor. Creates a document builder that can be used as XMLDocumentHandler

Method Detail

### reset

    public void reset()

  Resets the document builder state

### startElement

    public void startElement(NSName elem,
                             SAXAttrList attrlist)
                      throws SAXException

  Receive notification of the beginning of an element.
  Specified by:
    `startElement` in interface `XMLDocumentHandler`
  Overrides:
    `startElement` in class `DefaultXMLDocumentHandler`
  Parameters:
    `elem` - NSName object
    `attrlist` - SAXAttrList for the element
  Throws:
    `SAXException` - A `SAXException` could be thrown.
  See Also:
    `DocumentHandler.startElement(java.lang.String, org.xml.sax.AttributeList)`

### startElement

    public void startElement(java.lang.String namespaceURI,
                             java.lang.String localName,
                             java.lang.String qName,
                             Attributes atts)
                      throws SAXException

  Receive notification of the beginning of an element.
  Specified by:
    `startElement` in interface `ContentHandler`
  Overrides:
    `startElement` in class `DefaultXMLDocumentHandler`
  Parameters:
    `namespaceURI` - The Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed.
    `localName` - The local name (without prefix), or the empty string if Namespace processing is not being performed.
    `qName` - The qualified name (with prefix), or the empty string if qualified names are not available.
    `atts` - The attributes attached to the element. If there are no attributes, it shall be an empty Attributes object.
  Throws:
    `SAXException` - Any SAX exception, possibly wrapping another exception.
  See Also:
    `endElement(oracle.xml.parser.v2.NSName)`, `Attributes`

### endElement

    public void endElement(NSName elem)
                    throws SAXException

  Receive notification of the end of an element.
  Specified by:
    `endElement` in interface `XMLDocumentHandler`
  Overrides:
    `endElement` in class `DefaultXMLDocumentHandler`
  Parameters:
    `elem` - NSName object
  Throws:
    `SAXException` - A `SAXException` could be thrown.
  See Also:
    `DocumentHandler.endElement(java.lang.String)`

### endElement

    public void endElement(java.lang.String namespaceURI,
                           java.lang.String localName,
                           java.lang.String qName)
                    throws SAXException

  Receive notification of the end of an element.
  Specified by:
    `endElement` in interface `ContentHandler`
  Overrides:
    `endElement` in class `DefaultXMLDocumentHandler`
  Parameters:
    `namespaceURI` - The Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed.
    `localName` - The local name (without prefix), or the empty string if Namespace processing is not being performed.
    `qName` - The qualified XML 1.0 name (with prefix), or the empty string if qualified names are not available.
  Throws:
    `SAXException` - Any SAX exception, possibly wrapping another exception.

### setDocumentLocator

    public void setDocumentLocator(Locator locator)

  Receive a Locator object for document events.

  By default, do nothing. Application writers may override this method in a subclass if they wish to store the locator for use with other document events.

  Specified by:
    `setDocumentLocator` in interface `ContentHandler`
  Specified by:
    `setDocumentLocator` in interface `DocumentHandler`
  Overrides:
    `setDocumentLocator` in class `HandlerBase`
  Parameters:
    `locator` - A locator for all SAX document events.
  See Also:
    `DocumentHandler.setDocumentLocator(org.xml.sax.Locator)`, `Locator`

### getLocator

    public Locator getLocator()

  Get the locator reported by the Reader using setDocumentLocator
  Returns:
    locator

### getDocument

    public XMLDocument getDocument()

  Get the document being build
  Returns:
    XMLDocument

### getRoot

    public XMLNode getRoot()

  Get the root of tree being built
  Returns:
    the root node

### startDocument

    public void startDocument()
                       throws SAXException

  Receive notification of the beginning of the document.
  Specified by:
    `startDocument` in interface `ContentHandler`
  Specified by:
    `startDocument` in interface `DocumentHandler`
  Overrides:
    `startDocument` in class `HandlerBase`
  Throws:
    `SAXException` - Any SAX exception, possibly wrapping another exception.
  See Also:
    `DocumentHandler.startDocument()`

### endDocument

    public void endDocument()
                     throws SAXException

  Receive notification of the end of the document.
  Specified by:
    `endDocument` in interface `ContentHandler`
  Specified by:
    `endDocument` in interface `DocumentHandler`
  Overrides:
    `endDocument` in class `HandlerBase`
  Throws:
    `SAXException` - Any SAX exception, possibly wrapping another exception.
  See Also:
    `DocumentHandler.endDocument()`

### setDoctype

    public void setDoctype(DTD dtd)
                    throws SAXException

  Receive notification of DTD Sets the DTD
  Specified by:
    `setDoctype` in interface `XMLDocumentHandler`
  Overrides:
    `setDoctype` in class `DefaultXMLDocumentHandler`
  Parameters:
    `dtd` - set the DTD for the document
  Throws:
    `SAXException` - Any SAX exception, possibly wrapping another exception.

### endDoctype

    public void endDoctype()
                    throws SAXException

  Receive notification of end of the DTD.
  Specified by:
    `endDoctype` in interface `XMLDocumentHandler`
  Overrides:
    `endDoctype` in class `DefaultXMLDocumentHandler`
  Throws:
    `SAXException` - Any SAX exception, possibly wrapping another exception.

### characters

    public void characters(char[] ch,
                           int start,
                           int length)
                    throws SAXException

  Receive notification of character data inside an element.
  Specified by:
    `characters` in interface `ContentHandler`
  Specified by:
    `characters` in interface `DocumentHandler`
  Overrides:
    `characters` in class `HandlerBase`
  Parameters:
    `ch` - The characters.
    `start` - The start position in the character array.
    `length` - The number of characters to use from the character array.
  Throws:
    `SAXException` - Any SAX exception, possibly wrapping another exception.
  See Also:
    `DocumentHandler.characters(char[], int, int)`

### cDATASection

    public void cDATASection(char[] ch,
                             int start,
                             int length)
                      throws SAXException

  Receive notification of CDATA Section data inside an element.
  Specified by:
    `cDATASection` in interface `XMLDocumentHandler`
  Overrides:
    `cDATASection` in class `DefaultXMLDocumentHandler`
  Parameters:
    `ch` - The CDATA characters.
    `start` - The start position in the character array.
    `length` - The number of characters to use from the character array.
  Throws:
    `SAXException` - Any SAX exception, possibly wrapping another exception.
  See Also:
    `DocumentHandler.characters(char[], int, int)`

### ignorableWhitespace

    public void ignorableWhitespace(char[] ch,
                                    int start,
                                    int length)
                             throws SAXException

  Receive notification of ignorable whitespace in element content.
  Specified by:
    `ignorableWhitespace` in interface `ContentHandler`
  Specified by:
    `ignorableWhitespace` in interface `DocumentHandler`
  Overrides:
    `ignorableWhitespace` in class `HandlerBase`
  Parameters:
    `ch` - The whitespace characters.
    `start` - The start position in the character array.
    `length` - The number of characters to use from the character array.
  Throws:
    `SAXException` - Any SAX exception, possibly wrapping another exception.
  See Also:
    `DocumentHandler.ignorableWhitespace(char[], int, int)`

### processingInstruction

    public void processingInstruction(java.lang.String target,
                                      java.lang.String data)
                               throws SAXException

  Receive notification of a processing instruction.
  Specified by:
    `processingInstruction` in interface `ContentHandler`
  Specified by:
    `processingInstruction` in interface `DocumentHandler`
  Overrides:
    `processingInstruction` in class `HandlerBase`
  Parameters:
    `target` - The processing instruction target.
    `data` - The processing instruction data, or null if none is supplied.
  Throws:
    `SAXException` - Any SAX exception, possibly wrapping another exception.
  See Also:
    `DocumentHandler.processingInstruction(java.lang.String, java.lang.String)`

### setXMLDecl

    public void setXMLDecl(java.lang.String version,
                           java.lang.String standalone,
                           java.lang.String encoding)
                    throws SAXException

  Receive notification of a XML Declaration.

  The Parser will invoke this method once for XML Decl

  Specified by:
    `setXMLDecl` in interface `XMLDocumentHandler`
  Overrides:
    `setXMLDecl` in class `DefaultXMLDocumentHandler`
  Parameters:
    `version` - The version number
    `standalone` - The standalone value (or null, if not specifed)
    `encoding` - The encoding name (or null, if not specifed)
  Throws:
    `SAXException` - Any SAX exception, possibly wrapping another exception.

### setTextDecl

    public void setTextDecl(java.lang.String version,
                            java.lang.String encoding)
                     throws SAXException

  Receive notification of a Text XML Declaration.

  The Parser will invoke this method once for each text XML Decl

  Specified by:
    `setTextDecl` in interface `XMLDocumentHandler`
  Overrides:
    `setTextDecl` in class `DefaultXMLDocumentHandler`
  Parameters:
    `version` - The version number (or null, if not specified)
    `encoding` - The encoding name
  Throws:
    `SAXException` - Any SAX exception, possibly wrapping another exception.

### comment

    public void comment(java.lang.String data)
                 throws SAXException

  Receive notification of a comment.
  Specified by:
    `comment` in interface `XMLDocumentHandler`
  Overrides:
    `comment` in class `DefaultXMLDocumentHandler`
  Parameters:
    `data` - The comment data, or null if none was supplied.
  Throws:
    `SAXException` - Any SAX exception, possibly wrapping another exception.

### startDTD

    public void startDTD(java.lang.String name,
                         java.lang.String publicId,
                         java.lang.String systemId)
                  throws SAXException

  Report the start of DTD declarations, if any.
  Specified by:
    `startDTD` in interface `LexicalHandler`
  Parameters:
    `name` - The document type name.
    `publicId` - The declared public identifier for the external DTD subset, or null if none was declared.
    `systemId` - The declared system identifier for the external DTD subset, or null if none was declared.
  Throws:
    `SAXException` - The application may raise an exception.
  See Also:
    `endDTD()`, `startEntity(java.lang.String)`

### endDTD

    public void endDTD()
                throws SAXException

  Report the end of DTD declarations.
  Specified by:
    `endDTD` in interface `LexicalHandler`
  Throws:
    `SAXException` - The application may raise an exception.
  See Also:
    `startDTD(java.lang.String, java.lang.String, java.lang.String)`

### startEntity

    public void startEntity(java.lang.String name)
                     throws SAXException

  Report the beginning of some internal and external XML entities.

  All start/endEntity events must be properly nested.

  Specified by:
    `startEntity` in interface `LexicalHandler`
  Parameters:
    `name` - The name of the entity. If it is a parameter entity, the name will begin with '%', and if it is the external DTD subset, it will be "[dtd]".
  Throws:
    `SAXException` - The application may raise an exception.
  See Also:
    `endEntity(java.lang.String)`, `DeclHandler.internalEntityDecl(java.lang.String, java.lang.String)`, `DeclHandler.externalEntityDecl(java.lang.String, java.lang.String, java.lang.String)`

### endEntity

    public void endEntity(java.lang.String name)
                   throws SAXException

  Report the end of an entity.
  Specified by:
    `endEntity` in interface `LexicalHandler`
  Parameters:
    `name` - The name of the entity that is ending.
  Throws:
    `SAXException` - The application may raise an exception.
  See Also:
    `startEntity(java.lang.String)`

### startCDATA

    public void startCDATA()
                    throws SAXException

  Report the start of a CDATA section.
  Specified by:
    `startCDATA` in interface `LexicalHandler`
  Throws:
    `SAXException` - The application may raise an exception.
  See Also:
    `endCDATA()`

### endCDATA

    public void endCDATA()
                  throws SAXException

  Report the end of a CDATA section.
  Specified by:
    `endCDATA` in interface `LexicalHandler`
  Throws:
    `SAXException` - The application may raise an exception.
  See Also:
    `startCDATA()`

### comment

    public void comment(char[] ch,
                        int start,
                        int length)
                 throws SAXException

  Report an XML comment anywhere in the document.
  Specified by:
    `comment` in interface `LexicalHandler`
  Parameters:
    `ch` - An array holding the characters in the comment.
    `start` - The starting position in the array.
    `length` - The number of characters to use from the array.
  Throws:
    `SAXException` - The application may raise an exception.

### elementDecl

    public void elementDecl(java.lang.String name,
                            java.lang.String model)
                     throws SAXException

  Report an element type declaration.
  Specified by:
    `elementDecl` in interface `DeclHandler`
  Parameters:
    `name` - The element type name.
    `model` - The content model as a normalized string.
  Throws:
    `SAXException` - The application may raise an exception.

### attributeDecl

    public void attributeDecl(java.lang.String eName,
                              java.lang.String aName,
                              java.lang.String type,
                              java.lang.String valueDefault,
                              java.lang.String value)
                       throws SAXException

  Report an attribute type declaration.
  Specified by:
    `attributeDecl` in interface `DeclHandler`
  Parameters:
    `eName` - The name of the associated element.
    `aName` - The name of the attribute.
    `type` - A string representing the attribute type.
    `valueDefault` - A string representing the attribute default ("#IMPLIED", "#REQUIRED", or "#FIXED") or null if none of these applies.
    `value` - A string representing the attribute's default value, or null if there is none.
  Throws:
    `SAXException` - The application may raise an exception.

### internalEntityDecl

    public void internalEntityDecl(java.lang.String name,
                                   java.lang.String value)
                            throws SAXException

  Report an internal entity declaration.
  Specified by:
    `internalEntityDecl` in interface `DeclHandler`
  Parameters:
    `name` - The name of the entity. If it is a parameter entity, the name will begin with '%'.
    `value` - The replacement text of the entity.
  Throws:
    `SAXException` - The application may raise an exception.
  See Also:
    `externalEntityDecl(java.lang.String, java.lang.String, java.lang.String)`, `DTDHandler.unparsedEntityDecl(java.lang.String, java.lang.String, java.lang.String, java.lang.String)`

### externalEntityDecl

    public void externalEntityDecl(java.lang.String name,
                                   java.lang.String publicId,
                                   java.lang.String systemId)
                            throws SAXException

  Report a parsed external entity declaration.
  Specified by:
    `externalEntityDecl` in interface `DeclHandler`
  Parameters:
    `name` - The name of the entity. If it is a parameter entity, the name will begin with '%'.
    `publicId` - The declared public identifier of the entity, or null if none was declared.
    `systemId` - The declared system identifier of the entity.
  Throws:
    `SAXException` - The application may raise an exception.
  See Also:
    `internalEntityDecl(java.lang.String, java.lang.String)`, `DTDHandler.unparsedEntityDecl(java.lang.String, java.lang.String, java.lang.String, java.lang.String)`

### setDebugMode

    public void setDebugMode(boolean flag)

  Sets a flag to turn on debug information in the document
  Parameters:
    `flag` - determines whether debug info is stored

### retainCDATASection

    public void retainCDATASection(boolean flag)

  Sets a flag to retain CDATA sections
  Parameters:
    `flag` - determines whether CDATA sections are retained

### setNodeFactory

    public void setNodeFactory(XMLDocument doc)

  Set document as the factory to create nodes
  Parameters:
    `doc` - the document to be used

### setNodeFactory

    public void setNodeFactory(NodeFactory f)

  Set a optional NodeFactory to be used for creating custom DOM trees
  Parameters:
    `f` - NodeFactory

### resetNodeFactory

    public void resetNodeFactory()

  Reset the NodeFactory and go back to the original behaviour.

### setAttribute

    public void setAttribute(java.lang.String name,
                             java.lang.Object value)
                      throws java.lang.IllegalArgumentException

  Allows the user to set specific attributes on the underlying implementation.
  Parameters:
    `name` - The name of the attribute.
    `value` - The value of the attribute.
  Throws:
    `java.lang.IllegalArgumentException` - thrown if the underlying implementation doesn't recognize the attribute.

Skip navigation links

Oracle® Database XML Java API Reference 11g Release 2 (11.2) E10769-01

Copyright © 2003, 2009, Oracle and/or its affiliates. All rights reserved.