nux.xom.pool
Class DocumentMap

java.lang.Object
  nux.xom.pool.DocumentMap

public class DocumentMap
extends Object

Efficient compact thread-safe main memory cache map of XOM XML Document objects; for example used by DocumentPool; Pool eviction is based on a LRU (least recently used) policy as defined by a tunable PoolConfig configuration.

Eviction occurs if at least one of the following conditions holds:

• The JVM runs low on free memory (soft references). Hence, the client application will never ever experience OutOfMemoryErrors.
• The maximum number of documents is exceeded (maxEntries).
• The maximum memory limit is exceeded by the sum of all contained documents (capacity).
• The time an entry has been inactive is exceeded ( maxIdleTime). That is, a key's entry is removed if the key has not been recalled for some time via getDocument.
• The time since the entry's creation via putDocument is exceeded (maxLifeTime). [There must hold: maxIdleTime <= maxLifeTime].
• A key's file has been modified or deleted since the entry has been inserted into the pool (fileMonitoring).

The pool can internally hold a compact representation of a document using the bnux BinaryXMLCodec algorithm. A zlib compression level ranging from -1 (no bnux, stores a reference to the document object "as is", best performance) to 0 (bnux with no ZLIB compression; good performance) to 1 (bnux with little ZLIB compression; reduced performance) to 9 (bnux with strongest ZLIB compression; worst performance) allows one to configure the CPU/memory consumption trade-off.

Unless there is a good reason to the contrary, you should always use level 0: the bnux algorithm typically already precompresses considerably, typically by a factor 20 over a XOM main memory tree. Level 9 can yield another factor 5 or so over that.

Method getDocument() returns a reference to the document previously stored if level == -1, otherwise it stores a compact immutable document copy and returns a separate copy on each invocation (for safety).

Keys must properly implement methods Object.equals(Object) and Object.hashCode() as required for a normal HashMap.

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

     PoolConfig config = new PoolConfig();
     config.setCompressionLevel(0);          // no zlib compression
     config.setMaxEntries(10000);            // max 10000 documents
     config.setCapacity(100 * 1024 * 1024);  // max 100 MB capacity
     config.setMaxIdleTime(60 * 1000);       // keep inactive entries for at most 60 secs
     config.setMaxLifeTime(60 * 60 * 1000);  // keep any entry for at most 1 hour
     config.setFileMonitoring(true);         // auto-remove cached files on file modification
     DocumentMap map = new DocumentMap(config);
 
     File key = new File("samples/data/periodic.xml"); // file to parse
     Document doc = map.getDocument(key);
     if (doc == null) { // not yet cached
         // build document from source
         doc = BuilderPool.GLOBAL_POOL.getBuilder(false).build(key);
 
         // cache it for future reuse
         map.putDocument(key, doc); 
     }
 
     // do something useful with the document
     System.out.println(doc.toXML());
 

Note: Internally uses extremely short-lived locks; the resulting potential lock contention is completely negligible.

Author:

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

Constructor Summary

DocumentMap(PoolConfig config)
Creates a new pool that uses the given configuration.

Method Summary

Document	getDocument(Object key) Returns the document associated with the given key.
void	putDocument(Object key, Document doc) Associates the given document with the given key.

Methods inherited from class java.lang.Object

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

Constructor Detail

DocumentMap

public DocumentMap(PoolConfig config)

Creates a new pool that uses the given configuration.

Parameters:

config - the configuration to use

Method Detail

getDocument

public Document getDocument(Object key)

Returns the document associated with the given key. Returns null if the pool contains no mapping for this key.

Parameters:

key - the key of the document to retrieve

Returns:

the document associated with the given key

putDocument

public void putDocument(Object key,
                        Document doc)

Associates the given document with the given key. If the pool previously contained a mapping for this key, the old document is replaced by the given document. doc == null indicates that the mapping should be removed, if it exists.

Parameters:

key - the key of the document

doc - the document to be associated with the given key; or null to remove the mapping if it exists