001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one
003: * or more contributor license agreements. See the NOTICE file
004: * distributed with this work for additional information
005: * regarding copyright ownership. The ASF licenses this file
006: * to you under the Apache License, Version 2.0 (the
007: * "License"); you may not use this file except in compliance
008: * with the License. You may obtain a copy of the License at
009: *
010: * http://www.apache.org/licenses/LICENSE-2.0
011: *
012: * Unless required by applicable law or agreed to in writing,
013: * software distributed under the License is distributed on an
014: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015: * KIND, either express or implied. See the License for the
016: * specific language governing permissions and limitations
017: * under the License.
018: */
019: package javax.xml.soap;
020:
021: /**
022: * The container for the SOAPHeader and SOAPBody portions of a <CODE>SOAPPart</CODE> object. By
023: * default, a <CODE> SOAPMessage</CODE> object is created with a <CODE> SOAPPart</CODE> object that
024: * has a <CODE>SOAPEnvelope</CODE> object. The <CODE>SOAPEnvelope</CODE> object by default has an
025: * empty <CODE>SOAPBody</CODE> object and an empty <CODE> SOAPHeader</CODE> object. The
026: * <CODE>SOAPBody</CODE> object is required, and the <CODE>SOAPHeader</CODE> object, though
027: * optional, is used in the majority of cases. If the <CODE> SOAPHeader</CODE> object is not needed,
028: * it can be deleted, which is shown later.</P>
029: * <p/>
030: * <P>A client can access the <CODE>SOAPHeader</CODE> and <CODE> SOAPBody</CODE> objects by calling
031: * the methods <CODE> SOAPEnvelope.getHeader</CODE> and <CODE> SOAPEnvelope.getBody</CODE>. The
032: * following lines of code use these two methods after starting with the <CODE> SOAPMessage</CODE>
033: * object <I>message</I> to get the <CODE> SOAPPart</CODE> object <I>sp</I>, which is then used to
034: * get the <CODE>SOAPEnvelope</CODE> object <I>se</I>.</P> <PRE> SOAPPart sp =
035: * message.getSOAPPart(); SOAPEnvelope se = sp.getEnvelope(); SOAPHeader sh = se.getHeader();
036: * SOAPBody sb = se.getBody(); </PRE>
037: * <p/>
038: * <P>It is possible to change the body or header of a <CODE> SOAPEnvelope</CODE> object by
039: * retrieving the current one, deleting it, and then adding a new body or header. The <CODE>
040: * javax.xml.soap.Node</CODE> method <CODE>detachNode</CODE> detaches the XML element (node) on
041: * which it is called. For example, the following line of code deletes the <CODE> SOAPBody</CODE>
042: * object that is retrieved by the method <CODE> getBody</CODE>.</P> <PRE>
043: * se.getBody().detachNode(); </PRE> To create a <CODE>SOAPHeader</CODE> object to replace the one
044: * that was removed, a client uses the method <CODE> SOAPEnvelope.addHeaderBlock</CODE>, which
045: * creates a new header and adds it to the <CODE>SOAPEnvelope</CODE> object. Similarly, the method
046: * <CODE>addBody</CODE> creates a new <CODE>SOAPBody</CODE> object and adds it to the
047: * <CODE>SOAPEnvelope</CODE> object. The following code fragment retrieves the current header,
048: * removes it, and adds a new one. Then it retrieves the current body, removes it, and adds a new
049: * one. <PRE> SOAPPart sp = message.getSOAPPart(); SOAPEnvelope se = sp.getEnvelope();
050: * se.getHeader().detachNode(); SOAPHeader sh = se.addHeaderBlock(); se.getBody().detachNode();
051: * SOAPBody sb = se.addBody(); </PRE> It is an error to add a <CODE>SOAPBody</CODE> or <CODE>
052: * SOAPHeader</CODE> object if one already exists.
053: * <p/>
054: * <P>The <CODE>SOAPEnvelope</CODE> interface provides three methods for creating <CODE>Name</CODE>
055: * objects. One method creates <CODE>Name</CODE> objects with a local name, a namespace prefix, and
056: * a namesapce URI. The second method creates <CODE>Name</CODE> objects with a local name and a
057: * namespace prefix, and the third creates <CODE>Name</CODE> objects with just a local name. The
058: * following line of code, in which <I>se</I> is a <CODE>SOAPEnvelope</CODE> object, creates a new
059: * <CODE>Name</CODE> object with all three.</P> <PRE> Name name = se.createName("GetLastTradePrice",
060: * "WOMBAT", "http://www.wombat.org/trader"); </PRE>
061: */
062: public interface SOAPEnvelope extends SOAPElement {
063:
064: /**
065: * Creates a new <CODE>Name</CODE> object initialized with the given local name, namespace
066: * prefix, and namespace URI.
067: * <p/>
068: * <P>This factory method creates <CODE>Name</CODE> objects for use in the SOAP/XML document.
069: *
070: * @param localName a <CODE>String</CODE> giving the local name
071: * @param prefix a <CODE>String</CODE> giving the prefix of the namespace
072: * @param uri a <CODE>String</CODE> giving the URI of the namespace
073: * @return a <CODE>Name</CODE> object initialized with the given local name, namespace prefix,
074: * and namespace URI
075: * @throws SOAPException if there is a SOAP error
076: */
077: public abstract Name createName(String localName, String prefix,
078: String uri) throws SOAPException;
079:
080: /**
081: * Creates a new <CODE>Name</CODE> object initialized with the given local name.
082: * <p/>
083: * <P>This factory method creates <CODE>Name</CODE> objects for use in the SOAP/XML document.
084: *
085: * @param localName a <CODE>String</CODE> giving the local name
086: * @return a <CODE>Name</CODE> object initialized with the given local name
087: * @throws SOAPException if there is a SOAP error
088: */
089: public abstract Name createName(String localName)
090: throws SOAPException;
091:
092: /**
093: * Returns the <CODE>SOAPHeader</CODE> object for this <CODE> SOAPEnvelope</CODE> object.
094: * <p/>
095: * <P>A new <CODE>SOAPMessage</CODE> object is by default created with a
096: * <CODE>SOAPEnvelope</CODE> object that contains an empty <CODE>SOAPHeader</CODE> object. As a
097: * result, the method <CODE>getHeader</CODE> will always return a <CODE>SOAPHeader</CODE> object
098: * unless the header has been removed and a new one has not been added.
099: *
100: * @return the <CODE>SOAPHeader</CODE> object or <CODE> null</CODE> if there is none
101: * @throws SOAPException if there is a problem obtaining the <CODE>SOAPHeader</CODE> object
102: */
103: public abstract SOAPHeader getHeader() throws SOAPException;
104:
105: /**
106: * Returns the <CODE>SOAPBody</CODE> object associated with this <CODE>SOAPEnvelope</CODE>
107: * object.
108: * <p/>
109: * <P>A new <CODE>SOAPMessage</CODE> object is by default created with a
110: * <CODE>SOAPEnvelope</CODE> object that contains an empty <CODE>SOAPBody</CODE> object. As a
111: * result, the method <CODE>getBody</CODE> will always return a <CODE>SOAPBody</CODE> object
112: * unless the body has been removed and a new one has not been added.
113: *
114: * @return the <CODE>SOAPBody</CODE> object for this <CODE> SOAPEnvelope</CODE> object or
115: * <CODE>null</CODE> if there is none
116: * @throws SOAPException if there is a problem obtaining the <CODE>SOAPBody</CODE> object
117: */
118: public abstract SOAPBody getBody() throws SOAPException;
119:
120: /**
121: * Creates a <CODE>SOAPHeader</CODE> object and sets it as the <CODE>SOAPHeader</CODE> object
122: * for this <CODE> SOAPEnvelope</CODE> object.
123: * <p/>
124: * <P>It is illegal to add a header when the envelope already contains a header. Therefore, this
125: * method should be called only after the existing header has been removed.
126: *
127: * @return the new <CODE>SOAPHeader</CODE> object
128: * @throws SOAPException if this <CODE> SOAPEnvelope</CODE> object already contains a valid
129: * <CODE>SOAPHeader</CODE> object
130: */
131: public abstract SOAPHeader addHeader() throws SOAPException;
132:
133: /**
134: * Creates a <CODE>SOAPBody</CODE> object and sets it as the <CODE>SOAPBody</CODE> object for
135: * this <CODE> SOAPEnvelope</CODE> object.
136: * <p/>
137: * <P>It is illegal to add a body when the envelope already contains a body. Therefore, this
138: * method should be called only after the existing body has been removed.
139: *
140: * @return the new <CODE>SOAPBody</CODE> object
141: * @throws SOAPException if this <CODE> SOAPEnvelope</CODE> object already contains a valid
142: * <CODE>SOAPBody</CODE> object
143: */
144: public abstract SOAPBody addBody() throws SOAPException;
145: }
|