org.opensaml.xml.parse
Class BasicParserPool

java.lang.Object
  extended by org.opensaml.xml.parse.BasicParserPool
All Implemented Interfaces:
ParserPool

public class BasicParserPool
extends Object
implements ParserPool

A pool of JAXP 1.3 DocumentBuilders.

This implementation of ParserPool allows its properties to be modified over time and versions the builders it manages appropriately. There are certain performance penalties for doing this. For a more performant implementation that does not support versioning or property modification over time, see StaticBasicParserPool.

This is a pool implementation of the caching factory variety, and as such imposes no upper bound on the number of DocumentBuilders allowed to be concurrently checked out and in use. It does however impose a limit on the size of the internal cache of idle builder instances via the value configured via setMaxPoolSize(int).

Builders retrieved from this pool may (but are not required to) be returned to the pool with the method returnBuilder(DocumentBuilder). Builders checked out prior to a change in the pool's properties will not be effected by the change and will be appropriately dealt with when they are returned.

References to builders are kept by way of SoftReference so that the garbage collector may reap the builders if the system is running out of memory.


Nested Class Summary
protected  class BasicParserPool.DocumentBuilderProxy
          A proxy that prevents the manages document builders retrieved from the parser pool.
 
Field Summary
private  Map<String,Object> builderAttributes
          Builder attributes.
private  DocumentBuilderFactory builderFactory
          Factory used to create new builders.
private  Map<String,Boolean> builderFeatures
          Builder features.
private  Stack<SoftReference<DocumentBuilder>> builderPool
          Cache of document builders.
private  boolean coalescing
          Whether the builders are coalescing.
private  boolean dirtyBuilderConfiguration
          Whether a change has been made to the builder configuration but has not yet been applied.
private  boolean dtdValidating
          Whether the builder should validate.
private  EntityResolver entityResolver
          Entity resolver used by builders.
private  ErrorHandler errorHandler
          Error handler used by builders.
private  boolean expandEntityReferences
          Whether the builders expand entity references.
private  boolean ignoreComments
          Whether the builders ignore comments.
private  boolean ignoreElementContentWhitespace
          Whether the builders ignore element content whitespace.
private  Logger log
          Class logger.
private  int maxPoolSize
          Max number of builders allowed in the pool.
private  boolean namespaceAware
          Whether the builders are namespace aware.
private  long poolVersion
          Current version of the pool.
private  Schema schema
          Schema used to validate parsed content.
private  boolean xincludeAware
          Whether the builders are XInclude aware.
 
Constructor Summary
BasicParserPool()
          Constructor.
 
Method Summary
protected  Map<String,Boolean> buildDefaultFeatures()
          Build the default set of parser features to use.
protected  DocumentBuilder createBuilder()
          Creates a new document builder.
 DocumentBuilder getBuilder()
          Gets a builder from the pool.
 Map<String,Object> getBuilderAttributes()
          Gets the builder attributes used when creating builders.
 Map<String,Boolean> getBuilderFeatures()
          Gets the builders' features.
 boolean getCreateBuildersAtPoolLimit()
          Deprecated.  
 boolean getIgnoreComments()
          Gets whether the builders ignore comments.
 int getMaxPoolSize()
          Gets the max number of builders the pool will hold.
protected  int getPoolSize()
          Gets the size of the current pool storage.
protected  long getPoolVersion()
          Gets the current pool version.
 Schema getSchema()
          Gets the schema builders use to validate.
protected  void initializePool()
          Initializes the pool with a new set of configuration options.
 boolean isCoalescing()
          Gets whether the builders are coalescing.
 boolean isDTDValidating()
          Gets whether the builders are validating.
 boolean isExpandEntityReferences()
          Gets whether builders expand entity references.
 boolean isIgnoreElementContentWhitespace()
          Get whether the builders ignore element content whitespace.
 boolean isNamespaceAware()
          Gets whether the builders are namespace aware.
 boolean isXincludeAware()
          Gets whether the builders are XInclude aware.
 Document newDocument()
          Convience method for creating a new document with a pooled builder.
 Document parse(InputStream input)
          Convience method for parsing an XML file using a pooled builder.
 Document parse(Reader input)
          Convience method for parsing an XML file using a pooled builder.
 void returnBuilder(DocumentBuilder builder)
          Returns a builder to the pool.
protected  void setAttributes(DocumentBuilderFactory factory, Map<String,Object> attributes)
          Sets document builder attributes.
 void setBuilderAttributes(Map<String,Object> newAttributes)
          Sets the builder attributes used when creating builders.
 void setBuilderFeatures(Map<String,Boolean> newFeatures)
          Sets the the builders' features.
 void setCoalescing(boolean isCoalescing)
          Sets whether the builders are coalescing.
 void setCreateBuildersAtPoolLimit(boolean createBuilders)
          Deprecated.  
 void setDTDValidating(boolean isValidating)
          Sets whether the builders are validating.
 void setExpandEntityReferences(boolean expand)
          Sets whether builders expand entity references.
protected  void setFeatures(DocumentBuilderFactory factory, Map<String,Boolean> features)
          Sets document builder features.
 void setIgnoreComments(boolean ignore)
          Sets whether the builders ignore comments.
 void setIgnoreElementContentWhitespace(boolean ignore)
          Sets whether the builders ignore element content whitespace.
 void setMaxPoolSize(int newSize)
          Sets the max number of builders the pool will hold.
 void setNamespaceAware(boolean isNamespaceAware)
          Sets whether the builders are namespace aware.
 void setSchema(Schema newSchema)
          Sets the schema builders use to validate.
 void setXincludeAware(boolean isXIncludeAware)
          Sets whether the builders are XInclude aware.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

log

private final Logger log
Class logger.


poolVersion

private long poolVersion
Current version of the pool.


dirtyBuilderConfiguration

private boolean dirtyBuilderConfiguration
Whether a change has been made to the builder configuration but has not yet been applied.


builderFactory

private DocumentBuilderFactory builderFactory
Factory used to create new builders.


builderPool

private Stack<SoftReference<DocumentBuilder>> builderPool
Cache of document builders.


maxPoolSize

private int maxPoolSize
Max number of builders allowed in the pool. Default value: 5


builderAttributes

private Map<String,Object> builderAttributes
Builder attributes.


coalescing

private boolean coalescing
Whether the builders are coalescing. Default value: true


expandEntityReferences

private boolean expandEntityReferences
Whether the builders expand entity references. Default value: true


builderFeatures

private Map<String,Boolean> builderFeatures
Builder features.


ignoreComments

private boolean ignoreComments
Whether the builders ignore comments. Default value: true


ignoreElementContentWhitespace

private boolean ignoreElementContentWhitespace
Whether the builders ignore element content whitespace. Default value: true


namespaceAware

private boolean namespaceAware
Whether the builders are namespace aware. Default value: true


schema

private Schema schema
Schema used to validate parsed content.


dtdValidating

private boolean dtdValidating
Whether the builder should validate. Default value: false


xincludeAware

private boolean xincludeAware
Whether the builders are XInclude aware. Default value: false


entityResolver

private EntityResolver entityResolver
Entity resolver used by builders.


errorHandler

private ErrorHandler errorHandler
Error handler used by builders.

Constructor Detail

BasicParserPool

public BasicParserPool()
Constructor.

Method Detail

getBuilder

public DocumentBuilder getBuilder()
                           throws XMLParserException
Gets a builder from the pool.

Specified by:
getBuilder in interface ParserPool
Returns:
a builder from the pool
Throws:
XMLParserException - thrown if the document builder factory is misconfigured

returnBuilder

public void returnBuilder(DocumentBuilder builder)
Returns a builder to the pool.

Specified by:
returnBuilder in interface ParserPool
Parameters:
builder - the builder to return

newDocument

public Document newDocument()
                     throws XMLParserException
Convience method for creating a new document with a pooled builder.

Specified by:
newDocument in interface ParserPool
Returns:
created document
Throws:
XMLParserException - thrown if there is a problem retrieving a builder

parse

public Document parse(InputStream input)
               throws XMLParserException
Convience method for parsing an XML file using a pooled builder.

Specified by:
parse in interface ParserPool
Parameters:
input - XML to parse
Returns:
parsed document
Throws:
XMLParserException - thrown if there is a problem retrieving a builder, the input stream can not be read, or the XML was invalid

parse

public Document parse(Reader input)
               throws XMLParserException
Convience method for parsing an XML file using a pooled builder.

Specified by:
parse in interface ParserPool
Parameters:
input - XML to parse
Returns:
parsed document
Throws:
XMLParserException - thrown if there is a problem retrieving a builder, the input stream can not be read, or the XML was invalid

getMaxPoolSize

public int getMaxPoolSize()
Gets the max number of builders the pool will hold.

Returns:
max number of builders the pool will hold

setMaxPoolSize

public void setMaxPoolSize(int newSize)
Sets the max number of builders the pool will hold.

Parameters:
newSize - max number of builders the pool will hold

getCreateBuildersAtPoolLimit

public boolean getCreateBuildersAtPoolLimit()
Deprecated. 

Gets whether new builders will be created when the max pool size is reached.

Note this method is deprecated and will be removed in the next release. It is also currently functionally non-operational.

Returns:
whether new builders will be created when the max pool size is reached

setCreateBuildersAtPoolLimit

public void setCreateBuildersAtPoolLimit(boolean createBuilders)
Deprecated. 

Sets whether new builders will be created when the max pool size is reached.

Note this method is deprecated and will be removed in the next release. It is also currently functionally non-operational.

Parameters:
createBuilders - whether new builders will be created when the max pool size is reached

getBuilderAttributes

public Map<String,Object> getBuilderAttributes()
Gets the builder attributes used when creating builders. This collection is unmodifiable.

Returns:
builder attributes used when creating builders

setBuilderAttributes

public void setBuilderAttributes(Map<String,Object> newAttributes)
Sets the builder attributes used when creating builders.

Parameters:
newAttributes - builder attributes used when creating builders

isCoalescing

public boolean isCoalescing()
Gets whether the builders are coalescing.

Returns:
whether the builders are coalescing

setCoalescing

public void setCoalescing(boolean isCoalescing)
Sets whether the builders are coalescing.

Parameters:
isCoalescing - whether the builders are coalescing

isExpandEntityReferences

public boolean isExpandEntityReferences()
Gets whether builders expand entity references.

Returns:
whether builders expand entity references

setExpandEntityReferences

public void setExpandEntityReferences(boolean expand)
Sets whether builders expand entity references.

Parameters:
expand - whether builders expand entity references

getBuilderFeatures

public Map<String,Boolean> getBuilderFeatures()
Gets the builders' features. This collection is unmodifiable.

Returns:
the builders' features

setBuilderFeatures

public void setBuilderFeatures(Map<String,Boolean> newFeatures)
Sets the the builders' features.

Parameters:
newFeatures - the builders' features

getIgnoreComments

public boolean getIgnoreComments()
Gets whether the builders ignore comments.

Returns:
whether the builders ignore comments

setIgnoreComments

public void setIgnoreComments(boolean ignore)
Sets whether the builders ignore comments.

Parameters:
ignore - The ignoreComments to set.

isIgnoreElementContentWhitespace

public boolean isIgnoreElementContentWhitespace()
Get whether the builders ignore element content whitespace.

Returns:
whether the builders ignore element content whitespace

setIgnoreElementContentWhitespace

public void setIgnoreElementContentWhitespace(boolean ignore)
Sets whether the builders ignore element content whitespace.

Parameters:
ignore - whether the builders ignore element content whitespace

isNamespaceAware

public boolean isNamespaceAware()
Gets whether the builders are namespace aware.

Returns:
whether the builders are namespace aware

setNamespaceAware

public void setNamespaceAware(boolean isNamespaceAware)
Sets whether the builders are namespace aware.

Parameters:
isNamespaceAware - whether the builders are namespace aware

getSchema

public Schema getSchema()
Gets the schema builders use to validate.

Specified by:
getSchema in interface ParserPool
Returns:
the schema builders use to validate

setSchema

public void setSchema(Schema newSchema)
Sets the schema builders use to validate.

Specified by:
setSchema in interface ParserPool
Parameters:
newSchema - the schema builders use to validate

isDTDValidating

public boolean isDTDValidating()
Gets whether the builders are validating.

Returns:
whether the builders are validating

setDTDValidating

public void setDTDValidating(boolean isValidating)
Sets whether the builders are validating.

Parameters:
isValidating - whether the builders are validating

isXincludeAware

public boolean isXincludeAware()
Gets whether the builders are XInclude aware.

Returns:
whether the builders are XInclude aware

setXincludeAware

public void setXincludeAware(boolean isXIncludeAware)
Sets whether the builders are XInclude aware.

Parameters:
isXIncludeAware - whether the builders are XInclude aware

getPoolVersion

protected long getPoolVersion()
Gets the current pool version.

Returns:
current pool version

getPoolSize

protected int getPoolSize()
Gets the size of the current pool storage.

Returns:
current pool storage size

initializePool

protected void initializePool()
                       throws XMLParserException
Initializes the pool with a new set of configuration options.

Throws:
XMLParserException - thrown if there is a problem initialzing the pool

setAttributes

protected void setAttributes(DocumentBuilderFactory factory,
                             Map<String,Object> attributes)
Sets document builder attributes. If an attribute is not supported it is ignored.

Parameters:
factory - document builder factory upon which the attribute will be set
attributes - the set of attributes to be set

setFeatures

protected void setFeatures(DocumentBuilderFactory factory,
                           Map<String,Boolean> features)
Sets document builder features. If an features is not supported it is ignored.

Parameters:
factory - document builder factory upon which the attribute will be set
features - the set of features to be set

createBuilder

protected DocumentBuilder createBuilder()
                                 throws XMLParserException
Creates a new document builder.

Returns:
newly created document builder
Throws:
XMLParserException - thrown if their is a configuration error with the builder factory

buildDefaultFeatures

protected Map<String,Boolean> buildDefaultFeatures()
Build the default set of parser features to use.

These will be overriden by a call to setBuilderFeatures(Map).

The default features set are:

Returns:
the default features map


Copyright © 1999-2013. All Rights Reserved.