001: /*
002: * $Id: SOAPElement.java,v 1.20 2006/03/30 00:59:40 ofung Exp $
003: * $Revision: 1.20 $
004: * $Date: 2006/03/30 00:59:40 $
005: */
006:
007: /*
008: * The contents of this file are subject to the terms
009: * of the Common Development and Distribution License
010: * (the License). You may not use this file except in
011: * compliance with the License.
012: *
013: * You can obtain a copy of the license at
014: * https://glassfish.dev.java.net/public/CDDLv1.0.html.
015: * See the License for the specific language governing
016: * permissions and limitations under the License.
017: *
018: * When distributing Covered Code, include this CDDL
019: * Header Notice in each file and include the License file
020: * at https://glassfish.dev.java.net/public/CDDLv1.0.html.
021: * If applicable, add the following below the CDDL Header,
022: * with the fields enclosed by brackets [] replaced by
023: * you own identifying information:
024: * "Portions Copyrighted [year] [name of copyright owner]"
025: *
026: * Copyright 2006 Sun Microsystems Inc. All Rights Reserved
027: */
028: package javax.xml.soap;
029:
030: import java.util.Iterator;
031:
032: import javax.xml.namespace.QName;
033:
034: /**
035: * An object representing an element of a SOAP message that is allowed but not
036: * specifically prescribed by a SOAP specification. This interface serves as the
037: * base interface for those objects that are specifically prescribed by a SOAP
038: * specification.
039: * <p>
040: * Methods in this interface that are required to return SAAJ specific objects
041: * may "silently" replace nodes in the tree as required to successfully return
042: * objects of the correct type. See {@link #getChildElements()} and
043: * {@link <a HREF="package-summary.html#package_description">javax.xml.soap<a>}
044: * for details.
045: */
046: public interface SOAPElement extends Node, org.w3c.dom.Element {
047:
048: /**
049: * Creates a new <code>SOAPElement</code> object initialized with the
050: * given <code>Name</code> object and adds the new element to this
051: * <code>SOAPElement</code> object.
052: * <P>
053: * This method may be deprecated in a future release of SAAJ in favor of
054: * addChildElement(javax.xml.namespace.QName)
055: *
056: * @param name a <code>Name</code> object with the XML name for the
057: * new element
058: *
059: * @return the new <code>SOAPElement</code> object that was created
060: * @exception SOAPException if there is an error in creating the
061: * <code>SOAPElement</code> object
062: * @see SOAPElement#addChildElement(javax.xml.namespace.QName)
063: */
064: public SOAPElement addChildElement(Name name) throws SOAPException;
065:
066: /**
067: * Creates a new <code>SOAPElement</code> object initialized with the given
068: * <code>QName</code> object and adds the new element to this <code>SOAPElement</code>
069: * object. The <i>namespace</i>, <i>localname</i> and <i>prefix</i> of the new
070: * <code>SOAPElement</code> are all taken from the <code>qname</code> argument.
071: *
072: * @param qname a <code>QName</code> object with the XML name for the
073: * new element
074: *
075: * @return the new <code>SOAPElement</code> object that was created
076: * @exception SOAPException if there is an error in creating the
077: * <code>SOAPElement</code> object
078: * @see SOAPElement#addChildElement(Name)
079: * @since SAAJ 1.3
080: */
081: public SOAPElement addChildElement(QName qname)
082: throws SOAPException;
083:
084: /**
085: * Creates a new <code>SOAPElement</code> object initialized with the
086: * specified local name and adds the new element to this
087: * <code>SOAPElement</code> object.
088: * The new <code>SOAPElement</code> inherits any in-scope default namespace.
089: *
090: * @param localName a <code>String</code> giving the local name for
091: * the element
092: * @return the new <code>SOAPElement</code> object that was created
093: * @exception SOAPException if there is an error in creating the
094: * <code>SOAPElement</code> object
095: */
096: public SOAPElement addChildElement(String localName)
097: throws SOAPException;
098:
099: /**
100: * Creates a new <code>SOAPElement</code> object initialized with the
101: * specified local name and prefix and adds the new element to this
102: * <code>SOAPElement</code> object.
103: *
104: * @param localName a <code>String</code> giving the local name for
105: * the new element
106: * @param prefix a <code>String</code> giving the namespace prefix for
107: * the new element
108: *
109: * @return the new <code>SOAPElement</code> object that was created
110: * @exception SOAPException if the <code>prefix</code> is not valid in the
111: * context of this <code>SOAPElement</code> or if there is an error in creating the
112: * <code>SOAPElement</code> object
113: */
114: public SOAPElement addChildElement(String localName, String prefix)
115: throws SOAPException;
116:
117: /**
118: * Creates a new <code>SOAPElement</code> object initialized with the
119: * specified local name, prefix, and URI and adds the new element to this
120: * <code>SOAPElement</code> object.
121: *
122: * @param localName a <code>String</code> giving the local name for
123: * the new element
124: * @param prefix a <code>String</code> giving the namespace prefix for
125: * the new element
126: * @param uri a <code>String</code> giving the URI of the namespace
127: * to which the new element belongs
128: *
129: * @return the new <code>SOAPElement</code> object that was created
130: * @exception SOAPException if there is an error in creating the
131: * <code>SOAPElement</code> object
132: */
133: public SOAPElement addChildElement(String localName, String prefix,
134: String uri) throws SOAPException;
135:
136: /**
137: * Add a <code>SOAPElement</code> as a child of this
138: * <code>SOAPElement</code> instance. The <code>SOAPElement</code>
139: * is expected to be created by a
140: * <code>SOAPFactory</code>. Callers should not rely on the
141: * element instance being added as is into the XML
142: * tree. Implementations could end up copying the content
143: * of the <code>SOAPElement</code> passed into an instance of
144: * a different <code>SOAPElement</code> implementation. For
145: * instance if <code>addChildElement()</code> is called on a
146: * <code>SOAPHeader</code>, <code>element</code> will be copied
147: * into an instance of a <code>SOAPHeaderElement</code>.
148: *
149: * <P>The fragment rooted in <code>element</code> is either added
150: * as a whole or not at all, if there was an error.
151: *
152: * <P>The fragment rooted in <code>element</code> cannot contain
153: * elements named "Envelope", "Header" or "Body" and in the SOAP
154: * namespace. Any namespace prefixes present in the fragment
155: * should be fully resolved using appropriate namespace
156: * declarations within the fragment itself.
157: *
158: * @param element the <code>SOAPElement</code> to be added as a
159: * new child
160: *
161: * @exception SOAPException if there was an error in adding this
162: * element as a child
163: *
164: * @return an instance representing the new SOAP element that was
165: * actually added to the tree.
166: */
167: public SOAPElement addChildElement(SOAPElement element)
168: throws SOAPException;
169:
170: /**
171: * Detaches all children of this <code>SOAPElement</code>.
172: * <p>
173: * This method is useful for rolling back the construction of partially
174: * completed <code>SOAPHeaders</code> and <code>SOAPBodys</code> in
175: * preparation for sending a fault when an error condition is detected. It
176: * is also useful for recycling portions of a document within a SOAP
177: * message.
178: *
179: * @since SAAJ 1.2
180: */
181: public abstract void removeContents();
182:
183: /**
184: * Creates a new <code>Text</code> object initialized with the given
185: * <code>String</code> and adds it to this <code>SOAPElement</code> object.
186: *
187: * @param text a <code>String</code> object with the textual content to be added
188: *
189: * @return the <code>SOAPElement</code> object into which
190: * the new <code>Text</code> object was inserted
191: * @exception SOAPException if there is an error in creating the
192: * new <code>Text</code> object or if it is not legal to
193: * attach it as a child to this
194: * <code>SOAPElement</code>
195: */
196: public SOAPElement addTextNode(String text) throws SOAPException;
197:
198: /**
199: * Adds an attribute with the specified name and value to this
200: * <code>SOAPElement</code> object.
201: *
202: * @param name a <code>Name</code> object with the name of the attribute
203: * @param value a <code>String</code> giving the value of the attribute
204: * @return the <code>SOAPElement</code> object into which the attribute was
205: * inserted
206: *
207: * @exception SOAPException if there is an error in creating the
208: * Attribute, or it is invalid to set
209: an attribute with <code>Name</code>
210: <code>name</code> on this SOAPElement.
211: * @see SOAPElement#addAttribute(javax.xml.namespace.QName, String)
212: */
213: public SOAPElement addAttribute(Name name, String value)
214: throws SOAPException;
215:
216: /**
217: * Adds an attribute with the specified name and value to this
218: * <code>SOAPElement</code> object.
219: *
220: * @param qname a <code>QName</code> object with the name of the attribute
221: * @param value a <code>String</code> giving the value of the attribute
222: * @return the <code>SOAPElement</code> object into which the attribute was
223: * inserted
224: *
225: * @exception SOAPException if there is an error in creating the
226: * Attribute, or it is invalid to set
227: an attribute with <code>QName</code>
228: <code>qname</code> on this SOAPElement.
229: * @see SOAPElement#addAttribute(Name, String)
230: * @since SAAJ 1.3
231: */
232: public SOAPElement addAttribute(QName qname, String value)
233: throws SOAPException;
234:
235: /**
236: * Adds a namespace declaration with the specified prefix and URI to this
237: * <code>SOAPElement</code> object.
238: *
239: * @param prefix a <code>String</code> giving the prefix of the namespace
240: * @param uri a <code>String</code> giving the uri of the namespace
241: * @return the <code>SOAPElement</code> object into which this
242: * namespace declaration was inserted.
243: *
244: * @exception SOAPException if there is an error in creating the
245: * namespace
246: */
247: public SOAPElement addNamespaceDeclaration(String prefix, String uri)
248: throws SOAPException;
249:
250: /**
251: * Returns the value of the attribute with the specified name.
252: *
253: * @param name a <code>Name</code> object with the name of the attribute
254: * @return a <code>String</code> giving the value of the specified
255: * attribute, Null if there is no such attribute
256: * @see SOAPElement#getAttributeValue(javax.xml.namespace.QName)
257: */
258: public String getAttributeValue(Name name);
259:
260: /**
261: * Returns the value of the attribute with the specified qname.
262: *
263: * @param qname a <code>QName</code> object with the qname of the attribute
264: * @return a <code>String</code> giving the value of the specified
265: * attribute, Null if there is no such attribute
266: * @see SOAPElement#getAttributeValue(Name)
267: * @since SAAJ 1.3
268: */
269: public String getAttributeValue(QName qname);
270:
271: /**
272: * Returns an <code>Iterator</code> over all of the attribute
273: * <code>Name</code> objects in this
274: * <code>SOAPElement</code> object. The iterator can be used to get
275: * the attribute names, which can then be passed to the method
276: * <code>getAttributeValue</code> to retrieve the value of each
277: * attribute.
278: *
279: * @see SOAPElement#getAllAttributesAsQNames()
280: * @return an iterator over the names of the attributes
281: */
282: public Iterator getAllAttributes();
283:
284: /**
285: * Returns an <code>Iterator</code> over all of the attributes
286: * in this <code>SOAPElement</code> as <code>QName</code> objects.
287: * The iterator can be used to get the attribute QName, which can then
288: * be passed to the method <code>getAttributeValue</code> to retrieve
289: * the value of each attribute.
290: *
291: * @return an iterator over the QNames of the attributes
292: * @see SOAPElement#getAllAttributes()
293: * @since SAAJ 1.3
294: */
295: public Iterator getAllAttributesAsQNames();
296:
297: /**
298: * Returns the URI of the namespace that has the given prefix.
299: *
300: * @param prefix a <code>String</code> giving the prefix of the namespace
301: * for which to search
302: * @return a <code>String</code> with the uri of the namespace that has
303: * the given prefix
304: */
305: public String getNamespaceURI(String prefix);
306:
307: /**
308: * Returns an <code>Iterator</code> over the namespace prefix
309: * <code>String</code>s declared by this element. The prefixes returned by
310: * this iterator can be passed to the method
311: * <code>getNamespaceURI</code> to retrieve the URI of each namespace.
312: *
313: * @return an iterator over the namespace prefixes in this
314: * <code>SOAPElement</code> object
315: */
316: public Iterator getNamespacePrefixes();
317:
318: /**
319: * Returns an <code>Iterator</code> over the namespace prefix
320: * <code>String</code>s visible to this element. The prefixes returned by
321: * this iterator can be passed to the method
322: * <code>getNamespaceURI</code> to retrieve the URI of each namespace.
323: *
324: * @return an iterator over the namespace prefixes are within scope of this
325: * <code>SOAPElement</code> object
326: *
327: * @since SAAJ 1.2
328: */
329: public Iterator getVisibleNamespacePrefixes();
330:
331: /**
332: * Creates a <code>QName</code> whose namespace URI is the one associated
333: * with the parameter, <code>prefix</code>, in the context of this
334: * <code>SOAPElement</code>. The remaining elements of the new
335: * <code>QName</code> are taken directly from the parameters,
336: * <code>localName</code> and <code>prefix</code>.
337: *
338: * @param localName
339: * a <code>String</code> containing the local part of the name.
340: * @param prefix
341: * a <code>String</code> containing the prefix for the name.
342: *
343: * @return a <code>QName</code> with the specified <code>localName</code>
344: * and <code>prefix</code>, and with a namespace that is associated
345: * with the <code>prefix</code> in the context of this
346: * <code>SOAPElement</code>. This namespace will be the same as
347: * the one that would be returned by
348: * <code>{@link #getNamespaceURI(String)}</code> if it were given
349: * <code>prefix</code> as it's parameter.
350: *
351: * @exception SOAPException if the <code>QName</code> cannot be created.
352: *
353: * @since SAAJ 1.3
354: */
355: public QName createQName(String localName, String prefix)
356: throws SOAPException;
357:
358: /**
359: * Returns the name of this <code>SOAPElement</code> object.
360: *
361: * @return a <code>Name</code> object with the name of this
362: * <code>SOAPElement</code> object
363: */
364: public Name getElementName();
365:
366: /**
367: * Returns the qname of this <code>SOAPElement</code> object.
368: *
369: * @return a <code>QName</code> object with the qname of this
370: * <code>SOAPElement</code> object
371: * @see SOAPElement#getElementName()
372: * @since SAAJ 1.3
373: */
374: public QName getElementQName();
375:
376: /**
377: * Changes the name of this <code>Element</code> to <code>newName</code> if
378: * possible. SOAP Defined elements such as SOAPEnvelope, SOAPHeader, SOAPBody
379: * etc. cannot have their names changed using this method. Any attempt to do
380: * so will result in a SOAPException being thrown.
381: *<P>
382: * Callers should not rely on the element instance being renamed as is.
383: * Implementations could end up copying the content of the
384: * <code>SOAPElement</code> to a renamed instance.
385: *
386: * @param newName the new name for the <code>Element</code>.
387: *
388: * @exception SOAPException if changing the name of this <code>Element</code>
389: * is not allowed.
390: * @return The renamed Node
391: *
392: * @since SAAJ 1.3
393: */
394: public SOAPElement setElementQName(QName newName)
395: throws SOAPException;
396:
397: /**
398: * Removes the attribute with the specified name.
399: *
400: * @param name the <code>Name</code> object with the name of the
401: * attribute to be removed
402: * @return <code>true</code> if the attribute was
403: * removed successfully; <code>false</code> if it was not
404: * @see SOAPElement#removeAttribute(javax.xml.namespace.QName)
405: */
406: public boolean removeAttribute(Name name);
407:
408: /**
409: * Removes the attribute with the specified qname.
410: *
411: * @param qname the <code>QName</code> object with the qname of the
412: * attribute to be removed
413: * @return <code>true</code> if the attribute was
414: * removed successfully; <code>false</code> if it was not
415: * @see SOAPElement#removeAttribute(Name)
416: * @since SAAJ 1.3
417: */
418: public boolean removeAttribute(QName qname);
419:
420: /**
421: * Removes the namespace declaration corresponding to the given prefix.
422: *
423: * @param prefix a <code>String</code> giving the prefix for which
424: * to search
425: * @return <code>true</code> if the namespace declaration was
426: * removed successfully; <code>false</code> if it was not
427: */
428: public boolean removeNamespaceDeclaration(String prefix);
429:
430: /**
431: * Returns an <code>Iterator</code> over all the immediate child
432: * {@link Node}s of this element. This includes <code>javax.xml.soap.Text</code>
433: * objects as well as <code>SOAPElement</code> objects.
434: * <p>
435: * Calling this method may cause child <code>Element</code>,
436: * <code>SOAPElement</code> and <code>org.w3c.dom.Text</code> nodes to be
437: * replaced by <code>SOAPElement</code>, <code>SOAPHeaderElement</code>,
438: * <code>SOAPBodyElement</code> or <code>javax.xml.soap.Text</code> nodes as
439: * appropriate for the type of this parent node. As a result the calling
440: * application must treat any existing references to these child nodes that
441: * have been obtained through DOM APIs as invalid and either discard them or
442: * refresh them with the values returned by this <code>Iterator</code>. This
443: * behavior can be avoided by calling the equivalent DOM APIs. See
444: * {@link <a HREF="package-summary.html#package_description">javax.xml.soap<a>}
445: * for more details.
446: *
447: * @return an iterator with the content of this <code>SOAPElement</code>
448: * object
449: */
450: public Iterator getChildElements();
451:
452: /**
453: * Returns an <code>Iterator</code> over all the immediate child
454: * {@link Node}s of this element with the specified name. All of these
455: * children will be <code>SOAPElement</code> nodes.
456: * <p>
457: * Calling this method may cause child <code>Element</code>,
458: * <code>SOAPElement</code> and <code>org.w3c.dom.Text</code> nodes to be
459: * replaced by <code>SOAPElement</code>, <code>SOAPHeaderElement</code>,
460: * <code>SOAPBodyElement</code> or <code>javax.xml.soap.Text</code> nodes as
461: * appropriate for the type of this parent node. As a result the calling
462: * application must treat any existing references to these child nodes that
463: * have been obtained through DOM APIs as invalid and either discard them or
464: * refresh them with the values returned by this <code>Iterator</code>. This
465: * behavior can be avoided by calling the equivalent DOM APIs. See
466: * {@link <a HREF="package-summary.html#package_description">javax.xml.soap<a>}
467: * for more details.
468: *
469: * @param name a <code>Name</code> object with the name of the child
470: * elements to be returned
471: *
472: * @return an <code>Iterator</code> object over all the elements
473: * in this <code>SOAPElement</code> object with the
474: * specified name
475: * @see SOAPElement#getChildElements(javax.xml.namespace.QName)
476: */
477: public Iterator getChildElements(Name name);
478:
479: /**
480: * Returns an <code>Iterator</code> over all the immediate child
481: * {@link Node}s of this element with the specified qname. All of these
482: * children will be <code>SOAPElement</code> nodes.
483: * <p>
484: * Calling this method may cause child <code>Element</code>,
485: * <code>SOAPElement</code> and <code>org.w3c.dom.Text</code> nodes to be
486: * replaced by <code>SOAPElement</code>, <code>SOAPHeaderElement</code>,
487: * <code>SOAPBodyElement</code> or <code>javax.xml.soap.Text</code> nodes as
488: * appropriate for the type of this parent node. As a result the calling
489: * application must treat any existing references to these child nodes that
490: * have been obtained through DOM APIs as invalid and either discard them or
491: * refresh them with the values returned by this <code>Iterator</code>. This
492: * behavior can be avoided by calling the equivalent DOM APIs. See
493: * {@link <a HREF="package-summary.html#package_description">javax.xml.soap<a>}
494: * for more details.
495: *
496: * @param qname a <code>QName</code> object with the qname of the child
497: * elements to be returned
498: *
499: * @return an <code>Iterator</code> object over all the elements
500: * in this <code>SOAPElement</code> object with the
501: * specified qname
502: * @see SOAPElement#getChildElements(Name)
503: * @since SAAJ 1.3
504: */
505: public Iterator getChildElements(QName qname);
506:
507: /**
508: * Sets the encoding style for this <code>SOAPElement</code> object
509: * to one specified.
510: *
511: * @param encodingStyle a <code>String</code> giving the encoding style
512: *
513: * @exception IllegalArgumentException if there was a problem in the
514: * encoding style being set.
515: * @exception SOAPException if setting the encodingStyle is invalid for this SOAPElement.
516: * @see #getEncodingStyle
517: */
518: public void setEncodingStyle(String encodingStyle)
519: throws SOAPException;
520:
521: /**
522: * Returns the encoding style for this <code>SOAPElement</code> object.
523: *
524: * @return a <code>String</code> giving the encoding style
525: *
526: * @see #setEncodingStyle
527: */
528: public String getEncodingStyle();
529: }
|