net.shibboleth.utilities.java.support.xml

Class BasicParserPool

java.lang.Object

net.shibboleth.utilities.java.support.component.AbstractInitializableComponent

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

All Implemented Interfaces:

Component, DestructableComponent, InitializableComponent, ParserPool

@ThreadSafe
public class BasicParserPool
extends AbstractInitializableComponent
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

Nested Classes

Modifier and Type	Class and Description
protected class	BasicParserPool.DocumentBuilderProxy A proxy that prevents the manages document builders retrieved from the parser pool.

Field Summary

Fields

Modifier and Type	Field and Description
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

Constructors

Constructor and Description
BasicParserPool() Constructor.

Method Summary

Methods

Modifier and Type	Method and Description
protected Map<String,Boolean>	buildDefaultFeatures() Build the default set of parser features to use.
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.
EntityResolver	getEntityResolver() Gets the EntityResolver.
ErrorHandler	getErrorHandler() Gets the ErrorHandler.
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.
private void	prepareBuilder(DocumentBuilder builder) Prepare a document builder instance for use, before returning it from a checkout call.
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	setEntityResolver(EntityResolver resolver) Sets the EntityResolver.
void	setErrorHandler(ErrorHandler handler) Sets the ErrorHandler.
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.AbstractInitializableComponent

destroy, initialize, isDestroyed, isInitialized

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.

builderFactory

private DocumentBuilderFactory builderFactory

Factory used to create new builders.

builderPool

private final 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

getEntityResolver

@Nullable
public EntityResolver getEntityResolver()

Gets the EntityResolver.

Returns:

the configured entity resolver, may be null

setEntityResolver

public void setEntityResolver(@Nullable
                     EntityResolver resolver)

Sets the EntityResolver.

Parameters:

resolver - the new entity resolver, may be null

getErrorHandler

@Nonnull
public ErrorHandler getErrorHandler()

Gets the ErrorHandler.

Returns:

the configured entity resolver, may be null

setErrorHandler

public void setErrorHandler(@Nonnull
                   ErrorHandler handler)

Sets the ErrorHandler.

Parameters:

handler - the new error handler

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

prepareBuilder

private void prepareBuilder(@Nonnull
                  DocumentBuilder builder)

Prepare a document builder instance for use, before returning it from a checkout call.

Parameters:

builder - the document builder to prepare

doInitialize

protected void doInitialize()
                     throws ComponentInitializationException

Initialize the pool.

Overrides:

doInitialize in class AbstractInitializableComponent

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. This method is executed within the lock on the object being destroyed. The default implementation of this method is a no-op.

Overrides:

doDestroy in class AbstractInitializableComponent

checkInitializedNotDestroyed

private void checkInitializedNotDestroyed()

Helper method to test class state.

checkNotInitializedNotDestroyed

private void checkNotInitializedNotDestroyed()

Helper method to test class state.

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:

• XMLConstants.FEATURE_SECURE_PROCESSING = true
• http://apache.org/xml/features/disallow-doctype-decl = true

Returns:

the default features map