Docjar: A Java Source and Docuemnt Enginecom.*    java.*    javax.*    org.*    all    new    plug-in

Quick Search    Search Deep
Overview  Package   Class  Use  Deprecated  Index 
Home >> All >> org >> jdom >> [ input overview ]  PREV CLASS  NEXT CLASS
SUMMARY: JavaDoc of org.jdom.input.SAXBuilder JAVADOC | Sourc code of org.jdom.input.SAXBuilder SOURCE | Download org.jdom.input.SAXBuilder DOWNLOAD | NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.jdom.input
Class SAXBuilder  view SAXBuilder download SAXBuilder.java

java.lang.Object
  extended byorg.jdom.input.SAXBuilder
public class SAXBuilder
extends java.lang.Object

Builds a JDOM document from files, streams, readers, URLs, or a SAX org.xml.sax.InputSource instance using a SAX parser. The builder uses a third-party SAX parser (chosen by JAXP by default, or you can choose manually) to handle the parsing duties and simply listens to the SAX events to construct a document. Details which SAX does not provide, such as whitespace outside the root element, are not represented in the JDOM document. Information about SAX can be found at http://www.saxproject.org.

Known issues: Relative paths for a org.jdom.DocType or org.jdom.EntityRef may be converted by the SAX parser into absolute paths.

Version:
$Revision: 1.89 $, $Date: 2004/09/03 18:24:28 $

Field Summary
private static java.lang.String CVS_ID
           
private static java.lang.String DEFAULT_SAX_DRIVER
          Default parser class to use.
private  boolean expand
          Whether expansion of entities should occur
private  org.jdom.input.JDOMFactory factory
          The factory for creating new JDOM objects
private  java.util.HashMap features
          User-specified features to be set on the SAX parser
private  boolean ignoringWhite
          Whether to ignore ignorable whitespace
private  java.util.HashMap properties
          User-specified properties to be set on the SAX parser
private  boolean reuseParser
          Whether parser reuse is allowed.
private  java.lang.String saxDriverClass
          Adapter class to use
private  org.xml.sax.DTDHandler saxDTDHandler
          DTDHandler class to use
private  org.xml.sax.EntityResolver saxEntityResolver
          EntityResolver class to use
private  org.xml.sax.ErrorHandler saxErrorHandler
          ErrorHandler class to use
private  org.xml.sax.XMLReader saxParser
          The current SAX parser, if parser reuse has been activated.
private  org.xml.sax.XMLFilter saxXMLFilter
          XMLFilter instance to use
private  boolean validate
          Whether validation should occur
 
Constructor Summary
SAXBuilder()
          Creates a new SAXBuilder which will attempt to first locate a parser via JAXP, then will try to use a set of default SAX Drivers.
SAXBuilder(boolean validate)
          Creates a new SAXBuilder which will attempt to first locate a parser via JAXP, then will try to use a set of default SAX Drivers.
SAXBuilder(java.lang.String saxDriverClass)
          Creates a new SAXBuilder using the specified SAX parser.
SAXBuilder(java.lang.String saxDriverClass, boolean validate)
          Creates a new SAXBuilder using the specified SAX parser.
 
Method Summary
 org.jdom.Document build(java.io.File file)
           This builds a document from the supplied filename.
 org.jdom.Document build(org.xml.sax.InputSource in)
          This builds a document from the supplied input source.
 org.jdom.Document build(java.io.InputStream in)
           This builds a document from the supplied input stream.
 org.jdom.Document build(java.io.InputStream in, java.lang.String systemId)
           This builds a document from the supplied input stream.
 org.jdom.Document build(java.io.Reader characterStream)
           This builds a document from the supplied Reader.
 org.jdom.Document build(java.io.Reader characterStream, java.lang.String systemId)
           This builds a document from the supplied Reader.
 org.jdom.Document build(java.lang.String systemId)
           This builds a document from the supplied URI.
 org.jdom.Document build(java.net.URL url)
           This builds a document from the supplied URL.
protected  void configureContentHandler(SAXHandler contentHandler)
          This configures the SAXHandler that will be used to build the Document.
protected  void configureParser(org.xml.sax.XMLReader parser, SAXHandler contentHandler)
          This configures the XMLReader to be used for reading the XML document.
protected  SAXHandler createContentHandler()
          This creates the SAXHandler that will be used to build the Document.
protected  org.xml.sax.XMLReader createParser()
          This creates the XMLReader to be used for reading the XML document.
private static java.net.URL fileToURL(java.io.File file)
          Custom File.toUrl() implementation to handle special chars in file names
 java.lang.String getDriverClass()
          Returns the driver class assigned in the constructor, or null if none.
 org.xml.sax.DTDHandler getDTDHandler()
          Returns the org.xml.sax.DTDHandler assigned, or null if none.
 org.xml.sax.EntityResolver getEntityResolver()
          Returns the org.xml.sax.EntityResolver assigned, or null if none.
 org.xml.sax.ErrorHandler getErrorHandler()
          Returns the org.xml.sax.ErrorHandler assigned, or null if none.
 boolean getExpandEntities()
          Returns whether or not entities are being expanded into normal text content.
 org.jdom.input.JDOMFactory getFactory()
          Returns the current org.jdom.JDOMFactory in use.
 boolean getIgnoringElementContentWhitespace()
          Returns whether element content whitespace is to be ignored during the build.
 boolean getReuseParser()
          Returns whether the contained SAX parser instance is reused across multiple parses.
 boolean getValidation()
          Returns whether validation is to be performed during the build.
 org.xml.sax.XMLFilter getXMLFilter()
          Returns the org.xml.sax.XMLFilter used during parsing, or null if none.
private  void internalSetFeature(org.xml.sax.XMLReader parser, java.lang.String feature, boolean value, java.lang.String displayName)
          Tries to set a feature on the parser.
private  void internalSetProperty(org.xml.sax.XMLReader parser, java.lang.String property, java.lang.Object value, java.lang.String displayName)
           Tries to set a property on the parser.
 void setDTDHandler(org.xml.sax.DTDHandler dtdHandler)
          This sets custom DTDHandler for the Builder.
 void setEntityResolver(org.xml.sax.EntityResolver entityResolver)
          This sets custom EntityResolver for the Builder.
 void setErrorHandler(org.xml.sax.ErrorHandler errorHandler)
          This sets custom ErrorHandler for the Builder.
 void setExpandEntities(boolean expand)
           This sets whether or not to expand entities for the builder.
 void setFactory(org.jdom.input.JDOMFactory factory)
          This sets a custom JDOMFactory for the builder.
 void setFeature(java.lang.String name, boolean value)
          This sets a feature on the SAX parser.
private  void setFeaturesAndProperties(org.xml.sax.XMLReader parser, boolean coreFeatures)
           
 void setIgnoringElementContentWhitespace(boolean ignoringWhite)
          Specifies whether or not the parser should elminate whitespace in element content (sometimes known as "ignorable whitespace") when building the document.
 void setProperty(java.lang.String name, java.lang.Object value)
          This sets a property on the SAX parser.
 void setReuseParser(boolean reuseParser)
          Specifies whether this builder shall reuse the same SAX parser when performing subsequent parses or allocate a new parser for each parse.
 void setValidation(boolean validate)
          This sets validation for the builder.
 void setXMLFilter(org.xml.sax.XMLFilter xmlFilter)
          This sets a custom org.xml.sax.XMLFilter for the builder.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CVS_ID

private static final java.lang.String CVS_ID
See Also:
Constant Field Values

DEFAULT_SAX_DRIVER

private static final java.lang.String DEFAULT_SAX_DRIVER
Default parser class to use. This is used when no other parser is given and JAXP isn't available.

See Also:
Constant Field Values

validate

private boolean validate
Whether validation should occur

expand

private boolean expand
Whether expansion of entities should occur

saxDriverClass

private java.lang.String saxDriverClass
Adapter class to use

saxErrorHandler

private org.xml.sax.ErrorHandler saxErrorHandler
ErrorHandler class to use

saxEntityResolver

private org.xml.sax.EntityResolver saxEntityResolver
EntityResolver class to use

saxDTDHandler

private org.xml.sax.DTDHandler saxDTDHandler
DTDHandler class to use

saxXMLFilter

private org.xml.sax.XMLFilter saxXMLFilter
XMLFilter instance to use

factory

private org.jdom.input.JDOMFactory factory
The factory for creating new JDOM objects

ignoringWhite

private boolean ignoringWhite
Whether to ignore ignorable whitespace

features

private java.util.HashMap features
User-specified features to be set on the SAX parser

properties

private java.util.HashMap properties
User-specified properties to be set on the SAX parser

reuseParser

private boolean reuseParser
Whether parser reuse is allowed.

Default: true

saxParser

private org.xml.sax.XMLReader saxParser
The current SAX parser, if parser reuse has been activated.

Constructor Detail

SAXBuilder

public SAXBuilder()
Creates a new SAXBuilder which will attempt to first locate a parser via JAXP, then will try to use a set of default SAX Drivers. The underlying parser will not validate.

SAXBuilder

public SAXBuilder(boolean validate)
Creates a new SAXBuilder which will attempt to first locate a parser via JAXP, then will try to use a set of default SAX Drivers. The underlying parser will validate or not according to the given parameter.

SAXBuilder

public SAXBuilder(java.lang.String saxDriverClass)
Creates a new SAXBuilder using the specified SAX parser. The underlying parser will not validate.

SAXBuilder

public SAXBuilder(java.lang.String saxDriverClass,
                  boolean validate)
Creates a new SAXBuilder using the specified SAX parser. The underlying parser will validate or not according to the given parameter.

Method Detail

getDriverClass

public java.lang.String getDriverClass()
Returns the driver class assigned in the constructor, or null if none.

getFactory

public org.jdom.input.JDOMFactory getFactory()
Returns the current org.jdom.JDOMFactory in use.

setFactory

public void setFactory(org.jdom.input.JDOMFactory factory)
This sets a custom JDOMFactory for the builder. Use this to build the tree with your own subclasses of the JDOM classes.

getValidation

public boolean getValidation()
Returns whether validation is to be performed during the build.

setValidation

public void setValidation(boolean validate)
This sets validation for the builder.

getErrorHandler

public org.xml.sax.ErrorHandler getErrorHandler()
Returns the org.xml.sax.ErrorHandler assigned, or null if none.

setErrorHandler

public void setErrorHandler(org.xml.sax.ErrorHandler errorHandler)
This sets custom ErrorHandler for the Builder.

getEntityResolver

public org.xml.sax.EntityResolver getEntityResolver()
Returns the org.xml.sax.EntityResolver assigned, or null if none.

setEntityResolver

public void setEntityResolver(org.xml.sax.EntityResolver entityResolver)
This sets custom EntityResolver for the Builder.

getDTDHandler

public org.xml.sax.DTDHandler getDTDHandler()
Returns the org.xml.sax.DTDHandler assigned, or null if none.

setDTDHandler

public void setDTDHandler(org.xml.sax.DTDHandler dtdHandler)
This sets custom DTDHandler for the Builder.

getXMLFilter

public org.xml.sax.XMLFilter getXMLFilter()
Returns the org.xml.sax.XMLFilter used during parsing, or null if none.

setXMLFilter

public void setXMLFilter(org.xml.sax.XMLFilter xmlFilter)
This sets a custom org.xml.sax.XMLFilter for the builder.

getIgnoringElementContentWhitespace

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

setIgnoringElementContentWhitespace

public void setIgnoringElementContentWhitespace(boolean ignoringWhite)
Specifies whether or not the parser should elminate whitespace in element content (sometimes known as "ignorable whitespace") when building the document. Only whitespace which is contained within element content that has an element only content model will be eliminated (see XML Rec 3.2.1). For this setting to take effect requires that validation be turned on. The default value of this setting is false.

getReuseParser

public boolean getReuseParser()
Returns whether the contained SAX parser instance is reused across multiple parses. The default is true.

setReuseParser

public void setReuseParser(boolean reuseParser)
Specifies whether this builder shall reuse the same SAX parser when performing subsequent parses or allocate a new parser for each parse. The default value of this setting is true (parser reuse).

Note: As SAX parser instances are not thread safe, the parser reuse feature should not be used with SAXBuilder instances shared among threads.

setFeature

public void setFeature(java.lang.String name,
                       boolean value)
This sets a feature on the SAX parser. See the SAX documentation for

NOTE: SAXBuilder requires that some particular features of the SAX parser be set up in certain ways for it to work properly. The list of such features may change in the future. Therefore, the use of this method may cause parsing to break, and even if it doesn't break anything today it might break parsing in a future JDOM version, because what JDOM parsers require may change over time. Use with caution.

setProperty

public void setProperty(java.lang.String name,
                        java.lang.Object value)
This sets a property on the SAX parser. See the SAX documentation for more information.

NOTE: SAXBuilder requires that some particular properties of the SAX parser be set up in certain ways for it to work properly. The list of such properties may change in the future. Therefore, the use of this method may cause parsing to break, and even if it doesn't break anything today it might break parsing in a future JDOM version, because what JDOM parsers require may change over time. Use with caution.

build

public org.jdom.Document build(org.xml.sax.InputSource in)
                        throws org.jdom.JDOMException,
                               java.io.IOException
This builds a document from the supplied input source.

createContentHandler

protected SAXHandler createContentHandler()
This creates the SAXHandler that will be used to build the Document.

configureContentHandler

protected void configureContentHandler(SAXHandler contentHandler)
This configures the SAXHandler that will be used to build the Document.

The default implementation simply passes through some configuration settings that were set on the SAXBuilder: setExpandEntities() and setIgnoringElementContentWhitespace().

createParser

protected org.xml.sax.XMLReader createParser()
                                      throws org.jdom.JDOMException
This creates the XMLReader to be used for reading the XML document.

The default behavior is to (1) use the saxDriverClass, if it has been set, (2) try to obtain a parser from JAXP, if it is available, and (3) if all else fails, use a hard-coded default parser (currently the Xerces parser). Subclasses may override this method to determine the parser to use in a different way.

configureParser

protected void configureParser(org.xml.sax.XMLReader parser,
                               SAXHandler contentHandler)
                        throws org.jdom.JDOMException
This configures the XMLReader to be used for reading the XML document.

The default implementation sets various options on the given XMLReader, such as validation, DTD resolution, entity handlers, etc., according to the options that were set (e.g. via setEntityResolver) and set various SAX properties and features that are required for JDOM internals. These features may change in future releases, so change this behavior at your own risk.

setFeaturesAndProperties

private void setFeaturesAndProperties(org.xml.sax.XMLReader parser,
                                      boolean coreFeatures)
                               throws org.jdom.JDOMException

internalSetFeature

private void internalSetFeature(org.xml.sax.XMLReader parser,
                                java.lang.String feature,
                                boolean value,
                                java.lang.String displayName)
                         throws org.jdom.JDOMException
Tries to set a feature on the parser. If the feature cannot be set, throws a JDOMException describing the problem.

internalSetProperty

private void internalSetProperty(org.xml.sax.XMLReader parser,
                                 java.lang.String property,
                                 java.lang.Object value,
                                 java.lang.String displayName)
                          throws org.jdom.JDOMException

Tries to set a property on the parser. If the property cannot be set, throws a JDOMException describing the problem.

build

public org.jdom.Document build(java.io.InputStream in)
                        throws org.jdom.JDOMException,
                               java.io.IOException

This builds a document from the supplied input stream.

build

public org.jdom.Document build(java.io.File file)
                        throws org.jdom.JDOMException,
                               java.io.IOException

This builds a document from the supplied filename.

build

public org.jdom.Document build(java.net.URL url)
                        throws org.jdom.JDOMException,
                               java.io.IOException

This builds a document from the supplied URL.

build

public org.jdom.Document build(java.io.InputStream in,
                               java.lang.String systemId)
                        throws org.jdom.JDOMException,
                               java.io.IOException

This builds a document from the supplied input stream.

build

public org.jdom.Document build(java.io.Reader characterStream)
                        throws org.jdom.JDOMException,
                               java.io.IOException

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.

build

public org.jdom.Document build(java.io.Reader characterStream,
                               java.lang.String systemId)
                        throws org.jdom.JDOMException,
                               java.io.IOException

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.

build

public org.jdom.Document build(java.lang.String systemId)
                        throws org.jdom.JDOMException,
                               java.io.IOException

This builds a document from the supplied URI.

fileToURL

private static java.net.URL fileToURL(java.io.File file)
                               throws java.net.MalformedURLException
Custom File.toUrl() implementation to handle special chars in file names

getExpandEntities

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

setExpandEntities

public void setExpandEntities(boolean expand)

This sets whether or not to expand entities for the builder. A true means to expand entities as normal content. A false means to leave entities unexpanded as EntityRef objects. The default is true.

When this setting is false, the internal DTD subset is retained; when this setting is true, the internal DTD subset is not retained.

Note that Xerces (at least up to 1.4.4) has a bug where entities in attribute values will be misreported if this flag is turned off, resulting in entities to appear within element content. When turning entity expansion off either avoid entities in attribute values, or use another parser like Crimson. http://nagoya.apache.org/bugzilla/show_bug.cgi?id=6111

Overview  Package   Class  Use  Deprecated  Index 
Home >> All >> org >> jdom >> [ input overview ]  PREV CLASS  NEXT CLASS
SUMMARY: JavaDoc of org.jdom.input.SAXBuilder JAVADOC | Sourc code of org.jdom.input.SAXBuilder SOURCE | Download org.jdom.input.SAXBuilder DOWNLOAD | NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD