This document describes the SIP resource adaptor sample applications and how to prepare, deploy, configure and run them.


About the Sample Applications

Descriptions and list of files and directories containing the sample resource adaptor, services, and SBBs for use with the Rhino SLEE


Brief instructions for setting up the environment, running the build script, and configuring the services

Manual Installation

More detailed instructions for configuring and deploying the SIP RA installation; specifying a location service; installing the Registrar, Proxy, and Presence services; and modifying service source code.

Using the Services

How to configure and use a SIP user agent with the example services, and enable tracing SIP services.

Other documentation for the Rhino TAS can be found on the Rhino TAS product page.

About the Sample Applications

The SIP Sample Applications are example applications for the Rhino SLEE which use the Session Initiation Protocol — RFC3261 (SIP) protocol.

As well as implementing some basic SIP services, these examples also demonstrate many SLEE features, such as:

  • deploying and undeploying components such as resource adaptors and services

  • service building blocks (SBBs) and container managed persistence (CMP) state

  • child SBBs and SBB local interfaces

  • shared state using null activities and activity-context attributes

  • storing subscriber data using profiles.

Below are descriptions of the examples and related files and directories.

Resource adaptor, service, and SBB examples

The example SIP components include:

Component What it does

SIP resource adaptor

Provides the interface between SIP user agents and the SLEE. The SIP RA is responsible for sending and receiving SIP messages over the network. The SIP RA processes messages from the network and converts them to SLEE activities and events, for use by SLEE applications. The SIP RA must be installed in the SLEE before the other SIP applications can be used.

SIP Registrar service

An implementation of a SIP registrar as defined in RFC3261 section 10. This service handles SIP REGISTER requests, which SIP user agents send to register a binding from a user’s public address to the physical network address of their user agent. The registrar service updates records in a location service, which other SIP applications use. The registrar service is implemented by a single SBB component, which uses a location service child SBB to query and update location service records.

SIP Stateful Proxy service

Implements a stateful proxy as described in RFC3261 section 16. This proxy is responsible for routing requests to their correct destination, as given by contact addresses that have been registered with the location service. The proxy service is implemented by a single SBB component, which uses a location service child SBB to query location service records.

SIP Find-me Follow-me service

Provides an intelligent SIP proxy service, which lets a user profile specify alternative SIP addresses to contact if their primary contact address is not available.

SIP Back-to-back User-Agent service

An example of a back-to-back user agent (B2BUA). Behaves like the proxy service, but maintains SIP dialog state (call state) using dialog activities.

AC-naming, Profile & JDBC Location-Service SBBs

Provide alternate implementations of a SIP location service, which the proxy and registrar services use. The AC-naming location service uses the SLEE’s ActivityContext Naming Facility to store location information. The profile location service uses SLEE profiles, and the JDBC location service stores location information in an external database.

SIP Presence service

An implementation of a SIP Presence service, as described in RFC3856, RFC3863, and RFC3903. Allows a user to subscribe to the presence information of another user, and to update his or her own presence information for other users to see. This enables the "buddy list" feature of many SIP clients, which in turn may also enable their instant-messaging features.

SIP example files and directories

The examples consist of the following files and directories:

File or directory Description

Ant build script for SIP sample applications. Manages building and deployment of the examples.

Properties for the Ant build script.

Properties for the SIP services. When the Ant build script runs, it substitutes these properties into the application deployment descriptors.


Text file containing "quick start" instructions.


Text file describing recent changes to the SIP RA and examples.


Contains RA and API documentation.


Contains source code for sample SIP services.


Contains SIP resource adaptor and RA-type jars, and required libraries.


Directory where the build script writes compiled class files.{ctd}


Directory where the build script writes jar files that are ready for deployment.


The sample SIP services which can be deployed with Rhino are: the Proxy, Registrar and Presence services. Together, these services provide basic SIP-server functionality, and are intended to work "out of the box" with minimal configuration.

To get the default SIP examples up and running straight away, follow the quick start instructions here. For more detailed information on building, installing and configuring the examples, see Manual Installation.

Below are instructions on configuring and deploying the sample services.

Note Files referred to in the instructions are in the directory created when extracting the examples, e.g. $RHINO_HOME/rhino-connectivity/sip-3.1.2

Configure sample SIP services

Before deploying the examples, you must first change the default configuration of the Proxy service to suit your environment. It is configured in the file. Edit this file, changing the PROXY_DOMAINS property as follows:

# Proxy SBB configuration
# Add domains that the proxy is authoritative for,

The default domains and are just examples — change this property to use the correct domains for your environment.

The PROXY_DOMAINS property contains the domains that the proxy SBB considers to be local. This means that if the proxy SBB receives a request addressed to a user in one of these domains (such as, it will use the location service to find the registered contact address of that user. If the user cannot be found, the Proxy service will return an error response.

If the Proxy service receives a request addressed to a user in an unknown domain, it will forward the request according to normal SIP routing rules.

Warning On a Windows host (e.g. running in a VM or via WSL), with user agents on separate PCs, the Windows firewall may block SIP messages sent over the network. You may need to re-configure the firewall to ensure that Rhino can receive SIP messages.

Deploy sample SIP services

By default, the Ant build script build.xml builds and deploys the Registrar, Proxy and Presence sample services with the components they need (including the SIP resource adaptor and location service), into Rhino.

To deploy the examples, run Ant with the deployexamples target:

$ ant deployexamples

If you don’t have Ant installed, you can use a copy that is bundled with Rhino: run the script.

Once you have deployed the sample Registrar, Proxy and Presence services, see Using the Services for instructions on how to test them with your SIP user agents.

Manual Installation

This page explains in more detail how to configure and deploy the SIP resource adaptor and examples services.

Tip If you just want to get something up and running quickly, see the Quickstart page.

To manually install and configure the example SIP services:


Configure and deploy the SIP resource adaptor (RA).




Please experiment with the examples, and try implementing new features. The source code for all the example services can be found in src/com/opencloud/slee/services.

  • If you change the source code of any of the examples, you can easily recompile and deploy them using the Ant targets in build.xml.

  • If a service is already installed, remove it using the relevant undeploy Ant target (such as undeployregistrar), then rebuild and redeploy using the relevant deploy target (use ant -p to list the possible targets).

  • All the deploy targets are written so that they recompile, rebuild jars, and deploy any dependencies that are not already installed.

It pays to familiarise yourself with Ant and the deploy/undeploy targets in build.xml. This will make it easier to build, deploy and test your own projects.

Configure the SIP RA

The default configuration of the SIP resource adaptor (RA) should be suitable for most environments. However, you can easily reconfigure it to suit a particular requirement, such as using a different IP address or port number.

Each resource adaptor defines a default set of configuration properties that determine its behaviour. When an administrator creates a resource adaptor entity (an "instance" of the RA), they can specify configuration property values other than the defaults.

Below are instructions for editing SIP RA configuration properties and a full listing of the default SIP RA configuration properties.

Editing SIP RA configuration properties

The Ant build script build.xml creates the SIP resource adaptor entity with the following properties (defined in the file):,Transports="udp,tcp",Port=5060,SecurePort=5061

To change these properties and specify others, edit the property. For example, to enable the SIP RA’s replicated-dialog support, you would add that property as follows (and then deploy the SIP RA):,Transports="udp,tcp",Port=5060,SecurePort=5061,ReplicatedDialogSupport=true

The Ant build.xml script will pass these properties to the createRAEntity management command.

SIP RA configuration properties

A full listing of available SIP RA configuration properties can be found in the Configuration section of the SIP Resource Adaptor Guide.

Tip See Resource Adaptor Entities in the Rhino Administration and Deployment Guide for more information on creating and managing resource adaptor entities.

Deploy the SIP RA

After configuring default properties, you can deploy the SIP resource adaptor into the SLEE.

The Ant build script build.xml contains build targets for deploying and undeploying the SIP RA, as follows.


To deploy the SIP RA, first ensure the SLEE is running, and then run build.xml with the target deploysipra. For example:

$ ant deploysipra

This script installs the SIP RA deployable unit and required libraries in the SLEE, and creates and activates the resource adaptor entity.


To undeploy the SIP RA, run build.xml with the target undeploysipra. For example:

$ ant undeploysipra

This script deactivates and removes the resource adaptor entity and uninstalls the SIP RA deployable unit.

Select and Deploy a Location Service

The sample SIP Registrar, Proxy, and Presence services require a location service, as defined by RFC3261 section 10. The location service stores SIP registrations, mapping a user’s public SIP address to actual contact addresses.

Tip If you don’t care how this is done, you can skip this step and use the default location service.

Below are instructions for selecting a location service, specifying an external database for the JDBC location service, and deploying the selected location service,

Selecting Activity Context Naming, JDBC, or Profile location services

The SIP examples include three implementations of the location-service interface, which demonstrate different SLEE features:

  • Activity Context Naming (Default) — stores registration information in memory using null activities, looked up using the SLEE Activity Context Naming Facility. This is deployed by default.

  • JDBC — stores registrations in an external database.

  • Profile — stores registrations in a writeable SLEE 1.1 profile table.

Many other implementations are possible, such as LDAP.

The file specifies the type of location service that build.xml deploys. To select one of the three available implementations, edit, changing the locationservice property:

# The locationservice property should be set to one of "ac", "profile" or "jdbc".
# If undefined or a different value, defaults to "profile".

Using an external database for JDBC

If you select the JDBC location service, you’ll need to select a database other than the default, which uses Rhino’s embedded database (Apache Derby in the SDK and PostgreSQLin the production versions of Rhino).

To select an external database, you need to:


Create a table with the correct schema for the SIP Registrar

The SQL script fragment below demonstrates how to create the table. This works on PostgreSQL and may need to be adjusted to suit your particular database server.

create table registrations (
    sipaddress varchar(80) not null,
    contactaddress varchar(80) not null,
    expiry bigint,
    qvalue integer,
    cseq integer,
    callid varchar(80),
    flowid varchar(80),
    primary key (sipaddress, contactaddress)
COMMENT ON TABLE registrations IS 'SIP Location Service registrations';


Configure the JDBC data source in Rhino

Please see External Databases in the Rhino Administration and Deployment Guide for instructions on setting up an external data source.


Edit the JDBC location service’s deployment descriptor to refer to the new data source

Edit the extension deployment descriptor src/com/opencloud/slee/services/sip/location/jdbc/META-INF/oc-sbb-jar.xml. The data source is specified in the resource-ref element:

Note The res-jndi-name element must refer to a configured data source. See Persistence Instances) for details on configuring persistence resources in Rhino.

Deploy the location service

Warning Normally you do not need to deploy the location service explicitly, since deploying the Registrar, Proxy, or Presence services will automatically deploy the location service as a dependency.

If necessary you can deploy a location service separately using the Ant target deploylocationservice. For example:

$ ant deploylocationservice

This will automatically deploy the location service that you specified in

Undeploy the location service

To undeploy the location service, use the Ant target undeploylocationservice. For example:

$ ant undeploylocationservice

Deploy the Sample SIP Services

Below are instructions for preconfiguring the Proxy service (required before installing it), and then installing and uninstalling the Registrar, Proxy, and Presence services.

Preconfigure the Proxy service

Before you install the Proxy service, you must change one configuration item to suit your environment. Edit the file, to change the PROXY_DOMAINS property as follows:

# Proxy SBB configuration
# Add domains that the proxy is authoritative for,
Warning The default domains and are just examples — change this property to use the correct domains for your environment.

The PROXY_DOMAINS property contains the domains that the proxy SBB considers to be local. Depending on what domain the user to whom a request is addressed is in, the proxy SBB will do the following:

User’s domain What the proxy service does

One of the local domains (such as in our example).

Uses the location service to find the registered contact address of that user.

Local domain, but not registered in the location service.

Returns an error response.

Unknown domain.

Forwards the request according to normal SIP routing rules.

Install services

To install the SIP Registrar, Proxy or Presence service, first ensure the SLEE is running. Then go to the SIP examples directory and execute the Ant targets deployregistrar, deployproxy, or deploypresence. For example:

$ ant deployregistrar

These scripts:

  • compile the service source code

  • assemble jar files

  • deploy the service and its dependencies into the SLEE

  • activate the service.

Uninstall services

To deactivate and remove the services, use the Ant target undeployregistrar, undeployproxy, or undeploypresence. For example:

$ ant undeployregistrar

Using the Services

The following topics describe how to configure and use a SIP user agent with the sample Registrar, Proxy, and Presence services.

What is a SIP user agent?

A "SIP user agent" means any SIP-capable device, such as a VoIP phone, softphone, or instant-messaging client. Some examples of user agents that have been used successfully with Rhino are:

The instructions in this section are intended to be generic and should apply to most user agents. Please see your user agent’s product documentation for specific installation and usage instructions.

Configure User Agents

Below are instructions for configuring typical network, SIP identity, and SIP server user-agent settings.

  • If you haven’t already, first deploy the sample SIP services into Rhino (see Quickstart or Manual Installation).

  • The following settings must be configured correctly before using the sample SIP services with Rhino (or any SIP server).

Default network port

A SIP user agent must listen on a network port, so that it can receive incoming calls or messages. The default port for SIP is 5060. Most user agents will attempt to use this port, and this is almost always the correct configuration.

However, if Rhino and a user agent are running on the same host, then there may be a conflict (because Rhino’s SIP resource adaptor defaults to port 5060 as well). If this is the case, you must change the port that either the SIP RA or the user agent uses. See Manual Installation for instructions on changing the port that the SIP RA uses.

If your user agent is running on a different host to Rhino, then no additional network configuration should be necessary.

SIP identity

Your SIP identity (sometimes called "address of record") is the public SIP address that you share with others so they can contact you. It is like your phone number or email address, and usually looks like sip:username@domain (for example,

When your user agent starts, it will register your SIP identity with the SIP server. The SIP server binds your SIP identity to the network address of your user agent (its contact address). This lets other users call you without knowing your user agent’s network address.

Unless you are integrating with an existing SIP network, the SIP identity you choose can be anything. However, the domain part of your identity ( should be one of the domains known by the sample Proxy service (see the PROXY_DOMAINS property described in Quickstart). This is so the proxy service forwards requests to your user agent’s contact address.

SIP servers

You need to tell your user agent which SIP servers it will use. Depending on the particular user agent, you may have to configure several SIP server addresses, for different SIP services. (Often a user agent will just require a single server address that it uses for everything.)

The typical types of server that you may need to configure are:

Server What it does


Receives registration and unregistration requests from your user agent, and updates a location service with your SIP identity and the user agent’s network address.

Proxy (or outbound proxy)

Receives messages or calls from the user agent, and figures out how to route them to their destination.


Provides the status of other users to the user agent (for example, for buddy lists), and lets it publish its own status information (such as "available", "busy", or "away").

Tip Some user agents may assume that the same server will provide all these services.

To configure your SIP servers, enter the address of your Rhino server in the appropriate fields. Often this will need to be in the form of a SIP URI. For example if Rhino is running on the machine and using port 5060, then the SIP address of the server would be

Use the Registrar Service

Most SIP user agents will automatically try to register when they start up, by sending a REGISTER request.

This updates the Registrar with the user agent’s contact address. SIP registrations are not permanent, so the user agent will periodically refresh its registration with the Registrar. When the user agent shuts down, it will send another request to un-register its contact address.

The registration process is defined in RFC3261 section 10. When registering, refreshing or un-registering, the user agent sends a REGISTER request and expects to receive a 200 OK response, indicating that the operation succeeded:

User Agent          Registrar
    |                   |
    |      REGISTER     |
    |       200 OK      |
    |                   |
Tip You can enable tracing in Rhino to see the messages received by the Registrar service.

Use the Proxy Service

The role of the Proxy service is to route calls between user agents, so they do not need to know where the other user is located.

The Proxy service will obey SIP Route headers, and by default will insert Record-Route headers so that it stays on the path of a call. If a request does not contain any routing information, the Proxy will use RFC3263 DNS procedures to locate an appropriate server.

To test the Proxy service, you can have it set up a call between two user agents on the same network. The user agents should run on different hosts, so that their SIP ports do not conflict, nor their RTP ports (used for streaming audio or video during a call).

Below are instructions for using the Proxy service to place a call, along with a sample message flow.

Placing a call

The following procedure places a call between two user agents, routed through the Proxy service. We will assume the Rhino server is at the address and configured to use as its domain. We will refer to the two user agents as A and B, with the SIP identities and respectively.

  1. Configure each user agent with server address and their SIP identities.

  2. Start the user agents and ensure they have registered successfully (the user agent should warn if registration failed).

  3. On user agent A, enter as the destination address and place a call. This will send an INVITE message to the proxy.

  4. The proxy will lookup in its location service, and route the call to user agent B.

  5. User agent B should indicate that it has a new incoming call.

  6. Answer the call on user agent B. This sends a SIP 200 OK response back to the proxy.

  7. The proxy forwards the response to user agent A.

  8. User agent A receives the response. A SIP dialog is now established and the users can talk to each other.

  9. Now one of the user agents can hang up the call. This sends a BYE message to the other user agent (through the proxy).

  10. The other user agent should send a 200 OK response back. The call is now terminated.

Message flow

The following diagram below shows the complete message flow for the test SIP call.

User A            Registrar             User B
  |      REGISTER     |                   |
  |------------------>|                   |
  |       200 OK      |                   |
  |<------------------|                   |
  |                   |      REGISTER     |
  |                   |<------------------|
  |                   |       200 OK      |
  |                   |------------------>|
  |       INVITE      |                   |
  |------------------>|                   |
  |                   |       INVITE      |
  |                   |------------------>|
  |                   |        1xx        |
  |                   |<------------------|
  |         1xx       |                   |
  |<------------------|                   |
  |                   |      200 OK       |
  |                   |<------------------|
  |       200 OK      |                   |
  |<------------------|                   |
  |        ACK        |                   |
  |------------------>|                   |
  |                   |        ACK        |
  |                   |------------------>|

          ... call established ...

  |        BYE        |                   |
  |------------------>|                   |
  |                   |        BYE        |
  |                   |------------------>|
  |                   |      200 OK       |
  |                   |<------------------|
  |       200 OK      |                   |
  |<------------------|                   |
Tip If at any point a message does not go through as expected, enable tracing in Rhino to see what the Proxy service is doing.

Use the Presence Service

You can use the SIP Presence service to enable the buddy list features of SIP clients that implement the SIP/SIMPLE specification.

Clients can view the online status of their registered contacts ("buddies"), and update their own online status for other clients to see. Many SIP clients require users' buddy lists to work before they can send instant messages — so the Presence service also enables sending instant messages for many SIP clients.

To use the Presence service, you need at least two SIP clients. They may be either different clients on a single host, or multiple instances of the same client on different hosts. (The same SIP client on different hosts may mean fewer interoperability issues, because many SIP clients only implement selected parts of the SIP/SIMPLE specification, or include custom extensions to the specification.)

Below are instructions for setting up SIP clients to demonstrate the Presence service, a sample message flow and details of basic and rich Presence.


Setting up the SIP clients to demonstrate the Presence service is similar to setting up to demonstrate the Registrar service:

  1. Start Rhino and deploy the Presence service.

  2. Start the clients you want to use.

  3. Create new SIP user accounts, pointing to the IP address and port that Rhino is using to run the Presence service.

  4. If the SIP clients implement the SIP/SIMPLE specification, you should then be able to add contacts to the buddy list, and send instant messages between clients.


Some example SIP clients that can be used to demonstrate the Presence service are:

Sample message flow

The Presence service accepts SIP SUBSCRIBE and PUBLISH requests, and sends NOTIFY requests when appropriate.

The client sending SIP SUBSCRIBE requests lets user agents subscribe to the Presence information of other users (adding them as contacts in the "buddy list"). The client sending PUBLISH requests lets user agents publish changes to their own Presence state.

The Presence service responds by providing Presence information through NOTIFY requests. The Presence service amalgamates the Presence information available to it for any given user, and composes the information into a single Presence state for that user. When this composed Presence state changes (either by the user publishing a change to their status, or by registering or de-registering with the Registrar), the Presence service notifies any users who have subscribed to that information. Thus, if user A registers user B as a contact, an example SIP message flow could resemble the one below:

User A              Service               User B
    |      SUBSCRIBE    |                    |
    |------------------>|                    |
    |       200 OK      |                    |
    |<------------------|                    |
    |       NOTIFY      |                    |
    |<------------------|                    |
    |       200 OK      |                    |
    |------------------>|                    |
    |                   |                    |
    |                   |       PUBLISH      |
    |                   |<-------------------|
    |                   |        200 OK      |
    |                   |------------------->|
    |                   |                    |
    |       NOTIFY      |                    |
    |<------------------|                    |
    |       200 OK      |                    |
    |------------------>|                    |

The Presence service responds to the user A’s initial SUBSCRIBE request with a NOTIFY containing the current Presence information of user B, and informs user A with a further NOTIFY request when user B’s Presence state changes.

Basic Presence

At the most basic level, Presence describes whether or not a client is online or offline. The Presence service determines the basic Presence state of users from any PUBLISH requests it has received from the user’s client, and through determining whether the user is registered as online with the Registrar.

Many SIP clients implement basic Presence. You can demonstrate this using two clients on a single host.

Note Pidgin and X-Lite are SIP clients that implement basic Presence. Most of them will either use SIP/SIMPLE by default, or will have SIP/SIMPLE listed as a protocol that they support.

To demonstrate the use of basic Presence:

  1. Start Rhino and deploy the Presence service.

  2. Set up two (or more) clients to use the Rhino host running the Presence service (identified by the Rhino host’s IP address and port) as their SIP server. The clients may either be on different hosts, or all on the same host.

  3. Make sure that each client has a unique user account, and ensure that each one successfully registers with the Registrar.

  4. In each client, add the other client accounts as contacts in the buddy list. The online status of the other client accounts should automatically display in the buddy list as either online or offline as appropriate.

  5. Register or deregister one of the clients (log on or off). The online status of that client should change from online to offline (or vice versa) in the buddy lists of the other clients.

Once the buddy list feature of the clients is working, most clients will also allow instant messages. Note that there are exceptions (for example, Microsoft Messenger uses proprietary extensions to the messaging part of the protocol, and will not exchange instant messages).

Rich Presence

The SIP/SIMPLE protocol also lets clients share more detailed Presence information. The Presence service implements the Presence information data format set out in RFC3863, "application/pidf+xml", which lets them communicate an extra layer of information (above the basic states of online and offline — for example publishing states such as "On the phone").

Use instances of the same client

The extra layer of Presence information has been left entirely open to implementations — there are no standard states (as is the case with basic Presence). Many clients do not implement this part of the protocol, and many add extensions to it. Because of these differences, using different clients to demonstrate extended Presence can therefore be difficult.

To demonstrate the use of extended Presence information with the Presence service, you can set up two instances the SIP client on separate hosts:

  1. Start Rhino and deploy the Presence service.

  2. Configure two instances of the SIP client, each on separate hosts, to use the Rhino host running the Presence service as their SIP server.

  3. In each client, add the other account as a contact in the buddy list. The status of each account should automatically update, once it has been added into the buddy list.

  4. Set the status of one of the clients to "Away" or "Do Not Disturb", by clicking on the circular button to the left of the account’s user name, and selecting the option from the drop-down list. The new status of the account should display in the buddy list of the other client.

Once the client’s buddy lists work, they should be able to exchange instant messages.

Enable Tracing for SIP Services

The SIP services can write tracing information to the Rhino SLEE logging system using the SLEE trace facility.

This is useful for understanding what the various services are doing.

Enabling tracing for a particular SBB

To enable tracing output for a particular SBB, use the setTracerLevel command in rhino-console, as follows:

user@host:~/rhino$ client/bin/rhino-console
Connecting as user admin
Interactive Rhino Management Shell
Rhino management console, enter 'help' for a list of commands
[Rhino@localhost (#0)] settracerlevel sbb service=ServiceID[name=SIP\ Proxy\ Service,
    vendor=OpenCloud,version=1.8] root finest
Set trace level of SbbNotification[service=ServiceID[name=SIP Proxy Service,
    vendor=OpenCloud,version=1.8]] root tracer to finest
[Rhino@localhost (#1)]

Enabling tracing for all SBBs

You can also enable tracing for all SBBs, and also the SIP RA, by modifying these settings in

# Default SBB/RA trace levels
# Possible values: Off, Severe, Warning, Config, Info, Fine, Finer, Finest.
Tip To apply the new trace levels, redeploy the services or ra.