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.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 }