net.shibboleth.utilities.java.support.xml
Class BasicParserPool

java.lang.Object
  net.shibboleth.utilities.java.support.component.AbstractDestructableInitializableComponent
      net.shibboleth.utilities.java.support.xml.BasicParserPool

All Implemented Interfaces:

Component, DestructableComponent, InitializableComponent, ParserPool

@ThreadSafe
public class BasicParserPool
extends AbstractDestructableInitializableComponent
implements ParserPool

A pool of JAXP 1.3 DocumentBuilders. 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). 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. This implementation of ParserPool does not allow its properties to be modified once it has been initialized.

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	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 Schema	schema Schema used to validate parsed content.
private boolean	xincludeAware Whether the builders are XInclude aware.

Constructor Summary

BasicParserPool()
Constructor.

Method Summary

private void	checkInitializedNotDestroyed() Helper method to test class state.
private void	checkNotInitializedNotDestroyed() Helper method to test class state.
protected DocumentBuilder	createBuilder() Creates a new document builder.
protected void	doDestroy() Performs component specific destruction logic.
protected void	doInitialize() Initialize the pool.
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.
int	getMaxPoolSize() Gets the max number of builders the pool will hold.
protected int	getPoolSize() Gets the size of the current pool storage.
Schema	getSchema() Gets the schema used to validate the XML document during the parsing process.
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	isIgnoreComments() Gets whether the builders ignore comments.
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() Convenience method for creating a new document with a pooled builder.
Document	parse(InputStream input) Convenience method for parsing an XML file using a pooled builder.
Document	parse(Reader input) Convenience method for parsing an XML file using a pooled builder.
void	returnBuilder(DocumentBuilder builder) Returns a builder to the pool.
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	setDTDValidating(boolean isValidating) Sets whether the builders are validating.
void	setExpandEntityReferences(boolean expand) Sets whether builders expand entity references.
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 used to validate the XML document during the parsing process.
void	setXincludeAware(boolean isXIncludeAware) Sets whether the builders are XInclude aware.

Methods inherited from class net.shibboleth.utilities.java.support.component.AbstractDestructableInitializableComponent

destroy, initialize, isDestroyed, isInitialized

Methods inherited from class java.lang.Object

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

Methods inherited from interface net.shibboleth.utilities.java.support.component.DestructableComponent

destroy, isDestroyed

Field Detail

log

private final Logger log

Class logger.

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

@Nonnull
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(@Nullable
                          DocumentBuilder builder)

Returns a builder to the pool.

Specified by:

returnBuilder in interface ParserPool

Parameters:

builder - the builder to return

newDocument

@Nonnull
public Document newDocument()
                     throws XMLParserException

Convenience 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

@Nonnull
public Document parse(@Nonnull
                              InputStream input)
               throws XMLParserException

Convenience 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

@Nonnull
public Document parse(@Nonnull
                              Reader input)
               throws XMLParserException

Convenience 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

getBuilderAttributes

@Nonnull
@NonnullElements
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(@Nullable@NullableElements
                                 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

@Nonnull
@NonnullElements
@Unmodifiable
public Map<String,Boolean> getBuilderFeatures()

Gets the builders' features. This collection is unmodifiable.

Returns:

the builders' features

setBuilderFeatures

public void setBuilderFeatures(@Nullable@NullableElements
                               Map<String,Boolean> newFeatures)

Sets the the builders' features.

Parameters:

newFeatures - the builders' features

isIgnoreComments

public boolean isIgnoreComments()

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

@Nullable
public Schema getSchema()

Gets the schema used to validate the XML document during the parsing process.

Returns:

schema used to validate the XML document during the parsing process

setSchema

public void setSchema(@Nullable
                      Schema newSchema)

Sets the schema used to validate the XML document during the parsing process.

Parameters:

newSchema - schema used to validate the XML document during the parsing process

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

getPoolSize

protected int getPoolSize()

Gets the size of the current pool storage.

Returns:

current pool storage size

createBuilder

@Nonnull
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

doInitialize

protected void doInitialize()
                     throws ComponentInitializationException

Initialize the pool.

Overrides:

doInitialize in class AbstractDestructableInitializableComponent

Throws:

ComponentInitializationException - thrown if pool can not be initialized, or if it is already initialized thrown if there is a problem initializing the component

doDestroy

protected void doDestroy()

Performs component specific destruction logic. Default implementation of this method is a no-op.

Overrides:

doDestroy in class AbstractDestructableInitializableComponent

checkInitializedNotDestroyed

private void checkInitializedNotDestroyed()

Helper method to test class state.

checkNotInitializedNotDestroyed

private void checkNotInitializedNotDestroyed()

Helper method to test class state.