nux.xom.pool
Class BuilderFactory

java.lang.Object
  nux.xom.pool.BuilderFactory

public class BuilderFactory
extends Object

Creates and returns new Builder objects that validate against W3C XML Schemas, DTDs, RELAX NG, Schematron or do not validate at all (thread-safe). Features and properties of the underlying XMLReader can be specified. A node factory can be specified by overriding the protected newBuilder method.

This implementation is thread-safe.

W3C XML Schema support (method createW3CBuilder) requires Xerces (either external for JDK 1.4, or as packaged inside JDK 1.5); the other methods do not require Xerces.

RELAX NG support (method createMSVBuilder) requires MSV. Sun Multi-Schema XML Validator (MSV) can validate XML documents against several kinds of XML schemata, including RELAX NG. MSV support requires the MSV jars in the classpath (BSD-style open source license, part of MSV download). Alternatively, those jar files are also part of the JAXB RI included in the JWSDP download (somewhat repackaged but otherwise identical). If you'd like to use Schematron assertions embedded in a RELAX NG schema, you will also need to download the MSV Schematron add-on and add relames.jar to the classpath. Note that MSV does not currently support the RELAX NG Compact Syntax. (The RELAX NG homepage lists converters from RELAX NG Compact Syntax to RELAX NG XML Syntax, including Trang). Note that we do not recommend using MSV for DTDs or W3C XML Schemas. Instead we recommend using the DTD or W3C XML Schema specific methods of this class, which are more reliable. The other methods of this class do not require MSV.

For anything but simple/basic use cases, this API is more robust, configurable and convenient than the underlying XOM Builder constructor API.

Example usage:

   // W3C XML Schema validation
   Map schemaLocations = new HashMap();
   schemaLocations.put(new File("/tmp/p2pio.xsd"), "http://dsd.lbl.gov/p2pio-1.0"); 
   Builder builder = new BuilderFactory().createW3CBuilder(schemaLocations);
   Document doc = builder.build(new File("/tmp/test.xml"));
   System.out.println(doc.toXML());
 
   // RELAX NG validation for DOCBOOK publishing system
   Builder builder = new BuilderFactory().createMSVBuilder(null, new URI("http://www.docbook.org/docbook-ng/ipa/docbook.rng"));
   //Builder builder = new BuilderFactory().createMSVBuilder(null, new File("/tmp/docbook/docbook.rng").toURI());
   Document doc = builder.build(new File("/tmp/mybook.xml"));
   System.out.println(doc.toXML());
 

Author:

whoschek.AT.lbl.DOT.gov, $Author: hoschek3 $

Constructor Summary

BuilderFactory()
Creates a factory instance for creating Builders with an underlying XMLReader that has no particular features and properties.

BuilderFactory(Map featuresAndProperties)
Creates a factory instance for creating Builders with an underlying XMLReader that has the given features and properties.

Method Summary

Builder	createBuilder(boolean validate) Creates and returns a new validating or non-validating Builder.
Builder	createDTDBuilder(EntityResolver resolver) Creates and returns a new Builder that validates against the DTD obtained by the given entity resolver.
Builder	createMSVBuilder(InputStream schema, URI systemID) Creates and returns a new Builder that validates against the given MSV (Multi-Schema Validator) schema.
EntityResolver	createResolver(InputStream in) Creates and returns a new EntityResolver that validates against the DTD obtained from the given input stream.
Builder	createW3CBuilder(Map schemaLocations) Creates and returns a new Builder that validates against W3C XML Schemas.
protected Builder	newBuilder(XMLReader parser, boolean validate) Callback that creates and returns a new validating or non-validating Builder for the given parser.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BuilderFactory

public BuilderFactory()

Creates a factory instance for creating Builders with an underlying XMLReader that has no particular features and properties.

BuilderFactory

public BuilderFactory(Map featuresAndProperties)

Creates a factory instance for creating Builders with an underlying XMLReader that has the given features and properties.

The features and properties are read by this class, and guaranteed to never be modified.

Parameters:

featuresAndProperties - the features and properties the underlying XMLReader should have (may be null). Keys must not be null. Values of type Boolean are interpreted as features, all other values are interpreted as properties.

See Also:

XMLReader.setFeature(java.lang.String, boolean), XMLReader.setProperty(java.lang.String, java.lang.Object)

Method Detail

createBuilder

public Builder createBuilder(boolean validate)

Creates and returns a new validating or non-validating Builder. In validating mode, a ValidityException will be thrown when encountering an XML validation error upon parsing.

Parameters:

validate - true if XML validation should be performed.

Returns:

a new Builder

Throws:

XMLException - if an appropriate parser cannot be found or created.

createDTDBuilder

public Builder createDTDBuilder(EntityResolver resolver)

Creates and returns a new Builder that validates against the DTD obtained by the given entity resolver. A ValidityException will be thrown when encountering an XML validation error upon parsing.

Quite possibly, you will want to use this in conjunction with a DoctypeChanger helper or a SAX-2.0.1 EntityResolver2.

Parameters:

resolver - the entity resolver obtaining the DTD

Returns:

a new Builder

Throws:

XMLException - if an appropriate parser cannot be found or created.

createResolver

public EntityResolver createResolver(InputStream in)
                              throws IOException

Creates and returns a new EntityResolver that validates against the DTD obtained from the given input stream. Caches the obtained DTD stream data for efficient future reuse.

Parameters:

in - the input stream for the DTD

Returns:

a new EntityResolver

Throws:

IOException - if an I/O error occured while reading the stream

createW3CBuilder

public Builder createW3CBuilder(Map schemaLocations)

Creates and returns a new Builder that validates against W3C XML Schemas. A ValidityException will be thrown when encountering an XML Schema validation error upon parsing.

Parameter schemaLocations specifies zero or more schemaLocation --> namespace associations. Each map entry's key and value are interpreted as follows:

• schemaLocation (key): the location URL of the external schema (must not be null)
• namespace (value): the namespace URI of the schema (may be null)

schemaLocation.toString() and, if applicable, namespace.toString() are used to determine string representations. Hence, the normal classes String, URI, URL, StringBuffer, etc. can all be used as input.

Note: This reflects the external-schemaLocation and external-noNamespaceSchemaLocation Xerces properties, among others.

Example usage:

     // no custom external schema; XMLReader takes schemaLocation declarations from XML document:
     // <ok xmlns="http://dsd.lbl.gov/p2pio-1.0" 
     //         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     //         xsi:schemaLocation="http://dsd.lbl.gov/p2pio-1.0 file:/tmp/p2pio.xsd">
     //     <transactionID>ec14f115-d97e-4f76-8d0a-40d81de79445</transactionID>
     // </ok>
     Builder builder = new BuilderFactory().createW3CBuilder(null);
     Document doc = builder.build(new File("/tmp/test.xml"));
     System.out.println(doc.toXML());
 
     // two custom external schemas with namespaces 
     // for soap message with application payload; 
     // ignores schemaLocation declarations from XML document:
     Map schemaLocations = new HashMap();
     schemaLocations.put(new File("/tmp/soap.xsd"),  "http://www.w3.org/2001/12/soap-envelope");  
     schemaLocations.put(new File("/tmp/p2pio.xsd"), "http://dsd.lbl.gov/p2pio-1.0"); 
     Builder builder = new BuilderFactory().createW3CBuilder(schemaLocations);
     Document doc = builder.build(new File("/tmp/test.xml"));
     System.out.println(doc.toXML());
 
     // a custom external schemas without namespaces;
     // ignores schemaLocation declarations from XML document:
     Map schemaLocations = new HashMap();
     schemaLocations.put("file:/tmp/foo.xsd", null);  
     Builder builder = new BuilderFactory().createW3CBuilder(schemaLocations);
     Document doc = builder.build(new File("/tmp/test.xml"));
     System.out.println(doc.toXML());
 

Parameters:

schemaLocations - the schemaLocation --> namespace associations (may be null).

Returns:

a new Builder

Throws:

XMLException - if an appropriate parser cannot be found or created.

createMSVBuilder

public Builder createMSVBuilder(InputStream schema,
                                URI systemID)

Creates and returns a new Builder that validates against the given MSV (Multi-Schema Validator) schema. A ParsingException will be thrown when encountering an XML validation error upon parsing.

The type of all schemas written in XML-syntax (RELAX NG, W3C XML Schema, etc) will be auto-detected correctly by MSV no matter what the format is.

At least one of the parameters schema and systemID must not be null.

Parameters:

schema - the schema to validate against. May be null, in which case the systemID parameter is used.

systemID - the URL of the schema. Also used to resolve relative URIs when including RELAX NG schema modules via include directives into a main schema. Need not be the stream's actual URI. May be null in which case it defaults to the current working directory.

Returns:

a new Builder

Throws:

XMLException - if the schema contains a syntax or semantic error or an appropriate parser cannot be found or created.

newBuilder

protected Builder newBuilder(XMLReader parser,
                             boolean validate)

Callback that creates and returns a new validating or non-validating Builder for the given parser.

This default implementation creates Builders with a null NodeFactory.

Override this method if you need custom node factories.

Note: A node factory may well be stateful and mutable, hence it may well be unsafe to share a single node factory instance among multiple Builders in a multi-threaded context. By providing this method, an application can create new node factories as needed via straightforward subclassing/overriding of this class.

Parameters:

parser - the underlying SAX XML parser

validate - whether or not to validate

Returns:

a new Builder