KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > soap > messaging > Message


1 /*
2  * The Apache Software License, Version 1.1
3  *
4  *
5  * Copyright (c) 2000 The Apache Software Foundation. All rights
6  * reserved.
7  *
8  * Redistribution and use in source and binary forms, with or without
9  * modification, are permitted provided that the following conditions
10  * are met:
11  *
12  * 1. Redistributions of source code must retain the above copyright
13  * notice, this list of conditions and the following disclaimer.
14  *
15  * 2. Redistributions in binary form must reproduce the above copyright
16  * notice, this list of conditions and the following disclaimer in
17  * the documentation and/or other materials provided with the
18  * distribution.
19  *
20  * 3. The end-user documentation included with the redistribution,
21  * if any, must include the following acknowledgment:
22  * "This product includes software developed by the
23  * Apache Software Foundation (http://www.apache.org/)."
24  * Alternately, this acknowledgment may appear in the software itself,
25  * if and wherever such third-party acknowledgments normally appear.
26  *
27  * 4. The names "SOAP" and "Apache Software Foundation" must
28  * not be used to endorse or promote products derived from this
29  * software without prior written permission. For written
30  * permission, please contact apache@apache.org.
31  *
32  * 5. Products derived from this software may not be called "Apache",
33  * nor may "Apache" appear in their name, without prior written
34  * permission of the Apache Software Foundation.
35  *
36  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
37  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
38  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
39  * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
40  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
41  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
42  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
43  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
44  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
45  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
46  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
47  * SUCH DAMAGE.
48  * ====================================================================
49  *
50  * This software consists of voluntary contributions made by many
51  * individuals on behalf of the Apache Software Foundation and was
52  * originally based on software copyright (c) 2000, International
53  * Business Machines, Inc., http://www.apache.org. For more
54  * information on the Apache Software Foundation, please see
55  * <http://www.apache.org/>.
56  */
57
58 package org.apache.soap.messaging;
59
60 import java.io.*;
61 import java.util.*;
62 import java.net.URL JavaDoc;
63 import javax.xml.parsers.*;
64 import org.w3c.dom.*;
65 import org.xml.sax.*;
66 import org.apache.soap.util.*;
67 import org.apache.soap.util.xml.*;
68 import org.apache.soap.rpc.SOAPContext;
69 import org.apache.soap.rpc.Call;
70 import org.apache.soap.*;
71 import org.apache.soap.transport.*;
72 import org.apache.soap.transport.http.*;
73 import javax.mail.*;
74 import javax.mail.internet.*;
75 import javax.activation.*;
76
77 /**
78  * A <code>Message</code> is the class whose instances represent
79  * one-way messages in SOAP. While messages are one-way, they are
80  * sometimes carried on two-way transports such as HTTP. To accomodate
81  * that, the API supported here has a "receive" method as well - that
82  * is only applicable if the transport that is being used supports
83  * the receive() method (@see org.apache.soap.transport.SOAPTransport)
84  * so that this API can get at the 'response' envelope.
85  *
86  * @author Sanjiva Weerawarana (sanjiva@watson.ibm.com)
87  */
88 public class Message {
89   SOAPTransport st;
90   SOAPContext reqCtx = new SOAPContext (), resCtx = null;
91   DocumentBuilder xdb = XMLParserUtils.getXMLDocBuilder();
92
93   public Message () {
94   }
95
96   public void setSOAPTransport (SOAPTransport st) {
97     this.st = st;
98   }
99    
100   public SOAPTransport getSOAPTransport () {
101     return st;
102   }
103
104   /**
105    * Send an envelope to the given URL via the SOAPTransport that has
106    * been configured for this instance (or SOAPHTTPConnection by default).
107    * The envelope is sent exactly as-is.
108    *
109    * @param url the url to send to
110    * @param actionURI the value of the SOAPAction header
111    * @param env envelope to send
112    *
113    * @exception SOAPException if something goes wrong.
114    */
115   public void send (URL JavaDoc url, String JavaDoc actionURI, Envelope env)
116        throws SOAPException {
117     // Construct default HTTP transport if not specified.
118 if (st == null) {
119       st = new SOAPHTTPConnection ();
120     }
121
122     // Send request.
123 st.send (url, actionURI, null, env, null, reqCtx);
124   }
125
126   /**
127    * Receive an envelope from the given transport. Only applicable
128    * where the transport supports the receive method.
129    * If the (root part of) the response does not have text/xml as the
130    * Content-Type, null will be returned. If the response is not a
131    * SOAP envelope, receive() should be used instead.
132    * @return the envelope received
133    * @exception SOAPException if something goes wrong
134    * @see #receive()
135    */
136   public Envelope receiveEnvelope () throws SOAPException {
137     if (st == null) {
138       throw new SOAPException (Constants.FAULT_CODE_CLIENT,
139                                "Unable to receive without sending on an " +
140                                "appropriate transport.");
141     }
142     try {
143       resCtx = st.getResponseSOAPContext ();
144       String JavaDoc payloadStr = Call.getEnvelopeString (st);
145
146       Document doc =
147           xdb.parse(new InputSource(new StringReader(payloadStr)));
148
149       if (doc == null) {
150         throw new SOAPException (Constants.FAULT_CODE_CLIENT,
151                                  "Parsing error, response was:\n" +
152                                   payloadStr);
153       }
154
155       return Envelope.unmarshall (doc.getDocumentElement (), resCtx);
156     } catch (MessagingException me) {
157       throw new SOAPException (Constants.FAULT_CODE_CLIENT, me.getMessage (),
158                               me);
159     } catch (SAXException ioe) {
160       throw new SOAPException (Constants.FAULT_CODE_CLIENT,
161                                "Parsing error, response was:\n" +
162                                ioe.getMessage(), ioe);
163     } catch (IOException ioe) {
164       throw new SOAPException (Constants.FAULT_CODE_CLIENT, ioe.getMessage (),
165                                ioe);
166     } catch (IllegalArgumentException JavaDoc e) {
167       throw new SOAPException (Constants.FAULT_CODE_CLIENT, e.getMessage (),
168                                e);
169     }
170   }
171
172   /**
173    * Receive a response from the given transport. Only applicable
174    * where the transport supports the receive method.
175    * @return the root part of the response as a DataHandler
176    * @exception SOAPException if something goes wrong
177    * @see #receive()
178    */
179   public DataHandler receive() throws SOAPException, MessagingException {
180     if (st == null) {
181       throw new SOAPException(Constants.FAULT_CODE_CLIENT,
182                               "Unable to receive without sending on an " +
183                               "appropriate transport.");
184     }
185     st.receive();
186     resCtx = st.getResponseSOAPContext();
187     return resCtx.getRootPart().getDataHandler();
188   }
189
190   /**
191    * Get the request SOAPContext.
192    * @return SOAPContext
193    */
194   public SOAPContext getRequestSOAPContext() {
195     return reqCtx;
196   }
197
198   /**
199    * Add a MIME BodyPart to the request MIME envelope.
200    *
201    * @param part The Part to be appended
202    * @exception MessagingException
203    */
204   public void addBodyPart(MimeBodyPart part) throws MessagingException {
205     reqCtx.addBodyPart(part);
206   }
207
208   /**
209    * Get the response SOAPContext.
210    * @return SOAPContext
211    */
212   public SOAPContext getResponseSOAPContext() {
213     return resCtx;
214   }
215
216   /**
217    * Find the MIME part referred to by the given URI in the response MIME
218    * envelope. This can be:<ul>
219    * <li>An absolute URI, in which case a part is located with a
220    * corresponding Content-Location header.
221    * <li>A relative URI, in which case an absolute URI is constructed
222    * relative to the Content-Location header of the root SOAP part
223    * or the multipart and the previous rule is then applied.
224    * <li>A URI of the format "cid:xxx"> in which case a part is located
225    * with a matching Content-ID header.
226    * </ul>Returns null if the part is not found.
227    * <p>Note: relative URIs not entirely implemented yet.
228    *
229    * @param uri the URI
230    * @return the Part or null if not found
231    */
232   public MimeBodyPart findBodyPart(String JavaDoc uri) {
233     if (resCtx == null)
234       return null;
235     else
236       return resCtx.findBodyPart(uri);
237   }
238
239   /**
240    * Return the number of enclosed BodyPart objects in the response MIME
241    * envelope.
242    *
243    * @return number of parts
244    * @exception MessagingException
245    */
246   public int getPartCount() throws MessagingException {
247     if (resCtx == null)
248       return 0;
249     else
250       return resCtx.getCount();
251   }
252
253   /**
254    * Get the specified Part in the reponse MIME envelope by its index.
255    * Parts are numbered starting at 0.
256    *
257    * @param index the index of the desired Part
258    * @return the Part
259    * @exception IndexOutOfBoundsException if no such Part exists
260    */
261   public MimeBodyPart getBodyPart(int index) throws IndexOutOfBoundsException JavaDoc {
262     if (resCtx == null)
263       return null;
264     else
265       return resCtx.getBodyPart(index);
266   }
267
268   /**
269    * Get the root Part of the reponse MIME envelope, or the only part if the
270    * response wasn't multipart.
271    *
272    * @return the Part
273    */
274   public MimeBodyPart getRootPart() throws MessagingException {
275     if (resCtx == null)
276       return null;
277     else
278       return resCtx.getRootPart();
279   }
280 }
281
Popular Tags