13 Deploying Applications

This chapter, through the following sections, describes deploying SIP servlet applications to application servers:

• "Overview of SIP Servlet Applications"

• "Deploying SIP Applications"

Overview of SIP Servlet Applications

A SIP application can be comprised of servlets, class files, static resources and content, along with descriptive meta information which unifies these elements. As specified in JSR-116, a SIP servlet application is a structured hierarchy of directories. For converged applications (those comprised of both HTTP and SIP), the root of the hierarchy serves as the document root for files published from a Web server.^Foot 1  Within the hierarchy of the SIP servlet application, the WEB-INF directory stores the directories containing the sip.xml deployment descriptor file (/WEB-INF/sip.xml), the utility classes available to the application loader class(/WEB-INF/classes), and the directories containing the JAR files, servlets, beans, and utility classes useful to the Web application (/WEB-INF/lib).

The Deployment Descriptor File

The SIP application's deployment descriptor file, sip.xml, is comprised of the following elements:

<sip-app>
   <context-param>...</context param>
   <display-name>...</display-name>
   <distributable>...</distributable>
   <session-config>...</session-config>
   <servlet>...</servlet>
   <servlet mappings>...</servlet mappings>
   <listener>...</listener>
   <security-constraint>...</security-constraint>
</sip-app>

The application's common parameters are set in within the <context-param> element. The <session-config> element defines the application sessions. The <servlet> element defines the servlet for the container through its <servlet-name> and <servlet-class> child elements. The <servlet mappings> element defines how the application's servlets respond to requests. The application's life cycle listener classes and error handling are defined within the <listener> element. Security is declared for each servlet using the <security-constraint> element. Refer to Oracle Communication and Mobility Server Developer's Guide for a full description of the sip.xml file's elements.

Development to Deployment

The cycle from development to deployment of a SIP servlet application is as follows:

• Creating a SIP servlet by extending javax.servlet.sip.SipServlet and then by overriding the required methods for a particular service.

• Defining the SIP servlet application's initialization parameters (servlet definitions) and invocation rules (servlet mappings).

• Creating the deployment descriptor file (sip.xml) and web.xml file.

• Building and packaging the application files and the sip.xml and web.xml files into a Web Archive format file (WAR file).

• Packaging the WAR file into an Enterprise Archive (EAR) file.

• Deploying the EAR file to OC4J.

Once the SIP servlet application has been successfully deployed and started on OC4J, view the log files and test it using a softphone client such as the Oracle Communicator client.

Deploying SIP Applications

OCMS accepts Enterprise Archive (EAR) files and Web Application Archive (WAR), but not SAR files. You must package a WAR file as an EAR file to enable the deployment of the SIP application to OC4J.

An EAR file can contain SAR files, JAR files, Web Application Archive (WAR) and EJB modules as follows:

J2EEAppName.ear
   META-INF/
   application.xml
   orion-application.xml (optional)
WebModuleName.war
   static HTML files, such as index.html
   JSP pages
   images
   WEB-INF/
      web.xml (Standard J2EE descriptor)
      orion-web.xml (optional OC4J Web descriptor)
      classes/
         servlet classes, according to package
      lib/
         JAR files for dependency classes
SIPApplicationName.sar
   WEB-INF/
      sip.xml (deployment descriptor)
      web.xml (for converged applications)
      classes/
         servlet classes, according to package
      lib/*.JAR
         JAR files for dependency classes

For more information on deployment and EAR application structure, see Oracle Containers for J2EE Developer's Guide.

Deploying, Undeploying, and Redeploying SIP Applications Using Oracle Application Server Control

Application Server Control provides a JSR 88-based deployment wizard, accessed by clicking the Deploy button on the Applications page. This wizard enables deployment and redeployment of J2EE applications and includes both task-oriented deployment plan editors for assigning or mapping the common deployment descriptors at deployment time as well as a generic deployment plan editor that enables you to access all deployment descriptors for advanced configuration. For information on undeploying and redeploying applications, see .

Note:

Although you can change an deployment plan using Application Server Control, you cannot use Application Server Control to alter the sip.xml deployment descriptor file. For information on deployment plans, see Oracle Containers for J2EE Deployment Guide.

Enterprise applications deployed beneath the application inherit security infrastructure and authentication-related EJBs (Enterprise Java Beans). This infrastructure is required to support authentication against the OCMS JAAS Security providers.

Note:

When an application has been undeployed, its MBeans are also undeployed.

Once an application has been deployed to the OC4J SIP Server instance, you can start or stop it using the admin_client.jar utility by executing the following command:

java -jar admin_client.jar uri adminId adminPwd -start|-stop appName

For Oracle Application Server, the URI parameter has the following format:

deployer:oc4j:opmn://host.example.com:6003/ocms 

For OC4J standalone, the URI parameter has the following format:

deployer:oc4j:localhost:23791

This section gives a brief overview of both of these options through the following topics:

• "Deploying, Undeploying, and Redeploying SIP Servlet Applications with Application Server Control"

• "Deploying, Undeploying, and Redeploying an Application Using the admin_client.jar Utility"

For more information, refer to Oracle Containers for J2EE Deployment Guide.

Note:

SIP applications can only be deployed to OC4J if they are packaged into a J2EE-compliant EAR file. For more information, see "Deploying Applications".

Deploying, Undeploying, and Redeploying SIP Servlet Applications with Application Server Control

The Application Server Control Console provides a wizard that steps you through deploying, undeploying, and redeploying SIP applications.

Tip:

Use a firewall to block all incoming SIP traffic until all of the applications have been fully deployed and the server started.

You can filter SIP traffic using a shell script, such as the following Linux script, blockport.sh, which uses the iptables tool.

#!/bin/bash 

 if [ $# != 1 ] 
 then 
   echo "blockport.sh <port>" 
   exit 
 fi 
 
 iptables -A INPUT -p tcp -m tcp --dport $1 -j DROP 
 iptables -A INPUT -p udp -m udp --dport $1 -j DROP 
 service iptables save 

 echo "Port "$1" blocked." 

Likewise, you can use a shell script to enable the flow of SIP traffic once the server is running and all applications have been fully deployed. The following Linux script, unblockport.sh, is an example of script that enables SIP traffic:

#!/bin/bash 
 
 if [ $# != 1 ] 
 then 
   echo "unblockport.sh <port>" 
   exit 
 fi 
 
 iptables -D INPUT -p tcp -m tcp --dport $1 -j DROP 
 iptables -D INPUT -p udp -m udp --dport $1 -j DROP 
 service iptables save 
 
 echo "Port "$1" unblocked."

For more information, see Deploying with Application Server Control Console in Oracle Containers for J2EE Deployment Guide.

Deploying an Application using the Deployment Wizard

The Deploy button on the Applications page invokes the deployment wizard which guides you through the deployment process through the following pages:

• The Select Archive page (Figure 13-1) is the first page of the wizard. To complete this page, point OC4J to the location of the EAR (Enterprise Archive) file containing the SIP application. This page also enables you to select the option to create or apply a deployment plan, a client-side aggregation of all of the configuration data needed to deploy an archive into OC4J. If you use an existing deployment plan, you enter its location. If you opt for new deployment plan, select the Automatically Create a New Deployment Plan option. Refer to "Deploying Applications" for information on EAR file structure and how to package a SIP application for deployment.

  Tip:

  The wizard automatically creates a new deployment plan if you do not enter the location of an existing plan.

  Figure 13-1 Deploying an Application: Entering the Archive Location

  
  Description of "Figure 13-1 Deploying an Application: Entering the Archive Location"
  
  

  • Clicking Next invokes the Application Attributes page (Figure 13-2). This page enables you to enter the application name and select the parent application. The application name cannot contain spaces.

    Select Subscriber Data Services as the parent application for OCMS applications requiring authentication.

    Note:

    The SIP application becomes a child of the default application if you do not specify a parent application.

    The Application Attributes page also enables you to set the binding of a Web application to a Web site by specifying the name portion of the name-web-site.xml configuration file that defines the Web site. A Web application deployed as part of a J2EE application must be bound to the Web site through which it is accessed.

    The Web module context root, which will be appended to the URL used to access the application through a Web browser, is also set as part of the process to enable Web access. This value is typically read from the application.xml deployment descriptor packaged with the application.

  Figure 13-2 Deploying an Application: Entering the Application Name and Parent Application

  
  Description of "Figure 13-2 Deploying an Application: Entering the Application Name and Parent Application"
  
  

• The Deployment Settings page (Figure 13-3) provides a tasks that enable you to edit the deployment plan.

  Figure 13-3 Deploying an Application: Configuring the Deployment Settings

  
  Description of "Figure 13-3 Deploying an Application: Configuring the Deployment Settings"
  
  

  Complete deployment tasks as needed and then click Deploy. The confirmation page appears (Figure 13-4).

  Figure 13-4 Confirming the Deployment

  
  Description of "Figure 13-4 Confirming the Deployment"
  
  

Note:

To ensure that the OMCS SIP servlet container responds appropriately to incoming requests, you must add any deployed application that processes requests to the Application Router's SIPUriList attribute. Configuring this attribute ensures that applications are added to the ROUTE header of incoming INVITE, MESSAGE, PUBLISH, REGISTER, or SUBSCRIBE requests from non-OCMS (that is, non-OCMS Communicator) SIP clients. The Proxy Registrar must always be the last item listed in the SIPUriList attribute.

Undeploying an Application Using the Deployment Wizard

You can remove (undeploy) an application by first selecting it and then by clicking the Undeploy button. When you undeploy an application, you likewise undeploy the MBeans registered to the application.

Likewise, if you undeploy a parent application, its the child applications are also undeployed. As a result, the parent application and all related applications must be redeployed. See Oracle Containers for J2EE Deployment Guide for information on when to restart OC4J when undeploying an application.

Redeploying an Application Using the Deployment Wizard

The Redeploy button enables you undeploy an application without restarting OC4J. Redeploying a SIP application packaged within an EAR file prompts OC4J to undeploy the previous instance; you do not have to first select the application and then click Undeploy.

Like deploying an application, the wizard prompts you through a three-step process for redeploying an application in which you point OC4J to the EAR file, select or create a deployment plan, select the parent application and Web bindings, and complete deployment descriptor configuration tasks.

Deploying, Undeploying, and Redeploying an Application Using the admin_client.jar Utility

The admin_client.jar command-line utility used to perform deployment-related operations on active OC4J instances in an Oracle Application Server clustered environment as well as on standalone OC4J servers.

The admin_client.jar utility is installed by default in ORACLE_HOME/j2ee/home in an OC4J instance. OC4J must be started before this utility can be used.

Deploying an Application Using admin_client.jar

To deploy an EAR, use the -deploy command with the EAR-specific context as follows:

java -jar admin_client.jar uri adminId adminPassword -deploy -file
path/filename -deploymentName appName [-bindAllWebApps [webSiteName]]
[-targetPath path] [-parent appName] [-deploymentDirectory path]
-enableIIOP [-iiopClientJar path/filename]

Undeploying an Application Using admin_client.jar

To undeploy an application:

java -jar admin_client.jar uri adminId adminPassword -undeploy appName

Redploying an Application Using admin_client.jar

To redeploy a previously deployed archive, use the -redeploy command and with the following syntax:

java -jar admin_client.jar uri adminId adminPassword -redeploy -file
path/filename -deploymentName appName [-keepSettings] [-sequential]

Refer to Deploying with the admin_client.jar Utility in Oracle Containers for J2EE Deployment Guide for more information on the -redeploy command subswitches.

Deploying the SIP Application Using the admin_client.jar Command-Line Utility

You can deploy an EAR file from the command line using the admin_client.jar utility as follows:

java -jar admin_client.jar uri adminId adminPassword -deploy -file
path/filename-deploymentName appName [-bindAllWebApps [webSiteName]]
[-targetPath path] [-parent appName] [-deploymentDirectory path]
-enableIIOP [-iiopClientJar path/filename][-deploymentPlan path/filename]

For more information undeploying and redeploying applications using the admin_client.jar utility, see . See also Oracle Containers for J2EE Configuration and Administration Guide and Oracle Containers for J2EE Deployment Guide.

Note:

The admin_client.jar utility is installed by default in ORACLE_HOME/j2ee/home in an OC4J instance. OC4J must be started before this utility can be used.

---

Footnote Legend

Footnote 1: SIP Servlet API, Version 1.0