- java.lang.Object
-
- javax.xml.parsers.DocumentBuilder
-
public abstract class DocumentBuilder extends Object
Defines the API to obtain DOM Document instances from an XML document. Using this class, an application programmer can obtain aDocumentfrom XML.An instance of this class can be obtained from the
DocumentBuilderFactory.newDocumentBuilder()method. Once an instance of this class is obtained, XML can be parsed from a variety of input sources. These input sources are InputStreams, Files, URLs, and SAX InputSources.Note that this class reuses several classes from the SAX API. This does not require that the implementor of the underlying DOM implementation use a SAX parser to parse XML document into a
Document. It merely requires that the implementation communicate with the application using these existing APIs.- Since:
- 1.4
-
-
Constructor Summary
Constructors Modifier Constructor Description protectedDocumentBuilder()Protected constructor
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description abstract DOMImplementationgetDOMImplementation()Obtain an instance of aDOMImplementationobject.SchemagetSchema()Get a reference to the theSchemabeing used by the XML processor.abstract booleanisNamespaceAware()Indicates whether or not this parser is configured to understand namespaces.abstract booleanisValidating()Indicates whether or not this parser is configured to validate XML documents.booleanisXIncludeAware()Get the XInclude processing mode for this parser.abstract DocumentnewDocument()Obtain a new instance of a DOMDocumentobject to build a DOM tree with.Documentparse(File f)Parse the content of the given file as an XML document and return a new DOMDocumentobject.Documentparse(InputStream is)Parse the content of the givenInputStreamas an XML document and return a new DOMDocumentobject.Documentparse(InputStream is, String systemId)Parse the content of the givenInputStreamas an XML document and return a new DOMDocumentobject.Documentparse(String uri)Parse the content of the given URI as an XML document and return a new DOMDocumentobject.abstract Documentparse(InputSource is)Parse the content of the given input source as an XML document and return a new DOMDocumentobject.voidreset()Reset thisDocumentBuilderto its original configuration.abstract voidsetEntityResolver(EntityResolver er)Specify theEntityResolverto be used to resolve entities present in the XML document to be parsed.abstract voidsetErrorHandler(ErrorHandler eh)Specify theErrorHandlerto be used by the parser.
-
-
-
Method Detail
-
reset
public void reset()
Reset this
DocumentBuilderto its original configuration.DocumentBuilderis reset to the same state as when it was created withDocumentBuilderFactory.newDocumentBuilder().reset()is designed to allow the reuse of existingDocumentBuilders thus saving resources associated with the creation of newDocumentBuilders.The reset
DocumentBuilderis not guaranteed to have the sameEntityResolverorErrorHandlerObjects, e.g.Object.equals(Object obj). It is guaranteed to have a functionally equalEntityResolverandErrorHandler.- Throws:
UnsupportedOperationException- When implementation does not override this method.- Since:
- 1.5
-
parse
public Document parse(InputStream is) throws SAXException, IOException
Parse the content of the givenInputStreamas an XML document and return a new DOMDocumentobject. AnIllegalArgumentExceptionis thrown if theInputStreamis null.- Parameters:
is- InputStream containing the content to be parsed.- Returns:
Documentresult of parsing theInputStream- Throws:
IOException- If any IO errors occur.SAXException- If any parse errors occur.IllegalArgumentException- Whenisisnull- See Also:
DocumentHandler
-
parse
public Document parse(InputStream is, String systemId) throws SAXException, IOException
Parse the content of the givenInputStreamas an XML document and return a new DOMDocumentobject. AnIllegalArgumentExceptionis thrown if theInputStreamis null.- Parameters:
is- InputStream containing the content to be parsed.systemId- Provide a base for resolving relative URIs.- Returns:
- A new DOM Document object.
- Throws:
IOException- If any IO errors occur.SAXException- If any parse errors occur.IllegalArgumentException- Whenisisnull- See Also:
DocumentHandler
-
parse
public Document parse(String uri) throws SAXException, IOException
Parse the content of the given URI as an XML document and return a new DOMDocumentobject. AnIllegalArgumentExceptionis thrown if the URI isnullnull.- Parameters:
uri- The location of the content to be parsed.- Returns:
- A new DOM Document object.
- Throws:
IOException- If any IO errors occur.SAXException- If any parse errors occur.IllegalArgumentException- Whenuriisnull- See Also:
DocumentHandler
-
parse
public Document parse(File f) throws SAXException, IOException
Parse the content of the given file as an XML document and return a new DOMDocumentobject. AnIllegalArgumentExceptionis thrown if theFileisnullnull.- Parameters:
f- The file containing the XML to parse.- Returns:
- A new DOM Document object.
- Throws:
IOException- If any IO errors occur.SAXException- If any parse errors occur.IllegalArgumentException- Whenfisnull- See Also:
DocumentHandler
-
parse
public abstract Document parse(InputSource is) throws SAXException, IOException
Parse the content of the given input source as an XML document and return a new DOMDocumentobject. AnIllegalArgumentExceptionis thrown if theInputSourceisnullnull.- Parameters:
is- InputSource containing the content to be parsed.- Returns:
- A new DOM Document object.
- Throws:
IOException- If any IO errors occur.SAXException- If any parse errors occur.IllegalArgumentException- Whenisisnull- See Also:
DocumentHandler
-
isNamespaceAware
public abstract boolean isNamespaceAware()
Indicates whether or not this parser is configured to understand namespaces.- Returns:
- true if this parser is configured to understand namespaces; false otherwise.
-
isValidating
public abstract boolean isValidating()
Indicates whether or not this parser is configured to validate XML documents.- Returns:
- true if this parser is configured to validate XML documents; false otherwise.
-
setEntityResolver
public abstract void setEntityResolver(EntityResolver er)
Specify theEntityResolverto be used to resolve entities present in the XML document to be parsed. Setting this tonullwill result in the underlying implementation using it's own default implementation and behavior.- Parameters:
er- TheEntityResolverto be used to resolve entities present in the XML document to be parsed.
-
setErrorHandler
public abstract void setErrorHandler(ErrorHandler eh)
Specify theErrorHandlerto be used by the parser. Setting this tonullwill result in the underlying implementation using it's own default implementation and behavior.- Parameters:
eh- TheErrorHandlerto be used by the parser.
-
newDocument
public abstract Document newDocument()
Obtain a new instance of a DOMDocumentobject to build a DOM tree with.- Returns:
- A new instance of a DOM Document object.
-
getDOMImplementation
public abstract DOMImplementation getDOMImplementation()
Obtain an instance of aDOMImplementationobject.- Returns:
- A new instance of a
DOMImplementation.
-
getSchema
public Schema getSchema()
Get a reference to the the
Schemabeing used by the XML processor.If no schema is being used,
nullis returned.- Returns:
Schemabeing used ornullif none in use- Throws:
UnsupportedOperationException- When implementation does not override this method- Since:
- 1.5
-
isXIncludeAware
public boolean isXIncludeAware()
Get the XInclude processing mode for this parser.
- Returns:
- the return value of
the
DocumentBuilderFactory.isXIncludeAware()when this parser was created from factory. - Throws:
UnsupportedOperationException- When implementation does not override this method- Since:
- 1.5
- See Also:
DocumentBuilderFactory.setXIncludeAware(boolean)
-
-