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.schema.XSBooleanValue; 25 import org.opensaml.xml.util.IDIndex; 26 import org.w3c.dom.Element; 27 28 /** 29 * A object that represents an XML element, usually of a specific schema type, that has been unmarshalled into this Java 30 * object. 31 */ 32 public interface XMLObject { 33 34 /** 35 * Adds a namespace to the ones already scoped to this element. 36 * 37 * @deprecated use appropriate methods on the XMLObject's {@link NamespaceManager}. 38 * 39 * @param namespace the namespace to add 40 */ 41 public void addNamespace(Namespace namespace); 42 43 /** 44 * Detaches the XMLObject from its parent. This will release the parent's cached DOM (if it has one) and set this 45 * object's parent to null. It does not remove this object from its parent, that's the responsibility of the invoker 46 * of this method, nor does it re-root the cached DOM node (if there is one) in a new document. This is handled at 47 * marshalling time. 48 */ 49 public void detach(); 50 51 /** 52 * Gets the DOM representation of this XMLObject, if one exists. 53 * 54 * @return the DOM representation of this XMLObject 55 */ 56 public Element getDOM(); 57 58 /** 59 * Gets the QName for this element. This QName <strong>MUST</strong> contain the namespace URI, namespace prefix, 60 * and local element name. Changes made to the returned QName are not reflected by the QName held by this element, 61 * that is, the returned QName is a copy of the internal QName member of this class. 62 * 63 * @return the QName for this attribute 64 */ 65 public QName getElementQName(); 66 67 /** 68 * Get the IDIndex holding the ID-to-XMLObject index mapping, rooted at this XMLObject's subtree. 69 * 70 * @return the IDIndex owned by this XMLObject 71 */ 72 public IDIndex getIDIndex(); 73 74 /** 75 * Gets the {@link NamespaceManager} instance for this object. 76 * 77 * @return the namespace manager for this object 78 */ 79 public NamespaceManager getNamespaceManager(); 80 81 /** 82 * Gets the namespaces that are scoped to this element. 83 * 84 * @return the namespaces that are scoped to this element 85 */ 86 public Set<Namespace> getNamespaces(); 87 88 /** 89 * Gets the value of the XML Schema noNamespaceSchemaLocation attribute for this object. 90 * 91 * @return value of the XML Schema noNamespaceSchemaLocation attribute for this object 92 */ 93 public String getNoNamespaceSchemaLocation(); 94 95 /** 96 * Gets an unmodifiable list of child elements in the order that they will appear in the DOM. 97 * 98 * @return ordered list of child elements 99 */ 100 public List<XMLObject> getOrderedChildren(); 101 102 /** 103 * Gets the parent of this element or null if there is no parent. 104 * 105 * @return the parent of this element or null 106 */ 107 public XMLObject getParent(); 108 109 /** 110 * Gets the value of the XML Schema schemaLocation attribute for this object. 111 * 112 * @return schema location defined for this object 113 */ 114 public String getSchemaLocation(); 115 116 /** 117 * Gets the XML schema type of this element. This translates to contents the xsi:type attribute for the element. 118 * 119 * @return XML schema type of this element 120 */ 121 public QName getSchemaType(); 122 123 /** 124 * Checks if this XMLObject has children. 125 * 126 * @return true if this XMLObject has children, false if not 127 */ 128 public boolean hasChildren(); 129 130 /** 131 * Checks to see if this object has a parent. 132 * 133 * @return true if the object has a parent, false if not 134 */ 135 public boolean hasParent(); 136 137 /** 138 * Releases the DOM representation of this XMLObject's children. 139 * 140 * @param propagateRelease true if all descendants of this element should release their DOM 141 */ 142 public void releaseChildrenDOM(boolean propagateRelease); 143 144 /** 145 * Releases the DOM representation of this XMLObject, if there is one. 146 */ 147 public void releaseDOM(); 148 149 /** 150 * Releases the DOM representation of this XMLObject's parent. 151 * 152 * @param propagateRelease true if all ancestors of this element should release their DOM 153 */ 154 public void releaseParentDOM(boolean propagateRelease); 155 156 /** 157 * Removes a namespace from this element. 158 * 159 * @deprecated use appropriate methods on the XMLObject's {@link NamespaceManager}. 160 * 161 * @param namespace the namespace to remove 162 */ 163 public void removeNamespace(Namespace namespace); 164 165 /** 166 * Find the XMLObject which is identified by the specified ID attribute, within the subtree of XMLObjects which has 167 * this XMLObject as its root. 168 * 169 * @param id the ID attribute to resolve to an XMLObject 170 * @return the XMLObject identified by the specified ID attribute value 171 */ 172 public XMLObject resolveID(String id); 173 174 /** 175 * Find the XMLObject which is identified by the specified ID attribute, from the root of the tree of XMLObjects in 176 * which this XMLObject is a member. 177 * 178 * @param id the ID attribute to resolve to an XMLObject 179 * @return the XMLObject identified by the specified ID attribute value 180 */ 181 public XMLObject resolveIDFromRoot(String id); 182 183 /** 184 * Sets the DOM representation of this XMLObject. 185 * 186 * @param dom DOM representation of this XMLObject 187 */ 188 public void setDOM(Element dom); 189 190 /** 191 * Sets the value of the XML Schema noNamespaceSchemaLocation attribute for this object. 192 * 193 * @param location value of the XML Schema noNamespaceSchemaLocation attribute for this object 194 */ 195 public void setNoNamespaceSchemaLocation(String location); 196 197 /** 198 * Sets the parent of this element. 199 * 200 * @param parent the parent of this element 201 */ 202 public void setParent(XMLObject parent); 203 204 /** 205 * Sets the value of the XML Schema schemaLocation attribute for this object. 206 * 207 * @param location value of the XML Schema schemaLocation attribute for this object 208 */ 209 public void setSchemaLocation(String location); 210 211 /** 212 * Gets whether the object declares that its element content 213 * is null, which corresponds to an <code>xsi:nil</code> 214 * attribute of <code>true</code>. 215 * 216 * <p> 217 * Note that it is up to the developer to ensure that the 218 * value of this attribute is consistent with the actual 219 * element content on the object instance. 220 * </p> 221 * 222 * <p> 223 * Per the XML Schema specification, a value of true disallows 224 * element content, but not element attributes. 225 * </p> 226 * 227 * @see <a href="http://www.w3.org/TR/xmlschema-0/#Nils"/> 228 * 229 * @return whether the object's content model is null 230 */ 231 public Boolean isNil(); 232 233 /** 234 * 235 * Gets whether the object declares that its element content 236 * is null, which corresponds to an <code>xsi:nil</code> 237 * attribute of <code>true</code>. 238 * 239 * <p> 240 * Note that it is up to the developer to ensure that the 241 * value of this attribute is consistent with the actual 242 * element content on the object instance. 243 * </p> 244 * 245 * <p> 246 * Per the XML Schema specification, a value of true disallows 247 * element content, but not element attributes. 248 * </p> 249 * 250 * @see <a href="http://www.w3.org/TR/xmlschema-0/#Nils/> 251 * 252 * @return whether the object's content model is null 253 */ 254 public XSBooleanValue isNilXSBoolean(); 255 256 /** 257 * Sets whether the object declares that its element content 258 * is null, which corresponds to an <code>xsi:nil</code> 259 * attribute of <code>true</code>. 260 * 261 * <p> 262 * Note that it is up to the developer to ensure that the 263 * value of this attribute is consistent with the actual 264 * element content on the object instance. 265 * </p> 266 * 267 * <p> 268 * Per the XML Schema specification, a value of true disallows 269 * element content, but not element attributes. 270 * </p> 271 * 272 * @see <a href="http://www.w3.org/TR/xmlschema-0/#Nils/> 273 * 274 * @param newNil whether the object's content model is expressed as null 275 */ 276 public void setNil(Boolean newNil); 277 278 /** 279 * Sets whether the object declares that its element content 280 * is null, which corresponds to an <code>xsi:nil</code> 281 * attribute of <code>true</code>. 282 * 283 * <p> 284 * Note that it is up to the developer to ensure that the 285 * value of this attribute is consistent with the actual 286 * element content on the object instance. 287 * </p> 288 * 289 * <p> 290 * Per the XML Schema specification, a value of true disallows 291 * element content, but not element attributes. 292 * </p> 293 * 294 * @see <a href="http://www.w3.org/TR/xmlschema-0/#Nils/> 295 * 296 * @param newNil whether the object's content model is expressed as null 297 */ 298 public void setNil(XSBooleanValue newNil); 299 300 }