Package org.opensaml.core.xml

Class AbstractXMLObject

    • Field Detail

      • log

        @Nonnull
private final org.slf4j.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.

      • nsManager

        private NamespaceManager nsManager
        The namespace manager for this XML object.

      • objectMetadata

        @Nonnull
private final 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

      • 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 String prepareForAssignment​(@Nullable
                                      String oldValue,
                                      @Nullable
                                      String newValue,
                                      boolean normalize)
        A helper function for derived classes. This 'normalizes' newString if normalize=true, and then if it is different from oldString invalidates the DOM. It returns the new effective value so subclasses just have to go. this.foo = prepareForAssignment(this.foo, foo);
        Parameters:
        oldValue - - the current value
        newValue - - the new value
        normalize - - whether the newValue should be normalized
        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:
        XML Schema: Nil Values

      • 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:
        XML Schema: Nil Values

      • 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:
        XML Schema: Nil Values

      • 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:
        XML Schema: Nil Values

      • getObjectMetadata

        @Nonnull
public 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