2 Getting Started

This chapter describes the Oracle Communications Converged Application Server Service Creation Environment (SCE), an Eclipse-based development environment that eases the task of developing SIP and converged applications.

About the Service Creation Environment

The SCE is a separately installed software component that supplements the Oracle Enterprise Pack for Eclipse (OEPE). The Converged Application SCE works with OEPE version 7.1 and later.

The OEPE supplements the underlying Eclipse software with features specifically intended to facilitate application development for WebLogic. The features are available for converged application development as well, and include:

• Tools for editing deployment descriptors and deployment plans graphically.

• Remote application deployment capabilities

• Oracle WebLogic Server Extension Facets

For more information about OEPE, see the Oracle Enterprise Pack for Eclipse overview page on Oracle Technology Network:

http://www.oracle.com/technetwork

In addition, the Converged Application SCE supplements the OEPE with features specifically intended for converged application development. The features enable you to:

• Create SIP and converged applications using rapid development tools, such as wizards and templates. SCE provides wizards for creating SIP listeners, SIP servlets and other SIP components.

• Use simulators to perform the functions of IMS components in your development environment, such as an XML Document Management Server (XDMS), media servers, and charging servers.

• Use SIPp directly from the Eclipse development environment.

• Reduce the time required to build, deploy, and debug your application due to the integration between the SCE and the Converged Application Server runtime environment.

The SCE supplements Eclipse using the mechanism of the Eclipse faceted project framework. Each facet in Eclipse is made up of a bundled set of features in the form of libraries, tools, and resources. The capabilities are typically targeted to a specific type of application or for creating applications for a target domain, such as communication services.

When you create a converged application project, the appropriate SCE facets are included in the project. In addition, you can add the SCE facets to existing projects. See "Converged Application Project Configuration" for more information about SCE project facets.

SCE Workflow Overview

The high-level steps for getting started developing converged applications with the SCE are:

1. Ensure that your system meets the requirements for installing and using the Service Creation Environment.

   See "Before Starting" for more information.

2. Install the Converged Application SCE software to OEPE.

   See "Installing the Converged Application Service Creation Environment" for more information.

3. Create a Converged Application Project, using the Converged Application Server as the runtime target environment for the project.

   See "Creating a Converged Application Project" for more information.

4. Use wizards and templates to create the initial source code for your converged application classes.

   See "Creating Applications with the Converged Application SCE Wizards" for more information.

5. Deploy, test, and debug the application using the SCE simulators and other testing tools.

   See "Creating Applications with the Converged Application SCE Wizards" for more information.

The followings sections provide more information on the steps specific for the SCE. For more information on using OEPE for Eclipse, see the Eclipse documentation.

About Converged Application Projects

Eclipse organizes the resources and artifacts associated with a particular application development effort into projects. There are various types of projects, each of which is intended for a particular type of application.

To develop SIP and converged applications with the SCE, you use the project type Converged Application Project. The Converged Application Project contains the resources for developing applications for the Converged Application Server.

The Converged Application Project offers two types of configuration types. The configuration types are the base Converged Application Project configuration and the Converged SIP Diameter Project configuration, which are described in the following sections.

Converged Application Project Configuration

A Converged Application Project is similar to a Dynamic Web Project, but it adds components intended for SIP and converged application development, such as SIP and SFT libraries, IMS simulators, and more.

The base Converged Application Project includes the following facets:

• Dynamic Web Module

• Java

• JavaScript

• Oracle Communication Converged Application Extensions, including:

  • SIP Servlet

  • SFT Communication Bean

• Oracle WebLogic Web Application Extensions

In addition to standard JRE resources, the facets contain Converged Application Server system library files, such as sft-communication-api.jar and sipservlet.jar, as well as sft.xml, sip.xml, and web.xml deployment descriptor files.

The Converged Application Projects enables you to create SFT Communication Beans and SIP Servlets along with standard HTTP Servlets, JPSs, static files, and EJB-based classes.

Notice that an additional Converged Application Project facet, the Diameter extension facet, is not enabled by default. To create Diameter applications with the SCE, either use the Converged SIP Diameter Project type configuration with the Converged Application Project, or enable the facet.

Converged SIP Diameter Project Configuration

You use the Converged SIP Diameter Project configuration for converged applications that need to interact with Diameter nodes.

The Converged SIP Diameter Project incorporates these facets:

• Dynamic Web Module

• Java

• JavaScript

• Oracle Communication Converged Application Extensions, including:

  • Diameter Extension

  • SIP Servlet

• Oracle WebLogic Web Application Extensions

The target domain server to which you deploy a Diameter-enabled application must be capable of operating as a Diameter node. Therefore, before deploying a Diameter application, you should ensure that the target domain has been extended for Diameter operability. The SCE provides an interface for extending target domains with Diameter capabilities. See "Extending Domains with Diameter Capabilities" for more information.

Notice that the SFT Communication Bean facet is not enabled by default. To create SFT applications, you need to enable the facet.

Before Starting

The SCE relies on external components that must be present before you can install or use SCE.

Before you can start working with the SCE, confirm the following prerequisites:

• A Converged Application Server installation with an administrative domain that you can configure and restart as necessary.

  See information on creating a domain in the Oracle Communications Converged Application Server Installation Guide.

• Oracle Enterprise Pack for Eclipse 11g R1 (11.1.1.7.1) or later.

To get OEPE, download the latest installer suitable for your operating system from the Oracle Enterprise Pack for Eclipse download page on Oracle Technology Network:

http://www.oracle.com/technetwork/developer-tools/eclipse

Follow the instructions provided for downloading and installing the OEPE software.

Enabling Converged Application Server Debug Option

When developing and testing converged applications, you may find it useful to enable debug options on the Converged Application Server.

Follow these steps to add debugging options to the startup script and to attach the debugger from within Eclipse.

Note:

On Linux, debug is enabled by default if you install in developer mode. However, the port is set to 8453.

1. Use a text editor to open the StartWebLogic.cmd script for your development domain.

2. Beneath the line that reads:

   set JAVA_OPTIONS=
   Enter the following line:
   set DEBUG_OPTS=-Xdebug -Xrunjdwp:transport=dt_socket,address=9000,server=y,suspend=n
   

3. In the last line of the file, add the %DEBUG_OPTS% variable in the place indicated below:

   "%JAVA_HOME%\bin\java" %JAVA_VM% %MEM_ARGS% %JAVA_OPTIONS% %DEBUG_OPTS% 
   -Dweblogic.Name=%SERVER_NAME% -Dweblogic.management.username=%WLS_USER% 
   -Dweblogic.management.password=%WLS_PW%
   -Dweblogic.management.server=%ADMIN_URL%
   -Djava.security.policy="%WL_HOME%\server\lib\weblogic.policy" weblogic.Server
   

4. Save the file and use the script to restart Converged Application Server.

5. To attach the debugger from within Eclipse select Run, and then select the Open debug dialog box.

6. Create a new Remote Java Application.

7. Enter the host and port corresponding to the DEBUG_OPTS.

Installing the Converged Application Service Creation Environment

The SCE software is distributed as a JAR file that is located in your Converged Application Server installation directory.

The JAR file is named:

com.oracle.occas.sce.updatesite_5.1.0.jar

The JAR file is located in the following directory:

MW_HOME/occas_5.1/sce

Where MW_HOME is the Oracle Middleware home directory as defined during installation.

You install the Converged Application SCE software to the OEPE using the Update Manager feature in the Eclipse environment.

Before starting, make sure that you have installed the correct version of OEPE and that you can access the JAR file from the computer on which you are using the OEPE. If necessary, copy the JAR file from the Converged Application Server computer to the computer on which you intend to install the SCE software.

The following steps describe how to use the update manager to install the SCE. As a final step in the installation, you will need to restart the OEPE. You should start the installation procedure only if it is convenient to restart Eclipse.

To install Converged Application Server SCE in OEPE:

1. From the main menu in the Eclipse window, click Help and then Install New Software.

2. Click the Add button next to the Work with field.

3. In the Add Repository dialog, click Archive.

4. In the Repository archive dialog, navigate to the directory that contains the SCE distribution archive. By default, the name and location of the file is:

   OCCAS_HOME/sce/com.oracle.occas.sce.updatesite_5.1.0.jar

5. Select the file and click OK.

6. In the Add Repository dialog, click OK.

   The available software list in the Available Software dialog refreshes, showing an item for OCCAS Service Creation Environment.

7. Select OCCAS Service Creation Environment check box.

8. If the option is enabled, clear the Contact all update sites during install to find required software check box.

9. Select OCCAS Service Creation Environment check box and click Next.

   The Install Details page appears in the Install dialog. The page lists the OCCAS Service Creation Environment as the item to install.

10. Make sure that the OCCAS Service Creation Environment appears as an item to be installed in the Install Details screen and click Next.

    The Review license page appears.

11. Review the license agreement and click I accept the terms of the license agreement and then Finish to complete the installation. Alternatively, click Cancel to terminate the installation.

    If you accepted the license agreement, the Installing Software dialog appears.

12. If a security warning appears that indicates that the software contains unsigned content, click OK to continue.

    The Installing Software dialog shows the progress of the installation. When it is finished, you are prompted to restart the Eclipse platform to complete the installation.

13. Click Restart Now to have the installation changes take effect.

The SCE software is now installed in OEPE. Notice that the OCCAS menu appears on the top menu bar of the Eclipse interface. You can now use the SCE to create Converged Application Server projects or add Converged Application Server facets to existing projects.

You can uninstall the SCE software at any time from the Install New Software dialog by clicking the What is already installed? link. When the list of installed software appears, select the OCCAS Service Creation Environment from the list and click the Uninstall button. Follow the on-screen instructions to complete the software removal.

Creating a Converged Application Project

Eclipse organizes the resources of a particular application or set of applications into projects. There are various types of projects, each associated with a particular type or class of application.

To develop converged applications with the SCE, you can use the Converged Application Project or the Converged SIP Diameter Project.

The Converged Application Project type is similar to the Dynamic Web Project, but adds support for SIP and converged application development. Thus, for example, you can use it to develop SIP servlets, HTTP servlets, JPSs, static files, EJBs, and so on.

The SIP Diameter Project type adds tools for developing SIP applications that can interact with Diameter nodes.

To create a new converged application project, follow these steps:

1. From the File menu, select New and Other.

2. In the Select a wizard screen, expand the Oracle node and then the OCCAS Application node.

3. Choose Converged Application Project and click Next.

4. Type a name for the project in the Project name field.

5. From the Target Runtime menu, choose the target server environment to which to deploy the converged application.

   If you have not already defined a Converged Application Server installation as a target server, do the following:

   1. Click New Runtime.

   2. Under the Oracle node in the target environment list, choose Oracle WebLogic Server 11gR1 (10.3.6) and click Next.

   3. Specify the WebLogic home directory by clicking the browse icon and selecting the wlserver_10.3 directory in your Oracle Middleware home.

   4. Specify the Java home, if it is not already populated based on your WebLogic home selection.

   5. Click Finish to save the target runtime configuration.

6. From the Dynamic web module version menu choose 2.5.

7. Verify that the Dynamic web module version value is 2.5.

8. From the Configuration menu, choose:

   • Converged Application Project to create converged and SIP applications, including SFT applications.

   • Converged SIP Diameter Project to create converged and SIP applications that can act as Diameter nodes.

9. If needed, select the option to have the project output added to an EAR file or to working sets.

   In most cases, converged applications are deployed as SAR or WAR files. However, you can choose to output to an EAR file if your project contains both SIP and enterprise JavaBean components.

10. Click Next and optionally specify the source file location. By default, source files are stored in the src directory.

11. If you want to modify the default context root or content directory, click Next and specify the new values for the project.

12. Click Finish

The wizard creates the project components and configuration settings. You can now add source files to the project by creating them manually or by using the SCE code generation wizards. SCE provides wizards and templates for creating a variety of SIP and converged application types.

Adding Converged Application Project Facets to an Existing Project

As an alternative to creating a new Converged Application Project, you can add the Converged Application Project facets to an existing project of a different type, such as a Dynamic Web Project or Enterprise Application Project.

Adding Converged Application facets to the projects makes the SCE wizards, tools, and project resources available in the existing project.

To add the Converged Application Project facets to an existing project:

1. In the Project Explorer, right click on the name of the project and choose Properties from the menu.

2. In the Properties dialog, choose Project Facets.

3. Select the following facets:

   • Oracle Communications Converged Applications Server SIP adds SIP API support to the project.

   • SIP Deployment Descriptor adds the SIP Deployment Descriptor file (sip.xml) to the project.

4. Click OK.

You can now use the Converged Application tools and wizards in your project.

Creating an Ant Build File

The OEPE includes project-build features that allow you to build your applications automatically. However, for complex projects, you may choose to use the Ant build tool. Ant provides fine-grained control over project building and deploying logic.

To create an Ant build file:

1. Right-click on the name of your project in Eclipse, and select New, and then select File.

2. Enter the name build.xml and click Finish. Eclipse opens the empty file in a new window.

3. Copy the sample text from Example 2-1, substituting your domain name and application name for myDomain and myApplication.

   Example 2-1 Ant Build File Contents

   <?xml version="1.0" encoding="ISO-8859-1"?>
   <project default="all">
     <property environment="env"/>
     <property name="beahome" value="${env.BEA_HOME}"/>
     <target name="all" depends="compile,install"/>
     <target name="compile">
       <mkdir dir="WEB-INF/classes"/>
       <javac destdir="WEB-INF/classes" srcdir="src" debug="true" debuglevel="lines,vars,source">
         <classpath>
           <pathelement path="${weblogic.jar}"/>
         </classpath>
       </javac>
     </target>
     <target name="install">
       <jar destfile="${beahome}/user_projects/domains/myDomain/applications/myApplication.war">
         <zipfileset dir="WEB-INF" prefix="WEB-INF"/>
         <zipfileset dir="WEB-INF" includes="*.html"/>
         <zipfileset dir="WEB-INF" includes="*.jsp"/>
       </jar>
     </target>
   </project>
   

4. Close the build.xml file and save your changes.

5. Verify that the build.xml file is valid by selecting the Window menu, then select Show View, and then select Ant and dragging the build.xml file into the Ant view. Correct any problems before proceeding.

6. Right-click on the project name and select Properties.

7. Select the Builders property in the left column, and click New.

8. Select the Ant Build tool type and click OK to add an Ant builder.

9. In the Buildfile field, click Browse Workspace and select the build.xml file you created.

10. In the Base Directory field, click Browse Workspace and select the top-level directory for your project.

11. Click the JRE tab and choose Separate JRE in the Runtime JRE field. Use the drop-down list or the Installed JREs... button to select an installed version 1.6 JRE.

12. Click the Environment tab, and then click New. Enter a new name/value pair to define the BEA_HOME variable. The BEA_HOME variable must point to the home directory of the Converged Application Server directory. For example:

    • Name: BEA_HOME

    • Value: c:\oracle

13. Click OK to add the new Ant builder to the project.

14. De-select Java Builder in the builder list to remove the Java builder from the project.

15. Click OK to finish configuring Builders for the project.

Deploying SIP Applications from Eclipse

The deployable SIP application is a EAR archive file created by the export wizard. In addition to project resources, the EAR file includes the SIP deployment descriptor file.

1. Right click on the project name in the Project Explorer, and select Run As, then select Run on Servers.

2. In the Run On Server dialog box, verify that the server you are targeting is selected.

3. Click Finish.

   The SCE does the following:

   • Packages the SIP application.

   • Starts the specified OCCAS instance if it is not running.

   • Publishes the application to the OCCAS instance.

   • Launches the application.

     The console view displays the log file tracking the progress of the deployment.