org.inria.ns.reflex.xml
Class XMLBuilder

java.lang.Object
  extended by org.inria.ns.reflex.processor.catalog.Builder
      extended by org.inria.ns.reflex.xml.XMLBuilder
Direct Known Subclasses:
XMLBuilder.TextBuilder

public class XMLBuilder
extends Builder

An XMLBuilder supplies an XML document.

When it is read for the first time, SAX events are fired both to the target application and to a DOM structure. When the first reading is completed, the DOM structure will be available for next readings ; this provide a kind of caching an avoid multiple parsing, except when several readings are expected at the same time if no SAX reading has been yet achieved. A single builder may supply safely several SAX sources and a single DOM source.

Additionally, non-XML sources are wrapped in XML text events and not cached into a DOM tree. When an XML source must be read as a non-XML source (that is to say that the XML document is not parsed, and is like if it was included in a huge CDATA section), a TextBuilder instance can be get.

Usage

Creation

XMLBuilder builder = new XMLBuilder( path, entityResolver, errorHandler );
 

First usage

 // can be SAX or DOM
 Object document = builder.getInstance();
 if ( document instanceof XMLReader ) {
     XMLReader reader = (XMLReader) document;
     reader.setEntityResolver( ... );
     InputStream is = new InputStream( path );
     reader.parse( is );
 }
 

Author:
Philippe Poulard

Nested Class Summary
 class XMLBuilder.SAXSplitter
          A SAXSplitter fires SAX events to 2 handlers : one is the applicative handler, the other perform a copy to a DOM structure for reusability.
static class XMLBuilder.TextBuilder
          A text builder doesn't use a SAX splitter but simply fire characters events to the applicative SAX handler.
 
Constructor Summary
XMLBuilder(String path, EntityResolver entityResolver, ErrorHandler errorHandler)
          Create an XML builder with a source.
XMLBuilder(XFile file, EntityResolver entityResolver, ErrorHandler errorHandler)
          Create an XML builder with a source.
 
Method Summary
 Object getInstance()
          Return an XML document (SAX or DOM)
 XMLBuilder.TextBuilder getTextBuilder(String encoding)
          Return a text builder that wraps an XML input (or a non-XML input) to an XML text with SAX, that is to say that characters events are fired.
 boolean isSupportFragments()
          Indicates whether this builder support XML fragments.
 void setSupportFragments(boolean supportFragments)
          Set the behaviour of this builder regarding XML fragments.
 
Methods inherited from class org.inria.ns.reflex.processor.catalog.Builder
equals, hashCode
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

XMLBuilder

public XMLBuilder(String path,
                  EntityResolver entityResolver,
                  ErrorHandler errorHandler)
Create an XML builder with a source.

Parameters:
path - The path to the source.
entityResolver - Used to resolve external identifiers.
errorHandler - Used to handle errors.

XMLBuilder

public XMLBuilder(XFile file,
                  EntityResolver entityResolver,
                  ErrorHandler errorHandler)
Create an XML builder with a source.

Parameters:
file - The source as a file.
entityResolver - Used to resolve external identifiers.
errorHandler - Used to handle errors.
Method Detail

getInstance

public Object getInstance()
                   throws Exception
Return an XML document (SAX or DOM)

Overrides:
getInstance in class Builder
Returns:
An XMLFilter or a Node if a previous parsing has been completed.
Throws:
Exception - When the input can't be used to build a new instance.
See Also:
Builder.getInstance(), Node, XMLFilter

getTextBuilder

public XMLBuilder.TextBuilder getTextBuilder(String encoding)
Return a text builder that wraps an XML input (or a non-XML input) to an XML text with SAX, that is to say that characters events are fired.

Parameters:
encoding - The charset encoding, or null.
Returns:
The TextBuilder that has the same source than this builder.
See Also:
ContentHandler.characters(char[], int, int)

isSupportFragments

public boolean isSupportFragments()
Indicates whether this builder support XML fragments. Default is false.

Returns:
true if XML fragments have to be accepted, false if they have to be rejected.
See Also:
setSupportFragments(boolean)

setSupportFragments

public void setSupportFragments(boolean supportFragments)
Set the behaviour of this builder regarding XML fragments.

Parameters:
supportFragments - true if XML fragments have to be accepted, false if they have to be rejected.
See Also:
isSupportFragments()