Package 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.

  • 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

      private DocumentBuilderFactory builderFactory
      Factory used to create new builders.

    • builderPool

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

    • 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:

      Returns:
      the default features map