org.opensaml.core.xml.io

Class AbstractXMLObjectUnmarshaller

java.lang.Object

org.opensaml.core.xml.io.AbstractXMLObjectUnmarshaller

All Implemented Interfaces:

Unmarshaller

Direct Known Subclasses:

AbstractElementExtensibleXMLObjectUnmarshaller, BaseXMLObjectUnmarshaller, XSAnyUnmarshaller, XSBase64BinaryUnmarshaller, XSBooleanUnmarshaller, XSIntegerUnmarshaller, XSQNameUnmarshaller, XSStringUnmarshaller, XSURIUnmarshaller

public abstract class AbstractXMLObjectUnmarshaller
extends Object
implements Unmarshaller

A thread safe abstract unmarshaller. This unmarshaller will:

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

WARNING: In the case of Text nodes this unmarshaller will use Text.getWholeText() * to retrieve the content. This is acceptable if and only if our XML parsing classes are used in their default (safe) configuration on the Java platforms we officially support. If you need to deal with elements that contain multiple text node children, or you intend to rely on your own XML parser and/or JAXP implementation, you will need to override unmarshallTextContent(XMLObject, Text) and do "the right thing" for your implementation. Failure to adhere to this warning will very likely lead to security bugs.

Field Summary

Fields

Modifier and Type	Field and Description
private Logger	log Class logger.
private UnmarshallerFactory	unmarshallerFactory Factory for creating unmarshallers for child elements.
private XMLObjectBuilderFactory	xmlObjectBuilderFactory Factory for XMLObjectBuilders.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractXMLObjectUnmarshaller() Constructor.

Method Summary

Methods

Modifier and Type	Method and Description
protected XMLObject	buildXMLObject(Element domElement) Constructs the XMLObject that the given DOM Element will be unmarshalled into.
protected void	checkIDAttribute(Attr attribute) Check whether the attribute's QName is registered in the global ID attribute registry.
protected void	processAttribute(XMLObject xmlObject, Attr attribute) Called after an attribute has been unmarshalled so that it can be added to the XMLObject.
protected 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 void	processElementContent(XMLObject xmlObject, String elementContent) Called if the element being unmarshalled contained textual content so that it can be added to the XMLObject.
protected void	processUnknownAttribute(AttributeExtensibleXMLObject xmlObject, Attr attribute) Called to store wildcard attributes, if the object supports that.
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

Field Detail

log

@Nonnull
private final Logger log

Class logger.

xmlObjectBuilderFactory

@Nonnull
private final XMLObjectBuilderFactory xmlObjectBuilderFactory

Factory for XMLObjectBuilders.

unmarshallerFactory

@Nonnull
private final UnmarshallerFactory unmarshallerFactory

Factory for creating unmarshallers for child elements.

Constructor Detail

AbstractXMLObjectUnmarshaller

protected AbstractXMLObjectUnmarshaller()

Constructor.

Method Detail

unmarshall

@Nonnull
public XMLObject unmarshall(@Nonnull
                           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

buildXMLObject

@Nonnull
protected XMLObject buildXMLObject(@Nonnull
                               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(@Nonnull
                       XMLObject xmlObject,
                       @Nonnull
                       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 declaration (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(@Nonnull
                                XMLObject xmlObject,
                                @Nonnull
                                Attr attribute)

Unmarshalls a namespace declaration attribute.

Parameters:

xmlObject - the xmlObject to receive the namespace declaration

attribute - the namespace declaration attribute

unmarshallSchemaInstanceAttributes

protected void unmarshallSchemaInstanceAttributes(@Nonnull
                                      XMLObject xmlObject,
                                      @Nonnull
                                      Attr attribute)

Unmarshalls the XSI type, schemaLocation, and noNamespaceSchemaLocation attributes.

Parameters:

xmlObject - the xmlObject to recieve the namespace declaration

attribute - the namespace declaration attribute

checkIDAttribute

protected void checkIDAttribute(@Nonnull
                    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(@Nonnull
                          XMLObject xmlObject,
                          @Nonnull
                          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(@Nonnull
                         XMLObject xmlObject,
                         @Nonnull
                         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 void processChildElement(@Nonnull
                       XMLObject parentXMLObject,
                       @Nonnull
                       XMLObject childXMLObject)
                            throws UnmarshallingException

Called after a child element has been unmarshalled so that it can be added to the parent XMLObject. The default implementation of this method is a no-op.

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 void processAttribute(@Nonnull
                    XMLObject xmlObject,
                    @Nonnull
                    Attr attribute)
                         throws UnmarshallingException

Called after an attribute has been unmarshalled so that it can be added to the XMLObject. The default implementation of this method is a no-op

Parameters:

xmlObject - the XMLObject

attribute - the attribute

Throws:

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

processElementContent

protected void processElementContent(@Nonnull
                         XMLObject xmlObject,
                         @Nonnull
                         String elementContent)

Called if the element being unmarshalled contained textual content so that it can be added to the XMLObject. The default implementation of this method is a no-op

Parameters:

xmlObject - XMLObject the content will be given to

elementContent - the Element's content

processUnknownAttribute

protected void processUnknownAttribute(@Nonnull
                           AttributeExtensibleXMLObject xmlObject,
                           @Nonnull
                           Attr attribute)

Called to store wildcard attributes, if the object supports that. It is expected that the object's unmarshaller will have checked and dealt with known attributes before calling this.

Parameters:

xmlObject - The object which support anyAttribute.

attribute - The attribute in question.