Message is the class whose instances represent
* one-way messages in SOAP. While messages are one-way, they are
* sometimes carried on two-way transports such as HTTP. To accomodate
* that, the API supported here has a "receive" method as well - that
* is only applicable if the transport that is being used supports
* the receive() method (@see org.apache.soap.transport.SOAPTransport)
* so that this API can get at the 'response' envelope.
*
* @author Sanjiva Weerawarana (sanjiva@watson.ibm.com)
*/
public class Message {
SOAPTransport st;
SOAPContext reqCtx = new SOAPContext (), resCtx = null;
DocumentBuilder xdb = XMLParserUtils.getXMLDocBuilder();
public Message () {
}
public void setSOAPTransport (SOAPTransport st) {
this.st = st;
}
public SOAPTransport getSOAPTransport () {
return st;
}
/**
* Send an envelope to the given URL via the SOAPTransport that has
* been configured for this instance (or SOAPHTTPConnection by default).
* The envelope is sent exactly as-is.
*
* @param url the url to send to
* @param actionURI the value of the SOAPAction header
* @param env envelope to send
*
* @exception SOAPException if something goes wrong.
*/
public void send (URL url, String actionURI, Envelope env)
throws SOAPException {
// Construct default HTTP transport if not specified.
if (st == null) {
st = new SOAPHTTPConnection ();
}
// Send request.
st.send (url, actionURI, null, env, null, reqCtx);
}
/**
* Receive an envelope from the given transport. Only applicable
* where the transport supports the receive method.
* If the (root part of) the response does not have text/xml as the
* Content-Type, null will be returned. If the response is not a
* SOAP envelope, receive() should be used instead.
* @return the envelope received
* @exception SOAPException if something goes wrong
* @see #receive()
*/
public Envelope receiveEnvelope () throws SOAPException {
if (st == null) {
throw new SOAPException (Constants.FAULT_CODE_CLIENT,
"Unable to receive without sending on an " +
"appropriate transport.");
}
try {
resCtx = st.getResponseSOAPContext ();
String payloadStr = Call.getEnvelopeString (st);
Document doc =
xdb.parse(new InputSource(new StringReader(payloadStr)));
if (doc == null) {
throw new SOAPException (Constants.FAULT_CODE_CLIENT,
"Parsing error, response was:\n" +
payloadStr);
}
return Envelope.unmarshall (doc.getDocumentElement (), resCtx);
} catch (MessagingException me) {
throw new SOAPException (Constants.FAULT_CODE_CLIENT, me.getMessage (),
me);
} catch (SAXException ioe) {
throw new SOAPException (Constants.FAULT_CODE_CLIENT,
"Parsing error, response was:\n" +
ioe.getMessage(), ioe);
} catch (IOException ioe) {
throw new SOAPException (Constants.FAULT_CODE_CLIENT, ioe.getMessage (),
ioe);
} catch (IllegalArgumentException e) {
throw new SOAPException (Constants.FAULT_CODE_CLIENT, e.getMessage (),
e);
}
}
/**
* Receive a response from the given transport. Only applicable
* where the transport supports the receive method.
* @return the root part of the response as a DataHandler
* @exception SOAPException if something goes wrong
* @see #receive()
*/
public DataHandler receive() throws SOAPException, MessagingException {
if (st == null) {
throw new SOAPException(Constants.FAULT_CODE_CLIENT,
"Unable to receive without sending on an " +
"appropriate transport.");
}
st.receive();
resCtx = st.getResponseSOAPContext();
return resCtx.getRootPart().getDataHandler();
}
/**
* Get the request SOAPContext.
* @return SOAPContext
*/
public SOAPContext getRequestSOAPContext() {
return reqCtx;
}
/**
* Add a MIME BodyPart to the request MIME envelope.
*
* @param part The Part to be appended
* @exception MessagingException
*/
public void addBodyPart(MimeBodyPart part) throws MessagingException {
reqCtx.addBodyPart(part);
}
/**
* Get the response SOAPContext.
* @return SOAPContext
*/
public SOAPContext getResponseSOAPContext() {
return resCtx;
}
/**
* Find the MIME part referred to by the given URI in the response MIME
* envelope. This can be:Note: relative URIs not entirely implemented yet. * * @param uri the URI * @return the Part or null if not found */ public MimeBodyPart findBodyPart(String uri) { if (resCtx == null) return null; else return resCtx.findBodyPart(uri); } /** * Return the number of enclosed BodyPart objects in the response MIME * envelope. * * @return number of parts * @exception MessagingException */ public int getPartCount() throws MessagingException { if (resCtx == null) return 0; else return resCtx.getCount(); } /** * Get the specified Part in the reponse MIME envelope by its index. * Parts are numbered starting at 0. * * @param index the index of the desired Part * @return the Part * @exception IndexOutOfBoundsException if no such Part exists */ public MimeBodyPart getBodyPart(int index) throws IndexOutOfBoundsException { if (resCtx == null) return null; else return resCtx.getBodyPart(index); } /** * Get the root Part of the reponse MIME envelope, or the only part if the * response wasn't multipart. * * @return the Part */ public MimeBodyPart getRootPart() throws MessagingException { if (resCtx == null) return null; else return resCtx.getRootPart(); } }