org.echarts.servlet.sip
Class EChartsSipServlet

java.lang.Object
  javax.servlet.GenericServlet
      javax.servlet.sip.SipServlet
          org.echarts.servlet.sip.EChartsSipServlet

All Implemented Interfaces:

java.io.Serializable, java.util.EventListener, javax.servlet.Servlet, javax.servlet.ServletConfig, SipApplicationSessionListener

public class EChartsSipServlet
extends SipServlet
implements SipApplicationSessionListener

SipServlet that provides a gateway to ECharts-defined application logic. The application developer uses this class as is, rather than subclassing as is the practice in traditional servlet programming. Upon receipt of an initial request, this class creates an instance of a FeatureBox that contains the application logic specified in the init-param called machineClassName, or a B2BUA machine if none is specified. Subsequent messages are dispatched to ports associated with the appropriate SipSession.

See Also:

Serialized Form

Field Summary

static java.lang.String	FEATURE_BOX
static java.lang.String	IS_INCOMING
protected static Monitor	monitor
static java.lang.String	SERVLET_NAME

Fields inherited from class javax.servlet.sip.SipServlet

OUTBOUND_INTERFACES, PRACK_SUPPORTED, SIP_FACTORY, SIP_SESSIONS_UTIL, SUPPORTED, SUPPORTED_RFCs, TIMER_SERVICE

Constructor Summary

EChartsSipServlet()

Method Summary

protected ContainerAdapter	createContainerAdapter()
protected void	createMonitor()
protected Request	createRequest(SipServletRequest req) Factory method to create an object of a specific subclass of Request to wrap a SipServletRequest that is dispatched to the application.
protected Response	createResponse(SipServletResponse resp) Factory method to create an object of a specific subclass of Response to wrap a SipServletResponse that is dispatched to the application.
void	destroy()
static SipApplicationSession	doNonSip(java.lang.Object req) Create a FeatureBox via non-SIP means, analagous to doRequest.
static SipApplicationSession	doNonSip(java.lang.Object req, java.lang.String boxAddress) Create a FeatureBox via non-SIP means, analagous to doRequest.
static SipApplicationSession	doNonSip(java.lang.Object req, java.lang.String boxAddress, java.lang.Object echartsMachineToJava) Create a FeatureBox via non-SIP means, analagous to doRequest.
void	doRequest(SipServletRequest req)
void	doResponse(SipServletResponse resp)
static SipApplicationSession	getApplicationSession(java.lang.String appSessionId) Returns the SIP application session associated with the specified application session ID.
static ContainerAdapter	getContainerAdapter()
RequestModifier	getDefaultModifier() Deprecated. With support for standardized application composition, the need to have a "forwarding" capability built into many apps is now reduced. It can of course still be done with a RequestModifier, or in a separate app that can be composed with other functionality as desired.
java.lang.Object[]	getMachineArguments(FeatureBox box)
java.lang.String	getMachineClassName()
protected static Monitor	getMonitor() Returns the monitor value currently used for newly created feature boxes.
java.util.Properties	getServletProperties() Gets initialization parameters from sip.xml.
static SipFactory	getSipFactory()
void	init(javax.servlet.ServletConfig sc) Initializes servlet with values from deployment descriptor, creates a logfile for monitor events, enables or disables debug output.
protected void	servletInit(javax.servlet.ServletConfig config) Called when the Servlet.init() is called by the container.
void	sessionCreated(SipApplicationSessionEvent ev) for SipApplicationSessionListener interface
void	sessionDestroyed(SipApplicationSessionEvent ev) for SipApplicationSessionListener interface
void	sessionExpired(SipApplicationSessionEvent ev) Always extend application session lifetime.
protected java.lang.String	sessionKeyFromRequest(SipServletRequest req) Generate the key used for key based session targeting mechanism.
void	sessionReadyToInvalidate(SipApplicationSessionEvent ev) for SipApplicationSessionListener interface.
protected static void	setMonitor(Monitor monitor) Set the monitor value to be used for all feature boxes created subsequent to calling this method.
static java.lang.String	sipApplicationKey(SipServletRequest req) If the top-level ECharts machine implements BoundBoxMachine, this method calls BoundBoxMachine.sessionKey() to obtain the key used for key based SipApplicationSession targeting mechanism.

Methods inherited from class javax.servlet.sip.SipServlet

doAck, doBranchResponse, doBye, doCancel, doErrorResponse, doInfo, doInvite, doMessage, doNotify, doOptions, doPrack, doProvisionalResponse, doPublish, doRedirectResponse, doRefer, doRegister, doSubscribe, doSuccessResponse, doUpdate, log, log, service

Methods inherited from class javax.servlet.GenericServlet

getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletInfo, getServletName, init

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

monitor

protected static Monitor monitor

IS_INCOMING

public static final java.lang.String IS_INCOMING

See Also:

Constant Field Values

FEATURE_BOX

public static final java.lang.String FEATURE_BOX

See Also:

Constant Field Values

SERVLET_NAME

public static final java.lang.String SERVLET_NAME

See Also:

Constant Field Values

Constructor Detail

EChartsSipServlet

public EChartsSipServlet()

Method Detail

sessionKeyFromRequest

protected java.lang.String sessionKeyFromRequest(SipServletRequest req)

Generate the key used for key based session targeting mechanism.

This is only called if the top-level machine implements BoundBoxMachine. The default behavior is to return the String representation of the subscriber URI. An application may override this method to customize how the key is generated.

Parameters:

req - initial request that the Application Router has selected this application to handle

Returns:

the key

sipApplicationKey

public static java.lang.String sipApplicationKey(SipServletRequest req)

If the top-level ECharts machine implements BoundBoxMachine, this method calls BoundBoxMachine.sessionKey() to obtain the key used for key based SipApplicationSession targeting mechanism.

Returns:

session key if top-level ECharts machine implements BoundBoxMachine, null otherwise.

createRequest

protected Request createRequest(SipServletRequest req)

Factory method to create an object of a specific subclass of Request to wrap a SipServletRequest that is dispatched to the application.

An application may override this method to create application-specific subclasses.

Parameters:

req - the request that is dispatched to the application

Returns:

an object of the specific subclass of Request

createResponse

protected Response createResponse(SipServletResponse resp)

Factory method to create an object of a specific subclass of Response to wrap a SipServletResponse that is dispatched to the application.

An application may override this method to create application-specific subclasses.

Parameters:

resp - the response that is dispatched to the application

Returns:

an object of the specific subclass of Response

servletInit

protected void servletInit(javax.servlet.ServletConfig config)
                    throws java.lang.Exception

Called when the Servlet.init() is called by the container.

The application can perform application-specific initialization which should only be run once per application (i.e. a servlet instance) by overriding this method. This is in contrast to the constructor method of the top-level machine class, which is executed once per application instance.

Parameters:

config - a ServletConfig object container the servlet's configuration and initialization parameters

Throws:

java.lang.Exception

getApplicationSession

public static final SipApplicationSession getApplicationSession(java.lang.String appSessionId)

Returns the SIP application session associated with the specified application session ID. If the application session has been destroyed then returns null.

Parameters:

appSessionId - SIP application session ID (as returned by SipApplicationSession.getId())

Returns:

SIP application session instance associated with the specified ID

init

public void init(javax.servlet.ServletConfig sc)
          throws javax.servlet.ServletException

Initializes servlet with values from deployment descriptor, creates a logfile for monitor events, enables or disables debug output.

Specified by:

init in interface javax.servlet.Servlet

Overrides:

init in class javax.servlet.GenericServlet

Throws:

javax.servlet.ServletException

createMonitor

protected void createMonitor()

createContainerAdapter

protected ContainerAdapter createContainerAdapter()

destroy

public void destroy()

Specified by:

destroy in interface javax.servlet.Servlet

Overrides:

destroy in class javax.servlet.GenericServlet

doRequest

public void doRequest(SipServletRequest req)
               throws NoPortAssignedException,
                      PortException,
                      FeatureBoxException,
                      EChartsSipServletException

Overrides:

doRequest in class SipServlet

Throws:

NoPortAssignedException

PortException

FeatureBoxException

EChartsSipServletException

doResponse

public void doResponse(SipServletResponse resp)
                throws NoPortAssignedException,
                       PortException,
                       FeatureBoxException

Overrides:

doResponse in class SipServlet

Throws:

NoPortAssignedException

PortException

FeatureBoxException

doNonSip

public static SipApplicationSession doNonSip(java.lang.Object req)
                                      throws NoPortAssignedException,
                                             PortException,
                                             FeatureBoxException,
                                             EChartsSipServletException

Create a FeatureBox via non-SIP means, analagous to doRequest. The supplied request will be enqueued in the BoxPort of the newly-created FeatureBox. The newly created feature box will be assigned the box address "nonSip". Note that this address is not used by the application router.

Parameters:

req - non-SIP request to be supplied to BoxPort

Returns:

application session associated with the newly created FeatureBox

Throws:

NoPortAssignedException

PortException

FeatureBoxException

EChartsSipServletException

doNonSip

public static SipApplicationSession doNonSip(java.lang.Object req,
                                             java.lang.String boxAddress)
                                      throws NoPortAssignedException,
                                             PortException,
                                             FeatureBoxException,
                                             EChartsSipServletException

Create a FeatureBox via non-SIP means, analagous to doRequest. The supplied request object will be enqueued in the BoxPort of the newly-created FeatureBox. The specified box address will be assigned to the newly created feature box. Note that this address is not used by the application router. If a null or empty string are provided then address value defaults to "nonSip".

Parameters:

req - non-SIP request to be supplied to BoxPort

boxAddress - desired address for box or null

Returns:

application session associated with the newly created FeatureBox

Throws:

NoPortAssignedException

PortException

FeatureBoxException

EChartsSipServletException

doNonSip

public static SipApplicationSession doNonSip(java.lang.Object req,
                                             java.lang.String boxAddress,
                                             java.lang.Object echartsMachineToJava)
                                      throws NoPortAssignedException,
                                             PortException,
                                             FeatureBoxException,
                                             EChartsSipServletException

Create a FeatureBox via non-SIP means, analagous to doRequest. The supplied request object will be enqueued in the BoxPort of the newly-created FeatureBox. The specified box address will be assigned to the newly created feature box. Note that this address is not used by the application router. If a null or empty string are provided then address value defaults to "nonSip". The echartsMachineToJava parameter will be associated with the newly created box's application session and accessible to the box's machine via a call to EChartsMachineToJava.getInstance().

Parameters:

req - non-SIP request to be supplied to BoxPort

boxAddress - desired address for box or null

echartsMachineToJava - echartsMachineToJava instance or null

Returns:

application session associated with the newly created FeatureBox

Throws:

NoPortAssignedException

PortException

FeatureBoxException

EChartsSipServletException

getMachineClassName

public java.lang.String getMachineClassName()

Returns:

Returns String representing fully qualified class name of machine associated with this application. This value is specified as an init-param called machineClassName in the sip.xml deployment descriptor. If none is specified, a B2BUA is instantiated by default.

getMachineArguments

public java.lang.Object[] getMachineArguments(FeatureBox box)
                                       throws java.lang.Exception

Returns:

Returns array of Objects to serve as constructor parameters for the feature's machine.

Throws:

java.lang.Exception

getSipFactory

public static final SipFactory getSipFactory()

Returns:

a reference to a SipFactory object

getServletProperties

public java.util.Properties getServletProperties()

Gets initialization parameters from sip.xml.

Returns:

All init-param key/value pairs from sip.xml deployment descriptor.

getDefaultModifier

@Deprecated
public RequestModifier getDefaultModifier()

Deprecated. With support for standardized application composition, the need to have a "forwarding" capability built into many apps is now reduced. It can of course still be done with a RequestModifier, or in a separate app that can be composed with other functionality as desired.

Gets convenience RequestModifier corresponding to init-params in sip.xml.

Returns:

a RequestModifier that will modify Request-URI according to servlet parameters:

nextUser

set user of Request-URI

nextHost

set host of Request-URI

nextPort

set port of Request-URI

sessionCreated

public void sessionCreated(SipApplicationSessionEvent ev)

for SipApplicationSessionListener interface

Specified by:

sessionCreated in interface SipApplicationSessionListener

sessionDestroyed

public void sessionDestroyed(SipApplicationSessionEvent ev)

for SipApplicationSessionListener interface

Specified by:

sessionDestroyed in interface SipApplicationSessionListener

sessionExpired

public final void sessionExpired(SipApplicationSessionEvent ev)

Always extend application session lifetime. Calling FeatureBox.destroy() will explicitly invalidate the appSession, and prevent this method from being called again by the container.

Specified by:

sessionExpired in interface SipApplicationSessionListener

sessionReadyToInvalidate

public void sessionReadyToInvalidate(SipApplicationSessionEvent ev)

for SipApplicationSessionListener interface.

Specified by:

sessionReadyToInvalidate in interface SipApplicationSessionListener

setMonitor

protected static void setMonitor(Monitor monitor)

Set the monitor value to be used for all feature boxes created subsequent to calling this method.

getMonitor

protected static Monitor getMonitor()

Returns the monitor value currently used for newly created feature boxes.

getContainerAdapter

public static ContainerAdapter getContainerAdapter()