wtfiniteintegrity.rar

/* * Copyright (c) 1997, 2008, Oracle and/or its affiliates. All rights reserved. * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms. * * * * * * * * * * * * * * * * * * * * */ /* * $Id: SOAPElement.java,v 1.19 2005/12/13 09:20:25 vj135062 Exp $ * $Revision: 1.19 $ * $Date: 2005/12/13 09:20:25 $ */ package javax.xml.soap; import java.util.Iterator; import javax.xml.namespace.QName; /** * An object representing an element of a SOAP message that is allowed but not * specifically prescribed by a SOAP specification. This interface serves as the * base interface for those objects that are specifically prescribed by a SOAP * specification. * <p> * Methods in this interface that are required to return SAAJ specific objects * may "silently" replace nodes in the tree as required to successfully return * objects of the correct type. See {@link #getChildElements()} and * {@link <a HREF="package-summary.html#package_description" rel='nofollow' onclick='return false;'>javax.xml.soap<a rel='nofollow' onclick='return false;'>} * for details. */ public interface SOAPElement extends Node, org.w3c.dom.Element { /** * Creates a new <code>SOAPElement</code> object initialized with the * given <code>Name</code> object and adds the new element to this * <code>SOAPElement</code> object. * <P> * This method may be deprecated in a future release of SAAJ in favor of * addChildElement(javax.xml.namespace.QName) * * @param name a <code>Name</code> object with the XML name for the * new element * * @return the new <code>SOAPElement</code> object that was created * @exception SOAPException if there is an error in creating the * <code>SOAPElement</code> object * @see SOAPElement#addChildElement(javax.xml.namespace.QName) */ public SOAPElement addChildElement(Name name) throws SOAPException; /** * Creates a new <code>SOAPElement</code> object initialized with the given * <code>QName</code> object and adds the new element to this <code>SOAPElement</code> * object. The <i>namespace</i>, <i>localname</i> and <i>prefix</i> of the new * <code>SOAPElement</code> are all taken from the <code>qname</code> argument. * * @param qname a <code>QName</code> object with the XML name for the * new element * * @return the new <code>SOAPElement</code> object that was created * @exception SOAPException if there is an error in creating the * <code>SOAPElement</code> object * @see SOAPElement#addChildElement(Name) * @since SAAJ 1.3 */ public SOAPElement addChildElement(QName qname) throws SOAPException; /** * Creates a new <code>SOAPElement</code> object initialized with the * specified local name and adds the new element to this * <code>SOAPElement</code> object. * The new <code>SOAPElement</code> inherits any in-scope default namespace. * * @param localName a <code>String</code> giving the local name for * the element * @return the new <code>SOAPElement</code> object that was created * @exception SOAPException if there is an error in creating the * <code>SOAPElement</code> object */ public SOAPElement addChildElement(String localName) throws SOAPException; /** * Creates a new <code>SOAPElement</code> object initialized with the * specified local name and prefix and adds the new element to this * <code>SOAPElement</code> object. * * @param localName a <code>String</code> giving the local name for * the new element * @param prefix a <code>String</code> giving the namespace prefix for * the new element * * @return the new <code>SOAPElement</code> object that was created * @exception SOAPException if the <code>prefix</code> is not valid in the * context of this <code>SOAPElement</code> or if there is an error in creating the * <code>SOAPElement</code> object */ public SOAPElement addChildElement(String localName, String prefix) throws SOAPException; /** * Creates a new <code>SOAPElement</code> object initialized with the * specified local name, prefix, and URI and adds the new element to this * <code>SOAPElement</code> object. * * @param localName a <code>String</code> giving the local name for * the new element * @param prefix a <code>String</code> giving the namespace prefix for * the new element * @param uri a <code>String</code> giving the URI of the namespace * to which the new element belongs * * @return the new <code>SOAPElement</code> object that was created * @exception SOAPException if there is an error in creating the * <code>SOAPElement</code> object */ public SOAPElement addChildElement(String localName, String prefix, String uri) throws SOAPException; /** * Add a <code>SOAPElement</code> as a child of this * <code>SOAPElement</code> instance. The <code>SOAPElement</code> * is expected to be created by a * <code>SOAPFactory</code>. Callers should not rely on the * element instance being added as is into the XML * tree. Implementations could end up copying the content * of the <code>SOAPElement</code> passed into an instance of * a different <code>SOAPElement</code> implementation. For * instance if <code>addChildElement()</code> is called on a * <code>SOAPHeader</code>, <code>element</code> will be copied * into an instance of a <code>SOAPHeaderElement</code>. * * <P>The fragment rooted in <code>element</code> is either added * as a whole or not at all, if there was an error. * * <P>The fragment rooted in <code>element</code> cannot contain * elements named "Envelope", "Header" or "Body" and in the SOAP * namespace. Any namespace prefixes present in the fragment * should be fully resolved using appropriate namespace * declarations within the fragment itself. * * @param element the <code>SOAPElement</code> to be added as a * new child * * @exception SOAPException if there was an error in adding this * element as a child * * @return an instance representing the new SOAP element that was * actually added to the tree. */ public SOAPElement addChildElement(SOAPElement element) throws SOAPException; /** * Detaches all children of this <code>SOAPElement</code>. * <p> * This method is useful for rolling back the construction of partially * completed <code>SOAPHeaders</code> and <code>SOAPBodys</code> in * preparation for sending a fault when an error condition is detected. It * is also useful for recycling portions of a document within a SOAP * message. * * @since SAAJ 1.2 */ public abstract void removeContents(); /** * Creates a new <code>Text</code> object initialized with the given * <code>String</code> and adds it to this <code>SOAPElement</code> object. * * @param text a <code>String</code> object with the textual content to be added * * @return the <code>SOAPElement</code> object into which * the new <code>Text</code> object was inserted * @exception SOAPException if there is an error in creating the * new <code>Text</code> object or if it is not legal to * attach it as a child to this * <code>SOAPElement</code> */ public SOAPElement addTextNode(String text) throws SOAPException; /** * Adds an attribute with the specified name and value to this * <