Package org.opensaml.core.xml.io

Class AbstractXMLObjectUnmarshaller

java.lang.Object

org.opensaml.core.xml.io.AbstractXMLObjectUnmarshaller

All Implemented Interfaces:

Unmarshaller

Direct Known Subclasses:

AbstractElementExtensibleXMLObjectUnmarshaller, XSAnyUnmarshaller, XSBase64BinaryUnmarshaller, XSBooleanUnmarshaller, XSDateTimeUnmarshaller, 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: As of OpenSAML v3.4 you must not surface comment or CDATA Node instances in the parsed DOM which is to be unmarshalled. DOM elements containing either comment or CDATA Node children will be rejected, resulting in a thrown UnmarshallingException. When using a JAXP parser, this may be accomplished by setting both DocumentBuilderFactory.setIgnoringComments(boolean) and DocumentBuilderFactory.setCoalescing(boolean) to true. Our BasicParserPool implementation defaults both of these appropriately and we highly recommend its use.

WARNING: In the case of Text nodes this unmarshaller will use CharacterData.getData() to retrieve the content. This is acceptable if and only if XML parsing is done in a manner consistent with the above warning, such that multiple adjacent Text nodes are not surfaced in the DOM. 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 either of these warnings will very likely lead to security bugs and/or incorrect unmarshalling behavior.

Field Summary

Fields

Modifier and Type	Field	Description
private org.slf4j.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	Description
protected	AbstractXMLObjectUnmarshaller()	Constructor.

Method Summary

Modifier and Type	Method	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 CharacterData.getData() 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 org.slf4j.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 CharacterData.getData() and passes it off to processElementContent(XMLObject, String) if the string is not null and contains something other than whitespace.

Parameters:

xmlObject - the XMLObject receiving 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.