Return-Path: Delivered-To: apmail-ws-axis-dev-archive@www.apache.org Received: (qmail 64409 invoked from network); 3 Jun 2005 14:56:06 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (209.237.227.199) by minotaur.apache.org with SMTP; 3 Jun 2005 14:56:06 -0000 Received: (qmail 55894 invoked by uid 500); 3 Jun 2005 14:56:04 -0000 Delivered-To: apmail-ws-axis-dev-archive@ws.apache.org Received: (qmail 55856 invoked by uid 500); 3 Jun 2005 14:56:03 -0000 Mailing-List: contact axis-cvs-help@ws.apache.org; run by ezmlm Precedence: bulk list-help: list-unsubscribe: List-Post: List-Id: Delivered-To: mailing list axis-cvs@ws.apache.org Received: (qmail 55840 invoked by uid 99); 3 Jun 2005 14:56:03 -0000 X-ASF-Spam-Status: No, hits=-9.8 required=10.0 tests=ALL_TRUSTED,NO_REAL_NAME X-Spam-Check-By: apache.org Received: from minotaur.apache.org (HELO minotaur.apache.org) (209.237.227.194) by apache.org (qpsmtpd/0.28) with SMTP; Fri, 03 Jun 2005 07:55:54 -0700 Received: (qmail 63665 invoked by uid 65534); 3 Jun 2005 14:54:47 -0000 Message-ID: <20050603145447.63663.qmail@minotaur.apache.org> Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Subject: svn commit: r179806 [2/3] - in /webservices/axis/trunk/archive/java/scratch/ashu_jaya_venkat/saaj/src/javax/xml: namespace/ soap/ Date: Fri, 03 Jun 2005 14:54:43 -0000 To: axis-cvs@ws.apache.org From: venkat@apache.org X-Mailer: svnmailer-1.0.0-dev X-Virus-Checked: Checked X-Spam-Rating: minotaur.apache.org 1.6.2 0/1000/N Added: webservices/axis/trunk/archive/java/scratch/ashu_jaya_venkat/saaj/sr= c/javax/xml/soap/SOAPElement.java URL: http://svn.apache.org/viewcvs/webservices/axis/trunk/archive/java/scra= tch/ashu_jaya_venkat/saaj/src/javax/xml/soap/SOAPElement.java?rev=3D179806&= view=3Dauto =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D --- webservices/axis/trunk/archive/java/scratch/ashu_jaya_venkat/saaj/src/j= avax/xml/soap/SOAPElement.java (added) +++ webservices/axis/trunk/archive/java/scratch/ashu_jaya_venkat/saaj/src/j= avax/xml/soap/SOAPElement.java Fri Jun 3 07:54:42 2005 @@ -0,0 +1,288 @@ +/* + * Copyright 2001-2004 The Apache Software Foundation. + *=20 + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + *=20 + * http://www.apache.org/licenses/LICENSE-2.0 + *=20 + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied= . + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.xml.soap; + +import java.util.Iterator; + +/** + * An object representing the contents in a + * SOAPBody object, the contents in a SOAPHeader + * object, the content that can follow the SOAPBody object in= a + * SOAPEnvelope object, or what can follow the detail element + * in a SOAPFault object. It is + * the base class for all of the classes that represent the SOAP objects a= s + * defined in the SOAP specification. + */ +public interface SOAPElement extends Node, org.w3c.dom.Element { + + /** + * Creates a new SOAPElement object initialized with the + * given Name object and adds the new element to this + * SOAPElement object. + * @param name a Name object with the XML name for the + * new element + * @return the new SOAPElement object that was created + * @throws SOAPException if there is an error in creating the + * SOAPElement object + */ + public abstract SOAPElement addChildElement(Name name) throws SOAPExce= ption; + + /** + * Creates a new SOAPElement object initialized with the + * given String object and adds the new element to this + * SOAPElement object. + * @param localName a String giving the local name for + * the element + * @return the new SOAPElement object that was created + * @throws SOAPException if there is an error in creating the + * SOAPElement object + */ + public abstract SOAPElement addChildElement(String localName) + throws SOAPException; + + /** + * Creates a new SOAPElement object initialized with the + * specified local name and prefix and adds the new element to this + * SOAPElement object. + * @param localName a String giving the local name for + * the new element + * @param prefix a String giving the namespace prefix f= or + * the new element + * @return the new SOAPElement object that was created + * @throws SOAPException if there is an error in creating the + * SOAPElement object + */ + public abstract SOAPElement addChildElement(String localName, String p= refix) + throws SOAPException; + + /** + * Creates a new SOAPElement object initialized with the + * specified local name, prefix, and URI and adds the new element to t= his + * SOAPElement object. + * @param localName a String giving the local name for + * the new element + * @param prefix a String giving the namespace prefix = for + * the new element + * @param uri a String giving the URI of the namespace + * to which the new element belongs + * @return the new SOAPElement object that was created + * @throws SOAPException if there is an error in creating the + * SOAPElement object + */ + public abstract SOAPElement addChildElement( + String localName, String prefix, String uri) throws SOAPException; + + /** + * Add a SOAPElement as a child of this + * SOAPElement instance. The SOAPElement + * is expected to be created by a + * SOAPElementFactory. 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 SOAPElement passed into an instance of + * a different SOAPElement implementation. For + * instance if addChildElement() is called on a + * SOAPHeader, element will be copied + * into an instance of a SOAPHeaderElement. + * + *

The fragment rooted in element is either added + * as a whole or not at all, if there was an error. + * + *

The fragment rooted in element 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 SOAPElement to be added as a + * new child + * @return an instance representing the new SOAP element that was + * actually added to the tree. + * @throws SOAPException if there was an error in adding this + * element as a child + */ + public abstract SOAPElement addChildElement(SOAPElement element) + throws SOAPException; + + /** + * Creates a new Text object initialized with the given + * String and adds it to this SOAPElement ob= ject. + * @param text a String object with the textual content= to be added + * @return the SOAPElement object into which + * the new Text object was inserted + * @throws SOAPException if there is an error in creating the + * new Text object + */ + public abstract SOAPElement addTextNode(String text) throws SOAPExcept= ion; + + /** + * Adds an attribute with the specified name and value to this + * SOAPElement object. + *

+ * @param name a Name object with the name of the attri= bute + * @param value a String giving the value of the attrib= ute + * @return the SOAPElement object into which the attribu= te was + * inserted + * @throws SOAPException if there is an error in creating the + * Attribute + */ + public abstract SOAPElement addAttribute(Name name, String value) + throws SOAPException; + + /** + * Adds a namespace declaration with the specified prefix and URI to t= his + * SOAPElement object. + *

+ * @param prefix a String giving the prefix of the name= space + * @param uri a String giving + * the prefix of the namespace + * @return the SOAPElement object into which this + * namespace declaration was inserted. + * @throws SOAPException if there is an error in creating the + * namespace + */ + public abstract SOAPElement addNamespaceDeclaration( + String prefix, String uri) throws SOAPException; + + /** + * Returns the value of the attribute with the specified + * name. + * @param name a Name object with + * the name of the attribute + * @return a String giving the value of the + * specified attribute + */ + public abstract String getAttributeValue(Name name); + + /** + * Returns an iterator over all of the attribute names in + * this SOAPElement object. The iterator can be + * used to get the attribute names, which can then be passed to + * the method getAttributeValue to retrieve the + * value of each attribute. + * @return an iterator over the names of the attributes + */ + public abstract Iterator getAllAttributes(); + + /** + * Returns the URI of the namespace that has the given + * prefix. + * + * @param prefix a String giving + * the prefix of the namespace for which to search + * @return a String with the uri of the namespace + * that has the given prefix + */ + public abstract String getNamespaceURI(String prefix); + + /** + * Returns an iterator of namespace prefixes. The iterator + * can be used to get the namespace prefixes, which can then be + * passed to the method getNamespaceURI to retrieve + * the URI of each namespace. + * @return an iterator over the namespace prefixes in this + * SOAPElement object + */ + public abstract Iterator getNamespacePrefixes(); + + /** + * Returns the name of this SOAPElement + * object. + * @return a Name object with the name of this + * SOAPElement object + */ + public abstract Name getElementName(); + + /** + * Removes the attribute with the specified name. + * @param name the Name object with + * the name of the attribute to be removed + * @return true if the attribute was removed + * successfully; false if it was not + */ + public abstract boolean removeAttribute(Name name); + + /** + * Removes the namespace declaration corresponding to the + * given prefix. + * @param prefix a String giving + * the prefix for which to search + * @return true if the namespace declaration was + * removed successfully; false if it was + * not + */ + public abstract boolean removeNamespaceDeclaration(String prefix); + + /** + * Returns an iterator over all the immediate content of + * this element. This includes Text objects as well + * as SOAPElement objects. + * @return an iterator with the content of this + * SOAPElement object + */ + public abstract Iterator getChildElements(); + + /** + * Returns an iterator over all the child elements with the + * specified name. + * @param name a Name object with + * the name of the child elements to be returned + * @return an Iterator object over all the elements + * in this SOAPElement object with the + * specified name + */ + public abstract Iterator getChildElements(Name name); + + /** + * Sets the encoding style for this SOAPElement + * object to one specified. + * @param encodingStyle a String + * giving the encoding style + * @throws java.lang.IllegalArgumentException if + * there was a problem in the encoding style being set. + * @see #getEncodingStyle() getEncodingStyle() + */ + public abstract void setEncodingStyle(String encodingStyle) + throws SOAPException; + + /** + * Returns the encoding style for this + * SOAPElement object. + * @return a String giving the encoding style + * @see #setEncodingStyle(java.lang.String) setEncodingStyle(java.lang= .String) + */ + public abstract String getEncodingStyle(); + + /** + * Detaches all children of this SOAPElement. + *

+ * This method is useful for rolling back the construction of partiall= y + * completed SOAPHeaders and SOAPBodys in + * reparation for sending a fault when an error condition is detected.= It is + * also useful for recycling portions of a document within a SOAP mess= age. + */ + public abstract void removeContents(); + + /** + * Returns an Iterator over the namespace prefix + * Strings visible to this element. The prefixes returned= by + * this iterator can be passed to the method getNamespaceURI() + * to retrieve the URI of each namespace. + * + * @return an iterator over the namespace prefixes are within scope of= this + * SOAPElement object + */ + public abstract Iterator getVisibleNamespacePrefixes(); +} Added: webservices/axis/trunk/archive/java/scratch/ashu_jaya_venkat/saaj/sr= c/javax/xml/soap/SOAPElementFactory.java URL: http://svn.apache.org/viewcvs/webservices/axis/trunk/archive/java/scra= tch/ashu_jaya_venkat/saaj/src/javax/xml/soap/SOAPElementFactory.java?rev=3D= 179806&view=3Dauto =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D --- webservices/axis/trunk/archive/java/scratch/ashu_jaya_venkat/saaj/src/j= avax/xml/soap/SOAPElementFactory.java (added) +++ webservices/axis/trunk/archive/java/scratch/ashu_jaya_venkat/saaj/src/j= avax/xml/soap/SOAPElementFactory.java Fri Jun 3 07:54:42 2005 @@ -0,0 +1,116 @@ +/* + * Copyright 2001-2004 The Apache Software Foundation. + *=20 + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + *=20 + * http://www.apache.org/licenses/LICENSE-2.0 + *=20 + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied= . + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.xml.soap; + +/** + *

SOAPElementFactory is a factory for XML + * fragments that will eventually end up in the SOAP part. These + * fragments can be inserted as children of the + * SOAPHeader or SOAPBody or + * SOAPEnvelope.

+ * + *

Elements created using this factory do not have the + * properties of an element that lives inside a SOAP header + * document. These elements are copied into the XML document tree + * when they are inserted.

+ * @deprecated - Use javax.xml.soap.SOAPFactory for creating SOAPElements. + * @see SOAPFactory SOAPFactory + */ +public class SOAPElementFactory { + + /** + * Create a new SOAPElementFactory from a SOAPFactory. + * + * @param soapfactory the SOAPFactory to use + */ + private SOAPElementFactory(SOAPFactory soapfactory) { + sf =3D soapfactory; + } + + /** + * Create a SOAPElement object initialized with + * the given Name object. + * @param name a Name object with + * the XML name for the new element + * @return the new SOAPElement object that was + * created + * @throws SOAPException if there is an error in + * creating the SOAPElement object + * @deprecated Use javax.xml.soap.SOAPFactory.createElement(javax.xml.= soap.Name) instead + * @see SOAPFactory#createElement(javax.xml.soap.Name) SOAPFactory.cre= ateElement(javax.xml.soap.Name) + */ + public SOAPElement create(Name name) throws SOAPException { + return sf.createElement(name); + } + + /** + * Create a SOAPElement object initialized with + * the given local name. + * @param localName a String giving + * the local name for the new element + * @return the new SOAPElement object that was + * created + * @throws SOAPException if there is an error in + * creating the SOAPElement object + * @deprecated Use javax.xml.soap.SOAPFactory.createElement(String loc= alName) instead + * @see SOAPFactory#createElement(java.lang.String) SOAPFactory.create= Element(java.lang.String) + */ + public SOAPElement create(String localName) throws SOAPException { + return sf.createElement(localName); + } + + /** + * Create a new SOAPElement object with the + * given local name, prefix and uri. + * @param localName a String giving + * the local name for the new element + * @param prefix the prefix for this + * SOAPElement + * @param uri a String giving the + * URI of the namespace to which the new element + * belongs + * @return the new SOAPElement object that was + * created + * @throws SOAPException if there is an error in + * creating the SOAPElement object + * @deprecated Use javax.xml.soap.SOAPFactory.createElement(String loc= alName, String prefix, String uri) instead + * @see SOAPFactory#createElement(java.lang.String, java.lang.String, = java.lang.String) SOAPFactory.createElement(java.lang.String, java.lang.Str= ing, java.lang.String) + */ + public SOAPElement create(String localName, String prefix, String uri) + throws SOAPException { + return sf.createElement(localName, prefix, uri); + } + + /** + * Creates a new instance of SOAPElementFactory. + * + * @return a new instance of a + * SOAPElementFactory + * @throws SOAPException if there was an error creating + * the default SOAPElementFactory + */ + public static SOAPElementFactory newInstance() throws SOAPException { + + try { + return new SOAPElementFactory(SOAPFactory.newInstance()); + } catch (Exception exception) { + throw new SOAPException("Unable to create SOAP Element Factory= : " + + exception.getMessage()); + } + } + + private SOAPFactory sf; +} Added: webservices/axis/trunk/archive/java/scratch/ashu_jaya_venkat/saaj/sr= c/javax/xml/soap/SOAPEnvelope.java URL: http://svn.apache.org/viewcvs/webservices/axis/trunk/archive/java/scra= tch/ashu_jaya_venkat/saaj/src/javax/xml/soap/SOAPEnvelope.java?rev=3D179806= &view=3Dauto =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D --- webservices/axis/trunk/archive/java/scratch/ashu_jaya_venkat/saaj/src/j= avax/xml/soap/SOAPEnvelope.java (added) +++ webservices/axis/trunk/archive/java/scratch/ashu_jaya_venkat/saaj/src/j= avax/xml/soap/SOAPEnvelope.java Fri Jun 3 07:54:42 2005 @@ -0,0 +1,191 @@ +/* + * Copyright 2001-2004 The Apache Software Foundation. + *=20 + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + *=20 + * http://www.apache.org/licenses/LICENSE-2.0 + *=20 + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied= . + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.xml.soap; + +/** + * The container for the SOAPHeader and SOAPBody portions of a + * SOAPPart object. By default, a + * SOAPMessage object is created with a + * SOAPPart object that has a SOAPEnvelope + * object. The SOAPEnvelope object by default has an + * empty SOAPBody object and an empty + * SOAPHeader object. The SOAPBody object is + * required, and the SOAPHeader object, though + * optional, is used in the majority of cases. If the + * SOAPHeader object is not needed, it can be deleted, + * which is shown later.

+ * + *

A client can access the SOAPHeader and + * SOAPBody objects by calling the methods + * SOAPEnvelope.getHeader and + * SOAPEnvelope.getBody. The following lines of code use + * these two methods after starting with the + * SOAPMessage object message to get the + * SOAPPart object sp, which is then used to get the + * SOAPEnvelope object se.

+ * 
+ *    SOAPPart sp =3D message.getSOAPPart();
+ *    SOAPEnvelope se =3D sp.getEnvelope();
+ *    SOAPHeader sh =3D se.getHeader();
+ *    SOAPBody sb =3D se.getBody();
+ *
+ * + *

It is possible to change the body or header of a + * SOAPEnvelope object by retrieving the current one, + * deleting it, and then adding a new body or header. The + * javax.xml.soap.Node method detachNode + * detaches the XML element (node) on which it is called. For + * example, the following line of code deletes the + * SOAPBody object that is retrieved by the method + * getBody.

+ * 
+ *     se.getBody().detachNode();
+ *
+ * To create a SOAPHeader object to replace the one + * that was removed, a client uses the method + * SOAPEnvelope.addHeader, which creates a new header and + * adds it to the SOAPEnvelope object. Similarly, the + * method addBody creates a new SOAPBody + * object and adds it to the SOAPEnvelope object. The + * following code fragment retrieves the current header, removes + * it, and adds a new one. Then it retrieves the current body, + * removes it, and adds a new one. + * 
+ *    SOAPPart sp =3D message.getSOAPPart();
+ *    SOAPEnvelope se =3D sp.getEnvelope();
+ *    se.getHeader().detachNode();
+ *    SOAPHeader sh =3D se.addHeader();
+ *    se.getBody().detachNode();
+ *    SOAPBody sb =3D se.addBody();
+ *
+ * It is an error to add a SOAPBody or + * SOAPHeader object if one already exists. + * + *

The SOAPEnvelope interface provides three + * methods for creating Name objects. One method + * creates Name objects with a local name, a + * namespace prefix, and a namesapce URI. The second method + * creates Name objects with a local name and a + * namespace prefix, and the third creates Name + * objects with just a local name. The following line of code, in + * which se is a SOAPEnvelope object, creates + * a new Name object with all three.

+ * 
+ *    Name name =3D se.createName("GetLastTradePrice", "WOMBAT",
+ *                               "http://www.wombat.org/trader");
+ *
+ */ +public interface SOAPEnvelope extends SOAPElement { + + /** + * Creates a new Name object initialized with the + * given local name, namespace prefix, and namespace URI. + * + *

This factory method creates Name objects + * for use in the SOAP/XML document. + * @param localName a String giving + * the local name + * @param prefix a String giving + * the prefix of the namespace + * @param uri a String giving the + * URI of the namespace + * @return a Name object initialized with the given + * local name, namespace prefix, and namespace URI + * @throws SOAPException if there is a SOAP error + */ + public abstract Name createName(String localName, String prefix, Strin= g uri) + throws SOAPException; + + /** + * Creates a new Name object initialized with the + * given local name. + * + *

This factory method creates Name objects + * for use in the SOAP/XML document. + * + * @param localName a String giving + * the local name + * @return a Name object initialized with the given + * local name + * @throws SOAPException if there is a SOAP error + */ + public abstract Name createName(String localName) throws SOAPException= ; + + /** + * Returns the SOAPHeader object for this + * SOAPEnvelope object. + * + *

A new SOAPMessage object is by default + * created with a SOAPEnvelope object that + * contains an empty SOAPHeader object. As a + * result, the method getHeader will always + * return a SOAPHeader object unless the header + * has been removed and a new one has not been added. + * @return the SOAPHeader object or + * null if there is none + * @throws SOAPException if there is a problem + * obtaining the SOAPHeader object + */ + public abstract SOAPHeader getHeader() throws SOAPException; + + /** + * Returns the SOAPBody object associated with + * this SOAPEnvelope object. + * + *

A new SOAPMessage object is by default + * created with a SOAPEnvelope object that + * contains an empty SOAPBody object. As a + * result, the method getBody will always return + * a SOAPBody object unless the body has been + * removed and a new one has not been added. + * @return the SOAPBody object for this + * SOAPEnvelope object or null if there + * is none + * @throws SOAPException if there is a problem + * obtaining the SOAPBody object + */ + public abstract SOAPBody getBody() throws SOAPException; + + /** + * Creates a SOAPHeader object and sets it as the + * SOAPHeader object for this + * SOAPEnvelope object. + * + *

It is illegal to add a header when the envelope already + * contains a header. Therefore, this method should be called + * only after the existing header has been removed. + * @return the new SOAPHeader object + * @throws SOAPException if this + * SOAPEnvelope object already contains a valid + * SOAPHeader object + */ + public abstract SOAPHeader addHeader() throws SOAPException; + + /** + * Creates a SOAPBody object and sets it as the + * SOAPBody object for this + * SOAPEnvelope object. + * + *

It is illegal to add a body when the envelope already + * contains a body. Therefore, this method should be called + * only after the existing body has been removed. + * @return the new SOAPBody object + * @throws SOAPException if this + * SOAPEnvelope object already contains a valid + * SOAPBody object + */ + public abstract SOAPBody addBody() throws SOAPException; +} Added: webservices/axis/trunk/archive/java/scratch/ashu_jaya_venkat/saaj/sr= c/javax/xml/soap/SOAPException.java URL: http://svn.apache.org/viewcvs/webservices/axis/trunk/archive/java/scra= tch/ashu_jaya_venkat/saaj/src/javax/xml/soap/SOAPException.java?rev=3D17980= 6&view=3Dauto =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D --- webservices/axis/trunk/archive/java/scratch/ashu_jaya_venkat/saaj/src/j= avax/xml/soap/SOAPException.java (added) +++ webservices/axis/trunk/archive/java/scratch/ashu_jaya_venkat/saaj/src/j= avax/xml/soap/SOAPException.java Fri Jun 3 07:54:42 2005 @@ -0,0 +1,177 @@ +/* + * Copyright 2001-2004 The Apache Software Foundation. + *=20 + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + *=20 + * http://www.apache.org/licenses/LICENSE-2.0 + *=20 + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied= . + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.xml.soap; + +/** + * An exception that signals that a SOAP exception has + * occurred. A SOAPException object may contain a + * String that gives the reason for the exception, an + * embedded Throwable object, or both. This class + * provides methods for retrieving reason messages and for + * retrieving the embedded Throwable object.

+ * + *

Typical reasons for throwing a SOAPException + * object are problems such as difficulty setting a header, not + * being able to send a message, and not being able to get a + * connection with the provider. Reasons for embedding a + * Throwable object include problems such as input/output + * errors or a parsing problem, such as an error in parsing a + * header. + */ +public class SOAPException extends Exception { + + /** + * Constructs a SOAPException object with no + * reason or embedded Throwable object. + */ + public SOAPException() { + cause =3D null; + } + + /** + * Constructs a SOAPException object with the + * given String as the reason for the exception + * being thrown. + * @param reason a description of what caused + * the exception + */ + public SOAPException(String reason) { + + super(reason); + + cause =3D null; + } + + /** + * Constructs a SOAPException object with the + * given String as the reason for the exception + * being thrown and the given Throwable object as + * an embedded exception. + * @param reason a description of what caused + * the exception + * @param cause a Throwable object + * that is to be embedded in this SOAPException + * object + */ + public SOAPException(String reason, Throwable cause) { + + super(reason); + + initCause(cause); + } + + /** + * Constructs a SOAPException object + * initialized with the given Throwable + * object. + * @param cause a Throwable object + * that is to be embedded in this SOAPException + * object + */ + public SOAPException(Throwable cause) { + + super(cause.toString()); + + initCause(cause); + } + + /** + * Returns the detail message for this + * SOAPException object. + * + *

If there is an embedded Throwable object, + * and if the SOAPException object has no detail + * message of its own, this method will return the detail + * message from the embedded Throwable + * object.

+ * @return the error or warning message for this + * SOAPException or, if it has none, the message of + * the embedded Throwable object, if there is + * one + */ + public String getMessage() { + + String s =3D super.getMessage(); + + if ((s =3D=3D null) && (cause !=3D null)) { + return cause.getMessage(); + } else { + return s; + } + } + + /** + * Returns the Throwable object embedded in + * this SOAPException if there is one. Otherwise, + * this method returns null. + * @return the embedded Throwable object or + * null if there is none + */ + public Throwable getCause() { + return cause; + } + + /** + * Initializes the cause field of this + * SOAPException object with the given + * Throwable object. + * + *

This method can be called at most once. It is generally + * called from within the constructor or immediately after the + * constructor has returned a new SOAPException + * object. If this SOAPException object was + * created with the constructor {@link #SOAPException(java.lang.Thro= wable) SOAPException(java.lang.Throwable)} + * or {@link #SOAPException(java.lang.String, java.lang.Throwable) S= OAPException(java.lang.String, java.lang.Throwable)}, meaning + * that its cause field already has a value, this + * method cannot be called even once. + * + * @param cause the Throwable + * object that caused this SOAPException object + * to be thrown. The value of this parameter is saved for + * later retrieval by the + * getCause() method. A null value + * is permitted and indicates that the cause is nonexistent + * or unknown. + * @return a reference to this SOAPException + * instance + * @throws java.lang.IllegalArgumentException if + * cause is this Throwable object. + * (A Throwable object cannot be its own + * cause.) + * @throws java.lang.IllegalStateException if this + * SOAPException object was created with {@link #SOAPExcept= ion(java.lang.Throwable) SOAPException(java.lang.Throwable)} + * or {@link #SOAPException(java.lang.String, java.lang.Throwable) S= OAPException(java.lang.String, java.lang.Throwable)}, or this + * method has already been called on this + * SOAPException object + */ + public synchronized Throwable initCause(Throwable cause) { + + if (this.cause !=3D null) { + throw new IllegalStateException("Can't override cause"); + } + + if (cause =3D=3D this) { + throw new IllegalArgumentException("Self-causation not permitt= ed"); + } else { + this.cause =3D cause; + + return this; + } + } + + private Throwable cause; +} Added: webservices/axis/trunk/archive/java/scratch/ashu_jaya_venkat/saaj/sr= c/javax/xml/soap/SOAPFactory.java URL: http://svn.apache.org/viewcvs/webservices/axis/trunk/archive/java/scra= tch/ashu_jaya_venkat/saaj/src/javax/xml/soap/SOAPFactory.java?rev=3D179806&= view=3Dauto =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D --- webservices/axis/trunk/archive/java/scratch/ashu_jaya_venkat/saaj/src/j= avax/xml/soap/SOAPFactory.java (added) +++ webservices/axis/trunk/archive/java/scratch/ashu_jaya_venkat/saaj/src/j= avax/xml/soap/SOAPFactory.java Fri Jun 3 07:54:42 2005 @@ -0,0 +1,147 @@ +/* + * Copyright 2001-2004 The Apache Software Foundation. + *=20 + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + *=20 + * http://www.apache.org/licenses/LICENSE-2.0 + *=20 + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied= . + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.xml.soap; + +/** + * SOAPFactory is a factory for creating various objects + * that exist in the SOAP XML tree. + * + * SOAPFactory can be + * used to create XML fragments that will eventually end up in the + * SOAP part. These fragments can be inserted as children of the + * SOAPHeaderElement or SOAPBodyElement or + * SOAPEnvelope. + * + * SOAPFactory also has methods to create + * javax.xml.soap.Detail objects as well as + * java.xml.soap.Name objects. + * + */ +public abstract class SOAPFactory { + + public SOAPFactory() {} + + /** + * Create a SOAPElement object initialized with the + * given Name object. + * + * @param name a Name object with the XML name for + * the new element + * @return the new SOAPElement object that was + * created + * @throws SOAPException if there is an error in creating the + * SOAPElement object + */ + public abstract SOAPElement createElement(Name name) throws SOAPExcept= ion; + + /** + * Create a SOAPElement object initialized with the + * given local name. + * + * @param localName a String giving the local name for + * the new element + * @return the new SOAPElement object that was + * created + * @throws SOAPException if there is an error in creating the + * SOAPElement object + */ + public abstract SOAPElement createElement(String localName) throws SOA= PException; + + /** + * Create a new SOAPElement object with the given + * local name, prefix and uri. + * + * @param localName a String giving the local name + * for the new element + * @param prefix the prefix for this SOAPElement + * @param uri a String giving the URI of the + * namespace to which the new element belongs + * @return the new SOAPElement object that was + * created + * @throws SOAPException if there is an error in creating the + * SOAPElement object + */ + public abstract SOAPElement createElement(String localName, String pre= fix, String uri) + throws SOAPException; + + /** + * Creates a new Detail object which serves as a containe= r + * for DetailEntry objects. + *

+ * This factory method creates Detail objects for use in + * situations where it is not practical to use the SOAPFault + * abstraction. + * + * @return a Detail object + * @throws SOAPException if there is a SOAP error + */ + public abstract Detail createDetail() throws SOAPException; + + /** + * Creates a new Name object initialized with the + * given local name, namespace prefix, and namespace URI. + *

+ * This factory method creates Name objects for use in + * situations where it is not practical to use the SOAPEnvelope<= /code> + * abstraction. + * + * @param localName a String giving the local name + * @param prefix a String giving the prefix of the namesp= ace + * @param uri a String giving the URI of the namespace + * @return a Name object initialized with the given + * local name, namespace prefix, and namespace URI + * @throws SOAPException if there is a SOAP error + */ + public abstract Name createName(String localName, String prefix, Strin= g uri) + throws SOAPException; + + /** + * Creates a new Name object initialized with the + * given local name. + *

+ * This factory method creates Name objects for use in + * situations where it is not practical to use the SOAPEnvelope<= /code> + * abstraction. + * + * @param localName a String giving the local name + * @return a Name object initialized with the given + * local name + * @throws SOAPException if there is a SOAP error + */ + public abstract Name createName(String localName) throws SOAPException= ; + + /** + * Creates a new instance of SOAPFactory. + * + * @return a new instance of a SOAPFactory + * @throws SOAPException if there was an error creating the + * default SOAPFactory + */ + public static SOAPFactory newInstance() throws SOAPException { + + try { + return (SOAPFactory) FactoryFinder.find(SF_PROPERTY, DEFAULT_S= F); + } catch (Exception exception) { + throw new SOAPException("Unable to create SOAP Factory: " + + exception.getMessage()); + } + } + + private static final String SF_PROPERTY =3D "javax.xml.soap.SOAPFactor= y"; + + private static final String DEFAULT_SF =3D + "org.apache.axis.saaj.SOAPFactoryImpl"; +} Added: webservices/axis/trunk/archive/java/scratch/ashu_jaya_venkat/saaj/sr= c/javax/xml/soap/SOAPFault.java URL: http://svn.apache.org/viewcvs/webservices/axis/trunk/archive/java/scra= tch/ashu_jaya_venkat/saaj/src/javax/xml/soap/SOAPFault.java?rev=3D179806&vi= ew=3Dauto =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D --- webservices/axis/trunk/archive/java/scratch/ashu_jaya_venkat/saaj/src/j= avax/xml/soap/SOAPFault.java (added) +++ webservices/axis/trunk/archive/java/scratch/ashu_jaya_venkat/saaj/src/j= avax/xml/soap/SOAPFault.java Fri Jun 3 07:54:42 2005 @@ -0,0 +1,203 @@ +/* + * Copyright 2001-2004 The Apache Software Foundation. + *=20 + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + *=20 + * http://www.apache.org/licenses/LICENSE-2.0 + *=20 + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied= . + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.xml.soap; + +import java.util.Locale; + +/** + * An element in the SOAPBody object that contains + * error and/or status information. This information may relate to + * errors in the SOAPMessage object or to problems + * that are not related to the content in the message itself. + * Problems not related to the message itself are generally errors + * in processing, such as the inability to communicate with an + * upstream server. + *

+ * The SOAPFault interface provides methods for + * retrieving the information contained in a + * SOAPFault object and for setting the fault code, the + * fault actor, and a string describing the fault. A fault code is + * one of the codes defined in the SOAP 1.1 specification that + * describe the fault. An actor is an intermediate recipient to + * whom a message was routed. The message path may include one or + * more actors, or, if no actors are specified, the message goes + * only to the default actor, which is the final intended + * recipient. + */ +public interface SOAPFault extends SOAPBodyElement { + + /** + * Sets this SOAPFault object with the given + * fault code. + * + *

Fault codes, which given information about the fault, + * are defined in the SOAP 1.1 specification.

+ * @param faultCode a String giving + * the fault code to be set; must be one of the fault codes + * defined in the SOAP 1.1 specification + * @throws SOAPException if there was an error in + * adding the faultCode to the underlying XML + * tree. + * @see #getFaultCode() getFaultCode() + */ + public abstract void setFaultCode(String faultCode) throws SOAPExcepti= on; + + /** + * Gets the fault code for this SOAPFault + * object. + * @return a String with the fault code + * @see #setFaultCode(java.lang.String) setFaultCode(java.lang.String) + */ + public abstract String getFaultCode(); + + /** + * Sets this SOAPFault object with the given + * fault actor. + * + *

The fault actor is the recipient in the message path who + * caused the fault to happen.

+ * @param faultActor a String + * identifying the actor that caused this + * SOAPFault object + * @throws SOAPException if there was an error in + * adding the faultActor to the underlying XML + * tree. + * @see #getFaultActor() getFaultActor() + */ + public abstract void setFaultActor(String faultActor) throws SOAPExcep= tion; + + /** + * Gets the fault actor for this SOAPFault + * object. + * @return a String giving the actor in the message + * path that caused this SOAPFault object + * @see #setFaultActor(java.lang.String) setFaultActor(java.lang.Strin= g) + */ + public abstract String getFaultActor(); + + /** + * Sets the fault string for this SOAPFault + * object to the given string. + * + * @param faultString a String + * giving an explanation of the fault + * @throws SOAPException if there was an error in + * adding the faultString to the underlying XML + * tree. + * @see #getFaultString() getFaultString() + */ + public abstract void setFaultString(String faultString) + throws SOAPException; + + /** + * Gets the fault string for this SOAPFault + * object. + * @return a String giving an explanation of the + * fault + */ + public abstract String getFaultString(); + + /** + * Returns the detail element for this SOAPFault + * object. + * + *

A Detail object carries + * application-specific error information related to + * SOAPBodyElement objects.

+ * @return a Detail object with + * application-specific error information + */ + public abstract Detail getDetail(); + + /** + * Creates a Detail object and sets it as the + * Detail object for this SOAPFault + * object. + * + *

It is illegal to add a detail when the fault already + * contains a detail. Therefore, this method should be called + * only after the existing detail has been removed.

+ * @return the new Detail object + * @throws SOAPException if this + * SOAPFault object already contains a valid + * Detail object + */ + public abstract Detail addDetail() throws SOAPException; + + /** + * Sets this SOAPFault object with the given fault code. + * + * Fault codes, which give information about the fault, are defined in= the + * SOAP 1.1 specification. A fault code is mandatory and must be of ty= pe + * QName. This method provides a convenient way to set a = fault + * code. For example, + * + * 
+     SOAPEnvelope se =3D ...;
+     // Create a qualified name in the SOAP namespace with a localName
+     // of "Client".  Note that prefix parameter is optional and is null
+     // here which causes the implementation to use an appropriate prefix.
+     Name qname =3D se.createName("Client", null,
+     SOAPConstants.URI_NS_SOAP_ENVELOPE);
+     SOAPFault fault =3D ...;
+     fault.setFaultCode(qname);
+     *
+     * It is preferable to use this method over setFaultCode(String).
+     *
+     * @param name a Name object giving the fault code to be =
set.
+     *              It must be namespace qualified.
+     * @throws SOAPException if there was an error in adding the
+     *              faultcode element to the underlying XML t=
ree
+     */
+    public abstract void setFaultCode(Name name) throws SOAPException;
+
+    /**
+     * Gets the mandatory SOAP 1.1 fault code for this SOAPFault
+     * object as a SAAJ Name object. The SOAP 1.1 specificati=
on
+     * requires the value of the "faultcode" element to be of type QName. =
This
+     * method returns the content of the element as a QName in the form of=
 a
+     * SAAJ Name object. This method should be used instead o=
f the
+     * getFaultCode() method since it allows applications to =
easily
+     * access the namespace name without additional parsing.
+     * 

+     * In the future, a QName object version of this method may also be ad=
ded.
+     * @return a Name representing the faultcode
+     */
+    public abstract Name getFaultCodeAsName();
+
+    /**
+     * Sets the fault string for this SOAPFault object to the=
 given
+     * string and localized to the given locale.
+     *
+     * @param faultString       a String giving an explanatio=
n of
+     *              the fault
+     * @param locale            a Locale object indicating th=
e
+     *              native language of the faultString
+     * @throws SOAPException    if there was an error in adding the
+     *              faultString to the underlying XML tree
+     */
+    public abstract void setFaultString(String faultString, Locale locale)=
 throws SOAPException;
+
+    /**
+     * Returns the optional detail element for this SOAPFault
+     * object.
+     *
+     * @return a Locale object indicating the native language=
 of
+     *              the fault string or null if no locale was
+     *              specified
+     */
+    public abstract Locale getFaultStringLocale();
+}

Added: webservices/axis/trunk/archive/java/scratch/ashu_jaya_venkat/saaj/sr=
c/javax/xml/soap/SOAPFaultElement.java
URL: http://svn.apache.org/viewcvs/webservices/axis/trunk/archive/java/scra=
tch/ashu_jaya_venkat/saaj/src/javax/xml/soap/SOAPFaultElement.java?rev=3D17=
9806&view=3Dauto
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D
--- webservices/axis/trunk/archive/java/scratch/ashu_jaya_venkat/saaj/src/j=
avax/xml/soap/SOAPFaultElement.java (added)
+++ webservices/axis/trunk/archive/java/scratch/ashu_jaya_venkat/saaj/src/j=
avax/xml/soap/SOAPFaultElement.java Fri Jun  3 07:54:42 2005
@@ -0,0 +1,26 @@
+/*
+ * Copyright 2001-2004 The Apache Software Foundation.
+ *=20
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *=20
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *=20
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied=
.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.xml.soap;
+
+/**
+ * A representation of the contents in
+ * a SOAPFault object.  The Detail interface
+ * is a SOAPFaultElement object that has been defined.
+ * 

+ * Content is added to a SOAPFaultElement using the
+ * SOAPElement method addTextNode.
+ */
+public interface SOAPFaultElement extends SOAPElement {}

Added: webservices/axis/trunk/archive/java/scratch/ashu_jaya_venkat/saaj/sr=
c/javax/xml/soap/SOAPHeader.java
URL: http://svn.apache.org/viewcvs/webservices/axis/trunk/archive/java/scra=
tch/ashu_jaya_venkat/saaj/src/javax/xml/soap/SOAPHeader.java?rev=3D179806&v=
iew=3Dauto
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D
--- webservices/axis/trunk/archive/java/scratch/ashu_jaya_venkat/saaj/src/j=
avax/xml/soap/SOAPHeader.java (added)
+++ webservices/axis/trunk/archive/java/scratch/ashu_jaya_venkat/saaj/src/j=
avax/xml/soap/SOAPHeader.java Fri Jun  3 07:54:42 2005
@@ -0,0 +1,149 @@
+/*
+ * Copyright 2001-2004 The Apache Software Foundation.
+ *=20
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *=20
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *=20
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied=
.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.xml.soap;
+
+import java.util.Iterator;
+
+/**
+ * 
A representation of the SOAP header element. A SOAP header
+ *   element consists of XML data that affects the way the
+ *   application-specific content is processed by the message
+ *   provider. For example, transaction semantics, authentication
+ *   information, and so on, can be specified as the content of a
+ *   SOAPHeader object.

+ *
+ *   
A SOAPEnvelope object contains an empty 
+ *   SOAPHeader object by default. If the 
+ *   SOAPHeader object, which is optional, is not needed, it
+ *   can be retrieved and deleted with the following line of code.
+ *   The variable se is a SOAPEnvelope
+ *   object.

+ * 
+ *     se.getHeader().detachNode();
+ * 

+ *   A SOAPHeader object is created with the 
+ *   SOAPEnvelope method addHeader. This method,
+ *   which creates a new header and adds it to the envelope, may be
+ *   called only after the existing header has been removed.
+ * 
+ *     se.getHeader().detachNode();
+ *     SOAPHeader sh =3D se.addHeader();
+ * 

+ *
+ *   
A SOAPHeader object can have only 
+ *   SOAPHeaderElement objects as its immediate children. The
+ *   method addHeaderElement creates a new 
+ *   HeaderElement object and adds it to the 
+ *   SOAPHeader object. In the following line of code, the
+ *   argument to the method addHeaderElement is a
+ *   Name object that is the name for the new 
+ *   HeaderElement object.

+ * 
+ *     SOAPHeaderElement shElement =3D sh.addHeaderElement(name);
+ * 

+ * @see SOAPHeaderElement SOAPHeaderElement
+ */
+public interface SOAPHeader extends SOAPElement {
+
+    /**
+     * Creates a new SOAPHeaderElement object
+     * initialized with the specified name and adds it to this
+     * SOAPHeader object.
+     * @param   name a Name object with
+     *     the name of the new SOAPHeaderElement
+     *     object
+     * @return the new SOAPHeaderElement object that
+     *     was inserted into this SOAPHeader
+     *     object
+     * @throws  SOAPException if a SOAP error occurs
+     */
+    public abstract SOAPHeaderElement addHeaderElement(Name name)
+        throws SOAPException;
+
+    /**
+     * Returns a list of all the SOAPHeaderElement
+     * objects in this SOAPHeader object that have the
+     * the specified actor. An actor is a global attribute that
+     * indicates the intermediate parties to whom the message should
+     * be sent. An actor receives the message and then sends it to
+     * the next actor. The default actor is the ultimate intended
+     * recipient for the message, so if no actor attribute is
+     * included in a SOAPHeader object, the message is
+     * sent to its ultimate destination.
+     * @param   actor  a String giving the
+     *     URI of the actor for which to search
+     * @return an Iterator object over all the 
+     *     SOAPHeaderElement objects that contain the
+     *     specified actor
+     * @see #extractHeaderElements(java.lang.String) extractHeaderElements=
(java.lang.String)
+     */
+    public abstract Iterator examineHeaderElements(String actor);
+
+    /**
+     * Returns a list of all the SOAPHeaderElement
+     *   objects in this SOAPHeader object that have
+     *   the the specified actor and detaches them from this 
+     *   SOAPHeader object.
+     *
+     *   
This method allows an actor to process only the parts of
+     *   the SOAPHeader object that apply to it and to
+     *   remove them before passing the message on to the next
+     *   actor.
+     * @param   actor  a String giving the
+     *     URI of the actor for which to search
+     * @return an Iterator object over all the 
+     *     SOAPHeaderElement objects that contain the
+     *     specified actor
+     * @see #examineHeaderElements(java.lang.String) examineHeaderElements=
(java.lang.String)
+     */
+    public abstract Iterator extractHeaderElements(String actor);
+
+    /**
+     * Returns an Iterator over all the
+     * SOAPHeaderElement objects in this SOAPHeader
+     * object that have the specified actor and that have a MustUnderstand
+     * attribute whose value is equivalent to true.
+     *
+     * @param actor a String giving the URI of the actor for =
which
+     *              to search
+     * @return an Iterator object over all the
+     *              SOAPHeaderElement objects that contain th=
e
+     *              specified actor and are marked as MustUnderstand
+     */
+    public abstract Iterator examineMustUnderstandHeaderElements(String ac=
tor);
+
+    /**
+     * Returns an Iterator over all the
+     * SOAPHeaderElement objects in this SOAPHeader
+     * object.
+     *
+     * @return an Iterator object over all the
+     *              SOAPHeaderElement objects contained by th=
is
+     *              SOAPHeader
+     */
+    public abstract Iterator examineAllHeaderElements();
+
+    /**
+     * Returns an Iterator over all the
+     * SOAPHeaderElement objects in this SOAPHeader 
+     * object and detaches them from this SOAPHeader object.
+     *
+     * @return an Iterator object over all the
+     *              SOAPHeaderElement objects contained by th=
is
+     *              SOAPHeader
+     */
+    public abstract Iterator extractAllHeaderElements();
+}

Added: webservices/axis/trunk/archive/java/scratch/ashu_jaya_venkat/saaj/sr=
c/javax/xml/soap/SOAPHeaderElement.java
URL: http://svn.apache.org/viewcvs/webservices/axis/trunk/archive/java/scra=
tch/ashu_jaya_venkat/saaj/src/javax/xml/soap/SOAPHeaderElement.java?rev=3D1=
79806&view=3Dauto
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D
--- webservices/axis/trunk/archive/java/scratch/ashu_jaya_venkat/saaj/src/j=
avax/xml/soap/SOAPHeaderElement.java (added)
+++ webservices/axis/trunk/archive/java/scratch/ashu_jaya_venkat/saaj/src/j=
avax/xml/soap/SOAPHeaderElement.java Fri Jun  3 07:54:42 2005
@@ -0,0 +1,77 @@
+/*
+ * Copyright 2001-2004 The Apache Software Foundation.
+ *=20
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *=20
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *=20
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied=
.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.xml.soap;
+
+/**
+ *     
An object representing the contents in the SOAP header part
+ *   of the SOAP envelope. The immediate children of a 
+ *   SOAPHeader object can be represented only as 
+ *   SOAPHeaderElement objects.

+ *
+ *   
A SOAPHeaderElement object can have other
+ *   SOAPElement objects as its children.

+ */
+public interface SOAPHeaderElement extends SOAPElement {
+
+    /**
+     * Sets the actor associated with this 
+     * SOAPHeaderElement object to the specified actor. The
+     * default value of an actor is: 
+     * SOAPConstants.URI_SOAP_ACTOR_NEXT
+     * @param  actorURI  a String giving
+     *     the URI of the actor to set
+     * @see #getActor() getActor()
+     * @throws java.lang.IllegalArgumentException if
+     *     there is a problem in setting the actor.
+     */
+    public abstract void setActor(String actorURI);
+
+    /**
+     * Returns the uri of the actor associated with this 
+     * SOAPHeaderElement object.
+     * @return  a String giving the URI of the
+     *     actor
+     * @see #setActor(java.lang.String) setActor(java.lang.String)
+     */
+    public abstract String getActor();
+
+    /**
+     * Sets the mustUnderstand attribute for this 
+     *   SOAPHeaderElement object to be on or off.
+     *
+     *   
If the mustUnderstand attribute is on, the actor who
+     *   receives the SOAPHeaderElement must process it
+     *   correctly. This ensures, for example, that if the 
+     *   SOAPHeaderElement object modifies the message, that
+     *   the message is being modified correctly.

+     * @param  mustUnderstand  true to
+     *     set the mustUnderstand attribute on; false
+     *     to turn if off
+     * @throws java.lang.IllegalArgumentException if
+     *     there is a problem in setting the actor.
+     * @see #getMustUnderstand() getMustUnderstand()
+     */
+    public abstract void setMustUnderstand(boolean mustUnderstand);
+
+    /**
+     * Returns whether the mustUnderstand attribute for this
+     * SOAPHeaderElement object is turned on.
+     * @return  true if the mustUnderstand attribute of
+     *     this SOAPHeaderElement object is turned on;
+     *     false otherwise
+     */
+    public abstract boolean getMustUnderstand();
+}

Added: webservices/axis/trunk/archive/java/scratch/ashu_jaya_venkat/saaj/sr=
c/javax/xml/soap/SOAPMessage.java
URL: http://svn.apache.org/viewcvs/webservices/axis/trunk/archive/java/scra=
tch/ashu_jaya_venkat/saaj/src/javax/xml/soap/SOAPMessage.java?rev=3D179806&=
view=3Dauto
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D
--- webservices/axis/trunk/archive/java/scratch/ashu_jaya_venkat/saaj/src/j=
avax/xml/soap/SOAPMessage.java (added)
+++ webservices/axis/trunk/archive/java/scratch/ashu_jaya_venkat/saaj/src/j=
avax/xml/soap/SOAPMessage.java Fri Jun  3 07:54:42 2005
@@ -0,0 +1,378 @@
+/*
+ * Copyright 2001-2004 The Apache Software Foundation.
+ *=20
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *=20
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *=20
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied=
.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.xml.soap;
+
+//import javax.activation.DataHandler;
+import java.io.IOException;
+import java.io.OutputStream;
+import java.util.Iterator;
+
+/**
+ * 
The root class for all SOAP messages. As transmitted on the
+ * "wire", a SOAP message is an XML document or a MIME message
+ * whose first body part is an XML/SOAP document.

+ *
+ * 
A SOAPMessage object consists of a SOAP part
+ * and optionally one or more attachment parts. The SOAP part for
+ * a SOAPMessage object is a SOAPPart
+ * object, which contains information used for message routing and
+ * identification, and which can contain application-specific
+ * content. All data in the SOAP Part of a message must be in XML
+ * format.

+ *
+ * 
A new SOAPMessage object contains the following
+ * by default:

+ *
+ * 
    
+ *  
  • A SOAPPart object
    • 
+ *
+ *  
  • A SOAPEnvelope object
    • 
+ *
+ *  
  • A SOAPBody object
    • 
+ *
+ *  
  • A SOAPHeader object
    • 
+ * 

+ * The SOAP part of a message can be retrieved by calling the
+ * method SOAPMessage.getSOAPPart(). The 
+ * SOAPEnvelope object is retrieved from the 
+ * SOAPPart object, and the SOAPEnvelope
+ * object is used to retrieve the SOAPBody and 
+ * SOAPHeader objects.
+ * 
+ * SOAPPart sp =3D message.getSOAPPart();
+ * SOAPEnvelope se =3D sp.getEnvelope();
+ * SOAPBody sb =3D se.getBody();
+ * SOAPHeader sh =3D se.getHeader();
+ * 

+ *
+ * 
In addition to the mandatory SOAPPart object, a
+ * SOAPMessage object may contain zero or more 
+ * AttachmentPart objects, each of which contains
+ * application-specific data. The SOAPMessage
+ * interface provides methods for creating 
+ * AttachmentPart objects and also for adding them to a
+ * SOAPMessage object. A party that has received a
+ * SOAPMessage object can examine its contents by
+ * retrieving individual attachment parts.

+ *
+ * 
Unlike the rest of a SOAP message, an attachment is not
+ * required to be in XML format and can therefore be anything from
+ * simple text to an image file. Consequently, any message content
+ * that is not in XML format must be in an 
+ * AttachmentPart object.

+ *
+ * 
A MessageFactory object creates new 
+ * SOAPMessage objects. If the MessageFactory
+ * object was initialized with a messaging Profile, it produces
+ * SOAPMessage objects that conform to that Profile.
+ * For example, a SOAPMessage object created by a
+ * MessageFactory object initialized with the ebXML
+ * Profile will have the appropriate ebXML headers.

+ * @see MessageFactory MessageFactory
+ * @see AttachmentPart AttachmentPart
+ */
+public abstract class SOAPMessage {
+
+    public SOAPMessage() {}
+
+    /**
+     * Retrieves a description of this SOAPMessage
+     * object's content.
+     * @return  a String describing the content of this
+     *     message or null if no description has been
+     *     set
+     * @see #setContentDescription(java.lang.String) setContentDescription=
(java.lang.String)
+     */
+    public abstract String getContentDescription();
+
+    /**
+     * Sets the description of this SOAPMessage
+     * object's content with the given description.
+     * @param  description a String
+     *     describing the content of this message
+     * @see #getContentDescription() getContentDescription()
+     */
+    public abstract void setContentDescription(String description);
+
+    /**
+     * Gets the SOAP part of this SOAPMessage object.
+     *
+     *
+     *   
If a SOAPMessage object contains one or
+     *   more attachments, the SOAP Part must be the first MIME body
+     *   part in the message.

+     * @return the SOAPPart object for this 
+     *     SOAPMessage object
+     */
+    public abstract SOAPPart getSOAPPart();
+
+    /**
+     * Removes all AttachmentPart objects that have
+     *   been added to this SOAPMessage object.
+     *
+     *   
This method does not touch the SOAP part.

+     */
+    public abstract void removeAllAttachments();
+
+    /**
+     * Gets a count of the number of attachments in this
+     * message. This count does not include the SOAP part.
+     * @return  the number of AttachmentPart objects
+     *     that are part of this SOAPMessage
+     *     object
+     */
+    public abstract int countAttachments();
+
+    /**
+     * Retrieves all the AttachmentPart objects
+     * that are part of this SOAPMessage object.
+     * @return  an iterator over all the attachments in this
+     *     message
+     */
+    public abstract Iterator getAttachments();
+
+    /**
+     * Retrieves all the AttachmentPart objects
+     * that have header entries that match the specified headers.
+     * Note that a returned attachment could have headers in
+     * addition to those specified.
+     * @param   headers a MimeHeaders
+     *     object containing the MIME headers for which to
+     *     search
+     * @return an iterator over all attachments that have a header
+     *     that matches one of the given headers
+     */
+    public abstract Iterator getAttachments(MimeHeaders headers);
+
+    /**
+     * Adds the given AttachmentPart object to this
+     * SOAPMessage object. An 
+     * AttachmentPart object must be created before it can be
+     * added to a message.
+     * @param  attachmentpart an 
+     *     AttachmentPart object that is to become part of
+     *     this SOAPMessage object
+     * @throws java.lang.IllegalArgumentException
+     */
+    public abstract void addAttachmentPart(AttachmentPart attachmentpart);
+
+    /**
+     * Creates a new empty AttachmentPart object.
+     * Note that the method addAttachmentPart must be
+     * called with this new AttachmentPart object as
+     * the parameter in order for it to become an attachment to this
+     * SOAPMessage object.
+     * @return  a new AttachmentPart object that can be
+     *     populated and added to this SOAPMessage
+     *     object
+     */
+    public abstract AttachmentPart createAttachmentPart();
+
+    /**
+     * Creates an AttachmentPart object and
+     * populates it using the given DataHandler
+     * object.
+     * @param   datahandler  the 
+     *     javax.activation.DataHandler object that will
+     *     generate the content for this SOAPMessage
+     *     object
+     * @return a new AttachmentPart object that
+     *     contains data generated by the given 
+     *     DataHandler object
+     * @throws java.lang.IllegalArgumentException if
+     *     there was a problem with the specified 
+     *     DataHandler object
+     * @see DataHandler DataHandler
+     * @see javax.activation.DataContentHandler DataContentHandler
+     */
+    /*public AttachmentPart createAttachmentPart(DataHandler datahandler) =
{
+
+        AttachmentPart attachmentpart =3D createAttachmentPart();
+
+        attachmentpart.setDataHandler(datahandler);
+
+        return attachmentpart;
+    }*/
+
+    /**
+     * Returns all the transport-specific MIME headers for this
+     * SOAPMessage object in a transport-independent
+     * fashion.
+     * @return a MimeHeaders object containing the
+     *     MimeHeader objects
+     */
+    public abstract MimeHeaders getMimeHeaders();
+
+    /**
+     * Creates an AttachmentPart object and
+     * populates it with the specified data of the specified content
+     * type.
+     * @param   content  an Object
+     *     containing the content for this SOAPMessage
+     *     object
+     * @param   contentType a String
+     *     object giving the type of content; examples are
+     *     "text/xml", "text/plain", and "image/jpeg"
+     * @return a new AttachmentPart object that
+     *     contains the given data
+     * @throws java.lang.IllegalArgumentException if the contentType does =
not match the type of the content
+     *     object, or if there was no 
+     *     DataContentHandler object for the given content
+     *     object
+     * @see DataHandler DataHandler
+     * @see javax.activation.DataContentHandler DataContentHandler
+     */
+    public AttachmentPart createAttachmentPart(Object content,
+                                               String contentType) {
+
+        AttachmentPart attachmentpart =3D createAttachmentPart();
+
+        attachmentpart.setContent(content, contentType);
+
+        return attachmentpart;
+    }
+
+    /**
+     * Updates this SOAPMessage object with all the
+     *   changes that have been made to it. This method is called
+     *   automatically when a message is sent or written to by the
+     *   methods ProviderConnection.send, 
+     *   SOAPConnection.call, or 
+     *   SOAPMessage.writeTo. However, if changes are made to
+     *   a message that was received or to one that has already been
+     *   sent, the method saveChanges needs to be
+     *   called explicitly in order to save the changes. The method
+     *   saveChanges also generates any changes that
+     *   can be read back (for example, a MessageId in profiles that
+     *   support a message id). All MIME headers in a message that
+     *   is created for sending purposes are guaranteed to have
+     *   valid values only after saveChanges has been
+     *   called.
+     *
+     *   
In addition, this method marks the point at which the
+     *   data from all constituent AttachmentPart
+     *   objects are pulled into the message.

+     * @throws  SOAPException if there
+     *     was a problem saving changes to this message.
+     */
+    public abstract void saveChanges() throws SOAPException;
+
+    /**
+     * Indicates whether this SOAPMessage object
+     * has had the method saveChanges called on
+     * it.
+     * @return true if saveChanges has
+     *     been called on this message at least once; 
+     *     false otherwise.
+     */
+    public abstract boolean saveRequired();
+
+    /**
+     * Writes this SOAPMessage object to the given
+     *   output stream. The externalization format is as defined by
+     *   the SOAP 1.1 with Attachments specification.
+     *
+     *   
If there are no attachments, just an XML stream is
+     *   written out. For those messages that have attachments,
+     *   writeTo writes a MIME-encoded byte stream.

+     * @param   out the OutputStream
+     *     object to which this SOAPMessage object will
+     *     be written
+     * @throws  SOAPException  if there was a problem in
+     *     externalizing this SOAP message
+     * @throws  IOException  if an I/O error
+     *     occurs
+     */
+    public abstract void writeTo(OutputStream out)
+        throws SOAPException, IOException;
+
+    /**
+     * Gets the SOAP Body contained in this SOAPMessage objec=
t=2E
+     *
+     * @return the SOAPBody object contained by this
+     *              SOAPMessage object
+     * @throws SOAPException if the SOAP Body does not exist or cannot be
+     *              retrieved
+     */
+    public SOAPBody getSOAPBody() throws SOAPException {
+        throw new UnsupportedOperationException("getSOAPBody must be overr=
idden in subclasses of SOAPMessage");       =20
+    }
+
+    /**
+     * Gets the SOAP Header contained in this SOAPMessage obj=
ect.
+     *
+     * @return the SOAPHeader object contained by this
+     *              SOAPMessage object
+     * @throws SOAPException  if the SOAP Header does not exist or cannot =
be
+     *              retrieved
+     */
+    public SOAPHeader getSOAPHeader() throws SOAPException {
+        throw new UnsupportedOperationException("getSOAPHeader must be ove=
rridden in subclasses of SOAPMessage");       =20
+    }
+
+    /**
+     * Associates the specified value with the specified property. If ther=
e was
+     * already a value associated with this property, the old value is rep=
laced.
+     * 

+     * The valid property names include WRITE_XML_DECLARATION=
 and
+     * CHARACTER_SET_ENCODING. All of these standard SAAJ
+     * properties are prefixed by "javax.xml.soap". Vendors may also add
+     * implementation specific properties. These properties must be prefix=
ed
+     * with package names that are unique to the vendor.
+     * 

+     * Setting the property WRITE_XML_DECLARATION to
+     * "true" will cause an XML Declaration to be written out=
 at
+     * the start of the SOAP message. The default value of "false" suppres=
ses
+     * this declaration.
+     * 

+     * The property CHARACTER_SET_ENCODING defaults to the va=
lue
+     * "utf-8" which causes the SOAP message to be encoded us=
ing
+     * UTF-8. Setting CHARACTER_SET_ENCODING to
+     * "utf-16" causes the SOAP message to be encoded using U=
TF-16.
+     * 

+     * Some implementations may allow encodings in addition to UTF-8 and U=
TF-16.
+     * Refer to your vendor's documentation for details.
+     *
+     * @param property the property with which the specified value is to b=
e
+     *              associated
+     * @param value the value to be associated with the specified property
+     * @throws SOAPException if the property name is not recognized
+     */
+    public void setProperty(String property, Object value)
+            throws SOAPException  {
+        throw new UnsupportedOperationException("setProperty must be overr=
idden in subclasses of SOAPMessage");       =20
+    }
+
+    /**
+     * Retrieves value of the specified property.
+     *
+     * @param property the name of the property to retrieve
+     * @return the value of the property or null if no such
+     *              property exists
+     * @throws SOAPException  if the property name is not recognized
+     */
+    public Object getProperty(String property) throws SOAPException {
+        throw new UnsupportedOperationException("getProperty must be overr=
idden in subclasses of SOAPMessage");       =20
+    }
+
+    /** Specifies the character type encoding for the SOAP Message. */
+    public static final String CHARACTER_SET_ENCODING
+            =3D "javax.xml.soap.character-set-encoding";
+
+    /** Specifies whether the SOAP Message should contain an XML declarati=
on. */
+    public static final String WRITE_XML_DECLARATION
+            =3D "javax.xml.soap.write-xml-declaration";
+}