Look what Java and SIP can do
 (SIP)Java = ∞
Home     News     Projects     Downloads     Support     Contact
Related Pages
Jiplet Container Home

Jiplet Developer Guide

Installation Howto

Configuration Howto
Phone settings
X-ten client

Windows Messenger client







Jiplet Reference Application Howto

In order to understand how to install and use the reference application, you must read the entire howto sequentially, not just the topics you need to know more about. This is because one topic may refer to a previous topic.

Topics:

Conventions

  1. We have used the term "directory" to specify a file location. This is a common Unix convention. In the Windows environment, the term "folder" is used to mean the same thing.
  2. We have used the Unix directory naming convention in this document. In the Unix environment, a directory hierarchy is specified by the "/" separator. In the Windows environment, the "\" separator is used. In addition, Unix system do not use drive letters as in Windows. If you are using Windows, you will need to modify the commands accordingly. For example, if we stated $JIPLET_HOME/bin, if you are using Windows, it may translate to C:\jiplet-standalone\bin.
  3. We have used $JIPLET_HOME or similar names to specify environmental variables. While installing/configuring, you will need to replace these variables with the actual values for your machine. For example, in this document, the variable $JIPLET_HOME has been used to specify the directory where the jiplet container code binary is installed. We have commonly used the following variables:
    1. $JAVA_HOME - directory where the Java Runtime Environment (JRE) is installed.
    2. $JIPLET_HOME - directory where the Jiplet Container software is installed.
    3. $JBOSS_HOME - directory where JBOSS is installed.
    4. $TOMCAT_HOME - directory where Tomcat is installed.
    5. $HOST - host name/IP address of the system where the jiplet container is installed.
    6. $RUN - the JBOSS run mode (default, minimal, all, etc.).
    7. $ANT_HOME - the directory where Ant is installed.
  4. Commands are specified using bold. You need to enter the command by typing/pasting the command and pressing the Enter/Return key. Although in the Unix world this may seem natural, in the Windows environment, lots of users are lost when it comes to entering a command. Also, the prompts "#" or "C:\>" are shown, do not enter them.

Running your first jiplet application

This section explains how to write your own jiplet application.  We will use the reference jiplet application that we have created in this example. You can also use the reference application as a template for your future applications. First we will build the jiplet reference application from the sources.

Downloading the reference application

The download site contains two distributions of the reference application. They are:
  1. The source distribution: The source distribution contains the source code for the reference application. If you are a software developer and would like to see the code and build the application from the source, you need to download this distribution. Follow the instruction outlines in the next section to build the application from source.
  2. The binary distribution: If you would just like to check out the reference application and you are not interested in the source, this the the distribution for you. Follow the instructions outlined in the next section to extract the application.

Unpacking the binary distribution

The distribution is a ZIP file. Download the distribution and unpack the distribution using a unzip utility. For Windows, you can use jar, WINZIP or similar software to extract the content. For Linux, use jar or the unzip utility.  On unzipping, you will find a file called my-jiplets.spr. This is the reference application file that you can install.

Building the application

If you have downloaded the source distribution, please follow the steps below to build the application from the source:
  1. Before you start, please make sure that you have installed the pre-requisite software.
  2. Unpack the source code for the reference into your system. For Windows, you can use jar, WINZIP or similar software to extract the content. For Linux, use jar or the unzip utility. It will create a directory called jiplet-ref.
  3. Set an environment variable called CAFESIP_HOME and specify the value as the parent directory of the directory called jiplet-ref (see above). For example, if the reference jiplet source was installed in C:\jiplet-ref, set the value of CAFESIP-HOME as "C:\". On Windows system, you can set the variable using the "set" command or you can set the variable from the "My Computer" icon. On Linux, use the "export" or "setenv" command depending on your shell environment.
  4.  Similarly set the variables JAVA_HOME and ANT_HOME to point to the location where Java and Ant is installed respectively.
  5. Open a command line terminal (DOS prompt for Windows). Change directory to the jiplet-ref directory.
  6. Invoke the Ant build script by running the command:

    $ # for Linux:
    $ $ANT_HOME/bin/ant

    or

    REM for Windows
    C:\jiplet-ref> %ANT_HOME%\bin\ant
  7. The above command will create a file called my-jiplets.spr in the jiplet-ref directory. The next step is to deploy the SPR file you just created.

Installing the application

If you installed the source distribution, you have to build the source to create the my-jiplets.spr file as outlined above. If you have downloaded the binary distribution, this file is included in the distribution as explained above. Your next step is to deploy the application into the jiplet container. The deployment procedure will differ depending on whether you have installed the standalone jiplet container or installed the jiplet container as a JBOSS service.

If you have installed the jiplet container as a JBOSS service, follow the steps below:
  1. Make sure that JBOSS is running and the jiplet container service has been started (you check the JBOSS logs or JBOSS JMX console to find that out).
  2. Copy the my-jiplets.spr file to the $JBOSS_HOME/server/$RUN/deploy directory. JBOSS will automatically start the jiplet context called my-jiplets. Alternatively, install the application using the jiplet console as explained below.

If you are using the standalone jiplet container and have installed the jiplet console, follow the steps as outlined below:
  1. Make sure that the jiplet container is running.
  2. Make sure that Tomcat is running and the jiplet console has been started (using a browser, go to the URL http://$HOST:8080/jiplet-console and make sure that you get the login dialog).
  3. Login to the jiplet console by entering your user name and password.
  4. Select "Contexts" from the navigation bar and a list of contexts will be displayed (will be an empty list). Use the "+" icon to add a new context.
  5. On the context screen, use the upload option to upload and deploy the my-jiplets.spr.
  6. Verify that the context has been started by checking the jiplet log files.

If you are using the standalone jiplet container and have not installed the jiplet console, follow the steps as outlined below:
  1. Copy the my-jiplets.spr file into $JIPLET_HOME/deploy directory.
  2. Start the jiplet container.
  3. Verify that the context has been started by checking the jiplet log files.

From the jiplet console, you can override the context mapping. This is optional but you may want to do it. Basically, by default, the reference application only supports calls from the domain "cafesip.org". You can override this during the install time by using the jiplet console.

Now you are ready to check out if this works.

Checking it out

After installing the reference application, you will want to check out the application functions. The reference application implements the functionality of a very simple PBX. It implements the functionality of a simple registrar and a very simple proxy/presence server. Using this application, one or more users can register their location with the server from their SIP phone or IM client application. Once registered, the users can call each other (make call and receive calls). If the SIP phones you're using support the buddy list feature, the users can add each other into their buddy lists and monitor presence. The application also records summaries of received SIP messages into a SQL database. In short, the application provides the following functionality:
  1. Stores location information: Using a SIP phone, an user can register its location with the SIP server. When an incoming call is received for this user, this location is used to forward the call to the user.
  2. Forwards request and response messages: This application acts as a very simple proxy forwarding SIP messages to appropriate parties. This functionality is used to establish call sessions.
  3. Presence: Using a SIP phone that supports the buddy list feature, the application provides support for a simple presence server. Users can create a buddy list consisting of other users and get notified when someone in the list registers or unregisters.
  4. Records message summary: This application also stores summaries of all SIP messages recieved by the application into a SQL database.
Registration and Proxy
A SIP registrar stores the contact information for users belonging to a SIP domain. Users belonging to this domain configure the SIP server's host name/IP address as their proxy location. When users belonging to the domain, starts their SIP phones, the SIP phones send  a SIP REGISTER message to the server. The server authenticates the users and stores their contact information in the database. When an user wants to make a call to the another user belonging to this domain, the SIP invite message is sent by the calling user's (from) SIP phone  to the server. The server looks up the called user (to) in its database to locate the user's current location and forwards the INVITE message to the called user's SIP phone. All responses are similarly forwarded back to the calling user.




Here sip:amit@cafesip.org and  sip:becky@cafesip.org are registered users who register with the cafesip.org SIP server. The SIP server stores the location in its "database" and when amit makes a call to becky, the call is routed to cafesip.org SIP proxy server. The SIP server forwards the call to becky's actual location (contact address). When becky's phone sends response messages (on ringing, answer, etc), the response is forwarded to amit. Once a call is established, amit and becky's phone exchange RTP messages to transmit voice and other media payload. When one of the parties hang up, a BYE message is sent to the other party via the proxy.

To set this up, you will need two SIP phones in addition to the system running the jiplet container. You can download free SIP soft-phones that run on your computer from various sites - see phone interoperability notes. We have tested this reference application with X-Lite, PhonerLite, Windows Messenger and iSip. You will need two systems, each running the phone software. It is possible to use the same system for running the jiplet container as well as one of the phones. Just make sure that the phone does not use UDP port 5060 for SIP messaging.  Also, make sure that there is no firewall blocking the SIP and RTP ports between the SIP phones and the SIP servers.

Setup amit's SIP phone as  follows:
  1. Specify a proxy server. Enter the Host name/IP address of the system running the jiplet container. Use UDP port 5060 and TCP port 5060 for the server port number.
  2. Enter the user name: Use the name "amit". You must enter this name for the application to work.
  3. Enter a Domain: Use "cafesip.org". You must enter this name for the application to work.
  4. Enter a password: Use "a1b2c3d4". You must enter this name for the application to work.
For the X-lite SIP phone, here are the screen-shots and setup information/notes. For Windows Messenger, here are the screen-shots. These screen-shots will help you configure the phones. Also, please read the phone interoperability notes page for limitations regarding Windows Messenger.

Setup becky's sip phone the same way as amit's. Just enter the user name as "becky" and leave everything else the same. If you want to use different user names instead of becky and amit, read the next topic to find out how.

Once the systems are setup as described, bring up amit's phone and check if amit has successfully logged in. Then bring up becky's phone and make sure that becky has logged in successfully. Once logged in, let amit make a call by entering the address sip:becky@cafesip.org.

If this works as described, you should be able to establish a voice call between amit and becky.

To test if the registration feature works properly, you can move amit to another SIP phone and the SIP server should be able to route calls to amit successfully.
Presence
To check out the presence functionality, you have to use a SIP phone that supports a buddy list and standard SUBSCRIBE/NOTIFY signaling. We have tested with the XTEN LITE (X-lite) phone from http://www.counterpath.com/x-lite.html and Microsoft Windows Messenger (Version 5.1, 0680).  For the X-lite SIP phone, here are the screen-shots and setup information/notes. For Windows Messenger, here are the screen-shots. These screen-shots will help you configure and see how to use the phones. Also, please read the phone interoperability notes page for limitations regarding Windows Messenger.

If you are using the default settings as explained above, two users called "amit" and "becky" would have already been created for you in the realm database. If you are logged in as "amit", add "becky@cafesip.org" to the contacts list. Similarly, for user "becky", add "amit@cafesip.org" to the contact list. When either of the users login or logout, you should see their presence status changed in the buddy list. Also, an user can call a buddy by selecting the buddy in his/her contact list and using the right-click dropdown menu to initiate a call.
Recorder (message log)
If you want to test out the recorder functionality, install a MYSQL database server in the same system where you have installed the Jiplet server and re-start the application. The server must have a database called "test" that any user can create table and insert records (the default installation of the MYSQL server already comes with this setup as described). You can check the summary records from a MySQL client using the following SQL commands:

mysql> use test;
mysql> select * from SipLogs;

User accounts management

The SipRegistrar jiplet uses Container Managed Authentication and Authorization (CMAA). That is, the jiplet container authenticates the users when the REGISTER message is received by the container. The authentication is performed by looking up the user name and password from an authentication database (realm).  The default factory settings for the jiplet container includes a memory realm called subscribers.cafesip.org.  You can add your own user accounts by modifying the file $JIPLET_HOME/conf/jiplet-users.xml. That way, you do not have to use the user names 'amit' and 'becky'. Instead you can use 'joe', 'july' or whatever user names and passwords you want.

 It is also possible to create a JDBC realm where the user information is stored in a SQL database. If you are using the JDBC realm, you will also be able to add, modify and remove user accounts from the jiplet console. The JDBC realm configuration is explained in more details in the installation and configuration howtos.

Phone-specific setup and issues

We have tested with a number of different SIP phones, and we have seen that some are better than others. See the phone interoperability notes page for details.

Specifically, we have tested this reference application with X-Lite, PhonerLite, Windows Messenger and iSip.

Search this website 


Send questions or comments about this web site to webmaster@cafesip.org.
Copyright © 2005, CafeSip.org.
Licensed under the CafeSip License.
The CafeSip.org projects, web site and web facilities have been sponsored by QUIK Computing

Top of page