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`, `SimpleXMLObjectUnmarshaller`, `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 default `ParserPool` 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
`static final String`
`CONFIG_PROPERTY_XML_STRICT_MODE`
Config property for controlling the use of strict mode.
`private final org.slf4j.Logger`
`log`
Class logger.
`private final boolean`
`strictMode`
Flag for strict mode which disallows unexpected content.
`private final UnmarshallerFactory`
`unmarshallerFactory`
Factory for creating unmarshallers for child elements.
`private final 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 Details

### CONFIG_PROPERTY_XML_STRICT_MODE

@Nonnull @NotEmpty public static final String CONFIG_PROPERTY_XML_STRICT_MODE
Config property for controlling the use of strict mode.

See Also:
  - Constant Field Values

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

### strictMode

private final boolean strictMode
Flag for strict mode which disallows unexpected content.

## 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) throws UnmarshallingException
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
Throws:
  `UnmarshallingException` - if there is a problem adding the element content to the XMLObject

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