org.systinet.wasp.messaging
Interface WaspProviderConnection

All Superinterfaces:

ProviderConnection

public interface WaspProviderConnection

extends ProviderConnection

A client's connection to WSO2 SOA Enablement Server messaging provider.

A WaspProviderConnection object is created using a ProviderConnectionFactory object from WSO2 SOA Enablement Server provider implementation.

After the client has obtained a connection to the messaging provider, it can use that connection to create MessageFactory objects of given protocol (profile, e.g. soap11 or soap12), which can then be used to create SOAPMessage objects.

When a client uses a messaging provider to send messages, it can send either one-way messages without blocking a client or request-response messages which blocks the client until it has returned the response.

An example how to send one-way message from default message factory (default protocol):

   ProviderConnectionFactory factory = ProviderConnectionFactory.newInstance();
   WaspProviderConnection connection = (WaspProviderConnection)factory.createConnection();

   MessageFactory msgFactory = MessageFactory.newInstance();
   SOAPMessage msg = msgFactory.createMessage();
   msg...
   connection.send(msg, "http://service.company.com/one-way");
 

another example how to do request-response call with SOAP 1.2 protocol with the same provider connection:

   MessageFactory msgFactory = connection.createMessageFactory(WaspProviderConnection.MESSAGE_FACTORY_SOAP12);
   SOAPMessage request = msgFactory.createMessage();
   request...
   SOAPMessage response = connection.call(request, "http://service.company.com/request-response");
   response...
 

another example with the same message factory with custom processing:

   SOAPMessage request = msgFactory.createMessage();
   ServiceClient client = ServiceClient.create();
   client.setServiceURL("http://service.company.com/request-response");
   client.setConnectionTimeout(10000);
   client.getInterceptors().insert(new MyInterceptor(), Interceptors.DIRECTION_INOUT);
   request...
   SOAPMessage response = connection.call(request, client);
   response...
 

asynchronous messaging using this class

   SOAPMessage request = msgFactory.createMessage();
   request...
   AsyncConversation async = connection.beginCall(request, "http://service.company.com/request-response");
   async.setAsyncCallback(new MyCallback());

   //invoked once the response is ready
   class MyCallback implements AsyncCallback {
      public void onResponse(AsyncConversation asyncConversation) {
          SOAPMessage response = connection.endCall(asyncConversation);
          response...
      }
   }
 

Component:

Core

Field Summary

static java.lang.String	MESSAGE_FACTORY_DEFAULT Message factory of deafult protocol.
static java.lang.String	MESSAGE_FACTORY_SOAP11 Message factory of SOAP 1.1 protocol.
static java.lang.String	MESSAGE_FACTORY_SOAP12 Message factory of SOAP 1.2 protocol.

Method Summary

AsyncConversation	beginCall(SOAPMessage request, ServiceClient serviceClient) Sends the SOAPMessage using specified configuration of serviceClient processing without blocking a serviceClient.
AsyncConversation	beginCall(SOAPMessage request, java.lang.String endpoint) Sends the SOAPMessage to specified endpoint without blocking a client.
AsyncConversation	beginSend(SOAPMessage message, ServiceClient serviceClient) Sends the SOAPMessage using specified configuration of serviceClient processing without blocking a client.
AsyncConversation	beginSend(SOAPMessage message, java.lang.String endpoint) Sends the SOAPMessage to specified endpoint without blocking a client.
SOAPMessage	call(SOAPMessage request, ServiceClient client) Sends the SOAPMessage with given configuration and blocks until it has returned the response.
SOAPMessage	call(SOAPMessage request, java.lang.String endpoint) Sends the SOAPMessage to the specified endpoint and blocks until it has returned the response.
SOAPMessage	endCall(AsyncConversation asyncConversation) Retrieves SOAPMessage which is a response to the message send using beginCall(javax.xml.soap.SOAPMessage, java.lang.String) and identified by AsyncConversation.
SOAPMessage	endCall(AsyncConversation asyncConversation, ServiceClient serviceClient) The behaviour of this method is exactly the same as endCall(org.systinet.wasp.async.AsyncConversation).
void	endSend(AsyncConversation asyncConversation) This method can be used to find out, if the message send using beginSend(javax.xml.soap.SOAPMessage, java.lang.String) was send successfully or some problem occured.
void	endSend(AsyncConversation asyncConversation, ServiceClient serviceClient) The behaviour of this method is exactly the same as endSend(org.systinet.wasp.async.AsyncConversation).
void	send(SOAPMessage message, ServiceClient client) Sends the given SOAPMessage object and blocks until the message wasn't sent.
void	send(SOAPMessage message, java.lang.String endpoint) Sends the given SOAPMessage object and blocks until the message wasn't sent.

Methods inherited from interface javax.xml.messaging.ProviderConnection

close, createMessageFactory, getMetaData, send

Field Detail

MESSAGE_FACTORY_DEFAULT

public static final java.lang.String MESSAGE_FACTORY_DEFAULT

Message factory of deafult protocol. Use ProviderConnection.createMessageFactory(java.lang.String) to obtain this factory.

MESSAGE_FACTORY_SOAP11

public static final java.lang.String MESSAGE_FACTORY_SOAP11

Message factory of SOAP 1.1 protocol. Use ProviderConnection.createMessageFactory(java.lang.String) to obtain this factory.

See Also:

Constant Field Values

MESSAGE_FACTORY_SOAP12

public static final java.lang.String MESSAGE_FACTORY_SOAP12

Message factory of SOAP 1.2 protocol. Use ProviderConnection.createMessageFactory(java.lang.String) to obtain this factory.

See Also:

Constant Field Values

Method Detail

send

public void send(SOAPMessage message,
                 java.lang.String endpoint)
          throws JAXMException

Sends the given SOAPMessage object and blocks until the message wasn't sent.

Parameters:

message - the SOAPMessage object that is sent

endpoint - the endpoint where to send message

Throws:

JAXMException - if a JAXM transmission error occurs

send

public void send(SOAPMessage message,
                 ServiceClient client)
          throws JAXMException

Sends the given SOAPMessage object and blocks until the message wasn't sent.

Parameters:

message - the SOAPMessage object that is sent

client - the client configuration

Throws:

JAXMException - if a JAXM transmission error occurs

beginSend

public AsyncConversation beginSend(SOAPMessage message,
                                   java.lang.String endpoint)
                            throws JAXMException

Sends the SOAPMessage to specified endpoint without blocking a client. The message is send as one-way and returned AsyncConversation is a handle, which can be used to find out if the message was send successfully. endSend(org.systinet.wasp.async.AsyncConversation).

Parameters:

message - the SOAPMessage object to be sent

endpoint - the endpoint where to send message(f.e. http://localhost:6060/HelloService)

Returns:

handle to started asynchronous invocation

Throws:

JAXMException - if a JAXM transmission error occurs

beginSend

public AsyncConversation beginSend(SOAPMessage message,
                                   ServiceClient serviceClient)
                            throws JAXMException

Sends the SOAPMessage using specified configuration of serviceClient processing without blocking a client. The message is send as one-way and returned AsyncConversation is a handle, which can be used to find out if the message was send successfully. endSend(org.systinet.wasp.async.AsyncConversation, ServiceClient).

Parameters:

message - the SOAPMessage object to be sent

serviceClient - configuration of client processing, used during processing of request message

Returns:

handle to started asynchronous invocation

Throws:

JAXMException - if a JAXM transmission error occurs

endSend

public void endSend(AsyncConversation asyncConversation)
             throws JAXMException

This method can be used to find out, if the message send using beginSend(javax.xml.soap.SOAPMessage, java.lang.String) was send successfully or some problem occured. This method blocks client until result is ready. Typical usage of this method is from within (AsyncCallback) onResponse(AsyncConversation asyncConversation) method.

  onResponse(AsyncConversation asyncConversation) {
     try {
        conn.endSend(asyncConversation);
     } catch(Throwable th) {
        // handle exception
        // ...
     } finally {
       asyncConversation.finish();
     }
  }
 

It is of course possible to call this method directly without using callback.

Parameters:

asyncConversation - handle to async invocation

Throws:

JAXMException - if a JAXM transmission error occurs

endSend

public void endSend(AsyncConversation asyncConversation,
                    ServiceClient serviceClient)
             throws JAXMException

The behaviour of this method is exactly the same as endSend(org.systinet.wasp.async.AsyncConversation). The only difference here is that user can provide additional configuration of client side processing using ServiceClient object. This method MUST be used, if the asynchronous invocation was started using beginCall(javax.xml.soap.SOAPMessage, org.systinet.wasp.webservice.ServiceClient).

Parameters:

asyncConversation - handle to async invocation

serviceClient - configuration of client processing, used during processing of received response

Throws:

JAXMException - if a JAXM transmission error occurs

call

public SOAPMessage call(SOAPMessage request,
                        java.lang.String endpoint)
                 throws JAXMException

Sends the SOAPMessage to the specified endpoint and blocks until it has returned the response.

Parameters:

request - the SOAPMessage object to be sent

endpoint - the endpoint where to send message

Returns:

the SOAPMessage object that is the response to the message that was sent

Throws:

JAXMException - if there is a SOAP error

call

public SOAPMessage call(SOAPMessage request,
                        ServiceClient client)
                 throws JAXMException

Sends the SOAPMessage with given configuration and blocks until it has returned the response.

Parameters:

request - the SOAPMessage object to be sent

client - the endpoint where to send message

Returns:

the SOAPMessage object that is the response to the message that was sent

Throws:

JAXMException - if there is a SOAP error

beginCall

public AsyncConversation beginCall(SOAPMessage request,
                                   java.lang.String endpoint)
                            throws JAXMException

Sends the SOAPMessage to specified endpoint without blocking a client. Returned AsyncConversation is a handle to response. Response can be retrieved using endCall(org.systinet.wasp.async.AsyncConversation).

Parameters:

request - the SOAPMessage object to be sent

endpoint - the endpoint where to send message(f.e. http://localhost:6060/HelloService)

Returns:

handle to started asynchronous invocation

Throws:

JAXMException - if a JAXM transmission error occurs

beginCall

public AsyncConversation beginCall(SOAPMessage request,
                                   ServiceClient serviceClient)
                            throws JAXMException

Sends the SOAPMessage using specified configuration of serviceClient processing without blocking a serviceClient. Returned AsyncConversation is a handle to response. Response can be retrieved using endCall(org.systinet.wasp.async.AsyncConversation, org.systinet.wasp.webservice.ServiceClient).

Parameters:

request - the SOAPMessage object to be sent

serviceClient - configuration of serviceClient processing, used during request processing

Returns:

handle to started asynchronous invocation

Throws:

JAXMException - if a JAXM transmission error occurs

endCall

public SOAPMessage endCall(AsyncConversation asyncConversation)
                    throws JAXMException

Retrieves SOAPMessage which is a response to the message send using beginCall(javax.xml.soap.SOAPMessage, java.lang.String) and identified by AsyncConversation. This method blocks client until message is ready. Typical usage of this method is from within (AsyncCallback) onResponse(AsyncConversation asyncConversation) method.

  onResponse(AsyncConversation asyncConversation) {
     SOAPMessage mess = conn.endCall(asyncConversation);
     mess... //further processing of retrieved message
  }
 

It is of course possible to call this method directly without using callback.

Parameters:

asyncConversation - handle to async invocation

Returns:

the SOAPMessage object that is the response to the message that was sent by corresponding

Throws:

JAXMException - if a JAXM transmission error occurs

endCall

public SOAPMessage endCall(AsyncConversation asyncConversation,
                           ServiceClient serviceClient)
                    throws JAXMException

The behaviour of this method is exactly the same as endCall(org.systinet.wasp.async.AsyncConversation). The only difference here is that user can provide additional configuration of client side processing using ServiceClient object. This method MUST be used, if the asynchronous invocation was started using beginCall(javax.xml.soap.SOAPMessage, org.systinet.wasp.webservice.ServiceClient).

Parameters:

asyncConversation - handle to async invocation

serviceClient - configuration of client processing, used during processing of received response

Returns:

the SOAPMessage object that is the response to the message that was sent by corresponding

Throws:

JAXMException - if a JAXM transmission error occurs