Package net.shibboleth.shared.xml.impl

# Class BasicParserPool

java.lang.Object
net.shibboleth.shared.component.AbstractInitializableComponent
net.shibboleth.shared.xml.impl.BasicParserPool

All Implemented Interfaces:
  `Component`, `DestructableComponent`, `InitializableComponent`, `ParserPool`

@ThreadSafe public class BasicParserPool extends AbstractInitializableComponent implements ParserPool
A pool of JAXP 1.3 `DocumentBuilder`s. 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
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
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 final 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 final org.slf4j.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 String`
`securityManagerAttributeName`
Name of security manager attribute, if any.
`private boolean`
`xincludeAware`
Whether the builders are XInclude aware.

## Constructor Summary

Constructors
Constructor
Description
`BasicParserPool()`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`protected Map<String,Boolean>`
`buildDefaultFeatures()`
Build the default set of parser features to use.
`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`
`setSecurityManagerAttributeName(String name)`
Set the name of the builder attribute that controls the use of an XMLSecurityManager.
`void`
`setXincludeAware(boolean isXIncludeAware)`
Sets whether the builders are XInclude aware.

### Methods inherited from class net.shibboleth.shared.component.AbstractInitializableComponent

`checkComponentActive, checkSetterPreconditions, destroy, ifDestroyedThrowDestroyedComponentException, ifInitializedThrowUnmodifiabledComponentException, ifNotInitializedThrowUninitializedComponentException, initialize, isDestroyed, isInitialized`

### Methods inherited from class java.lang.Object

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

## Field Details

### log

@Nonnull private final org.slf4j.Logger log
Class logger.

### securityManagerAttributeName

@Nullable private String securityManagerAttributeName
Name of security manager attribute, if any.

### builderFactory

@NonnullAfterInit private DocumentBuilderFactory builderFactory
Factory used to create new builders.

### builderPool

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

@Nonnull @Unmodifiable @NotLive 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: false

### builderFeatures

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

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

@Nullable private EntityResolver entityResolver
Entity resolver used by builders.

### errorHandler

@Nonnull private ErrorHandler errorHandler
Error handler used by builders.

## Constructor Details

### BasicParserPool

public BasicParserPool()
Constructor.

## Method Details

### 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

### setSecurityManagerAttributeName

public void setSecurityManagerAttributeName(@Nullable String name)
Set the name of the builder attribute that controls the use of an XMLSecurityManager.

If set, this allows the pool to interrogate the factory to determine whether a security manager is installed and log its class.

Parameters:
  `name` - name of attribute

### 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 @NullableElements @Unmodifiable @NotLive public Map<String,Object> getBuilderAttributes()
Gets the builder attributes used when creating builders.

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 @NullableElements @Unmodifiable @NotLive public Map<String,Boolean> getBuilderFeatures()
Gets the builders' features.

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 error handler

### 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`

### buildDefaultFeatures

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