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, AbstractSAMLObjectUnmarshaller, AbstractWSAddressingObjectUnmarshaller, AbstractWSPolicyObjectUnmarshaller, AbstractWSSecurityObjectUnmarshaller, AbstractWSTrustObjectUnmarshaller, AbstractXACMLObjectUnmarshaller, AbstractXMLEncryptionUnmarshaller, AbstractXMLSignatureUnmarshaller, AddressUnmarshaller, AppliesToUnmarshaller, BodyUnmarshaller, DetailUnmarshaller, EndPointReferenceUnmarshaller, EnvelopeUnmarshaller, FaultUnmarshaller, HeaderUnmarshaller, RequestedSecurityTokenUnmarshaller, RequestSecurityTokenResponseUnmarshaller, X509SerialNumberUnmarshaller, 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 Details

    • 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 Details

    • AbstractXMLObjectUnmarshaller

      protected AbstractXMLObjectUnmarshaller()
      Constructor.

  • Method Details

    • 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.