org.opensaml
Class XML.ParserPool

java.lang.Object
  extended by org.opensaml.XML.ParserPool
All Implemented Interfaces:
EntityResolver, ErrorHandler
Enclosing class:
XML

public static class XML.ParserPool
extends Object
implements ErrorHandler, EntityResolver

Nested class that provides XML parsers as a pooled resource

Author:
Scott Cantor, Howard Gilbert

Field Summary
protected  SAMLConfig config
          OpenSAML configuration
 
Constructor Summary
XML.ParserPool()
          Constructor for the ParserPool object
 
Method Summary
 void error(SAXParseException e)
          Called by parser if an error is detected, currently just throws e
 void fatalError(SAXParseException e)
          Called by parser if a fatal error is detected, does nothing
 DocumentBuilder get()
          Get a DocumentBuilder for the default Schema
 DocumentBuilder get(javax.xml.validation.Schema schema)
          Get a DOM parser suitable for our task
 javax.xml.validation.Schema getDefaultSchema()
           
 javax.xml.validation.Schema getSchemaSAML10()
           
 javax.xml.validation.Schema getSchemaSAML11()
           
 Document newDocument()
          Builds a new DOM document
 Document parse(InputSource in, javax.xml.validation.Schema schema)
          Parses a document using a pooled parser with the proper settings
 Document parse(InputStream in)
          Short form of parse to support legacy callers
 Document parse(String systemId)
          Legacy version of parse where the default Schema is implied
 Document parse(String systemId, javax.xml.validation.Schema schema)
          Parses a document using a pooled parser with the proper settings
 void put(DocumentBuilder p)
          Return a parser to the pool
 void registerSchemas(Map exts)
          Registers one or more extension schemas in the default schema set.
 InputSource resolveEntity(String publicId, String systemId)
           
 void setDefaultSchema(javax.xml.validation.Schema schema)
          Deprecated.  
 void setDefaultSchemas(javax.xml.validation.Schema schema10, javax.xml.validation.Schema schema11)
          Directly installs a custom schema.
 void warning(SAXParseException e)
          Called by parser if a warning is issued, currently logs the condition
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

config

protected SAMLConfig config
OpenSAML configuration

Constructor Detail

XML.ParserPool

public XML.ParserPool()
Constructor for the ParserPool object

To demonstrate the technology, the current version of this code creates both 1.0 and 1.1 Schema objects. However, it then selects only one of the two to use. Future code could refine this and maintain two pools of parsers.

Method Detail

setDefaultSchema

public void setDefaultSchema(javax.xml.validation.Schema schema)
Deprecated. 

Original method to install a custom schema. Use setDefaultSchemas instead to maintain support for SAML 1.0 and 1.1.

Parameters:
schema -

setDefaultSchemas

public void setDefaultSchemas(javax.xml.validation.Schema schema10,
                              javax.xml.validation.Schema schema11)
Directly installs a custom schema. You must supply both a SAML 1.0 and a SAML 1.1 schema object.

Parameters:
schema10 - The schemas to use when handling SAML 1.0
schema11 - The schemas to use when handling SAML 1.1

getDefaultSchema

public javax.xml.validation.Schema getDefaultSchema()

getSchemaSAML10

public javax.xml.validation.Schema getSchemaSAML10()

getSchemaSAML11

public javax.xml.validation.Schema getSchemaSAML11()

registerSchemas

public void registerSchemas(Map exts)
Registers one or more extension schemas in the default schema set. This relieves SAML applications from managing their own JAXP schema objects and enables dual compatibility with SAML 1.0 and 1.1

Note that you must insure that any dependencies are specified ahead of the schemas that require them, because they must be loaded by the SchemaFactory before they are required.

Parameters:
exts - A map of EntityResolver interfaces keyed by "systemId" to enable the SAML runtime to obtain the schema instances anytime required

get

public DocumentBuilder get(javax.xml.validation.Schema schema)
                    throws SAMLException
Get a DOM parser suitable for our task

Parameters:
schema - JAXP 1.3 Schema object (or null for no XSD)
Returns:
A DOM parser ready to use
Throws:
SAMLException - Raised if a system error prevents a parser from being created

get

public DocumentBuilder get()
                    throws SAMLException
Get a DocumentBuilder for the default Schema

Note: This uses the default (probably SAML 1.1) Schema. To get an non-schema-validating parser, call "get(null)".

Returns:
Document Builder
Throws:
SAMLException - can't create a DocumentBuilder

parse

public Document parse(InputSource in,
                      javax.xml.validation.Schema schema)
               throws SAMLException,
                      SAXException,
                      IOException
Parses a document using a pooled parser with the proper settings

Parameters:
in - A stream containing the content to be parsed
schema - Schema object or null
Returns:
The DOM document resulting from the parse
Throws:
SAMLException - Raised if a parser is unavailable
SAXException - Raised if a parsing error occurs
IOException - Raised if an I/O error occurs

parse

public Document parse(InputStream in)
               throws SAMLException,
                      SAXException,
                      IOException
Short form of parse to support legacy callers

This version is not preferred. If the caller converts the InputStream to an InputSource, then it can append a file name as the systemId. Here we only get the InputStream and create an InputSource with no identifier to be used in logging or generating error messages.

Parameters:
in - InputStream of XML to be parsed
Returns:
DOM Document
Throws:
SAMLException - Raised if a parser is unavailable
SAXException - Raised if a parsing error occurs
IOException - Raised if an I/O error occurs

parse

public Document parse(String systemId,
                      javax.xml.validation.Schema schema)
               throws SAMLException,
                      SAXException,
                      IOException
Parses a document using a pooled parser with the proper settings

Parameters:
systemId - The URI to parse
Returns:
The DOM document resulting from the parse
Throws:
SAMLException - Raised if a parser is unavailable
SAXException - Raised if a parsing error occurs
IOException - Raised if an I/O error occurs

parse

public Document parse(String systemId)
               throws SAMLException,
                      SAXException,
                      IOException
Legacy version of parse where the default Schema is implied

Parameters:
systemId - URI to be parsed, becomes systemId of InputSource
Returns:
DOM Document
Throws:
SAMLException - Raised if a parser is unavailable
SAXException - Raised if a parsing error occurs
IOException - Raised if an I/O error occurs

newDocument

public Document newDocument()
Builds a new DOM document

In JAXP, you get a new empty DOM document from a DocumentBuilder. There is no evidence that the Schema is attached to the DOM, so it doesn't matter what pool to use.

Returns:
An empty DOM document

put

public void put(DocumentBuilder p)
Return a parser to the pool

Parameters:
p - Description of Parameter

fatalError

public void fatalError(SAXParseException e)
                throws SAXException
Called by parser if a fatal error is detected, does nothing

Specified by:
fatalError in interface ErrorHandler
Parameters:
exception - Describes the error
Throws:
SAXException - Can be raised to indicate an explicit error

error

public void error(SAXParseException e)
           throws SAXParseException
Called by parser if an error is detected, currently just throws e

Specified by:
error in interface ErrorHandler
Parameters:
e - Description of Parameter
Throws:
SAXParseException - Can be raised to indicate an explicit error

warning

public void warning(SAXParseException e)
             throws SAXParseException
Called by parser if a warning is issued, currently logs the condition

Specified by:
warning in interface ErrorHandler
Parameters:
e - Describes the warning
Throws:
SAXParseException - Can be raised to indicate an explicit error

resolveEntity

public InputSource resolveEntity(String publicId,
                                 String systemId)
                          throws SAXException,
                                 IOException
Specified by:
resolveEntity in interface EntityResolver
Throws:
SAXException
IOException


Copyright ? 2005 UCAID. All Rights Reserved.