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 }