org.opensaml.core.xml

Class AbstractXMLObject

java.lang.Object

org.opensaml.core.xml.AbstractXMLObject

All Implemented Interfaces:

XMLObject

Direct Known Subclasses:

AbstractElementExtensibleXMLObject, XSAnyImpl, XSBase64BinaryImpl, XSBooleanImpl, XSDateTimeImpl, XSIntegerImpl, XSQNameImpl, XSStringImpl, XSURIImpl

public abstract class AbstractXMLObject
extends Object
implements XMLObject

An abstract implementation of XMLObject.

Field Summary

Fields

Modifier and Type	Field and Description
private Element	dom DOM Element representation of this object.
private QName	elementQname The name of this element with namespace and prefix information.
private IDIndex	idIndex Mapping of ID attributes to XMLObjects in the subtree rooted at this object.
private Logger	log Class logger.
private XSBooleanValue	nil The value of the xsi:nil attribute.
private String	noNamespaceSchemaLocation No-namespace schema locations for this XML object.
private NamespaceManager	nsManager The namespace manager for this XML object.
private net.shibboleth.utilities.java.support.collection.LockableClassToInstanceMultiMap<Object>	objectMetadata The multimap holding class-indexed instances of additional info associated with this XML object.
private XMLObject	parent Parent of this element.
private String	schemaLocation Schema locations for this XML object.
private QName	typeQname The schema type of this element with namespace and prefix information.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractXMLObject(String namespaceURI, String elementLocalName, String namespacePrefix) Constructor.

Method Summary

Methods

Modifier and Type	Method and Description
void	detach() Detaches the XMLObject from its parent.
Element	getDOM() Gets the DOM representation of this XMLObject, if one exists.
QName	getElementQName() Gets the QName for this element.
IDIndex	getIDIndex() Get the IDIndex holding the ID-to-XMLObject index mapping, rooted at this XMLObject's subtree.
NamespaceManager	getNamespaceManager() Gets the NamespaceManager instance for this object.
Set<Namespace>	getNamespaces() Gets the namespaces that are scoped to this element.
String	getNoNamespaceSchemaLocation() Gets the value of the XML Schema noNamespaceSchemaLocation attribute for this object.
net.shibboleth.utilities.java.support.collection.LockableClassToInstanceMultiMap<Object>	getObjectMetadata() Get the mutable multimap which holds additional information (represented by plain Java object instances) associated with this XMLObject.
XMLObject	getParent() Gets the parent of this element or null if there is no parent.
String	getSchemaLocation() Gets the value of the XML Schema schemaLocation attribute for this object.
QName	getSchemaType() Gets the XML schema type of this element.
boolean	hasChildren() Checks if this XMLObject has children.
boolean	hasParent() Checks to see if this object has a parent.
Boolean	isNil() Gets whether the object declares that its element content is null, which corresponds to an xsi:nil attribute of true.
XSBooleanValue	isNilXSBoolean() Gets whether the object declares that its element content is null, which corresponds to an xsi:nil attribute of true.
protected void	manageQualifiedAttributeNamespace(QName attributeName, boolean hasValue) A helper function for derived classes.
protected QName	prepareAttributeValueForAssignment(String attributeID, QName oldValue, QName newValue) A helper function for derived classes.
protected QName	prepareElementContentForAssignment(QName oldValue, QName newValue) A helper function for derived classes.
protected String	prepareForAssignment(String oldValue, String newValue) A helper function for derived classes.
protected <T> T	prepareForAssignment(T oldValue, T newValue) A helper function for derived classes that checks to see if the old and new value are equal and if so releases the cached dom.
protected <T extends XMLObject> T	prepareForAssignment(T oldValue, T newValue) A helper function for derived classes, similar to assignString, but for (singleton) XML objects.
protected void	registerOwnID(String oldID, String newID) A helper function for derived classes.
void	releaseChildrenDOM(boolean propagateRelease) Releases the DOM representation of this XMLObject's children.
void	releaseDOM() Releases the DOM representation of this XMLObject, if there is one.
void	releaseParentDOM(boolean propagateRelease) Releases the DOM representation of this XMLObject's parent.
void	releaseThisAndChildrenDOM() A convenience method that is equal to calling releaseDOM() then releaseChildrenDOM(boolean) with the release being propagated.
void	releaseThisandParentDOM() A convenience method that is equal to calling releaseDOM() then releaseParentDOM(boolean) with the release being propagated.
XMLObject	resolveID(String id) Find the XMLObject identified by the specified ID attribute, within the subtree of XMLObjects which has this XMLObject as its root.
XMLObject	resolveIDFromRoot(String id) Find the XMLObject identified by the specified ID attribute, from the root of the tree of XMLObjects in which this XMLObject is a member.
void	setDOM(Element newDom) Sets the DOM representation of this XMLObject.
void	setElementNamespacePrefix(String prefix) Sets the prefix for this element's namespace.
protected void	setElementQName(QName name) Sets the element QName.
void	setNil(Boolean newNil) Sets whether the object declares that its element content is null, which corresponds to an xsi:nil attribute of true.
void	setNil(XSBooleanValue newNil) Sets whether the object declares that its element content is null, which corresponds to an xsi:nil attribute of true.
void	setNoNamespaceSchemaLocation(String location) Sets the value of the XML Schema noNamespaceSchemaLocation attribute for this object.
void	setParent(XMLObject newParent) Sets the parent of this element.
void	setSchemaLocation(String location) Sets the value of the XML Schema schemaLocation attribute for this object.
protected void	setSchemaType(QName type) Sets a given QName as the schema type for the Element represented by this XMLObject.

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.opensaml.core.xml.XMLObject

getOrderedChildren

Field Detail

log

@Nonnull
private final Logger log

Class logger.

parent

private XMLObject parent

Parent of this element.

elementQname

@Nonnull
private QName elementQname

The name of this element with namespace and prefix information.

schemaLocation

private String schemaLocation

Schema locations for this XML object.

noNamespaceSchemaLocation

private String noNamespaceSchemaLocation

No-namespace schema locations for this XML object.

typeQname

private QName typeQname

The schema type of this element with namespace and prefix information.

dom

private Element dom

DOM Element representation of this object.

nil

private XSBooleanValue nil

The value of the xsi:nil attribute.

nsManager

private NamespaceManager nsManager

The namespace manager for this XML object.

objectMetadata

@Nonnull
private final net.shibboleth.utilities.java.support.collection.LockableClassToInstanceMultiMap<Object> objectMetadata

The multimap holding class-indexed instances of additional info associated with this XML object.

idIndex

private final IDIndex idIndex

Mapping of ID attributes to XMLObjects in the subtree rooted at this object. This allows constant-time dereferencing of ID-typed attributes within the subtree.

Constructor Detail

AbstractXMLObject

protected AbstractXMLObject(@Nullable
                 String namespaceURI,
                 @Nonnull@NotEmpty
                 String elementLocalName,
                 @Nullable
                 String namespacePrefix)

Constructor.

Parameters:

namespaceURI - the namespace the element is in

elementLocalName - the local name of the XML element this Object represents

namespacePrefix - the prefix for the given namespace

Method Detail

detach

public void detach()

Detaches the XMLObject from its parent. This will release the parent's cached DOM (if it has one) and set this object's parent to null. It does not remove this object from its parent, that's the responsibility of the invoker of this method, nor does it re-root the cached DOM node (if there is one) in a new document. This is handled at marshalling time.

Specified by:

detach in interface XMLObject

getDOM

@Nullable
public Element getDOM()

Gets the DOM representation of this XMLObject, if one exists.

Specified by:

getDOM in interface XMLObject

Returns:

the DOM representation of this XMLObject, or null

getElementQName

@Nonnull
public QName getElementQName()

Gets the QName for this element. This QName MUST contain the namespace URI, namespace prefix, and local element name.

Specified by:

getElementQName in interface XMLObject

Returns:

the QName for this attribute

getIDIndex

@Nonnull
public IDIndex getIDIndex()

Get the IDIndex holding the ID-to-XMLObject index mapping, rooted at this XMLObject's subtree.

Specified by:

getIDIndex in interface XMLObject

Returns:

the IDIndex owned by this XMLObject

getNamespaceManager

@Nonnull
public NamespaceManager getNamespaceManager()

Gets the NamespaceManager instance for this object.

Specified by:

getNamespaceManager in interface XMLObject

Returns:

the namespace manager for this object

getNamespaces

@Nonnull
public Set<Namespace> getNamespaces()

Gets the namespaces that are scoped to this element.

Specified by:

getNamespaces in interface XMLObject

Returns:

the namespaces that are scoped to this element

getNoNamespaceSchemaLocation

@Nullable
public String getNoNamespaceSchemaLocation()

Gets the value of the XML Schema noNamespaceSchemaLocation attribute for this object.

Specified by:

getNoNamespaceSchemaLocation in interface XMLObject

Returns:

value of the XML Schema noNamespaceSchemaLocation attribute for this object

getParent

@Nullable
public XMLObject getParent()

Gets the parent of this element or null if there is no parent.

Specified by:

getParent in interface XMLObject

Returns:

the parent of this element or null

getSchemaLocation

@Nullable
public String getSchemaLocation()

Gets the value of the XML Schema schemaLocation attribute for this object.

Specified by:

getSchemaLocation in interface XMLObject

Returns:

schema location defined for this object

getSchemaType

@Nullable
public QName getSchemaType()

Gets the XML schema type of this element. This translates to the contents of the xsi:type attribute.

Specified by:

getSchemaType in interface XMLObject

Returns:

XML schema type of this element, or null

hasChildren

public boolean hasChildren()

Checks if this XMLObject has children.

Specified by:

hasChildren in interface XMLObject

Returns:

true if this XMLObject has children, false if not

hasParent

public boolean hasParent()

Checks to see if this object has a parent.

Specified by:

hasParent in interface XMLObject

Returns:

true if the object has a parent, false if not

manageQualifiedAttributeNamespace

protected void manageQualifiedAttributeNamespace(@Nonnull
                                     QName attributeName,
                                     boolean hasValue)

A helper function for derived classes. This method should be called when the value of a namespace-qualified attribute changes.

Parameters:

attributeName - the attribute name

hasValue - true to indicate that the attribute has a value, false to indicate it has no value

prepareElementContentForAssignment

@Nullable
protected QName prepareElementContentForAssignment(@Nullable
                                                QName oldValue,
                                                @Nullable
                                                QName newValue)

A helper function for derived classes. This checks for semantic equality between two QNames, and if they are different invalidates the DOM. It returns the normalized value so subclasses just have to use: this.foo = prepareElementContentForAssignment(this.foo, foo);

Parameters:

oldValue - - the current value

newValue - - the new value

Returns:

the value that should be assigned

prepareAttributeValueForAssignment

@Nullable
protected QName prepareAttributeValueForAssignment(@Nonnull
                                                String attributeID,
                                                @Nullable
                                                QName oldValue,
                                                @Nullable
                                                QName newValue)

A helper function for derived classes. This checks for semantic equality between two QNames and if they are different invalidates the DOM. It returns the normalized value so subclasses just have to use: this.foo = prepareAttributeValueForAssignment(this.foo, foo);

Parameters:

attributeID - - unique identifier of the attribute in the content model within this XMLObject, used to identify the attribute within the XMLObject's NamespaceManager

oldValue - - the current value

newValue - - the new value

Returns:

the value that should be assigned

prepareForAssignment

@Nullable
protected String prepareForAssignment(@Nullable
                                   String oldValue,
                                   @Nullable
                                   String newValue)

A helper function for derived classes. This 'normalizes' newString and then if it is different from oldString invalidates the DOM. It returns the normalized value so subclasses just have to use: this.foo = prepareForAssignment(this.foo, foo);

Parameters:

oldValue - - the current value

newValue - - the new value

Returns:

the value that should be assigned

prepareForAssignment

@Nullable
protected <T> T prepareForAssignment(@Nullable
                                  T oldValue,
                                  @Nullable
                                  T newValue)

A helper function for derived classes that checks to see if the old and new value are equal and if so releases the cached dom. Derived classes are expected to use this thus: this.foo = prepareForAssignment(this.foo, foo); This method will do a (null) safe compare of the objects and will also invalidate the DOM if appropriate

Type Parameters:

T - - type of object being compared and assigned

Parameters:

oldValue - - current value

newValue - - proposed new value

Returns:

The value to assign to the saved Object.

prepareForAssignment

@Nullable
protected <T extends XMLObject> T prepareForAssignment(@Nullable
                                                    T oldValue,
                                                    @Nullable
                                                    T newValue)

A helper function for derived classes, similar to assignString, but for (singleton) XML objects. It is indifferent to whether either the old or the new version of the value is null. Derived classes are expected to use this thus: this.foo = prepareForAssignment(this.foo, foo); This method will do a (null) safe compare of the objects and will also invalidate the DOM if appropriate

Type Parameters:

T - type of object being compared and assigned

Parameters:

oldValue - current value

newValue - proposed new value

Returns:

The value to assign to the saved Object.

registerOwnID

protected void registerOwnID(@Nullable
                 String oldID,
                 @Nullable
                 String newID)

A helper function for derived classes. The mutator/setter method for any ID-typed attributes should call this method in order to handle getting the old value removed from the ID-to-XMLObject mapping, and the new value added to the mapping.

Parameters:

oldID - the old value of the ID-typed attribute

newID - the new value of the ID-typed attribute

releaseChildrenDOM

public void releaseChildrenDOM(boolean propagateRelease)

Releases the DOM representation of this XMLObject's children.

Specified by:

releaseChildrenDOM in interface XMLObject

Parameters:

propagateRelease - true if all descendants of this element should release their DOM

releaseDOM

public void releaseDOM()

Releases the DOM representation of this XMLObject, if there is one.

Specified by:

releaseDOM in interface XMLObject

releaseParentDOM

public void releaseParentDOM(boolean propagateRelease)

Releases the DOM representation of this XMLObject's parent.

Specified by:

releaseParentDOM in interface XMLObject

Parameters:

propagateRelease - true if all ancestors of this element should release their DOM

releaseThisAndChildrenDOM

public void releaseThisAndChildrenDOM()

A convenience method that is equal to calling releaseDOM() then releaseChildrenDOM(boolean) with the release being propagated.

releaseThisandParentDOM

public void releaseThisandParentDOM()

A convenience method that is equal to calling releaseDOM() then releaseParentDOM(boolean) with the release being propagated.

resolveID

@Nullable
public XMLObject resolveID(@Nonnull@NotEmpty
                           String id)

Find the XMLObject identified by the specified ID attribute, within the subtree of XMLObjects which has this XMLObject as its root.

Specified by:

resolveID in interface XMLObject

Parameters:

id - the ID attribute to resolve to an XMLObject

Returns:

the XMLObject identified by the specified ID attribute value, or null

resolveIDFromRoot

@Nullable
public XMLObject resolveIDFromRoot(@Nonnull@NotEmpty
                                   String id)

Find the XMLObject identified by the specified ID attribute, from the root of the tree of XMLObjects in which this XMLObject is a member.

Specified by:

resolveIDFromRoot in interface XMLObject

Parameters:

id - the ID attribute to resolve to an XMLObject

Returns:

the XMLObject identified by the specified ID attribute value, or null

setDOM

public void setDOM(@Nullable
          Element newDom)

Sets the DOM representation of this XMLObject.

Specified by:

setDOM in interface XMLObject

Parameters:

newDom - DOM representation of this XMLObject

setElementNamespacePrefix

public void setElementNamespacePrefix(@Nullable
                             String prefix)

Sets the prefix for this element's namespace.

Parameters:

prefix - the prefix for this element's namespace

setElementQName

protected void setElementQName(@Nonnull
                   QName name)

Sets the element QName.

Parameters:

name - the element's QName

setNoNamespaceSchemaLocation

public void setNoNamespaceSchemaLocation(@Nullable
                                String location)

Sets the value of the XML Schema noNamespaceSchemaLocation attribute for this object.

Specified by:

setNoNamespaceSchemaLocation in interface XMLObject

Parameters:

location - value of the XML Schema noNamespaceSchemaLocation attribute for this object

setParent

public void setParent(@Nullable
             XMLObject newParent)

Sets the parent of this element.

Specified by:

setParent in interface XMLObject

Parameters:

newParent - the parent of this element

setSchemaLocation

public void setSchemaLocation(@Nullable
                     String location)

Sets the value of the XML Schema schemaLocation attribute for this object.

Specified by:

setSchemaLocation in interface XMLObject

Parameters:

location - value of the XML Schema schemaLocation attribute for this object

setSchemaType

protected void setSchemaType(@Nullable
                 QName type)

Sets a given QName as the schema type for the Element represented by this XMLObject. This will register the namespace for the type as well as for the xsi:type qualified attribute name with the namespace manager for this XMLObject. If null is passed, the type name and xsi:type name will be deregistered.

Parameters:

type - the schema type

isNil

public Boolean isNil()

Gets whether the object declares that its element content is null, which corresponds to an xsi:nil attribute of true.

Note that it is up to the developer to ensure that the value of this attribute is consistent with the actual element content on the object instance.

Per the XML Schema specification, a value of true disallows element content, but not element attributes.

Specified by:

isNil in interface XMLObject

Returns:

whether the object's content model is null

See Also:

isNilXSBoolean

public XSBooleanValue isNilXSBoolean()

Gets whether the object declares that its element content is null, which corresponds to an xsi:nil attribute of true.

Note that it is up to the developer to ensure that the value of this attribute is consistent with the actual element content on the object instance.

Per the XML Schema specification, a value of true disallows element content, but not element attributes.

Specified by:

isNilXSBoolean in interface XMLObject

Returns:

whether the object's content model is null

See Also:

setNil

public void setNil(@Nullable
          Boolean newNil)

Sets whether the object declares that its element content is null, which corresponds to an xsi:nil attribute of true.

Note that it is up to the developer to ensure that the value of this attribute is consistent with the actual element content on the object instance.

Per the XML Schema specification, a value of true disallows element content, but not element attributes.

Specified by:

setNil in interface XMLObject

Parameters:

newNil - whether the object's content model is expressed as null

See Also:

setNil

public void setNil(@Nullable
          XSBooleanValue newNil)

Sets whether the object declares that its element content is null, which corresponds to an xsi:nil attribute of true.

Note that it is up to the developer to ensure that the value of this attribute is consistent with the actual element content on the object instance.

Per the XML Schema specification, a value of true disallows element content, but not element attributes.

Specified by:

setNil in interface XMLObject

Parameters:

newNil - whether the object's content model is expressed as null

See Also:

getObjectMetadata

@Nonnull
public net.shibboleth.utilities.java.support.collection.LockableClassToInstanceMultiMap<Object> getObjectMetadata()

Get the mutable multimap which holds additional information (represented by plain Java object instances) associated with this XMLObject.

Objects added to this multimap will be indexed and retrievable by their concrete Class as well as by the Class types representing all superclasses (excluding java.lang.Object) and all implemented interfaces.

Specified by:

getObjectMetadata in interface XMLObject

Returns:

the class-to-instance multimap