com.verisign.epp.util

## Class EPPSchemaCachingParser

- java.lang.Object
- - javax.xml.parsers.DocumentBuilder
  - - com.verisign.epp.util.EPPSchemaCachingParser

- All Implemented Interfaces:
    EPPSchemaCacher
  Direct Known Subclasses:
    EPPStrictContactParser, EPPXMLSignatureSchemaCachingParser

      public class EPPSchemaCachingParser
      extends javax.xml.parsers.DocumentBuilder
      implements EPPSchemaCacher

  XML Parser that pre-caches the XML schemas from the XML schemas registered in the `EPPFactory` for improved XML parsing performance.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `BIG_PRIME` A default prime number to use for the SymbolTable size.
    `static java.lang.String` | `CREATE_ENTITY_REF_NODES` Create EntityReference nodes in the DOM tree.
    `static java.lang.String` | `DEFER_NODE_EXPANSION` Constant for setting the defer node expansion parser feature.
    `static java.lang.String` | `DISALLOW_DOCTYPE_DECL` If DTDs (doctypes) are disallowed, almost all XML entity attacks are prevented
    `static java.lang.String` | `EXTERNAL_GENERAL_ENTITIES` If DTDs (doctypes) are disallowed, almost all XML entity attacks are prevented
    `static java.lang.String` | `EXTERNAL_PARAMETER_ENTITIES` Include external parameter entities and the external DTD subset.
    `static java.lang.String` | `INCLUDE_IGNORABLE_WHITE_SPACE` Include text nodes that can be considered "ignorable whitespace" in the DOM tree.
    `static java.lang.String` | `LOAD_DTD_GRAMMAR` Load the DTD and use it to add default attributes and set attribute types when parsing.
    `static java.lang.String` | `LOAD_EXTERNAL_DTD` Apache constant for loading external DTD's when they are seen in the instance document
    `static java.lang.String` | `NAMESPACES_FEATURE_ID` Namespaces feature id (http://xml.org/sax/features/namespaces).
    `static java.lang.String` | `NORMALIZE_DATA` attempt to normalize data in an entity reference or CDATA section.
    `static java.lang.String` | `POOL` Name of the EPP XML Parser Pool managed by `GenericPoolManager`
    `static java.lang.String` | `SCHEMA_FULL_CHECKING_FEATURE_ID` Schema full checking feature id (http://apache.org/xml/features/validation/schema-full-checking).
    `static java.lang.String` | `SCHEMA_VALIDATION_FEATURE_ID` Schema validation feature id (http://apache.org/xml/features/validation/schema).
    `protected static java.lang.String` | `SYMBOL_TABLE` Property identifier: The symbol table feature
    `static java.lang.String` | `VALIDATION_FEATURE_ID` Validation feature id (http://xml.org/sax/features/validation).
    `static java.lang.String` | `XMLGRAMMAR_POOL` Property identifier: The XML Grammar pool feature

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `EPPSchemaCachingParser()` Create a new instance of EPPSchemaCachingParser.
    `EPPSchemaCachingParser(int aSymbolTableSize)` Creates an EPPSchemaCachingParser instance with the specified symbol table size.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addSchemaToCache(org.apache.xerces.xni.parser.XMLInputSource aSchema)` Addes the XMLInputSource instance to the current cache of schemas.
    `org.w3c.dom.DOMImplementation` | `getDOMImplementation()` Returns the DOM implementation
    `boolean` | `getFeature(java.lang.String aFeatureId)` Query the state of a feature.
    `java.lang.Object` | `getProperty(java.lang.String aPropertyId)` Query the value of a property.
    `int` | `getSymbolTableSize()` Gets the symbol table size
    `protected java.util.Set<java.lang.String>` | `getXmlSchemas()` Gets the XML schemas to pre-load into the XML parser.
    `protected void` | `init()` Helper method to initialize this instance of `EPPSchemaCachingParser`.
    `boolean` | `isNamespaceAware()` Returns true if the parser is setup to be Namespace aware, false otherwise.
    `boolean` | `isValidating()` Returns true if this parser is setup to validate XML instances, false otherwise
    `org.w3c.dom.Document` | `newDocument()` Non-preferred: use the getDOMImplementation() method instead of this one to get a DOM Level 2 DOMImplementation object and then use DOM Level 2 methods to create a DOM Document object.
    `org.w3c.dom.Document` | `parse(java.io.File aFile)` Parse a file to a DOM Document.
    `org.w3c.dom.Document` | `parse(org.xml.sax.InputSource aXmlInstance)` Parses the InputSource passed in which should be an XML instance.
    `org.w3c.dom.Document` | `parse(java.io.InputStream aInputStream)` Implemented as part of standard Document Builder API.
    `org.w3c.dom.Document` | `parse(java.io.InputStream aInputStream, java.lang.String aSystemId)` Implemented as part of standard Document Builder API.
    `org.w3c.dom.Document` | `parse(java.lang.String aUri)` Implemented as part of standard Document Builder API.
    `protected void` | `preloadSchemas()` Pre-load the XML schemas into the parser based on the `EPPFactory` XML schemas.
    `void` | `setEntityResolver(org.xml.sax.EntityResolver aEntityResolver)` Sets the EntityResolver of this DocumentBuilder
    `void` | `setErrorHandler(org.xml.sax.ErrorHandler aErrorHandler)` Sets the ErrorHandler this DocumentBuilder instance.
    `void` | `setFeature(java.lang.String aFeatureId, boolean aBoolean)` Set the state of any feature in a SAX2 parser.
    `void` | `setLockSchemaCache(boolean aBoolean)` Lock the schema cache.
    `void` | `setProperty(java.lang.String aProperty, java.lang.Object aObject)` Set the state of any property in a SAX2 parser.
    `void` | `setSymbolTableSize(int aSymbolTableSize)` Sets the symbol table size.

    - ### Methods inherited from class javax.xml.parsers.DocumentBuilder

      `getSchema, isXIncludeAware, reset`

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

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

- - ### Field Detail

    - #### POOL

          public static final java.lang.String POOL

      Name of the EPP XML Parser Pool managed by `GenericPoolManager`
      See Also:
        Constant Field Values

    - #### BIG_PRIME

          public static final int BIG_PRIME

      A default prime number to use for the SymbolTable size. Some other sample big primes: 1299709 1299721 1299743 1299763 1299791 1299811 1299817 1299821 1299827
      See Also:
        Constant Field Values

    - #### NAMESPACES_FEATURE_ID

          public static final java.lang.String NAMESPACES_FEATURE_ID

      Namespaces feature id (http://xml.org/sax/features/namespaces). \
      See Also:
        Constant Field Values

    - #### VALIDATION_FEATURE_ID

          public static final java.lang.String VALIDATION_FEATURE_ID

      Validation feature id (http://xml.org/sax/features/validation).
      See Also:
        Constant Field Values

    - #### SCHEMA_VALIDATION_FEATURE_ID

          public static final java.lang.String SCHEMA_VALIDATION_FEATURE_ID

      Schema validation feature id (http://apache.org/xml/features/validation/schema).
      See Also:
        Constant Field Values

    - #### SCHEMA_FULL_CHECKING_FEATURE_ID

          public static final java.lang.String SCHEMA_FULL_CHECKING_FEATURE_ID

      Schema full checking feature id (http://apache.org/xml/features/validation/schema-full-checking). Enable full schema grammar constraint checking, including checking which may be time-consuming or memory intensive. Currently, particle unique attribution constraint checking and particle derivation resriction checking are controlled by this option.
      See Also:
        Constant Field Values

    - #### XMLGRAMMAR_POOL

          public static final java.lang.String XMLGRAMMAR_POOL

      Property identifier: The XML Grammar pool feature
      See Also:
        Constant Field Values

    - #### SYMBOL_TABLE

          protected static final java.lang.String SYMBOL_TABLE

      Property identifier: The symbol table feature
      See Also:
        Constant Field Values

    - #### DEFER_NODE_EXPANSION

          public static final java.lang.String DEFER_NODE_EXPANSION

      Constant for setting the defer node expansion parser feature. The recommendation is to set this to false for EPP packets since the are not large documents.
      See Also:
        Constant Field Values

    - #### LOAD_EXTERNAL_DTD

          public static final java.lang.String LOAD_EXTERNAL_DTD

      Apache constant for loading external DTD's when they are seen in the instance document
      See Also:
        Constant Field Values

    - #### LOAD_DTD_GRAMMAR

          public static final java.lang.String LOAD_DTD_GRAMMAR

      Load the DTD and use it to add default attributes and set attribute types when parsing. False: Build the grammar but do not use the default attributes and attribute types information it contains.
      See Also:
        Constant Field Values

    - #### CREATE_ENTITY_REF_NODES

          public static final java.lang.String CREATE_ENTITY_REF_NODES

      Create EntityReference nodes in the DOM tree. The EntityReference nodes and their child nodes will be read-only. False: Do not create EntityReference nodes in the DOM tree. No EntityReference nodes will be created, only the nodes corresponding to their fully expanded substitution text will be created
      See Also:
        Constant Field Values

    - #### INCLUDE_IGNORABLE_WHITE_SPACE

          public static final java.lang.String INCLUDE_IGNORABLE_WHITE_SPACE

      Include text nodes that can be considered "ignorable whitespace" in the DOM tree. False: Do not include ignorable whitespace in the DOM tree.
      See Also:
        Constant Field Values

    - #### EXTERNAL_GENERAL_ENTITIES

          public static final java.lang.String EXTERNAL_GENERAL_ENTITIES

      If DTDs (doctypes) are disallowed, almost all XML entity attacks are prevented
      See Also:
        Constant Field Values

    - #### EXTERNAL_PARAMETER_ENTITIES

          public static final java.lang.String EXTERNAL_PARAMETER_ENTITIES

      Include external parameter entities and the external DTD subset. False: Do not include external parameter entities or the external DTD subset.
      See Also:
        Constant Field Values

    - #### NORMALIZE_DATA

          public static final java.lang.String NORMALIZE_DATA

      attempt to normalize data in an entity reference or CDATA section. To preserve character data within entity references and CDATA sections, turn off http://apache.org/xml/features/validation/schema/normalized-value feature.
      See Also:
        Constant Field Values

    - #### DISALLOW_DOCTYPE_DECL

          public static final java.lang.String DISALLOW_DOCTYPE_DECL

      If DTDs (doctypes) are disallowed, almost all XML entity attacks are prevented
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### EPPSchemaCachingParser

          public EPPSchemaCachingParser()

      Create a new instance of EPPSchemaCachingParser. Defaults are: Namespace aware: true Validation: true Schema Validation: true Full Schema checking: true

    - #### EPPSchemaCachingParser

          public EPPSchemaCachingParser(int aSymbolTableSize)

      Creates an EPPSchemaCachingParser instance with the specified symbol table size.
      Parameters:
        `aSymbolTableSize` - Size of the symbol table

  - ### Method Detail

    - #### init

          protected void init()
                       throws EPPParserException

      Helper method to initialize this instance of `EPPSchemaCachingParser`.
      Throws:
        `EPPParserException` - Error initializing `EPPSchemaCachingParser`

    - #### getXmlSchemas

          protected java.util.Set<java.lang.String> getXmlSchemas()

      Gets the XML schemas to pre-load into the XML parser. Derived classes can override this method to pre-load a custom set of XML schemas.
      Returns:
        XML schema names to pre-load

    - #### preloadSchemas

          protected void preloadSchemas()
                                 throws EPPParserException

      Pre-load the XML schemas into the parser based on the `EPPFactory` XML schemas. A derived class can customize what XML schemas to pre-load.
      Throws:
        `EPPParserException` - Error loading the XML schemas into the parser

    - #### setLockSchemaCache

          public void setLockSchemaCache(boolean aBoolean)

      Lock the schema cache. True param locks it, false unlocks it
      Specified by:
        `setLockSchemaCache` in interface `EPPSchemaCacher`
      Parameters:
        `aBoolean` - True param locks it, false unlocks it

    - #### addSchemaToCache

          public void addSchemaToCache(org.apache.xerces.xni.parser.XMLInputSource aSchema)
                                throws EPPParserException

      Addes the XMLInputSource instance to the current cache of schemas. Only addes the schema to the cache if it isn't already in the cache.
      Specified by:
        `addSchemaToCache` in interface `EPPSchemaCacher`
      Parameters:
        `aSchema` - The schema instance to be cached
      Throws:
        `EPPParserException` - Error adding schema to the cache

    - #### isNamespaceAware

          public boolean isNamespaceAware()

      Returns true if the parser is setup to be Namespace aware, false otherwise.
      Specified by:
        `isNamespaceAware` in class `javax.xml.parsers.DocumentBuilder`
      Returns:
        true if the parser is setup to be Namespace aware, false otherwise.
      Throws:
        `java.lang.IllegalStateException` - Parser is not in a state to query it's properties

    - #### setEntityResolver

          public void setEntityResolver(org.xml.sax.EntityResolver aEntityResolver)

      Sets the EntityResolver of this DocumentBuilder
      Specified by:
        `setEntityResolver` in class `javax.xml.parsers.DocumentBuilder`
      Parameters:
        `aEntityResolver` - The EntityResolver instance that this DocumentBuilder will use when parsing.

    - #### getDOMImplementation

          public org.w3c.dom.DOMImplementation getDOMImplementation()

      Returns the DOM implementation
      Specified by:
        `getDOMImplementation` in class `javax.xml.parsers.DocumentBuilder`
      Returns:
        the DOM implementation

    - #### newDocument

          public org.w3c.dom.Document newDocument()

      Non-preferred: use the getDOMImplementation() method instead of this one to get a DOM Level 2 DOMImplementation object and then use DOM Level 2 methods to create a DOM Document object.
      Specified by:
        `newDocument` in class `javax.xml.parsers.DocumentBuilder`
      Returns:
        DOCUMENT ME!

    - #### parse

          public org.w3c.dom.Document parse(org.xml.sax.InputSource aXmlInstance)
                                     throws org.xml.sax.SAXException,
                                            java.io.IOException

      Parses the InputSource passed in which should be an XML instance. Returns a DOM document.
      Specified by:
        `parse` in class `javax.xml.parsers.DocumentBuilder`
      Parameters:
        `aXmlInstance` - The XML instance to parse
      Returns:
        The DOM Document that represents the XML instance
      Throws:
        `org.xml.sax.SAXException` - Thrown if any errors occur
        `java.io.IOException` - Thrown if any errors occur
        `java.lang.IllegalArgumentException` - DOCUMENT ME!

    - #### parse

          public org.w3c.dom.Document parse(java.io.InputStream aInputStream,
                                            java.lang.String aSystemId)
                                     throws org.xml.sax.SAXException,
                                            java.io.IOException

      Implemented as part of standard Document Builder API. Delegates to DOMParser
      Overrides:
        `parse` in class `javax.xml.parsers.DocumentBuilder`
      Parameters:
        `aInputStream` - The InputStream instance to parse
        `aSystemId` - XML System Id
      Returns:
        The DOM Document created after the parsing episode
      Throws:
        `org.xml.sax.SAXException` - Error parsing XML
        `java.io.IOException` - Error processing input

    - #### parse

          public org.w3c.dom.Document parse(java.lang.String aUri)
                                     throws org.xml.sax.SAXException,
                                            java.io.IOException

      Implemented as part of standard Document Builder API. Delegates to DOMParser
      Overrides:
        `parse` in class `javax.xml.parsers.DocumentBuilder`
      Parameters:
        `aUri` - The URI to parse
      Returns:
        The DOM Document created after the parsing episode
      Throws:
        `org.xml.sax.SAXException` - Error parsing XML
        `java.io.IOException` - Error processing input

    - #### parse

          public org.w3c.dom.Document parse(java.io.InputStream aInputStream)
                                     throws org.xml.sax.SAXException,
                                            java.io.IOException

      Implemented as part of standard Document Builder API. Delegates to DOMParser
      Overrides:
        `parse` in class `javax.xml.parsers.DocumentBuilder`
      Parameters:
        `aInputStream` - The InputStream to parse
      Returns:
        The DOM Document created after parsing the stream
      Throws:
        `org.xml.sax.SAXException` - Error parsing XML
        `java.io.IOException` - Error processing input

    - #### parse

          public org.w3c.dom.Document parse(java.io.File aFile)
                                     throws org.xml.sax.SAXException,
                                            java.io.IOException

      Parse a file to a DOM Document.
      Overrides:
        `parse` in class `javax.xml.parsers.DocumentBuilder`
      Parameters:
        `aFile` - XML file to parse to a DOM Document
      Returns:
        The DOM Document created after parsing the file
      Throws:
        `java.io.IOException` - Error opening XML file
        `org.xml.sax.SAXException` - Error parsing XML file

    - #### setErrorHandler

          public void setErrorHandler(org.xml.sax.ErrorHandler aErrorHandler)

      Sets the ErrorHandler this DocumentBuilder instance.
      Specified by:
        `setErrorHandler` in class `javax.xml.parsers.DocumentBuilder`
      Parameters:
        `aErrorHandler` - The ErrorHandler instance to use

    - #### isValidating

          public boolean isValidating()

      Returns true if this parser is setup to validate XML instances, false otherwise
      Specified by:
        `isValidating` in class `javax.xml.parsers.DocumentBuilder`
      Returns:
        Returns true if this parser is setup to validate XML instances, false otherwise
      Throws:
        `java.lang.IllegalStateException` - Error setting the validation feature

    - #### getSymbolTableSize

          public int getSymbolTableSize()

      Gets the symbol table size
      Returns:
        the symbol table size

    - #### setSymbolTableSize

          public void setSymbolTableSize(int aSymbolTableSize)
                                  throws EPPParserException

      Sets the symbol table size. If set to 0 then the symbol table size will use the default provided with the ParserConfiguration.
      Parameters:
        `aSymbolTableSize` - The new value of the symbol table size
      Throws:
        `EPPParserException` - Error setting the symbol table size

    - #### setFeature

          public void setFeature(java.lang.String aFeatureId,
                                 boolean aBoolean)
                          throws org.xml.sax.SAXNotSupportedException,
                                 org.xml.sax.SAXNotRecognizedException

      Set the state of any feature in a SAX2 parser. The parser might not recognize the feature, and if it does recognize it, it might not be able to fulfill the request.
      Parameters:
        `aFeatureId` - The unique identifier (URI) of the feature.
        `aBoolean` - The requested state of the feature (true or false).
      Throws:
        `org.xml.sax.SAXNotSupportedException` - If the requested feature is known, but the requested state is not supported.
        `org.xml.sax.SAXNotRecognizedException` - If the requested feature is not known.

    - #### setProperty

          public void setProperty(java.lang.String aProperty,
                                  java.lang.Object aObject)
                           throws org.xml.sax.SAXNotSupportedException,
                                  org.xml.sax.SAXNotRecognizedException

      Set the state of any property in a SAX2 parser. The parser might not recognize the feature, and if it does recognize it, it might not be able to fulfill the request.
      Parameters:
        `aProperty` - The unique identifier (URI) of the feature.
        `aObject` - The requested state of the feature (true or false).
      Throws:
        `org.xml.sax.SAXNotSupportedException` - If the requested feature is known, but the requested state is not supported.
        `org.xml.sax.SAXNotRecognizedException` - If the requested feature is not known.

    - #### getFeature

          public boolean getFeature(java.lang.String aFeatureId)
                             throws org.xml.sax.SAXNotSupportedException,
                                    org.xml.sax.SAXNotRecognizedException

      Query the state of a feature. Query the current state of any feature in a SAX2 parser. The parser might not recognize the feature.
      Parameters:
        `aFeatureId` - The unique identifier (URI) of the feature being set.
      Returns:
        The current state of the feature.
      Throws:
        `org.xml.sax.SAXNotSupportedException` - If the requested feature is known but not supported.
        `org.xml.sax.SAXNotRecognizedException` - If the requested feature is not known.

    - #### getProperty

          public java.lang.Object getProperty(java.lang.String aPropertyId)
                                       throws org.xml.sax.SAXNotSupportedException,
                                              org.xml.sax.SAXNotRecognizedException

      Query the value of a property. Return the current value of a property in a SAX2 parser. The parser might not recognize the property.
      Parameters:
        `aPropertyId` - The unique identifier (URI) of the property being set.
      Returns:
        The current value of the property.
      Throws:
        `org.xml.sax.SAXNotSupportedException` - If the requested property is known but not supported.
        `org.xml.sax.SAXNotRecognizedException` - If the requested property is not known.