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.