Skip Headers

Oracle® Communication and Mobility Server Developer's Guide Release 10.1.3 Part Number E10293-02 |
Home | Contents | Index | Contact Us

Previous | Next
| View PDF

# 5 Building a SIP Servlet Application

This chapter illustrates how to build a SIP Servlet application through OCMS SCE by creating a new project, importing an existing project, or by importing one of the example project provided with OCMS SCE. For more information on the OCMS SCE example projects and other SIP servlets, including source code, refer to Oracle Communication and Mobility Server documents on Oracle Technology Network (http://www.oracle.com/technology/index.html).

This chapter contains the following sections:

- Prerequisites

- SIP Application Development Process

- Creating a New Dynamic Web Project with SIP Support

- Importing an Existing Project

- Importing Example Projects

  - Importing the Basic Response SIP Application Example Project

  - Importing the Call Forward SIP Application Example Project

  - Importing the Message Sender SIP/Web Converged Application Example Project

  - Importing the Proxy/Registrar Example Project

  - Importing the Third Party Call Control Example Project

- Deploying a SIP Application to OCMS

- Testing an Application

## Prerequisites

Before building a SIP servlet application, ensure that you have completed the following prerequisite steps:

1. Installing Eclipse Web Tools Platform 1.5.

   Refer to Oracle Communication and Mobility Server Installation Guide for installation instructions. For information on Eclipse functionality, refer to the tutorial at http://www.eclipse.org/webtools/community/communityresources.html.

2. Installing OCMS with the OCMS Service Creation Environment component. Select from one of the following installation mode options: OC4J mode (Oracle Containers for J2EE must already be installed) or standalone mode (a standalone version of Oracle Containers for J2EE is installed with OCMS).

   Refer to Oracle Communication and Mobility Server Installation Guide for installation instructions.

3. Initializing the OCMS Service Creation Environment, and adding OCMS as a Server in OCMS SCE. Refer to Oracle Communication and Mobility Server Installation Guide.

4. Defining the public and private hosts (for JBoss installations): the Tomcat Web container is configured by default to have two hosts that can be used by any service; a public host and a private host. By default the hosts are set to yourdomain.com and private.yourdomain.com. Because these two hosts are not in your network's Domain Name Service (DNS) you must define them.

## SIP Application Development Process

Applications developers can create a fully-converged SIP and HTTP application with OCMS by performing the following tasks.

For more information on performing these tasks, refer to Chapter 5, "Building a SIP Servlet Application".

1. Create a SIP servlet

   1. Create a SIP Servlet Project.

      - Create a SIP servlet.

      - Define the SIP servlet's initialization parameters (servlet definitions) and invocation rules (servlet mappings) in the application of the SIP Servlet in each of the deployment descriptors created.

2. Create a SIP application

   1. Create a SIP Application Project (SSR).

   2. Choose the servlets to include.

   3. Update the deployment descriptor with the following:

      - Servlet Context init parameters

      - Session configurations

      - Application lifecycle listener classes

      - Error handler

3. Create Utility Classes (business logic)

   1. Create an EJB Project.

   2. Create EJBs.

4. Create static resources and content such as text and speech announcement.

5. Create Web functionality

   1. Create a Web Application Project.

   2. Create servlets and JSPs.

6. Create an Enterprise Application

   1. Create an Enterprise Application Project.

   2. Choose your applications that should form the Enterprise Application. (SIP Application, Business Logic, Web Application).

7. Test your application

   1. Deploy the application to the application server.

   2. Test and debug the application.

## Creating a New Dynamic Web Project with SIP Support

Perform the following procedure to create a new project in Eclipse for deployment to OCMS:

1. Close the "welcome" window of Eclipse if it is shown.

2. Select the Eclipse Java perspective by selecting Window, Open Perspective, and Java.

3. Create a new project by selecting File, New, Project, OCMS SCE, Dynamic Web Project with SIP Support.

4. Enter the project name.

5. Select the target runtime from the drop-down menu.

   This runtime will be preconfigured if the OCMS Server has been added as described in Prerequisites.

6. Click Finish.

   A new Java Project is created in the Package Explorer. Access the Package Explorer by selecting Window, Show View, Package Explorer. To deploy your project, perform the steps described in Deploying a SIP Application to OCMS.

## Importing an Existing Project

Perform the following procedure to import an existing project into Eclipse for deployment to OCMS:

Note:

When importing a new project into Eclipse for use with the OCMS SCE, the project must be located in the workspace directory. Otherwise the deployment into OCMS will not work.

1. Close the "welcome" window of Eclipse if it is shown.

2. Select the Eclipse Java perspective by selecting Window, Open Perspective, and Java.

3. Create a new project by selecting File, Import, Web, WAR file.

4. Navigate to the Eclipse workspace directory and locate the WAR file to be imported.

5. Select the project.

6. Select "OCMS SipAS - OC4J 10.1.3.2" as the target runtime from the drop-down menu.

   This runtime will be preconfigured if the OCMS Server has been added as described in Prerequisites.

7. Click Finish.

   A new Java Project is created in the Package Explorer. Access the Package Explorer by selecting Window, Show View, Package Explorer. To deploy your project, perform the steps described in Deploying a SIP Application to OCMS.

## Importing Example Projects

The section describes how to import and configure the example projects provided by OCMS SCE. There is a Readme file provided with all the example projects (except the Basic Response project) that includes steps to deploy and use the project. Refer to the Readme file bundled with the project for additional information.

OCMS SCE provides the following six example projects (Figure 5-1):

- Basic Response SIP Application Example Project: This SIP servlet receives an incoming MESSAGE and sends back a response to the sender.

- Call Forward SIP Application Example Project: This SIP servlet provides Call Forward on No Answer functionality.

- Message Sender SIP/WEB Converged Application Example Project: This application includes the Message Sender SIP Servlet and a web page from which a message can be sent to a SIP address.

- Parlay X Web Services Client Example Project: This is a Parlay X Web Services client example project that uses the Presence Supplier interface.

  Note:

  The Parlay X Web Services client is a client side project, and cannot be deployed on a server (it is not packaged as a WAR or EJB). You should run this project as a normal Java application

- Proxy/registrar SIP Application Example Project: This SIP application can register and authenticate users and can set up voice and video calls as well as allow instant messaging between registered users.

- Third Party Call Control SIP Application Example Project: This application is a Third Party Call Control SIP example application that performs basic Click-to-Call functionality, implements Flow I in RFC 3725 (the recommended call flow for man-machine call setup), and provides a Web interface.

Figure 5-1 OCMS SCE Example Projects

Description of "Figure 5-1 OCMS SCE Example Projects"

### Importing the Basic Response SIP Application Example Project

Perform the following procedure to import the Basic Response example project into Eclipse SCE:

1. Close the "welcome" window of Eclipse if it is shown.

2. Select the Eclipse Java perspective by selecting Window, Open Perspective, and Java.

3. Import the example SIP servlet project by selecting File, New, Project, OCMS SCE, Example Projects, Basic Response SIP Application Example Project.

4. Enter basicresponse as the project name and click Finish.

   A new Java Project is created in the Package Explorer. Access the Package Explorer by selecting Window, Show View, Package Explorer. To deploy your project, perform the steps described in Deploying a SIP Application to OCMS.

### Importing the Call Forward SIP Application Example Project

Perform the following procedure to import the Call Forward example project into Eclipse SCE:

1. Close the "welcome" window of Eclipse if it is shown.

2. Select the Eclipse Java perspective by selecting Window, Open Perspective, and Java.

3. Import the example SIP servlet project by selecting File, New, Project, OCMS SCE, Example Projects, Call Forward SIP Application Example Project.

4. Enter callforward as the project name and click Finish.

   A new Java Project is created in the Package Explorer. Access the Package Explorer by selecting Window, Show View, Package Explorer. To deploy your project, perform the steps described in Deploying a SIP Application to OCMS.

### Importing the Message Sender SIP/Web Converged Application Example Project

Perform the following procedure to import the Message Sender example project into Eclipse SCE:

1. Close the "welcome" window of Eclipse if it is shown.

2. Select the Eclipse Java perspective by selecting Window, Open Perspective, and Java.

3. Import the example SIP servlet project by selecting File, New, Project, OCMS SCE, Example Projects, Message Sender SIP/Web Converged Application Example Project.

4. Enter messagesender as the project name and click Finish.

   A new Java Project is created in the Package Explorer. Access the Package Explorer by selecting Window, Show View, Package Explorer. To deploy your project, perform the steps described in Deploying a SIP Application to OCMS.

### Importing the Proxy/Registrar Example Project

Perform the following procedure to import the Proxy/Registrar example project into Eclipse SCE:

1. Close the "welcome" window of Eclipse if it is shown.

2. Select the Eclipse Java perspective by selecting Window, Open Perspective, and Java.

3. Import the example SIP servlet project by selecting File, New, Project, OCMS SCE, Example Projects, Proxy/registrar SIP Application Example Project.

4. Enter proxyregistrar as the project name and click Finish.

   A new Java Project is created in the Package Explorer. Access the Package Explorer by selecting Window, Show View, Package Explorer. To deploy your project, perform the steps described in Deploying a SIP Application to OCMS.

### Importing the Third Party Call Control Example Project

Perform the following procedure to import the Third Party Call Control example project into Eclipse SCE:

1. Close the "welcome" window of Eclipse if it is shown.

2. Select the Eclipse Java perspective by selecting Window, Open Perspective, and Java.

3. Import the example SIP servlet project by selecting File, New, Project, OCMS SCE, Example Projects, Third Party Call Control.

4. Enter tpcc as the project name and click Finish.

   A new Java Project is created in the Package Explorer. Access the Package Explorer by selecting Window, Show View, Package Explorer. To deploy your project, perform the steps described in Deploying a SIP Application to OCMS.

## Deploying a SIP Application to OCMS

Perform the following procedure to deploy SIP applications to OCMS:

1. Associate the projects to be deployed to a server by performing the following steps:

   - In the Servers view right-click "OCMS SipAS - OC4J 10.1.3" and select Add and Remove Projects (Figure 5-2).

     Figure 5-2 Adding Projects to a Server

     Description of "Figure 5-2 Adding Projects to a Server"

   - In the Add or Remove Projects dialog box select the projects and use the Add button to add your projects to the list on the right called "Configured projects."

   - Select Finish to complete the association of the projects to the OCMS server.

2. Right-click the server in the Servers view and select Publish to start and deploy the SIP applications (Figure 5-3).

   Figure 5-3 Selecting Publish in the Servers View to Deploy Applications

   Description of "Figure 5-3 Selecting Publish in the Servers View to Deploy Applications"

   The application is ready to be tested.

## Testing an Application

After you have built and deployed your application you must test its functionality. When starting OCMS the application will automatically be started. Verify that the application has started correctly by examining the system logging files.

Tip:

You can obtain a tool to view frequently updated log files. Install one of the following log viewers tools, if you do not already have one:

- LogWatcher, downloadable from `http://graysky.sourceforge.net` or

- Tail XP, downloadable from `http://infiero.com/tailxp`.

### Changing the Logging Level

Setting the log level to DEBUG provides a more detailed level of information for the developer. Using the SIPServletContainerLogging MBean, set the system log level to DEBUG by entering DEBUG as the value of the System attribute. See Oracle Communication and Mobility Server Administrator's Guide for more information.

### Viewing the System Log File

Start the log file viewer and view the system log file, `system.log`. Log files are located under <ocms_home>/j2ee/home/log/sdp.

### Starting the OCMS Server in Eclipse

Start the server by opening the Server view. Select Window, Show view, Other… and select Server, Servers and click OK. Right-click on the OCMS SipAS 10.1.3 server and from the context menu select Debug to start the server in debug mode.

Eclipse changes the active view to the console view. This view is active until the server has changed the log output to the `system.log` file, as indicated by a message ("Configuring from URL:...") in the preceding Console view.

Eclipse will start when the server has changed back to the server view. Look for the following message in the console: "<date> <time> Oracle Containers for J2EE 10g (10.1.3.3) initialized."

Note:

Even if a SIP servlet fails to startup the server will display that it is started. You must view the log file to verify whether the SIP servlet deployed successfully.

### Testing a Third Party Call Control Servlet

To test an application, open a Web browser and navigate to the URL of the application on the OCMS server.

For example, to test the Third Party Call Control servlet perform the following steps:

1. Navigate to the following URL `http://localhost:8888/tpcc` (Figure 5-4).

2. Enter two SIP addresses.

   If you have a PSTN Gateway, you can call a PSTN telephone, by entering the full number with the PSTN gateway address. For example, sip:16505555555@<ip-address-of-gateway>

3. Click Connect.

   The call is connected. Invitation 1 (the invitation to the first address/number) is sent first. Invitation 2 is sent after a short delay. Verify that the communication is successfully established.

Figure 5-4 Using Click-to-Call (Third-Party Call Control)

Description of "Figure 5-4 Using Click-to-Call (Third-Party Call Control)"