Interaction between Servlet Contexts

Lifecycle Interaction

When the WEB-INF directory of an application contains web.xml and sip.xml, SIP Servlet Engine considers that this application uses Web and SIP at the same time.

If such application is deployed, when WebLogic Server 8.1 SP3 creates an HTTP servlet context, the SIP servlet container generates a SIP servlet context. When the HTTP servlet is discarded, the SIP servlet context is also discarded.

SIP Servlet Engine 3.0 implements this lifecycle interaction using ServletContextListener defined by Servlet API 2.3. Application developers or system administrators must define the following event listener in the deployment descriptor (web.xml) when deploying a Web application containing a SIP servlet

<listener>
    <listener-class>com.oki.sip.bea.wls81.ContextEventHook</listener-class>
</listener>

Context Attribute Interaction

Context attribute interaction is a function that allows you to take attribute information registered with setAttribute() in one servlet context from the other context. For example, SIP Servlet API registers SipFactory with the context attribute under the name "javax.Servlet.sip.SipFactory." This attribute can be extracted from the HTTP servlet context under the same name.

You can set an event listener in the context attribute. Events are delivered properly when the context is managed from either side. For example, when you add a context attribute on the HTTP side, attributeAdded method is invoked on the listener that is registered in the SIP context.

Event notification to the event listener on the SIP is implemented through the ContextEventHook object described earlier.

Interaction of Invocation from HTTP Servlet

SIP Servlet Engine 3.0 provides a framework of starting a SIP servlet from an HTTP context. This function invokes a SIP servlet in the same context from an HTTP servlet or Action object of Struts and is used in applications such as Click2Dial.

SIP Servlet Engine 3.0 supports the invocation only from HTTP to SIP. A SIP servlet has a built-in function of sending a request as a client and a SIP terminal can receive the request.

You can use the servlet interaction function using RequestDispatcher between HTTP servlets (or SIP servlets). However, when you want to make different types of servlets work together, you can not use RequestDispatchersuch since:

• Method to be invoked can not be determined since HTTP and SIP use different messaging systems.
• When a SIP servlet acts as a client, there is no method corresponding to doXXX.

In SIP Servlet Engine, you can use a SipRequestDispatcher class to invoke a SIP servlet from an HTTP servlet.

This section describes the API of the SipRequestDispatcher class.

package com.oki.sip.engine;

public class SipRequestDispatcher {
    public static SipRequestDispatcher getInstance(Object source, ServletContext context, String servletName);

    public static SipRequestDispatcher getInstance(Object source, String contextName, String servletName);

    public Object invoke(String methodName, SipRequestParams params)
        throws Exception;
}

You create instances of SipRequestDispatcher with a getInstance method. You specify three arguments in the method as follows:

source

Information that represents the source of the method call. It is used to write source information to an access log.

context

Specifies a servlet context. The servlet context may be an HTTP or SIP servlet context. If you only know the name of the context, you can use the second getInstance method.

servletName

Specifies the name of the target SIP servlet. This is the name specified in the <servlet-name> tag in the sip.xml file.

The invoke method performs method call. The first argument methodName specifies the method name to be called. The second argument is a parameter passed on the method call. The called method must have a single SipRequestParams argument.

The SipRequestParams class is used to store application-specific arguments. Arguments are maintained as a name-value pairs so that multiple arguments can be specified. The API of the SipRequestParams class is shown below:

package com.oki.sip.engine;

public class SipRequestParams {
    public SipRequestParams();

    public void setParam(String name, Object value);

    public Object getParam(String name);
}

setParam is a method to set a parameter, and getParam is a method to get a set parameter.

The following code sample performs a method call using these APIs:

ServletContext context = session.getServletContext();
SipRequestDispatcher dispatcher = SipRequestDispatcher.getInstance(this, context, "caller");
SipRequestParams params = SipRequestParams();
params.setParam("3pcc.flow", new Integer(1));
params.setParam("3pcc.caller", caller);
params.setParam("3pcc.callee", callee);

CallingProgressHandler handler =
   (CallingProgressHandler) dispatcher.invoke("makeCall", params);

Any method invoked on the SIP servlet side must have only one SipRequestParams argument. In the above code, the makeCall(SipRequestParams params) is invoked. This limitation is to avoid unexpected method calls. The code below is an example processing on the SIP servlet side corresponding to the code fragment shown above.

public CallingProgressHandler makeCall(SipRequestParams params)
    throws Exception
{
    Integer iflow = (Integer) params.getParam("3pcc.flow");
    CallingEntity caller = (CallingEntity) params.getParam("3pcc.caller");
    CallingEntity callee = (CallingEntity) params.getParam("3pcc.callee");

    return makeCall(flow, caller, callee);
}

There is no limitation on return values and exceptions. You can use any class as a return value.

Note that primitive types (such as int) can not be used as a return value.

Any exception thrown on the SIP servlet is passed to the caller. If an error occurs due to the fact that the target method can not be found, this exception is stored in the SipInvocationException class and thrown. If the SIP servlet does not throw SipInvocationException, you can check the type of the exception class to determine whether the exception occurs in the calling process or on the destination.

Timing of Call
When RequestDispatcher#forward(ServletRequest request, ServletResponse response) is used in an HTTP servlet, the process does not transit at call time. The forward process is performed when the called doXxx method returns. In contrast, the invoke method provided by this class can invoke a method on SIP servlet side at call time. Processes on the HTTP servlet side will remain blocked until a called method is returned, because the method is called synchronously on the SIP servlet side. Therefore, you need to design so that methods invoked by this class can return as soon as possible to return control to the HTTP side.