com.ibm.websphere.sip

Class AsynchronousWork

  • java.lang.Object
    • com.ibm.websphere.sip.AsynchronousWork
  • All Implemented Interfaces:
    java.io.Serializable


    public abstract class AsynchronousWork
    extends java.lang.Object
    implements java.io.Serializable
    The AsynchronousWork is an abstract class that should be overridden by an application that is interested in using asynchronous invocation of code. The propose of using such invocation would be for 2 reasons 1. The application code is executed on a certain server in a cluster while the SIP Application Session location it is referring to is unknown and might be residing on a different server in the cluster. Using this API will make sure the code is executed on the correct server. 2. SIP Container APIs are being accessed from a non-SIP container thread. This can happen if the code is not executed from a SIP servlet or any other SIP 1.0 or 1.1 API listener methods. In this case WebSphere Application Server will need this code to be executed using an extension to this AsynchronousWork, so that the code will be executed from a SIP container thread and by that eliminate the need for synchronization or other locking mechanisms on the related SIP Application Session elements.

    An application that extends this class should implement doAsyncTask abstract method that returns a Serializable object. When an application needs to run an asynchronous work, it creates a AsynchronousWork object providing the appSessionId to which the work relates, and calls dispatch method with a AsynchronousWorkListener (optional). This listener will receive a response when the work is completed.

    See Also:
    com.ibm.websphere.sip.AsynchronousWorkListener} interface for details. In case the application is not interested in a response, it should pass null in the AsynchronousWorkListener parameter.

    A sip container that receives the message is responsible either to execute the work locally or to send it to another server in the cluster which manages the session. After the message reaches the right server, or the right thread within the same server, the SIP container on this server invokes the doAsyncTask method where an application performs its work.

    Finally, after the work is done, a response (either success or failure) returns to the SIP container on the originating server and it invokes the appropriate AsynchronousWorkListener method to return a response to the application.

    An example of using the asynchronous invocation is shown here:

     
     public class MyListener implements AsynchronousWorkListener {
    		public void onCompleted(Serializeable myResponse){
    		?
    		}
    		public void onFailed(int reasonCode, String reason)	{
    		}
    	}
    
     public class MyClass extends AsynchronousWork {  
     	SipApplicationSession _sessionId;
     
     	public MyClass(String sessionId) { 
    		super(sessionId); 
    		_sessionId = sessionId; 
    	} 
     
    	// This is the code that will be invoked on the target machine/thread 
    	public Serializeable doAsyncTask() { 
    	  // Application code goes here...., For instance:
    	  appSession = sessionUtils.getApplicationSession(_sessionId);
    	  appSession.createRequest().....
    
    	  Serializeable myResponse = new MyResponse();
    	  myResponse.setStatus(200);
    	  return (myResponse);
    	}
     }
     
     // When need to invoke the asynchronous call (e.g., when you receive the proprietary message): 
    
    	public void onMyMessage() {
    		// Obtain the session ID from the message or somewhere else
     		String sessionId = obtainIdFromMessage();
    
    		MyClass myClass = new MyClass(sessionId);
    
    		// Create the listener
    		MyListener myListener = new MyListener();
    
    		// Dispatch it
    	 	myClass.dispatch(myListener);
    	}
     
    , Serialized Form
    • Constructor Summary

      Constructors 
      Constructor and Description
      AsynchronousWork(java.lang.String appSessionId)
      Constructor
    • Method Summary

      Methods 
      Modifier and Type Method and Description
      void dispatch(AsynchronousWorkListener listener)
      The application should call this method to dispatch the message to the right server or thread that will execute the asynchronous work task.
      abstract java.io.Serializable doAsyncTask()
      This abstract method should be overridden by an application with the work it wishes to invoke asynchorounously.
      java.lang.Object waitForResponse(long time)
      Wait until the response is received, this method will cause the current thread to be locked until the async work task is finished The application should use it if it wishes to wait until the async work is finished
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • AsynchronousWork

        public AsynchronousWork(java.lang.String appSessionId)
        Constructor
        Parameters:
        appSessionId - id of the SipApplicationSession that the SIP signaling code to be invoked asynchronously is related to.
    • Method Detail

      • dispatch

        public final void dispatch(AsynchronousWorkListener listener)
        The application should call this method to dispatch the message to the right server or thread that will execute the asynchronous work task.
        Parameters:
        listener - AsynchronousWorkListener object to receive notification when the work is done.
      • waitForResponse

        public final java.lang.Object waitForResponse(long time)
        Wait until the response is received, this method will cause the current thread to be locked until the async work task is finished The application should use it if it wishes to wait until the async work is finished
        Parameters:
        time - - the maximum time to wait in milliseconds, 0 is for waiting forever
        Returns:
        Object - the result of the async task or null if it was not finished yet
      • doAsyncTask

        public abstract java.io.Serializable doAsyncTask()
        This abstract method should be overridden by an application with the work it wishes to invoke asynchorounously. Note: The SIP signaling code that will be implemented in this method must relate only to the SipApplicationSession which ID was passed to the constructor and not to any other SipApplicationSession. Meaning that only the state of the related SIP dialogs (represented by that SipApplicationSession SipSessions) and their timers or attributes can be modified here.
        Returns:
        Serializable object that will pass to the AsynchronousWorkListener. If the return value is null, then the listener, if exists, will not be invoked.
IBM WebSphere Application ServerTM
Release 9.0