Top Description Fields Constructors Methods
org.jdom2.input.sax

public Class SAXBuilderEngine

extends Object
implements SAXEngine
Class Inheritance
All Implemented Interfaces
org.jdom2.input.sax.SAXEngine
Imports
java.io.File, .IOException, .InputStream, .Reader, java.net.MalformedURLException, .URL, org.xml.sax.DTDHandler, .EntityResolver, .ErrorHandler, .InputSource, .SAXException, .SAXParseException, .XMLReader, org.jdom2.Document, .JDOMException, .JDOMFactory, org.jdom2.input.JDOMParseException
Builds a JDOM document from files, streams, readers, URLs, or a SAX org.xml.sax.InputSource instance using a SAX parser. This Engine is built by the SAXBuilder based on the state of the SAXBuilder when the engine was produced. It is not possible to reconfigure the engine once built, but it can be reused many times (though not concurrently). This makes it the fastest way to process many multitudes of XML documents (if those documents are all parsed the same way). If you want to process in multiple threads you can safely have one SAXBuilderEngine in each thread on the condition that:
  1. The JDOMFactory is thread-safe (the JDOM-supplied JDOMFactories are)
  2. There is no XMLFilter given to the SAXBuilder, or, if there is, then it is thread-safe.
  3. If you have a custom XMLReaderJDOMFactory that it supplies a new instance of an XMLReader on each call (the JDOM-supplied ones all do).
  4. If you have a custom SAXHandlerFactory that it supplies a new instance of a SAXHanfler on each call (the JDOM-supplied one does)
Author
Rolf Lear
See Also
org.jdom2.input.sax

Field Summary

Modifier and TypeField and Description
private final SAXHandler
saxHandler

The SAXHandler

private final XMLReader
saxParser

The SAX XMLReader.

private final boolean
validating

indicates whether this is a validating parser

Constructor Summary

AccessConstructor and Description
public
SAXBuilderEngine(final XMLReader
The XMLReader this Engine parses with
reader, final SAXHandler
The SAXHandler that processes the SAX Events.
handler, final boolean
True if this is a validating system.
validating)

Creates a new SAXBuilderEngine.

Method Summary

Modifier and TypeMethod and Description
public Document
build(final InputSource
InputSource to read from
in)

Implements org.jdom2.input.sax.SAXEngine.build.

This builds a document from the supplied input source.
public Document
build(final InputStream
InputStream to read from
in)

Implements org.jdom2.input.sax.SAXEngine.build.

This builds a document from the supplied input stream.

public Document
build(final File
File to read from
file)

Implements org.jdom2.input.sax.SAXEngine.build.

This builds a document from the supplied filename.

public Document
build(final URL
URL to read from.
url)

Implements org.jdom2.input.sax.SAXEngine.build.

This builds a document from the supplied URL.

public Document
build(final InputStream
InputStream to read from.
in, final String
base for resolving relative URIs
systemId)

Implements org.jdom2.input.sax.SAXEngine.build.

This builds a document from the supplied input stream.

public Document
build(final Reader
Reader to read from
characterStream)

Implements org.jdom2.input.sax.SAXEngine.build.

This builds a document from the supplied Reader.

public Document
build(final Reader
Reader to read from.
characterStream, final String
base for resolving relative URIs
systemId)

Implements org.jdom2.input.sax.SAXEngine.build.

This builds a document from the supplied Reader.

public Document
build(final String
URI for the input
systemId)

Implements org.jdom2.input.sax.SAXEngine.build.

This builds a document from the supplied URI.

private static URL

Returns:

URL form of the file, with special characters handled
fileToURL(final File
file object whose path will be converted
file)

Custom File.toUrl() implementation to handle special chars in file names Actually, we can now rely on the core Java toURI function,

public DTDHandler
getDTDHandler()

Implements org.jdom2.input.sax.SAXEngine.getDTDHandler.

Returns the DTDHandler assigned, or null if none.
public EntityResolver
getEntityResolver()

Implements org.jdom2.input.sax.SAXEngine.getEntityResolver.

Returns the EntityResolver assigned, or null if none.
public ErrorHandler
getErrorHandler()

Implements org.jdom2.input.sax.SAXEngine.getErrorHandler.

Returns the ErrorHandler assigned, or null if none.
public boolean
getExpandEntities()

Implements org.jdom2.input.sax.SAXEngine.getExpandEntities.

Returns whether or not entities are being expanded into normal text content.
public boolean
getIgnoringBoundaryWhitespace()

Implements org.jdom2.input.sax.SAXEngine.getIgnoringBoundaryWhitespace.

Returns whether or not the parser will eliminate element content containing only whitespace.
public boolean
getIgnoringElementContentWhitespace()

Implements org.jdom2.input.sax.SAXEngine.getIgnoringElementContentWhitespace.

Returns whether element content whitespace is to be ignored during the build.
public JDOMFactory
getJDOMFactory()

Implements org.jdom2.input.sax.SAXEngine.getJDOMFactory.

Returns the current org.jdom2.JDOMFactory in use.
public boolean
isValidating()

Implements org.jdom2.input.sax.SAXEngine.isValidating.

Returns whether validation is to be performed during the build.
Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

saxHandlerback to summary
private final SAXHandler saxHandler

The SAXHandler

saxParserback to summary
private final XMLReader saxParser

The SAX XMLReader.

validatingback to summary
private final boolean validating

indicates whether this is a validating parser

Constructor Detail

SAXBuilderEngineback to summary
public SAXBuilderEngine(final XMLReader reader, final SAXHandler handler, final boolean validating)

Creates a new SAXBuilderEngine.

Parameters
reader:XMLReader

The XMLReader this Engine parses with

handler:SAXHandler

The SAXHandler that processes the SAX Events.

validating:boolean

True if this is a validating system.

Method Detail

buildback to summary
public Document build(final InputSource in) throws JDOMException, IOException

Implements org.jdom2.input.sax.SAXEngine.build.

Doc from org.jdom2.input.sax.SAXEngine.build.

This builds a document from the supplied input source.

Parameters
in:InputSource

InputSource to read from

Returns:Document

Document resultant Document object

Annotations
@Override
Exceptions
JDOMException:
when errors occur in parsing
IOException:
when an I/O error prevents a document from being fully parsed
buildback to summary
public Document build(final InputStream in) throws JDOMException, IOException

Implements org.jdom2.input.sax.SAXEngine.build.

Doc from org.jdom2.input.sax.SAXEngine.build.

This builds a document from the supplied input stream.

Parameters
in:InputStream

InputStream to read from

Returns:Document

Document resultant Document object

Annotations
@Override
Exceptions
JDOMException:
when errors occur in parsing
IOException:
when an I/O error prevents a document from being fully parsed.
buildback to summary
public Document build(final File file) throws JDOMException, IOException

Implements org.jdom2.input.sax.SAXEngine.build.

Doc from org.jdom2.input.sax.SAXEngine.build.

This builds a document from the supplied filename.

Parameters
file:File

File to read from

Returns:Document

Document resultant Document object

Annotations
@Override
Exceptions
JDOMException:
when errors occur in parsing
IOException:
when an I/O error prevents a document from being fully parsed
buildback to summary
public Document build(final URL url) throws JDOMException, IOException

Implements org.jdom2.input.sax.SAXEngine.build.

Doc from org.jdom2.input.sax.SAXEngine.build.

This builds a document from the supplied URL.

Parameters
url:URL

URL to read from.

Returns:Document

Document - resultant Document object.

Annotations
@Override
Exceptions
JDOMException:
when errors occur in parsing
IOException:
when an I/O error prevents a document from being fully parsed.
buildback to summary
public Document build(final InputStream in, final String systemId) throws JDOMException, IOException

Implements org.jdom2.input.sax.SAXEngine.build.

Doc from org.jdom2.input.sax.SAXEngine.build.

This builds a document from the supplied input stream.

Parameters
in:InputStream

InputStream to read from.

systemId:String

base for resolving relative URIs

Returns:Document

Document resultant Document object

Annotations
@Override
Exceptions
JDOMException:
when errors occur in parsing
IOException:
when an I/O error prevents a document from being fully parsed
buildback to summary
public Document build(final Reader characterStream) throws JDOMException, IOException

Implements org.jdom2.input.sax.SAXEngine.build.

Doc from org.jdom2.input.sax.SAXEngine.build.

This builds a document from the supplied Reader. It's the programmer's responsibility to make sure the reader matches the encoding of the file. It's often easier and safer to use an InputStream rather than a Reader, and to let the parser auto-detect the encoding from the XML declaration.

Parameters
characterStream:Reader

Reader to read from

Returns:Document

Document resultant Document object

Annotations
@Override
Exceptions
JDOMException:
when errors occur in parsing
IOException:
when an I/O error prevents a document from being fully parsed
buildback to summary
public Document build(final Reader characterStream, final String systemId) throws JDOMException, IOException

Implements org.jdom2.input.sax.SAXEngine.build.

Doc from org.jdom2.input.sax.SAXEngine.build.

This builds a document from the supplied Reader. It's the programmer's responsibility to make sure the reader matches the encoding of the file. It's often easier and safer to use an InputStream rather than a Reader, and to let the parser auto-detect the encoding from the XML declaration.

Parameters
characterStream:Reader

Reader to read from.

systemId:String

base for resolving relative URIs

Returns:Document

Document resultant Document object

Annotations
@Override
Exceptions
JDOMException:
when errors occur in parsing
IOException:
when an I/O error prevents a document from being fully parsed
buildback to summary
public Document build(final String systemId) throws JDOMException, IOException

Implements org.jdom2.input.sax.SAXEngine.build.

Doc from org.jdom2.input.sax.SAXEngine.build.

This builds a document from the supplied URI.

Parameters
systemId:String

URI for the input

Returns:Document

Document resultant Document object

Annotations
@Override
Exceptions
JDOMException:
when errors occur in parsing
IOException:
when an I/O error prevents a document from being fully parsed
fileToURLback to summary
private static URL fileToURL(final File file) throws MalformedURLException

Custom File.toUrl() implementation to handle special chars in file names Actually, we can now rely on the core Java toURI function,

Parameters
file:File

file object whose path will be converted

Returns:URL

URL form of the file, with special characters handled

Exceptions
MalformedURLException:
if there's a problem constructing a URL
getDTDHandlerback to summary
public DTDHandler getDTDHandler()

Implements org.jdom2.input.sax.SAXEngine.getDTDHandler.

Doc from org.jdom2.input.sax.SAXEngine.getDTDHandler.

Returns the DTDHandler assigned, or null if none.

Returns:DTDHandler

the DTDHandler assigned

Annotations
@Override
getEntityResolverback to summary
public EntityResolver getEntityResolver()

Implements org.jdom2.input.sax.SAXEngine.getEntityResolver.

Doc from org.jdom2.input.sax.SAXEngine.getEntityResolver.

Returns the EntityResolver assigned, or null if none.

Returns:EntityResolver

the EntityResolver assigned

Annotations
@Override
getErrorHandlerback to summary
public ErrorHandler getErrorHandler()

Implements org.jdom2.input.sax.SAXEngine.getErrorHandler.

Doc from org.jdom2.input.sax.SAXEngine.getErrorHandler.

Returns the ErrorHandler assigned, or null if none.

Returns:ErrorHandler

the ErrorHandler assigned, or null if none

Annotations
@Override
getExpandEntitiesback to summary
public boolean getExpandEntities()

Implements org.jdom2.input.sax.SAXEngine.getExpandEntities.

Doc from org.jdom2.input.sax.SAXEngine.getExpandEntities.

Returns whether or not entities are being expanded into normal text content.

Returns:boolean

whether entities are being expanded

Annotations
@Override
getIgnoringBoundaryWhitespaceback to summary
public boolean getIgnoringBoundaryWhitespace()

Implements org.jdom2.input.sax.SAXEngine.getIgnoringBoundaryWhitespace.

Doc from org.jdom2.input.sax.SAXEngine.getIgnoringBoundaryWhitespace.

Returns whether or not the parser will eliminate element content containing only whitespace.

Returns:boolean

boolean - whether only whitespace content will be ignored during build.

Annotations
@Override
getIgnoringElementContentWhitespaceback to summary
public boolean getIgnoringElementContentWhitespace()

Implements org.jdom2.input.sax.SAXEngine.getIgnoringElementContentWhitespace.

Doc from org.jdom2.input.sax.SAXEngine.getIgnoringElementContentWhitespace.

Returns whether element content whitespace is to be ignored during the build.

Returns:boolean

whether element content whitespace is to be ignored during the build

Annotations
@Override
getJDOMFactoryback to summary
public JDOMFactory getJDOMFactory()

Implements org.jdom2.input.sax.SAXEngine.getJDOMFactory.

Doc from org.jdom2.input.sax.SAXEngine.getJDOMFactory.

Returns the current org.jdom2.JDOMFactory in use.

Returns:JDOMFactory

the factory in use

Annotations
@Override
isValidatingback to summary
public boolean isValidating()

Implements org.jdom2.input.sax.SAXEngine.isValidating.

Doc from org.jdom2.input.sax.SAXEngine.isValidating.

Returns whether validation is to be performed during the build.

Returns:boolean

whether validation is to be performed during the build

Annotations
@Override