|
Nux 1.6 | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object nux.xom.pool.BuilderFactory
public class BuilderFactory
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());
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 |
---|
public BuilderFactory()
XMLReader
that has no particular features and properties.
public BuilderFactory(Map featuresAndProperties)
XMLReader
that has the given features and properties.
The features and properties are read by this class, and guaranteed to never be modified.
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.XMLReader.setFeature(java.lang.String, boolean)
,
XMLReader.setProperty(java.lang.String, java.lang.Object)
Method Detail |
---|
public Builder createBuilder(boolean validate)
Builder
. In validating mode, a
ValidityException
will be thrown when encountering an XML
validation error upon parsing.
validate
- true if XML validation should be performed.
XMLException
- if an appropriate parser cannot be found or created.public Builder createDTDBuilder(EntityResolver resolver)
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
.
resolver
- the entity resolver obtaining the DTD
XMLException
- if an appropriate parser cannot be found or created.public EntityResolver createResolver(InputStream in) throws IOException
EntityResolver
that validates
against the DTD obtained from the given input stream. Caches the obtained
DTD stream data for efficient future reuse.
in
- the input stream for the DTD
IOException
- if an I/O error occured while reading the streampublic Builder createW3CBuilder(Map schemaLocations)
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:
null
)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());
schemaLocations
- the schemaLocation --> namespace
associations
(may be null
).
XMLException
- if an appropriate parser cannot be found or created.public Builder createMSVBuilder(InputStream schema, URI systemID)
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
.
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.
XMLException
- if the schema contains a syntax or semantic error or an
appropriate parser cannot be found or created.protected Builder newBuilder(XMLReader parser, boolean validate)
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.
parser
- the underlying SAX XML parservalidate
- whether or not to validate
|
Nux 1.6 | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |