7 Packaging and Deploying Applications

This chapter, through the following sections, describes packaging and 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>
   <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).
Building and packaging the application files and the sip.xml file into a Servlet Archive format file (SAR file).

Note:
SIP applications deployed through JBoss AS must be called SIP Servlet Archive files (.ssr) rather than Servlet Archive (.sar) files. Although the formats of .ssr and .sar files are identical, The JBoss Application Server cannot dispatch files with the .sar extension. Because of this limitation, you must use the .ssr extension when deploying an application using JBoss Application Server.
Packaging the SAR (or SSR) file into an Enterprise Archive (EAR) file.
Deploying the EAR file to OC4J (or JBoss Application Server).

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. Refer to Oracle Communication and Mobility Server Developer's Guide for more information on developing SIP servlets using OCMS SCE and the Eclipse SDK.

Deploying SIP Applications

OCMS accepts Enterprise Archive (EAR) files and Web Application Archive (WAR), but not SAR (or SSR) files. Therefore, you must package the SAR (or SSR) 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 the SIP Application 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 "Deploying, Undeploying, and Redeploying SIP Servlet Applications with Application Server Control".

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.

SIP applications deployed beneath the Subscriber Data Services application inherit security infrastructure and authentication-related EJBs (Enterprise Java Beans). This infrastructure is required to support authentication against the OCMS JAAS Security providers. For more information, see Chapter 6, "OCMS Security".

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

Figure 7-1 Deploying an Application

Description of "Figure 7-1 Deploying an Application"

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 "Deploying, Undeploying, and Redeploying an Application Using the admin_client.jar Utility". 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