1 /* 2 * Copyright [2005] [University Corporation for Advanced Internet Development, Inc.] 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package org.opensaml.xml; 18 19 import java.util.List; 20 import java.util.Set; 21 22 import javax.xml.namespace.QName; 23 24 import org.opensaml.xml.util.IDIndex; 25 import org.w3c.dom.Element; 26 27 /** 28 * A object that represents an XML element, usually of a specific schema type, that has been unmarshalled into this Java 29 * object. 30 */ 31 public interface XMLObject { 32 33 /** 34 * Adds a namespace to the ones already scoped to this element. 35 * 36 * @param namespace the namespace to add 37 */ 38 public void addNamespace(Namespace namespace); 39 40 /** 41 * Detaches the XMLObject from its parent. This will release the parent's cached DOM (if it has one) and set this 42 * object's parent to null. It does not remove this object from its parent, that's the responsibility of the invoker 43 * of this method, nor does it re-root the cached DOM node (if there is one) in a new document. This is handled at 44 * marshalling time. 45 */ 46 public void detach(); 47 48 /** 49 * Gets the DOM representation of this XMLObject, if one exists. 50 * 51 * @return the DOM representation of this XMLObject 52 */ 53 public Element getDOM(); 54 55 /** 56 * Gets the QName for this element. This QName <strong>MUST</strong> contain the namespace URI, namespace prefix, 57 * and local element name. Changes made to the returned QName are not reflected by the QName held by this element, 58 * that is, the returned QName is a copy of the internal QName member of this class. 59 * 60 * @return the QName for this attribute 61 */ 62 public QName getElementQName(); 63 64 /** 65 * Get the IDIndex holding the ID-to-XMLObject index mapping, rooted at this XMLObject's subtree. 66 * 67 * @return the IDIndex owned by this XMLObject 68 */ 69 public IDIndex getIDIndex(); 70 71 /** 72 * Gets the namespaces that are scoped to this element. 73 * 74 * @return the namespaces that are scoped to this element 75 */ 76 public Set<Namespace> getNamespaces(); 77 78 /** 79 * Gets the value of the XML Schema noNamespaceSchemaLocation attribute for this object. 80 * 81 * @return value of the XML Schema noNamespaceSchemaLocation attribute for this object 82 */ 83 public String getNoNamespaceSchemaLocation(); 84 85 /** 86 * Gets an unmodifiable list of child elements in the order that they will appear in the DOM. 87 * 88 * @return ordered list of child elements 89 */ 90 public List<XMLObject> getOrderedChildren(); 91 92 /** 93 * Gets the parent of this element or null if there is no parent. 94 * 95 * @return the parent of this element or null 96 */ 97 public XMLObject getParent(); 98 99 /** 100 * Gets the value of the XML Schema schemaLocation attribute for this object. 101 * 102 * @return schema location defined for this object 103 */ 104 public String getSchemaLocation(); 105 106 /** 107 * Gets the XML schema type of this element. This translates to contents the xsi:type attribute for the element. 108 * 109 * @return XML schema type of this element 110 */ 111 public QName getSchemaType(); 112 113 /** 114 * Checks if this XMLObject has children. 115 * 116 * @return true if this XMLObject has children, false if not 117 */ 118 public boolean hasChildren(); 119 120 /** 121 * Checks to see if this object has a parent. 122 * 123 * @return true if the object has a parent, false if not 124 */ 125 public boolean hasParent(); 126 127 /** 128 * Releases the DOM representation of this XMLObject's children. 129 * 130 * @param propagateRelease true if all descendants of this element should release their DOM 131 */ 132 public void releaseChildrenDOM(boolean propagateRelease); 133 134 /** 135 * Releases the DOM representation of this XMLObject, if there is one. 136 */ 137 public void releaseDOM(); 138 139 /** 140 * Releases the DOM representation of this XMLObject's parent. 141 * 142 * @param propagateRelease true if all ancestors of this element should release their DOM 143 */ 144 public void releaseParentDOM(boolean propagateRelease); 145 146 /** 147 * Removes a namespace from this element. 148 * 149 * @param namespace the namespace to remove 150 */ 151 public void removeNamespace(Namespace namespace); 152 153 /** 154 * Find the XMLObject which is identified by the specified ID attribute, within the subtree of XMLObjects which has 155 * this XMLObject as its root. 156 * 157 * @param id the ID attribute to resolve to an XMLObject 158 * @return the XMLObject identified by the specified ID attribute value 159 */ 160 public XMLObject resolveID(String id); 161 162 /** 163 * Find the XMLObject which is identified by the specified ID attribute, from the root of the tree of XMLObjects in 164 * which this XMLObject is a member. 165 * 166 * @param id the ID attribute to resolve to an XMLObject 167 * @return the XMLObject identified by the specified ID attribute value 168 */ 169 public XMLObject resolveIDFromRoot(String id); 170 171 /** 172 * Sets the DOM representation of this XMLObject. 173 * 174 * @param dom DOM representation of this XMLObject 175 */ 176 public void setDOM(Element dom); 177 178 /** 179 * Sets the value of the XML Schema noNamespaceSchemaLocation attribute for this object. 180 * 181 * @param location value of the XML Schema noNamespaceSchemaLocation attribute for this object 182 */ 183 public void setNoNamespaceSchemaLocation(String location); 184 185 /** 186 * Sets the parent of this element. 187 * 188 * @param parent the parent of this element 189 */ 190 public void setParent(XMLObject parent); 191 192 /** 193 * Sets the value of the XML Schema schemaLocation attribute for this object. 194 * 195 * @param location value of the XML Schema schemaLocation attribute for this object 196 */ 197 public void setSchemaLocation(String location); 198 199 }