SipApplicationRouter

The SipApplicationRouter interface defines the API between the SIP Servlet container and the application router. It allows the container to determine how incoming SIP requests are routed to applications based on custom routing logic. The SipApplicationRouter is an important part of the SIP Servlet API that helps route SIP requests to the correct SIP servlet or application based on custom rules defined by the application. This interface provides the flexibility to implement routing rules based on various factors, such as the content of SIP headers, the type of request, or external business logic. By specifying this interface, the SIP Servlet API decouples routing logic from the container, allowing applications to define and control how requests are processed and which applications should handle them.

Methods:

init
void init()
The method initializes the SipApplicationRouter interface. This method is invoked by the SIP container during its lifecycle to set up the SipApplicationRouter. It can only be called once by the container, and any subsequent calls will result in an exception.
Exception:
java.lang.IllegalStateException: Thrown if the init method is called more than once, as the router is only intended to be initialized once per container lifecycle.

init
void init(java.util.Properties properties)
This overloaded version of the init method initializes the SipApplicationRouter while accepting a set of initialization properties. These properties provide additional context or configuration details to the router during the setup phase. The SIP container calls this method during its initialization process, and it can only be invoked once.
Parameters:
properties: A set of key-value pairs containing initialization properties for the SipApplicationRouter. The source of these properties is implementation-dependent and determined by the SIP container.
Exception:
java.lang.IllegalStateException: Thrown if the init method is invoked more than once, as the router is only intended to be initialized once.

destroy
void destroy()
The method is called by the SIP container when it no longer requires the SipApplicationRouter. This typically occurs when the container is shutting down or when the application is not deployed. The method allows the router to perform cleanup tasks, such as releasing resources or terminating any ongoing operations.

applicationDeployed
void applicationDeployed(java.util.List<java.lang.String> newlyDeployedApplicationNames)
The method is called by the SIP container to notify the SipApplicationRouter that new applications have been deployed. This allows the router to update its internal state or routing logic to include the newly deployed applications.
Parameters:
newlyDeployedApplicationNames: A list containing the names of the newly deployed SIP applications.

applicationUndeployed
void applicationUndeployed(java.util.List<java.lang.String> undeployedApplicationNames)
The method is called by the SIP container to notify the SipApplicationRouter that specific applications have been undeployed. This allows the router to update its internal state or routing logic to remove references to the undeployed applications.
Parameters:
undeployedApplicationNames: A list containing the names of the SIP applications that have been undeployed.

getNextApplication
SipApplicationRouterInfo getNextApplication(SipServletRequest initialRequest,
                                            SipApplicationRoutingRegion region,
                                            SipApplicationRoutingDirective directive,
                                            SipTargetedRequestInfo targetedRequestInfo,
                                            java.io.Serializable stateInfo)
The method is invoked by the SIP container to determine the next SIP application that should process an initial SIP request. This method provides routing logic based on the request and context provided, and returns a SipApplicationRouterInfo object that contains information about the selected application.
Parameters:
initialRequest: The initial SIP request for which the container is asking for application selection. The SipApplicationRouter must not modify this request. Attempting to mutate it should result in an exception, such as IllegalStateException.
region: Represents the region within which the application selection process is operating.
directive: Indicates the routing directive used to create the request. If the request is received externally, the directive is NEW.
targetedRequestInfo: Provides details if the request is a targeted request (e.g., ENCODED_URI, JOIN, or REPLACES). Includes the targeted application's name. If the request is not targeted, this parameter is null.
stateInfo: Contains state information relayed from a previous request by an application. This is the state returned by the application router in earlier invocations.
Returns:
Contains details about the selected application to handle the request. If no applications are deployed, the method returns null.
Exceptions:
java.lang.NullPointerException: Thrown if initialRequest is null.
java.lang.IllegalStateException: Thrown if the application router has not been initialized.