BasicParserPool (XMLTooling-J 1.4.6 API)

java.lang.Object
- 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

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

Constructors
Constructor and Description

BasicParserPool()
Constructor.

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.
`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.
`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.
`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
  - prepareBuilder
```
private void prepareBuilder(DocumentBuilder builder)
```
    Prepare a document builder instance for use, before returning it from a checkout call.
    
    Parameters:
    builder - the document builder to prepare
  - 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

Class BasicParserPool

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

log

poolVersion

dirtyBuilderConfiguration

builderFactory

builderPool

maxPoolSize

builderAttributes

coalescing

expandEntityReferences

builderFeatures

ignoreComments

ignoreElementContentWhitespace

namespaceAware

schema

dtdValidating

xincludeAware

entityResolver

errorHandler

Constructor Detail

BasicParserPool

Method Detail

getBuilder

returnBuilder

newDocument

parse

parse

getMaxPoolSize

setMaxPoolSize

getCreateBuildersAtPoolLimit

setCreateBuildersAtPoolLimit

getBuilderAttributes

setBuilderAttributes

isCoalescing

setCoalescing

isExpandEntityReferences

setExpandEntityReferences

getBuilderFeatures

setBuilderFeatures

getIgnoreComments

setIgnoreComments

isIgnoreElementContentWhitespace

setIgnoreElementContentWhitespace

isNamespaceAware

setNamespaceAware

getSchema

setSchema

isDTDValidating

setDTDValidating

isXincludeAware

setXincludeAware

getPoolVersion

getPoolSize

initializePool

setAttributes

setFeatures

createBuilder

prepareBuilder

buildDefaultFeatures