001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one
003: * or more contributor license agreements. See the NOTICE file
004: * distributed with this work for additional information
005: * regarding copyright ownership. The ASF licenses this file
006: * to you under the Apache License, Version 2.0 (the
007: * "License"); you may not use this file except in compliance
008: * with the License. You may obtain a copy of the License at
009: *
010: * http://www.apache.org/licenses/LICENSE-2.0
011: *
012: * Unless required by applicable law or agreed to in writing,
013: * software distributed under the License is distributed on an
014: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015: * KIND, either express or implied. See the License for the
016: * specific language governing permissions and limitations
017: * under the License.
018: */
019: package javax.xml.soap;
020:
021: import javax.xml.namespace.QName;
022: import java.util.Iterator;
023:
024: /**
025: * An object representing the contents in a <code>SOAPBody</code> object, the contents in a
026: * <code>SOAPHeader</code> object, the content that can follow the <code>SOAPBody</code> object in a
027: * <code>SOAPEnvelope</code> object, or what can follow the detail element in a
028: * <code>SOAPFault</code> object. It is the base class for all of the classes that represent the
029: * SOAP objects as defined in the SOAP specification.
030: */
031: public interface SOAPElement extends javax.xml.soap.Node,
032: org.w3c.dom.Element {
033:
034: /**
035: * Creates a new <code>SOAPElement</code> object initialized with the given <code>Name</code>
036: * object and adds the new element to this <code>SOAPElement</code> object.
037: *
038: * @param name a <code>Name</code> object with the XML name for the new element
039: * @return the new <code>SOAPElement</code> object that was created
040: * @throws SOAPException if there is an error in creating the <code>SOAPElement</code> object
041: */
042: public abstract SOAPElement addChildElement(Name name)
043: throws SOAPException;
044:
045: /**
046: * Creates a new <code>SOAPElement</code> object initialized with the given <code>String</code>
047: * object and adds the new element to this <code>SOAPElement</code> object.
048: *
049: * @param localName a <code>String</code> giving the local name for the element
050: * @return the new <code>SOAPElement</code> object that was created
051: * @throws SOAPException if there is an error in creating the <code>SOAPElement</code> object
052: */
053: public abstract SOAPElement addChildElement(String localName)
054: throws SOAPException;
055:
056: /**
057: * Creates a new <code>SOAPElement</code> object initialized with the specified local name and
058: * prefix and adds the new element to this <code>SOAPElement</code> object.
059: *
060: * @param localName a <code>String</code> giving the local name for the new element
061: * @param prefix a <code>String</code> giving the namespace prefix for the new element
062: * @return the new <code>SOAPElement</code> object that was created
063: * @throws SOAPException if there is an error in creating the <code>SOAPElement</code> object
064: */
065: public abstract SOAPElement addChildElement(String localName,
066: String prefix) throws SOAPException;
067:
068: /**
069: * Creates a new <code>SOAPElement</code> object initialized with the specified local name,
070: * prefix, and URI and adds the new element to this <code>SOAPElement</code> object.
071: *
072: * @param localName a <code>String</code> giving the local name for the new element
073: * @param prefix a <code>String</code> giving the namespace prefix for the new element
074: * @param uri a <code>String</code> giving the URI of the namespace to which the new
075: * element belongs
076: * @return the new <code>SOAPElement</code> object that was created
077: * @throws SOAPException if there is an error in creating the <code>SOAPElement</code> object
078: */
079: public abstract SOAPElement addChildElement(String localName,
080: String prefix, String uri) throws SOAPException;
081:
082: /**
083: * Add a <code>SOAPElement</code> as a child of this <code>SOAPElement</code> instance. The
084: * <code>SOAPElement</code> is expected to be created by a <code>SOAPElementFactory</code>.
085: * Callers should not rely on the element instance being added as is into the XML tree.
086: * Implementations could end up copying the content of the <code>SOAPElement</code> passed into
087: * an instance of a different <code>SOAPElement</code> implementation. For instance if
088: * <code>addChildElement()</code> is called on a <code>SOAPHeader</code>, <code>element</code>
089: * will be copied into an instance of a <code>SOAPHeaderElement</code>.
090: * <p/>
091: * <P>The fragment rooted in <code>element</code> is either added as a whole or not at all, if
092: * there was an error.
093: * <p/>
094: * <P>The fragment rooted in <code>element</code> cannot contain elements named "Envelope",
095: * "Header" or "Body" and in the SOAP namespace. Any namespace prefixes present in the fragment
096: * should be fully resolved using appropriate namespace declarations within the fragment
097: * itself.
098: *
099: * @param element the <code>SOAPElement</code> to be added as a new child
100: * @return an instance representing the new SOAP element that was actually added to the tree.
101: * @throws SOAPException if there was an error in adding this element as a child
102: */
103: public abstract SOAPElement addChildElement(SOAPElement element)
104: throws SOAPException;
105:
106: /**
107: * Creates a new <code>Text</code> object initialized with the given <code>String</code> and
108: * adds it to this <code>SOAPElement</code> object.
109: *
110: * @param text a <code>String</code> object with the textual content to be added
111: * @return the <code>SOAPElement</code> object into which the new <code>Text</code> object was
112: * inserted
113: * @throws SOAPException if there is an error in creating the new <code>Text</code> object
114: */
115: public abstract SOAPElement addTextNode(String text)
116: throws SOAPException;
117:
118: /**
119: * Adds an attribute with the specified name and value to this <code>SOAPElement</code> object.
120: * <p/>
121: *
122: * @param name a <code>Name</code> object with the name of the attribute
123: * @param value a <code>String</code> giving the value of the attribute
124: * @return the <code>SOAPElement</code> object into which the attribute was inserted
125: * @throws SOAPException if there is an error in creating the Attribute
126: */
127: public abstract SOAPElement addAttribute(Name name, String value)
128: throws SOAPException;
129:
130: /**
131: * Adds a namespace declaration with the specified prefix and URI to this
132: * <code>SOAPElement</code> object.
133: * <p/>
134: *
135: * @param prefix a <code>String</code> giving the prefix of the namespace
136: * @param uri a <CODE>String</CODE> giving the prefix of the namespace
137: * @return the <code>SOAPElement</code> object into which this namespace declaration was
138: * inserted.
139: * @throws SOAPException if there is an error in creating the namespace
140: */
141: public abstract SOAPElement addNamespaceDeclaration(String prefix,
142: String uri) throws SOAPException;
143:
144: /**
145: * Returns the value of the attribute with the specified name.
146: *
147: * @param name a <CODE>Name</CODE> object with the name of the attribute
148: * @return a <CODE>String</CODE> giving the value of the specified attribute
149: */
150: public abstract String getAttributeValue(Name name);
151:
152: /**
153: * Returns an iterator over all of the attribute names in this <CODE>SOAPElement</CODE> object.
154: * The iterator can be used to get the attribute names, which can then be passed to the method
155: * <CODE>getAttributeValue</CODE> to retrieve the value of each attribute.
156: *
157: * @return an iterator over the names of the attributes
158: */
159: public abstract Iterator getAllAttributes();
160:
161: /**
162: * Returns the URI of the namespace that has the given prefix.
163: *
164: * @param prefix a <CODE>String</CODE> giving the prefix of the namespace for which to search
165: * @return a <CODE>String</CODE> with the uri of the namespace that has the given prefix
166: */
167: public abstract String getNamespaceURI(String prefix);
168:
169: /**
170: * Returns an iterator of namespace prefixes. The iterator can be used to get the namespace
171: * prefixes, which can then be passed to the method <CODE>getNamespaceURI</CODE> to retrieve the
172: * URI of each namespace.
173: *
174: * @return an iterator over the namespace prefixes in this <CODE>SOAPElement</CODE> object
175: */
176: public abstract Iterator getNamespacePrefixes();
177:
178: /**
179: * Returns the name of this <CODE>SOAPElement</CODE> object.
180: *
181: * @return a <CODE>Name</CODE> object with the name of this <CODE>SOAPElement</CODE> object
182: */
183: public abstract Name getElementName();
184:
185: /**
186: * Removes the attribute with the specified name.
187: *
188: * @param name the <CODE>Name</CODE> object with the name of the attribute to be removed
189: * @return <CODE>true</CODE> if the attribute was removed successfully; <CODE>false</CODE> if it
190: * was not
191: */
192: public abstract boolean removeAttribute(Name name);
193:
194: /**
195: * Removes the namespace declaration corresponding to the given prefix.
196: *
197: * @param prefix a <CODE>String</CODE> giving the prefix for which to search
198: * @return <CODE>true</CODE> if the namespace declaration was removed successfully;
199: * <CODE>false</CODE> if it was not
200: */
201: public abstract boolean removeNamespaceDeclaration(String prefix);
202:
203: /**
204: * Returns an iterator over all the immediate content of this element. This includes
205: * <CODE>Text</CODE> objects as well as <CODE>SOAPElement</CODE> objects.
206: *
207: * @return an iterator with the content of this <CODE> SOAPElement</CODE> object
208: */
209: public abstract Iterator getChildElements();
210:
211: /**
212: * Returns an iterator over all the child elements with the specified name.
213: *
214: * @param name a <CODE>Name</CODE> object with the name of the child elements to be returned
215: * @return an <CODE>Iterator</CODE> object over all the elements in this
216: * <CODE>SOAPElement</CODE> object with the specified name
217: */
218: public abstract Iterator getChildElements(Name name);
219:
220: /**
221: * Sets the encoding style for this <CODE>SOAPElement</CODE> object to one specified.
222: *
223: * @param encodingStyle a <CODE>String</CODE> giving the encoding style
224: * @throws IllegalArgumentException
225: * if there was a problem in the encoding style being set.
226: * @see #getEncodingStyle() getEncodingStyle()
227: */
228: public abstract void setEncodingStyle(String encodingStyle)
229: throws SOAPException;
230:
231: /**
232: * Returns the encoding style for this <CODE> SOAPElement</CODE> object.
233: *
234: * @return a <CODE>String</CODE> giving the encoding style
235: * @see #setEncodingStyle(String) setEncodingStyle(java.lang.String)
236: */
237: public abstract String getEncodingStyle();
238:
239: /**
240: * Detaches all children of this <code>SOAPElement</code>.
241: * <p/>
242: * This method is useful for rolling back the construction of partially completed
243: * <code>SOAPHeaders</code> and <code>SOAPBodys</code> in reparation for sending a fault when an
244: * error condition is detected. It is also useful for recycling portions of a document within a
245: * SOAP message.
246: */
247: public abstract void removeContents();
248:
249: /**
250: * Returns an <code>Iterator</code> over the namespace prefix <code>String</code>s visible to
251: * this element. The prefixes returned by this iterator can be passed to the method
252: * <code>getNamespaceURI()</code> to retrieve the URI of each namespace.
253: *
254: * @return an iterator over the namespace prefixes are within scope of this
255: * <code>SOAPElement</code> object
256: */
257: public abstract Iterator getVisibleNamespacePrefixes();
258:
259: public abstract SOAPElement addAttribute(
260: javax.xml.namespace.QName qname, java.lang.String value)
261: throws SOAPException;
262:
263: public abstract SOAPElement addChildElement(
264: javax.xml.namespace.QName qname) throws SOAPException;
265:
266: public abstract javax.xml.namespace.QName createQName(
267: String localName, String prefix) throws SOAPException;
268:
269: public abstract java.util.Iterator getAllAttributesAsQNames();
270:
271: public abstract java.lang.String getAttributeValue(
272: javax.xml.namespace.QName qname);
273:
274: public abstract java.util.Iterator getChildElements(QName name);
275:
276: public abstract javax.xml.namespace.QName getElementQName();
277:
278: boolean removeAttribute(javax.xml.namespace.QName qname);
279:
280: public abstract SOAPElement setElementQName(
281: javax.xml.namespace.QName newName) throws SOAPException;
282: }
|