org.mobicents.javax.servlet.sip

Interface SipFactoryExt

All Superinterfaces:

SipFactory

public interface SipFactoryExt
extends SipFactory

Interface Extension that adds extra features to the JSR 289 SipFactory interface to allow proxying of orphaned requests.
It adds the following capabilities :

• Requests and responses that do NOT have associated SipSession or SipApplicationSession will still be delivered to the main servlet of the application this factory belongs to. Such requests and responses are called "orphaned".
• The requests and responses will be proxied outside the container to their regular destination after being delivered to the application
• When orphaned requests or responses are delivered to the application you can check this with SipServletRequest.isOrhpan() and SipServletResponse.isOrphan()
• The sessions for these requests are lost and getSession() methods will cause brand new sessions to be created. These new sessions are unrelated to the lost sessions.

You can turn on and off this feature on demand from your application at any time. By default it is off. This feature is useful for stateless applications that don't want the memory overhead of sessions and dialogs. Inherently when there are no sessions there is no need for session replication in clusters. You can start a session in the first stage of the call (INVITE-OK-ACK) then invalidate the session and the subsequent requests will still be proxied to the correct destination while you application is still on the path and notified of the messages. Good use cases for this feature are:

• Long calls proxied through the server that are being accounted in a remote database instead of sessions
• Proxy applications that must scale linearly in a cluster of Sip Servlets Application Servers

Since:

1.6

Author:

jean.deruelle@gmail.com, vladimir.ralev@gmail.com

Method Summary

Methods

Modifier and Type	Method and Description
SipApplicationSession	createApplicationSession(boolean isContainerManaged) Returns a new SipApplicationSession.
SipApplicationSession	createApplicationSessionByKey(String sipApplicationKey, boolean isContainerManaged) Returns a new SipApplicationSession identified by the specified SipApplicationKey.
SipServletRequest	createRequestWithCallID(SipApplicationSession appSession, String method, Address from, Address to, String callID) Extension variant to the spec allowing to specify CallID.
SipServletRequest	createRequestWithCallID(SipApplicationSession appSession, String method, String from, String to, String callID) Extension variant to the spec allowing to specify CallID This method requires org.restcomm.servlets.sip.OVERRIDE_SYSTEM_HEADER_MODIFICATION param to be set at web/sip.xml descriptor.
SipServletRequest	createRequestWithCallID(SipApplicationSession appSession, String method, URI from, URI to, String callID) Extension variant to the spec allowing to specify CallID This method requires org.restcomm.servlets.sip.OVERRIDE_SYSTEM_HEADER_MODIFICATION param to be set at web/sip.xml descriptor.
boolean	isRouteOrphanRequests() This flag specifies if the current application can receive subsequent requests after their session has been lost or invalidated.
void	setRouteOrphanRequests(boolean routeOrphanRequets) This flag specifies if the current application can receive subsequent requests after their session has been lost or invalidated.

Methods inherited from interface javax.servlet.sip.SipFactory

createAddress, createAddress, createAddress, createApplicationSession, createApplicationSessionByKey, createAuthInfo, createParameterable, createRequest, createRequest, createRequest, createRequest, createSipURI, createURI

Method Detail

isRouteOrphanRequests

boolean isRouteOrphanRequests()

This flag specifies if the current application can receive subsequent requests after their session has been lost or invalidated. This feature can't be used with chained applications. Only single application can be on the path of the requests.

Returns:

setRouteOrphanRequests

void setRouteOrphanRequests(boolean routeOrphanRequets)

This flag specifies if the current application can receive subsequent requests after their session has been lost or invalidated. This feature can't be used with chained applications. Only single application can be on the path of the requests.

createApplicationSession

SipApplicationSession createApplicationSession(boolean isContainerManaged)

Returns a new SipApplicationSession. This is useful, for example, when an application is being initialized and wishes to perform some signaling action.

Parameters:

isContainerManaged - whether or not the container should bind and lock the sip application session in the same thread as the one that created it

Returns:

a new SipApplicationSession object

Since:

7.0.2

createApplicationSessionByKey

SipApplicationSession createApplicationSessionByKey(String sipApplicationKey,
                                                  boolean isContainerManaged)

Returns a new SipApplicationSession identified by the specified SipApplicationKey. This is same as the one generated by the method annotated with @SipApplicationKey annotation. This allows a way to associate incoming requests to an already existing SipApplicationSession.

Parameters:

sipApplicationKey - - id for the SipApplicationSession

isContainerManaged - whether or not the container should bind and lock the sip application session in the same thread as the one that created it

Returns:

a new SipApplicationSession object with the specified id

Since:

7.0.2

createRequestWithCallID

SipServletRequest createRequestWithCallID(SipApplicationSession appSession,
                                        String method,
                                        Address from,
                                        Address to,
                                        String callID)

Extension variant to the spec allowing to specify CallID. This method requires org.restcomm.servlets.sip.OVERRIDE_SYSTEM_HEADER_MODIFICATION param to be set at web/sip.xml descriptor. Value "Modifiable"

Parameters:

appSession -

method -

from -

to -

callID - If null, the container will autogenerate the callId as usual

Returns:

createRequestWithCallID

SipServletRequest createRequestWithCallID(SipApplicationSession appSession,
                                        String method,
                                        String from,
                                        String to,
                                        String callID)
                                          throws ServletParseException

Extension variant to the spec allowing to specify CallID This method requires org.restcomm.servlets.sip.OVERRIDE_SYSTEM_HEADER_MODIFICATION param to be set at web/sip.xml descriptor. Value "Modifiable"

Parameters:

appSession -

method -

from -

to -

callID - If null, the container will autogenerate the callId as usual

Returns:

Throws:

ServletParseException

createRequestWithCallID

SipServletRequest createRequestWithCallID(SipApplicationSession appSession,
                                        String method,
                                        URI from,
                                        URI to,
                                        String callID)

Extension variant to the spec allowing to specify CallID This method requires org.restcomm.servlets.sip.OVERRIDE_SYSTEM_HEADER_MODIFICATION param to be set at web/sip.xml descriptor. Value "Modifiable"

Parameters:

appSession -

method -

from -

to -

callID - If null, the container will autogenerate the callId as usual

Returns: