org.opensaml.xml.io
Class AbstractXMLObjectUnmarshaller

java.lang.Object
  org.opensaml.xml.io.AbstractXMLObjectUnmarshaller

All Implemented Interfaces:

Unmarshaller

Direct Known Subclasses:

AbstractElementExtensibleXMLObjectUnmarshaller, AbstractXMLEncryptionUnmarshaller, AbstractXMLSignatureUnmarshaller, BaseXMLObjectUnmarshaller, X509SerialNumberUnmarshaller, XSAnyUnmarshaller, XSBase64BinaryUnmarshaller, XSIntegerUnmarshaller, XSQNameUnmarshaller, XSStringUnmarshaller, XSURIUnmarshaller

public abstract class AbstractXMLObjectUnmarshaller
extends Object
implements Unmarshaller

An thread safe abstract unmarshaller. This unmarshaller will:

• Unmarshalling namespace decleration attributes
• Unmarshalling schema instance type (xsi:type) decleration attributes
• Delegating to child classes element, text, and attribute processing

NOTE: In the case of Text nodes this unmarshaller will use Text.getWholeText() to retrieve the textual content. This is probably exceptable in almost all cases, if, however, you need to deal with elements that contain multiple text node children you will need to override unmarshallTextContent(XMLObject, Text) and do "the right thing" for your implementation.

Constructor Summary

protected	AbstractXMLObjectUnmarshaller() Constructor.
protected	AbstractXMLObjectUnmarshaller(String targetNamespaceURI, String targetLocalName) Deprecated. no replacement

Method Summary

protected XMLObject	buildXMLObject(Element domElement) Constructs the XMLObject that the given DOM Element will be unmarshalled into.
protected void	checkElementIsTarget(Element domElement) Checks that the given DOM Element's XSI type or namespace qualified element name matches the target QName of this unmarshaller.
protected void	checkIDAttribute(Attr attribute) Check whether the attribute's QName is registered in the global ID attribute registry.
protected abstract void	processAttribute(XMLObject xmlObject, Attr attribute) Called after an attribute has been unmarshalled so that it can be added to the XMLObject.
protected abstract void	processChildElement(XMLObject parentXMLObject, XMLObject childXMLObject) Called after a child element has been unmarshalled so that it can be added to the parent XMLObject.
protected abstract void	processElementContent(XMLObject xmlObject, String elementContent) Called if the element being unmarshalled contained textual content so that it can be added to the XMLObject.
XMLObject	unmarshall(Element domElement) Unmarshalls the given W3C DOM element into a XMLObject.
protected void	unmarshallAttribute(XMLObject xmlObject, Attr attribute) Unmarshalls the attributes from the given DOM Attr into the given XMLObject.
protected void	unmarshallChildElement(XMLObject xmlObject, Element childElement) Unmarshalls given Element's children.
protected void	unmarshallNamespaceAttribute(XMLObject xmlObject, Attr attribute) Unmarshalls a namespace declaration attribute.
protected void	unmarshallSchemaInstanceAttributes(XMLObject xmlObject, Attr attribute) Unmarshalls the XSI type, schemaLocation, and noNamespaceSchemaLocation attributes.
protected void	unmarshallTextContent(XMLObject xmlObject, Text content) Unmarshalls the given Text node into a usable string by way of Text.getWholeText() and passes it off to processElementContent(XMLObject, String) if the string is not null and contains something other than whitespace.

Methods inherited from class java.lang.Object

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

Constructor Detail

AbstractXMLObjectUnmarshaller

protected AbstractXMLObjectUnmarshaller()

Constructor.

AbstractXMLObjectUnmarshaller

protected AbstractXMLObjectUnmarshaller(String targetNamespaceURI,
                                        String targetLocalName)

Deprecated. no replacement

This constructor supports checking a DOM Element to be unmarshalled, either element name or schema type, against a given namespace/local name pair.

Parameters:

targetNamespaceURI - the namespace URI of either the schema type QName or element QName of the elements this unmarshaller operates on

targetLocalName - the local name of either the schema type QName or element QName of the elements this unmarshaller operates on

Method Detail

unmarshall

public XMLObject unmarshall(Element domElement)
                     throws UnmarshallingException

Unmarshalls the given W3C DOM element into a XMLObject.

Specified by:

unmarshall in interface Unmarshaller

Parameters:

domElement - the DOM Element

Returns:

the unmarshalled XMLObject

Throws:

UnmarshallingException - thrown if an error occurs unmarshalling the DOM element into the XMLObject

checkElementIsTarget

protected void checkElementIsTarget(Element domElement)
                             throws UnmarshallingException

Checks that the given DOM Element's XSI type or namespace qualified element name matches the target QName of this unmarshaller.

Parameters:

domElement - the DOM element to check

Throws:

UnmarshallingException - thrown if the DOM Element does not match the target of this unmarshaller

buildXMLObject

protected XMLObject buildXMLObject(Element domElement)
                            throws UnmarshallingException

Constructs the XMLObject that the given DOM Element will be unmarshalled into. If the DOM element has an XML Schema type defined this method will attempt to retrieve an XMLObjectBuilder, from the factory given at construction time, using the schema type. If no schema type is present or no builder is registered with the factory for the schema type, the elements QName is used. Once the builder is found the XMLObject is create by invoking XMLObjectBuilder.buildObject(String, String, String). Extending classes may wish to override this logic if more than just schema type or element name (e.g. element attributes or content) need to be used to determine which XMLObjectBuilder should be used to create the XMLObject.

Parameters:

domElement - the DOM Element the created XMLObject will represent

Returns:

the empty XMLObject that DOM Element can be unmarshalled into

Throws:

UnmarshallingException - thrown if there is now XMLObjectBuilder registered for the given DOM Element

unmarshallAttribute

protected void unmarshallAttribute(XMLObject xmlObject,
                                   Attr attribute)
                            throws UnmarshallingException

Unmarshalls the attributes from the given DOM Attr into the given XMLObject. If the attribute is an XML namespace declaration the attribute is passed to unmarshallNamespaceAttribute(XMLObject, Attr). If it is an schema type decleration (xsi:type) it is ignored because this attribute is handled by buildXMLObject(Element). All other attributes are passed to the processAttribute(XMLObject, Attr)

Parameters:

attribute - the attribute to be unmarshalled

xmlObject - the XMLObject that will recieve information from the DOM attribute

Throws:

UnmarshallingException - thrown if there is a problem unmarshalling an attribute

unmarshallNamespaceAttribute

protected void unmarshallNamespaceAttribute(XMLObject xmlObject,
                                            Attr attribute)

Unmarshalls a namespace declaration attribute.

Parameters:

xmlObject - the xmlObject to recieve the namespace decleration

attribute - the namespace decleration attribute

unmarshallSchemaInstanceAttributes

protected void unmarshallSchemaInstanceAttributes(XMLObject xmlObject,
                                                  Attr attribute)

Unmarshalls the XSI type, schemaLocation, and noNamespaceSchemaLocation attributes.

Parameters:

xmlObject - the xmlObject to recieve the namespace decleration

attribute - the namespace decleration attribute

checkIDAttribute

protected void checkIDAttribute(Attr attribute)

Check whether the attribute's QName is registered in the global ID attribute registry. If it is, and the specified attribute's DOM Level 3 Attr.isId() is false (due to lack of schema validation, for example), then declare the attribute as an ID type in the DOM on the attribute's owning element. This is to handle cases where the underlying DOM needs to accurately reflect an attribute's ID-ness, for example ID reference resolution within the Apache XML Security library.

Parameters:

attribute - the DOM attribute to be checked

unmarshallChildElement

protected void unmarshallChildElement(XMLObject xmlObject,
                                      Element childElement)
                               throws UnmarshallingException

Unmarshalls given Element's children. For each child an unmarshaller is retrieved using UnmarshallerFactory.getUnmarshaller(Element). The unmarshaller is then used to unmarshall the child element and the resultant XMLObject is passed to processChildElement(XMLObject, XMLObject) for further processing.

Parameters:

xmlObject - the parent object of the unmarshalled children

childElement - the child element to be unmarshalled

Throws:

UnmarshallingException - thrown if an error occurs unmarshalling the chilren elements

unmarshallTextContent

protected void unmarshallTextContent(XMLObject xmlObject,
                                     Text content)
                              throws UnmarshallingException

Unmarshalls the given Text node into a usable string by way of Text.getWholeText() and passes it off to processElementContent(XMLObject, String) if the string is not null and contains something other than whitespace.

Parameters:

xmlObject - the XMLObject recieving the element content

content - the textual content

Throws:

UnmarshallingException - thrown if there is a problem unmarshalling the text node

processChildElement

protected abstract void processChildElement(XMLObject parentXMLObject,
                                            XMLObject childXMLObject)
                                     throws UnmarshallingException

Called after a child element has been unmarshalled so that it can be added to the parent XMLObject.

Parameters:

parentXMLObject - the parent XMLObject

childXMLObject - the child XMLObject

Throws:

UnmarshallingException - thrown if there is a problem adding the child to the parent

processAttribute

protected abstract void processAttribute(XMLObject xmlObject,
                                         Attr attribute)
                                  throws UnmarshallingException

Called after an attribute has been unmarshalled so that it can be added to the XMLObject.

Parameters:

xmlObject - the XMLObject

attribute - the attribute

Throws:

UnmarshallingException - thrown if there is a problem adding the attribute to the XMLObject

processElementContent

protected abstract void processElementContent(XMLObject xmlObject,
                                              String elementContent)

Called if the element being unmarshalled contained textual content so that it can be added to the XMLObject.

Parameters:

xmlObject - XMLObject the content will be given to

elementContent - the Element's content