nux.xom.pool
Class BuilderPool

java.lang.Object
  nux.xom.pool.BuilderPool

public class BuilderPool
extends Object

Efficient thread-safe pool/cache of XOM Builder objects, creating and holding zero or more Builders per thread. On cache miss, a new Builder is created via a factory, cached for future reuse, and then returned. On cache hit a Builder is returned instantly.

Recognizing that Builders are not thread-safe but can be reused serially, this class helps to avoid the large overhead involved in creating a Builder instance (more precisely: an underlying XMLReader instance), in particular for Builders that parse small XML documents and/or validate against W3C XML schemas or RELAX NG schemas. Most useful in high throughput server container environments (e.g. large-scale Peer-to-Peer messaging network infrastructures over high-bandwidth networks, scalable MOMs, etc).

Internally, each thread has its own local pool entries, and each pool can hold at most a given number of builders, evicting old builders beyond that point via a LRU (least recently used) policy, or if the JVM runs low on free memory.

Thread-safe implementation (internally uses a ThreadLocal).

Example usage (in any arbitrary thread and any arbitrary object):

 public void foo() {
   // non-validating parser
   Document doc = BuilderPool.GLOBAL_POOL.getBuilder(false).build(new File("/tmp/test.xml"));
   //Document doc = new Builder(false).build(new File("/tmp/test.xml")); // would be inefficient
   System.out.println(doc.toXML());
 
   // W3C XML Schema parser
   Map schemaLocations = new HashMap(1);
   schemaLocations.put(new File("/tmp/p2pio.xsd"), "http://dsd.lbl.gov/p2pio-1.0"); 
   Builder builder = BuilderPool.GLOBAL_POOL.getW3CBuilder(schemaLocations);
   Document doc = builder.build(new File("/tmp/test.xml"));
   System.out.println(doc.toXML());
 
   // RELAX NG validation for DOCBOOK publishing system
   Builder builder = BuilderPool.GLOBAL_POOL.getMSVBuilder(new URI("http://www.docbook.org/docbook-ng/ipa/docbook.rng"));
   //Builder builder = BuilderPool.GLOBAL_POOL.getMSVBuilder(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 $

Field Summary

static BuilderPool

GLOBAL_POOL A default pool (can be shared freely across threads without harm); global per class loader.

Constructor Summary

BuilderPool()
Creates a new pool with default parameters.

BuilderPool(PoolConfig config, BuilderFactory factory)
Creates a new pool with the given configuration that uses the given factory on cache misses.

Method Summary

Builder	getBuilder(boolean validate) Returns a validating or non-validating Builder.
Builder	getDTDBuilder(EntityResolver resolver) Returns a Builder that validates against the DTD obtained by the given entity resolver.
Builder	getMSVBuilder(URI schema) Returns a Builder that validates against the given MSV (Multi-Schema Validator) schema.
Builder	getW3CBuilder(Map schemaLocations) Returns a Builder that validates against W3C XML Schemas.

Methods inherited from class java.lang.Object

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

Field Detail

GLOBAL_POOL

public static final BuilderPool GLOBAL_POOL

A default pool (can be shared freely across threads without harm); global per class loader.

Constructor Detail

BuilderPool

public BuilderPool()

Creates a new pool with default parameters.

BuilderPool

public BuilderPool(PoolConfig config,
                   BuilderFactory factory)

Creates a new pool with the given configuration that uses the given factory on cache misses.

Parameters:

config - the configuration to use

factory - the factory creating new Builder instances on cache misses

Method Detail

getBuilder

public Builder getBuilder(boolean validate)

Returns a 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.

getDTDBuilder

public Builder getDTDBuilder(EntityResolver resolver)

Returns a Builder that validates against the DTD obtained by the given entity resolver.

Parameters:

resolver - the entity resolver obtaining the DTD

Returns:

a new Builder

Throws:

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

getW3CBuilder

public Builder getW3CBuilder(Map schemaLocations)

Returns a Builder that validates against W3C XML Schemas.

For a detailed description of the parameters, see BuilderFactory.createW3CBuilder(Map).

Parameters:

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

Returns:

a new Builder

Throws:

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

getMSVBuilder

public Builder getMSVBuilder(URI schema)

Returns a 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.

Parameters:

schema - the URL of the schema to validate against.

Returns:

a new Builder

Throws:

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