nux.xom.pool
Class DocumentPool

java.lang.Object
  nux.xom.pool.DocumentPool

public class DocumentPool
extends Object

Efficient compact thread-safe pool/cache of XOM XML Document objects, storing documents in a DocumentMap. On cache miss, a new document is created via a factory, cached for future reuse, and then returned. On cache hit a document is returned almost instantly.

Pool eviction is delegated to the DocumentMap/PoolConfig store.

By default returns a copy of a cached document on each invocation of methods getDocument(...). This ensures that documents contained inside the cache cannot be modified by clients, which would be unsafe in the presense of multiple threads and application modules using a shared DocumentPool instance (a shared instance reduces overall memory consumption).

This class helps to avoid the large overhead involved in parsing XML documents. 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).

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

     // parse file with non-validating parser
     Document doc = DocumentPool.GLOBAL_POOL.getDocument(new File("samples/data/periodic.xml"));
 
     // pool with custom document factory for W3C XML Schema validation
     DocumentFactory factory = new DocumentFactory() { 
         protected Builder newBuilder() { 
             return BuilderPool.GLOBAL_POOL.getW3CBuilder(someW3CXMLSchema);
             // return new Builder(); 
         }
     };
     DocumentPool pool = new DocumentPool(new DocumentMap(new PoolConfig()), factory);
     Document doc = pool.getDocument(new File("samples/data/periodic.xml"));
 
     // pool reading binary xml documents
     DocumentPool pool = new DocumentPool(new DocumentMap(new PoolConfig()), 
         new DocumentFactory().getBinaryXMLFactory());
     Document doc = pool.getDocument(new File("samples/data/periodic.xml.bnux"));
 

Author:

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

Field Summary

static DocumentPool

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

Constructor Summary

DocumentPool()
Creates a new pool with default parameters.

DocumentPool(DocumentMap entries, DocumentFactory factory)
Creates a new pool that uses the given document cache data structure and factory.

Method Summary

Document	getDocument(File input) Returns a document for the given input file.
Document	getDocument(ResourceResolver resolver, String resourceName, URI baseURI) Returns a document for the input stream obtained from resolving the given resourceName against the given resolver.
Document	getDocument(URI systemID) Returns a document for the given URL.

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 DocumentPool GLOBAL_POOL

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

Constructor Detail

DocumentPool

public DocumentPool()

Creates a new pool with default parameters.

DocumentPool

public DocumentPool(DocumentMap entries,
                    DocumentFactory factory)

Creates a new pool that uses the given document cache data structure and factory.

Parameters:

entries - an empty document cache data structure

factory - the factory creating new Document instances on cache misses

Method Detail

getDocument

public Document getDocument(File input)
                     throws ParsingException,
                            IOException

Returns a document for the given input file.

Parameters:

input - the file to read from

Returns:

a document

Throws:

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

ParsingException - if an XML parsing error occurs

getDocument

public Document getDocument(URI systemID)
                     throws ParsingException,
                            IOException

Returns a document for the given URL.

Parameters:

systemID - the URL of the document

Returns:

a document

Throws:

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

ParsingException - if an XML parsing error occurs

getDocument

public Document getDocument(ResourceResolver resolver,
                            String resourceName,
                            URI baseURI)
                     throws ParsingException,
                            IOException,
                            MissingResourceException

Returns a document for the input stream obtained from resolving the given resourceName against the given resolver.

Parameters:

resolver - an object that can produce an input stream for a given resource name.

resourceName - the resource name (e.g. a path or URL)

baseURI - the base URI of the document (may be null) Need not be the actual URI of the resolver's stream.

Returns:

a document

Throws:

MissingResourceException - if the resolver could not find the resource (unchecked exception)

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

ParsingException - if an XML parsing error occurs