View Javadoc

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 }