Rhino SIP Servlet Overview and Concepts

WEB-INF/sip.xml     # Deployment descriptor
WEB-INF/classes/... # Application classes (servlets, listeners etc)
WEB-INF/lib/...     # Third-party libraries (jar files)

REGISTER: ("Registrar", "DAR:From", "ORIGINATING", "", "NO_ROUTE", "0"), ("Presence", "DAR:From", "ORIGINATING", "", "NO_ROUTE", "1")
INVITE: ("CallBarring", "DAR:From", "ORIGINATING", "", "NO_ROUTE", "0"), ("LocationServiceProxy", "DAR:From", "ORIGINATING", "", "NO_ROUTE", "1")

@SipApplication(name = "example", mainServlet = "main-servlet")
@SleeRATypes({
    @RATypeBinding(raType = @ComponentId(name = "HTTP", vendor = "OpenCloud", version = "2.2"),
        activityContentInterfaceFactoryName = "slee/resources/http/acifactory",
        resourceAdaptorEntityLink = "slee/resources/http",
        resourceAdaptorObjectName = "slee/resources/http/provider")
})
package com.example.app;

import com.opencloud.sipservlet.slee.annotation.SleeRATypes;
import javax.servlet.sip.annotation.SipApplication;
import javax.slee.annotation.*;

|This annotation marks those classes in the application that may receive SLEE events. Servlet and Listener classes may use this annotation.

|----
@EventMethod

|Like other SLEE components, event types are identified by name, vendor, and version.

|===

== Event handler methods

As well as the `@EventMethod` annotation, event handler methods must have a particular signature.

* They must be public, not-static methods that return `void`.
* The method name must be on `<event-name>`. The event name must be a unique name within the servlet application.
* The first parameter is the event object. The parameter type is defined by the SLEE event type's definition, usually part of the RA type definition.
* The second parameter is the ACI of the activity that the event was fired on.
* The last parameter is the `SipApplicationSession` instance that is processing the event.

The event handler method can process the event just like a SLEE SBB event handler method. The activity object associated with the event can be obtained using `ActivityContextInterface.getActivity()` on the ACI passed to the event handler method.

== Initial events

SIP servlet application instances are typically created when a new initial SIP request arrives, which is not associated with any existing `SipSession`. A new `SipSession` and `SipApplicationSession` are created to process the request, and the `SipApplicationSession` will hold any state for the new application instance.

It is also possible to trigger a new application instance using events from other SLEE RAs. To do this, the application must declare that one or more event types are _initial events_. This is done by adding the `initialEvent=true` attribute to an `@EventMethod` annotation:

[source,java]

Here this means that an HTTP GET request will create a new `SipApplicationSession` instance. It could then initiate a new `SipSession` with another SIP device, to implement a "click-to-dial" service.

Initial events can also enable bxref:converged-applications[converged applications].

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/ra/sipservlet/release-1.1.0/Release-docs/sipservlet-docs/rhino-sip-servlet-overview-and-concepts/slee-resource-adaptor-support/converged-applications.adoc

:here: slee-resource-adaptor-support/
:idprefix: converged-applications

:leveloffset: 1

= Converged Applications
:sortorder: 760

// DevPortal author: ~jonh



Often it is desirable to have initial events be processed by the same application instance.

For example, a conferencing service might want to have all calls to the conference address be handled by the same application instance, so the state of all participants can be easily managed in a single `SipApplicationSession`.

== Session targeting mechanisms

SIP Servlet provides several _session targeting_ mechanisms that allow initial SIP requests to be directed to the same `SipApplicationSession`. The most generic session targeting mechanism is the `@SipApplicationKey` method. The SIP Servlet container invokes a `@SipApplicationKey` method with the initial request, and the method returns a string which identifies a `SipApplicationSession`, creating the session if it doesn't exist.

`@SipApplicationKey` only applies to SIP requests, but Rhino SIP Servlet provides an equivalent session targeting mechanism for non-SIP initial events. This means that events from different protocols can be directed to the same application instance, enabling converged applications.

=== @SleeApplicationKey session targeting

To implement session targeting for non-SIP events, a servlet application defines a `@SleeApplicationKey` method. This is very similar to `@SipApplicationKey` methods, in that it takes an initial event and returns a string. The string identifies a `SipApplicationSession` instance, which is created automatically if it doesn't already exist.

TIP: The `@SleeApplicationKey` method is only used for non-SIP initial events; SIP events will still use `@SipApplicationKey`. To enable SIP and non-SIP initial events to select the same application instance, the application developer just has to ensure that these two methods return the same values for related events.

The signature of the `@SleeApplicationKey`-annotated method looks like this:

[source,java]

The method must satisfy these properties:

* Only one method in the application can be annotated with `@SleeApplicationKey`.
* The method must be public and static.
* The method may have any name.
* The method must return `String`.
* The method must have two `Object` parameters, which are the SLEE event and its activity object.

The body of the method can do anything, but it should be idempotent. It should inspect the event and activity parameters and extract the required information, such as user IDs or session IDs, to generate the return value.

=== Default session targeting behaviour

If there is no `@SleeApplicationKey` method defined in the application, Rhino SIP Servlet will just create a new `SipApplicationSession` instance for each new non-SIP activity.

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/ra/sipservlet/release-1.1.0/Release-docs/sipservlet-docs/rhino-sip-servlet-overview-and-concepts/slee-resource-adaptor-support/slee-libraries.adoc

:here: slee-resource-adaptor-support/
:idprefix: slee-libraries

:leveloffset: 1

= SLEE Libraries
:sortorder: 770

// DevPortal author: ~jonh

Servlet applications may also use any library components deployed in the SLEE.

Like RA type bindings, library bindings are declared using annotations on a package within the application:

[source,java]

Here the application has declared a dependency on two other libraries. These libraries must be deployed in the SLEE before the servlet application can deploy.

NOTE: Use of SLEE libraries is purely optional; servlet applications can also just put their dependencies in +
`WEB-INF/lib` in their SAR file. SLEE libraries may be useful if they are shared by many applications on the same SLEE platform.

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/ra/sipservlet/release-1.1.0/Release-docs/sipservlet-docs/rhino-sip-servlet-overview-and-concepts/example-applications.adoc

:here:
:idprefix: example-applications

:leveloffset: 1

= Example Applications
:sortorder: 800

// DevPortal author: ~ben

Your Rhino SIP Servlet installation comes with example applications, in the `examples/` directory. Each subdirectory under `examples/` holds a self-contained SIP Servlet application, with source code and Ant deployment scripts.

Running `ant` inside an example application's directory executes the default `deploy` build target, which builds the application and deploys it into the SLEE.

Once deployed, the application can be tested using your preferred SIP testing tools, such as http://sipp.sourceforge.net[SIPp] or https://sourceforge.net/projects/sipsak.berlios/[sipsak], or SIP softphones such as http://mfnboer.home.xs4all.nl/twinkle/index.html[Twinkle], http://www.linphone.org[Linphone] or http://www.counterpath.com/x-lite/[X-Lite].


WARNING: You must gxref:rhino-sip-servlet-installation-and-administration-guide/installing-rhino-sip-servlet[deploy a Rhino SIP Servlet RA entity] before attempting to install the example applications.

Below are descriptions of the sample applications: bxref:#code-sipservlet-services-code[sipservlet-services], bxref:#code-proxy-hybrid-code[proxy-hybrid] and bxref:#code-http-example-code[http-example].

== sipservlet-services

[cols="1h,5a"]
|===

| What it does
| Implements some typical SIP services:

* Registrar
* Back-to-back user agent (B2BUA) & Proxy
* Presence.

| How to configure
| * Only one of the B2BUA or Proxy servlets should be enabled at a time.
* The B2BUA servlet is enabled by default.
* To enable the Proxy servlet, uncomment the `<servlet-mapping>` element for `proxy-servlet` in the deployment descriptor, and comment out the corresponding `b2b-proxy-servlet` element.
* Use the env-entry "`localDomains`" to specify a comma-separated list of domain names that the proxy and B2BUA consider to be local.

If these servlets receive a request with a Request-URI containing a SIP identity (a.k.a. _address of record_) that is within one of these domains, the servlets lookup the SIP identity in the registration database to find a registered contact address. If no entry is found, an error response is returned to the caller.
The registration database is populated by the Registrar servlet when SIP clients send REGISTER requests to register their current contact address.

The application's deployment descriptor can be found at `resources/WEB-INF/sip.xml`.

| Database it uses
| An embedded (in-process) Derby database to store SIP registrations; created automatically during deployment.
|===

== proxy-hybrid

NOTE: This is an example *hybrid application* -- a SLEE service that uses the SIP Servlet 1.1 RA Type, and uses the SIP Servlet Proxy interface to implement a simple proxy.

[cols="1h,5a"]
|===

| What it does
| Implements a _very simple_ proxy; does not attempt to lookup registered SIP identities, so it can only forward requests to their next hop.

| How to configure
| Edit the service's SBB deployment descriptor: `resources/META-INF/sbb-jar.xml`.

_The environment entries_ `proxyRecordRoute` _and_ `proxySupervised` _are applied to the_ `Proxy` _instances that are created when processing initial requests._
|===

== http-example

NOTE: This is an example of a servlet application using a bxref:slee-resource-adaptor-support[SLEE Resource Adaptor] to communicate using another protocol, in this case HTTP.

[cols="1h,5a"]
|===

| What it does
| A simple proxy that also uses the HTTP RA to make an HTTP request. Also processes incoming HTTP requests as initial events.

| How to configure
| No configuration required.

|===

:leveloffset!: