org.opensaml
Class XML.ParserPool

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