You can use the Asynchronous Invocation API to transfer
events that require processing in the context of a Session Initiation
Protocol (SIP) application session to any server in a cluster based
on the related application session ID. The Asynchronous Invocation
API transfers the event task to the correct server.
Before you begin
Read the API documentation for information on the following
asynchronous work classes:
- com.ibm.websphere.sip.AsynchronousWork
- com.ibm.websphere.sip.AsynchronousWorkListener
For more information about the API classes, see the Reference
section in the information center and click APIs - Application Programming
Interfaces to view a list of the product API specifications.
About this task
When running code outside of a SIP thread, application
developers can use the Asynchronous Invocation API to create an object,
and configure the server to run that object either on a different
thread in the same container, or on a different server, if that is
where the session exists.
The following example shows the class
structure for the AsynchronousWork class, which is the abstract base
class that is extended when using the API.
public abstract class AsynchronousWork implements Serializable
{
private String sessionId;
public AsynchronousWork(String sessionId)
{
this.sessionId = sessionId;
....
}
public void dispatch (AsynchronousWorkListener listener)
{
....
}
public abstract Serializable doAsyncTask();
}
Procedure
- Extend the abstract class AsynchronousWork with the SIP
related code. The extended implementation of the doAsyncTask()
method is invoked on the target server that contains the SipApplicationSession,
and whose ID was set in the constructor that implements the AsynchronousWork
class. The implementation class must pass the session ID to the base
class by calling super in the constructor.
public class MyClass extends AsynchronousWork
{
String _sessionId;
public MyClass(String sessionId) {
super(sessionId);
_sessionId = sessionId;
}
// This code is invoked on the target machine or thread
public Serializable doAsyncTask() {
// Application code goes here; for instance:
appSession = sessionUtils.getApplicationSession(_sessionId);
appSession.createRequest().....
Serializable myResponse = new MyResponse();
myResponse.setStatus(200);
return (myResponse);
}
}
- To receive information about the task completion, implement
the AsynchronousWorkListener class, as in the following example. The code in these methods are invoked on the source server.
public class MyListener implements AsynchronousWorkListener
{
public void workCompleted(Serializeable myResponse)
{
....
}
public void workFailed(int reasonCode, String reason)
{
}
}
- To invoke the asynchronous call; for example, when you
receive the proprietary message, use this sample code as an example.
public void onMyMessage()
{
// Obtain the session ID from the message or
// somewhere else
String sessionId = obtainIdFromMessage();
// Create the runnable
MyClass myClass = new MyClass(sessionId);
// Create the listener
MyListener myListener = new MyListener();
// Dispatch it
myClass.dispatch(myListener);
}
Results
The SIP container ensures the task is invoked in the correct
server and on the correct thread, so that the application can avoid
synchronization on the session level.