8
Deploying Applications

Oracle9iAS Containers for J2EE (OC4J) provides a complete set of Java 2 Enterprise Edition containers that allow you to deploy all types of J2EE applications. This chapter provides an introduction to deploying J2EE applications to OC4J using the Enterprise Manager Web site and uses the familiar Petstore demo as an example of deploying an application.

It contains the following topics:

• Deploying J2EE Applications

• Deploying the Petstore Web Application Demo

• Recovering From Deployment Errors

• Undeploying J2EE Applications

  See Also: For complete information on deploying applications to OC4J, refer to Oracle9iAS Containers for J2EE User's Guide

Deploying J2EE Applications

You can deploy J2EE applications using the OC4J Home Page on the Enterprise Manager Web site. To navigate to an OC4J Home Page, do the following:

1. Navigate to the Instance Home Page where the OC4J instance resides. Scroll to the System Components section.

2. Select the OC4J instance in the Name column. This opens the OC4J Home Page for that OC4J instance.

3. Scroll to the Deployed Applications section on the OC4J Home Page.

Figure 8-1 shows the Deployed Applications section. In this section, you can deploy applications using the Deploy EAR file or Deploy WAR file buttons. After deployment, you can modify the configuration of each application.

An application may require service configuration, such as data sources or security. This chapter does not cover such configuration. See Oracle9iAS Containers for J2EE User's Guide or Oracle9iAS Containers for J2EE Services Guide for more information. The Deploying the Petstore Web Application Demo section provides an example of how you can configure data sources to support the application. In addition, the Oracle9iAS Containers for J2EE User's Guide provides more information on creating EAR and WAR files.

Figure 8-1 Deployed Applications Section

Text description of the illustration home_dep.gif

Clicking Deploy EAR File or Deploy WAR File starts the deployment wizard, which deploys the application to the OC4J instance and binds any Web application to a URL context.

Note: You can also deploy simple applications with dcmctl, the DCM command-line utility. See Appendix F, "DCM Command-Line Utility (dcmctl)" for more information.

Basic Deployment

Your J2EE application can contain the following modules:

• Web applications

  The Web applications module (WAR files) includes servlets and JSP pages.

• EJB applications

  The EJB applications module (EJB JAR files) includes Enterprise JavaBeans (EJBs).

• Client application contained within a JAR file

Archive the JAR and WAR files that belong to an enterprise Java application into an EAR file for deployment to OC4J. The J2EE specifications define the layout for an EAR file.

The internal layout of an EAR file should be as follows:

Figure 8-2 Archive Directory Format

Text description of the illustration deploya.gif

Archive these files using the JAR command in the <appname> directory, as follows:

% jar cvfM <appname>.EAR .

Note that the application.xml file acts as a manifest file.

• To deploy a J2EE application packaged within an EAR file, click Deploy Ear File in the Applications section of the OC4J Home Page.

• To deploy a J2EE Web application packaged within a WAR file, click Deploy WAR File in the Applications section of the OC4J Home Page.

Both of these buttons start an eight-step application deployment wizard that guides you through deploying an application. When you deploy an application within a WAR file, the application.xml file is created for the Web application. When you deploy an application within an EAR file, you must create the application.xml file within the EAR file. Thus, deploying a WAR file is an easier method for deploying a Web application.

Note: You must still provide configuration for J2EE services, such as data source and security configuration.

Figure 8-3 shows the eight steps required for application deployment:

Figure 8-3 Deployment Wizard Steps

Text description of the illustration buttons.gif

Introduction

The first page is an introduction to these steps. It reminds you to provide an EAR file with any OC4J-specific XML configuration files, if necessary. It also outlines some of the other steps in the deployment process.

Click Next to go to the next step in the wizard deployment process.

Select Application

Figure 8-4 shows the second page, which enables you to browse your system for the EAR file to be deployed and provide a name to be identified with this application. The application name is user-created and will be the identifier for the application in the OC4J Home Page.

Figure 8-4 Designate Ear File

Text description of the illustration deploy1.gif

When the application is deployed, the following occurs:

1. The EAR file is copied to the /applications directory.

2. A new entry is created in server.xml for the application, as follows:

   <application name=<app_name> path=<path_EARfile> auto-start="true" 
   /> 
   

   where

   • The name variable is the name of the application you provided.

   • The path indicates the directory and filename where the EAR file is deployed.

   • The auto-start variable indicates whether this application should be automatically restarted each time OC4J is restarted.

   For a description of the elements in server.xml, see Oracle9iAS Containers for J2EE User's Guide.

Click Next to go to the next step in the wizard deployment process.

Provide The URL Mappings For All Web Modules

Map any Web modules in your application to a specific URL for its servlet context. All OC4J servlet contexts must be prefixed with a slash "/". When you try to access any Web applications, you provide the host, port, and Web context.

For all Web modules, your URL mapping for the module includes the URL you bind in this screen. Thus, for the URL http://host:port/url_name, provide /url_name in the URL mapping screen of the wizard.

Figure 8-5 URL Mappings for Web Modules

Text description of the illustration deploy2.gif

Click Next to go to the next step in the wizard deployment process.

Provide Any Resource Reference Mappings

Map any resource references in your application, such as data sources or mail queues, to physical entities currently present on the OC4J container. Note that if you need a specific resource, you must have already added it to the OC4J container before you deploy your application in order for you to match them in this step.

For most applications, the resource reference you must designate is the data source JNDI name. This screen does not configure the data source information, it only designates an already configured data source or a data source that you will be configuring later. Designate the JNDI location name of the data source that the application uses.

Figure 8-6 Resource Reference Mappings

Text description of the illustration deploy3.gif

Click Next to go to the next step in the wizard deployment process.

Specify Any User Manager

You can specify what User Manager to use for security. For complete security, we recommend that you choose the JAZN XML User Manager.

Figure 8-7 User Manager Choices

Text description of the illustration usermgr.gif

As Figure 8-7 demonstrates, you must already have your User Manager set up and configured. Most of the entries require an XML file that designates the security roles, users, and groups for your security mappings.

The User Manager types are as follows:

• JAZN XML User Manager--This is the recommended User Manager. It requires a default realm and a jazn-data.xml file.

• XML User Manager--This is not the most secure option. It requires a principal.xml file.

• JAZN LDAP User Manager--This requires a default realm and an LDAP location.

• Custom User Manager--This User Manager must be programmed; provide the class name in this field.

For more information on security and User Managers, see both the Oracle9iAS Containers for J2EE User's Guide and the Security chapters in the Oracle9iAS Containers for J2EE Services Guide.

Provide Any Security Role Mappings

Map any security roles defined in your application to existing users and groups. If you have defined a security role within your application, you can map this role to a security group or role. You do not define security groups and users in this screen. Users and groups are obtained from your user manager.

Figure 8-8 Security Role Mappings

Text description of the illustration deploy5.gif

Click Next to go to the next step in the wizard deployment process.

Publish Web Services

Publish any Web services defined in your application. This feature requires the UDDI registry. Web services are not installed with a core install.

If you have defined any Web services, they are displayed on the Publish Web Services Page.

Figure 8-9 Publish Web Services

Text description of the illustration deploy6.gif

If you want to publish these Web services, then click Publish. This leads you through the process of publishing your Web services. When finished, it brings you back to this screen.

Click Next to go to the next step in the wizard deployment process.

Summary of Deployment

At this point, you will receive a summary of your application deployment modules and configuration, as shown in Figure 8-10.

Figure 8-10 Deploy Application Summary

Text description of the illustration deploy7.gif

In order to deploy this application, click Deploy. The wizard displays a message that tells you that your application is deployed.

Post-Deployment Application Modifications

You can modify any fields and perform additional configuration tasks by returning to the OC4J Home Page and selecting the application name in the Applications section. This brings you to a screen with the details of the deployed application.

From within this screen, you can view the Web and EJB modules. In addition, you can add and modify application-specific properties, resources, and security options in the Administration section. It is in this Administration section that you can add application-specific data sources or security groups or users mentioned in the deployment wizard.

Deploying the Petstore Web Application Demo

This section uses the Petstore demo as an example of how to configure and deploy a J2EE application. All OC4J server configuration and modifications to the Petstore application configuration have been performed for you. You can execute the Petstore demo with minimal effort to see how OC4J works.

Note: Displays of the screens for each step of the deployment wizard are shown in "Deploying J2EE Applications".

Downloading an OC4J-Ready Petstore Demo

This section contains instructions for downloading and deploying an OC4J-ready version of the Petstore demo. You must have a working Oracle database and an OC4J installation. You should use this installation for demonstration purposes only and not in a production environment. In this simplified version, we have pre-built the Petstore demo using Oracle database (instead of the default Cloudscape) and edited the configuration files to make the setup easy.

The Petstore demo is available on Oracle Technology Network (OTN). To install, configure, and run the Petstore demo:

1. Navigate to

   http://otn.oracle.com/sample_code/tech/java/oc4j/content.html
   

   and find the Petstore Demo in the Sample Code section.

2. Download the jps112.zip file, which contains version 1.1.2 of the Petstore demo. This ZIP file contains an annotated version of this application, along with preconfigured OC4J XML files.

3. Unzip the jps112.zip file, which contains the following:
   1. steps.html--Steps on how to deploy the Petstore demo in standalone mode. This HTML file does not contain directions on how to deploy using the Oracle Enterprise Manager. The steps in this book instruct you on how to deploy using Enterprise Manager.

   2. petstore.ear--The Petstore demo is contained in petstore.ear.

   3. config.zip--OC4J server XML configuration files are provided for you in config.zip file.

4. Unzip the config.zip file to retrieve the server.xml, default-web-site.xml, and data-sources.xml files.

5. Edit data-sources.xml to point to your database by replacing the host, port, and sid in the url attribute for the database as follows:

   url="jdbc:oracle:thin:@host:port:sid" 
   

6. Create the user estoreuser in your database and grant this user privileges to connect as SYSDBA to your database. You can create the user and grant privileges through the following command:

   SQL> grant connect, resource to estoreuser identified by estore; 
   

7. Navigate to the OC4J Home Page on the Oracle Enterprise Manager Web site.

8. Select default under the Default Application section. The default application is the automatic parent of each application and it holds global configuration information for all deployed applications, such as the data sources used. You are going to add the data sources that Petstore uses in the default application.

9. Add data sources. On the Default Application Page, scroll to the Administration section and select Advanced Properties in the Properties column.

   Since the data sources are provided in a data-sources.xml file, add these data sources using the XML editor within Enterprise Manager. Select data-sources.xml in the filename column. This brings up a screen with XML in a text window. Merge the data sources from the data-sources.xml that was provided within the config.zip of the Petstore download into the file in this window. Do not overwrite other data sources already configured in this file. When finished, click Apply.

   Note: Because you were provided the data-sources.xml file, you can add or modify this file directly through Advanced Properties. If you do not have the XML file, you can add the configuration details through the Data Sources option under the Resources column.

10. Return to the OC4J Home Page and scroll to the Applications section. Click Deploy EAR File. This starts the application deployment wizard.

11. Read the introduction to the deployment wizard. Click Next.

12. Provide the EAR file and the name of your application on the Select Application Page. Click Browse to find the petstore.ear file that you downloaded to your system. Type "petstore" in the application name field. Click Next.

13. Provide the URL mappings for the servlet context on all Web modules in the Petstore application. The Petstore demo contains a single Web module, which should be mapped to the /estore servlet context. Type "/estore" in the URL mapping field and click Next.

14. At this point, the Petstore demo does not need any additional configuration through the wizard. Click Finish., which takes you to the Summary Page.

15. Read the summary of the Petstore application deployment. Click Deploy to complete the application deployment.

16. Select "petstore" in the Name column of the Applications section on the OC4J Home Page. This shows the configuration and all deployed modules of the Petstore demo application. If the OC4J server is started, the application is automatically started.

17. Execute the Petstore application in your browser by accessing the Oracle HTTP Server, where the default port is 7777.

    http://http_server_host:http_server_port/estore 
    

    The Petstore splash screen appears. Follow the instructions provided by the Petstore application to load the Java Petstore database tables.

Recovering From Deployment Errors

If the deployment process is interrupted for any reason, you may need to clean up the temp directory, which by default is:

• (UNIX) /var/tmp

• (Windows) The directory defined by the TEMP system variable

The deployment wizard uses 20 MB of swap space in the temp directory for storing information during the deployment process. At completion, the deployment wizard cleans up the temp directory by removing its files. However, if the wizard is interrupted, it may not have the time or opportunity to clean up the temp directory. Thus, you must clean up any additional deployment files from this directory yourself. If you do not, this directory may fill up, which will disable any further deployment. If you receive an Out of Memory error, check for space available in the temp directory.

If the temp directory does not have enough space, you can configure OC4J to use a different temp directory using the Enterprise Manager Web site:

1. Navigate to the OC4J Home Page. Scroll to the Administration Section.

2. Select Server Properties in the Administration section. This opens the Server Properties Page.

3. Scroll to the Command Line Options section. Add the following variable definition to the OC4J Options line:

   java.io.tmpdir=new_temp_dir
   

   where new_temp_dir is the full path to the new temporary directory.

   All new OC4J processes will use the new temp directory.

Undeploying J2EE Applications

You can undeploy a J2EE Web application using the Enterprise Manager Web site:

1. Navigate to the OC4J Home Page that contains the application you would like to undeploy. Scroll to the Applications section.

2. Click the radio button in the Select column for the application.

3. Click Undeploy.

This operation results in the following:

• The application is removed from the OC4J runtime.

• All bindings for the Web modules are removed from all the Web sites to which the Web modules were bound.

• The application files are removed from both the applications and application-deployments directories.

  Note: You can also undeploy applications with dcmctl, the DCM command-line utility. See Appendix F, "DCM Command-Line Utility (dcmctl)" for directions.