1
Configuration and Deployment

This chapter demonstrates how to configure and execute OC4J as simply and quickly as possible. Within OC4J, you can execute servlets, JSP pages, EJBs, and SQLJ. As an example of deploying an application to OC4J, this chapter describes how to configure the FAQ application demo.

This chapter includes the following topics:

• Introduction to OC4J Standalone

• OC4J Installation

• Starting and Stopping OC4J

• Creating the Development Directory

• Configuring the FAQ Application Demo

• Deploying Applications

• Undeploying Web Applications

Introduction to OC4J Standalone

Oracle Application Server Containers for J2EE (OC4J) Standalone provides a complete Java 2 Enterprise Edition (J2EE) 1.3 environment written entirely in Java that executes on the Java virtual machine (JVM) of the standard Java Development Kit (JDK). You can run OC4J on the standard JDK that exists on your operating system or install it separately. Refer to the certification matrix on http://otn.oracle.com.

OC4J is J2EE 1.3 certified and provides all the containers, APIs, and services that J2EE specifies. OC4J is based on technology licensed from Ironflare Corporation, which develops the Orion server--one of the leading J2EE containers, so the product and some of the documentation still contains some reference to the Orion server.

OC4J supports and is certified for the standard J2EE APIs, as listed in Table 1-1.

Table 1-1 OC4J J2EE Support

J2EE 1.3 Standard APIs	Version Supported
JavaServer Pages (JSP)	1.2
Servlets	2.3
Enterprise JavaBeans (EJB)	2.0
Java Transaction API (JTA)	1.0
Java Message Service (JMS)	1.0
Java Naming and Directory Interface (JNDI)	1.2
Java Mail	1.1.2
Java Database Connectivity (JDBC)	2.0 Extension
Oracle Application Server Java Authentication and Authorization Service	1.0
J2EE Connector Architecture	1.0
JAXP	1.1

OC4J Standalone is for use by development and small-medium scale production deployments. Specifically, OC4J Standalone supports HTTP and HTTPS natively without the use of Oracle HTTP Server. It does not have support for load balancing, clustering, or management through Oracle Enterprise Manager. To use those features, customers must install one of the Oracle Application Server installation type, such as J2EE + WebCache. The standalone version is supported in a single instance, single JVM, and single machine configuration.

The OC4J documentation assumes that you have a basic understanding of Java programming, J2EE technology, and Web and EJB application technology. This includes deployment conventions such as the WEB-INF and META-INF directories.

Examples in each of the primers assume the following:

• You have a working JDK (1.3.1 or 1.4.1).

• You have installed OC4J.

• You have started OC4J.

Examples also use standard J2EE configuration files such as web.xml and application.xml.

OC4J Installation

OC4J is a lightweight container that is J2EE-compliant. It is configured with powerful and practical defaults and is ready to execute after installation. After downloading the oc4j_extended.zip file from OTN, unzip this file to install OC4J. The following sections describe how to do this:

• Requirements

• Basic Installation

• Testing the Default Configuration

Requirements

You do not need to add anything to your CLASSPATH to run OC4J, because it loads the Java JAR and class files directly from the installation directory, from the lib/ subdirectory, and from the deployed applications EAR, WAR, or ejb-jar files.

Basic Installation

OC4J is distributed within a ZIP file named oc4j_extended.zip on OTN. After unzipping this file, follow instructions listed in the README.TXT. Install this ZIP file in any directory that is in the path.

You must have a Java2 version Java executable in your $PATH, preferably version 1.3.1 or 1.4.1. To install OC4J, execute the following:

% cd /your_directory
% unzip oc4j_extended.zip
% cd j2ee/home 
% java -jar oc4j.jar -install 

Enter an administrator password

After the install is complete, the j2ee/home directory contains all the files necessary for running OC4J with a default configuration. The installation prompts you for an administration username and password, which is used for the administration console command-line tool.

Note: Instead of executing oc4j.jar from the j2ee/home directory, you can set a $J2EE_HOME variable (for UNIX) or the %J2EE_HOME% variable (for Windows NT) to j2ee/home, so that in the command line and execute oc4j.jar from any directory. For example, in the UNIX environment use the following: % java -jar $J2EE_HOME/oc4j.jar

Testing the Default Configuration

OC4J is installed with a default configuration that includes a default Web site and a default application. These are provided so you can start and test OC4J immediately.

Start OC4J by executing the following:

1. Change directory to the OC4J installation directory (j2ee/home), and issue one of the following commands:
   • java -jar oc4j.jar

     This starts OC4J using the default configuration files, which are located in j2ee/home/config.

   • java -jar oc4j.jar -config /mypath/server.xml

     This starts OC4J using the server.xml file located in /mypath.

   The server should output an initialization string with the version number.

2. Test OC4J by accessing "http://oc4j_host:8888/" from a Web browser. If you changed the default port number, access the Web server using "http://oc4j_host:oc4j_port/".

For example, test the Web server by connecting a Web browser to http://oc4j_host:8888/servlet/HelloWorldServlet, which should return a "Hello World" page.

For more information on starting and stopping OC4J, see "Starting and Stopping OC4J". For more information on configuration, see "Deploying Applications".

Starting and Stopping OC4J

• Starting OC4J

• Administering OC4J

• Shutting Down OC4J

Starting OC4J

OC4J is installed with a default configuration that includes a default Web site and a default application. Therefore, you can start OC4J immediately. To start OC4J in a standalone environment, issue the following command from the j2ee/home/ directory:

java -jar oc4j.jar options

This command starts OC4J using the default configuration files, which you can find in the j2ee/home/config directory.

Options for this command are not necessary to start OC4J. However, if you want to exercise more control, use the options listed in "Options for the OC4J Server JAR" or issue the following command from the j2ee/home directory:

java -jar oc4j.jar -help

After OC4J launches, a message is displayed on the screen to note this fact.

Note: Instead of executing oc4j.jar from the j2ee/home directory, you can set a $J2EE_HOME variable (for UNIX) or the %J2EE_HOME% variable (for Windows NT) to j2ee/home, so that in the command line and execute oc4j.jar from any directory. For example, in the UNIX environment use the following: % java -jar $J2EE_HOME/oc4j.jar

Administering OC4J

After starting the OC4J server, you can administer the server using the admin.jar command-line tool, which is located in <install_directory>/j2ee/home. To use the admin.jar command, see the following syntax:

java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port admin_id

    admin_password options

where the variables are as follows:

• oc4j_host:oc4j_ormi_port--The host name and port of the OC4J server from which you want to deploy the application. The admin.jar tool uses the OC4J Remote Method Invocation (ORMI) protocol to communicate with the OC4J server. Therefore, the host name and port identified by these variables are defined in the rmi.xml file for the OC4J server to which you are directing the request.

  The default port number for the ORMI protocol is 23791. Configure both the host name and port number--if not using the default--in the rmi.xml file in the <rmi-server> element, as follows:

  <rmi-server port="oc4j_ormi_port" host="oc4j_host"> 
  
  

• admin_id admin_password--The administration identity and password. Specify this identity and password for the OC4J server in its principals.xml file.

"Options for the OC4J Administration Management JAR" discusses the options for this tool.

Restarting OC4J

You can designate whether the task manager in OC4J automatically detects changes made to deployed applications. Once a change is detected, then OC4J reloads these applications automatically. In this case, you do not need to restart the server when redeploying an application.

The check-for-updates attribute in the <application-server> element in the server.xml file defaults to true, which enables automatic deployment. If true, task manager checks for XML configuration file modifications. Thus, if you set this to false, you can disable automatic refreshing of the configuration to any new XML modifications. Also, setting this attribute to false stops the automatic deployment of any applications until you execute admin.jar -updateConfig. If set to false, you cause the XML configuration to refresh from the XML files and any necessary automatic deployment to occur by using the admin.jar -updateConfig option.

If you enable automatic deployment, then you do not have to restart the OC4J process each time you make a modification to the application. However, enabling automatic deployment also effects your performance. Thus, it is recommended that you enable automatic deployment only in a development environment, not in a production environment.

Even if you have automatic deployment enabled, it does not detect modifications in the global server XML configuration files. Thus, if you modify any of the container-level configuration files, such as data-sources.xml, rmi.xml, or principals.xml, you must restart the OC4J process for these modifications to be recognized.

To restart OC4J using the default parameters, change to the installation root directory, and execute the following:

% java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port admin

    admin_password -restart

This command connects to the OC4J RMI listener port and requests it to restart. It may not work if the JVM is not responding to signals or accepting RMI messages. In this case, stop the JVM in the UNIX environment with the following operating system command: kill process. In the Windows NT environment, access the Windows NT Task Manager to terminate the JVM.

Shutting Down OC4J

Shut down OC4J by executing the following:

% java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port admin

    admin-password -shutdown

This command provides a graceful shutdown of the container. If it does not shut down the container, force a rapid shutdown by passing the force argument, as follows:

% java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port admin

    admin-password -shutdown force

If this method does not work, then kill OC4J processes with your operating system commands or tool, depending on your system.

HTTP and RMI Communication

For HTTP applications, clients can send their requests directly to OC4J. The default port number is 8888. You can change this port number in the appropriate *-web-site.xml file, such as the http-web-site.xml file.

For RMI-based applications--such as EJB and JMS--clients should send their requests directly to OC4J. The default RMI port is 23791. Modify this port number in the rmi.xml file. See "Configuring a Listener" for directions.

Quick Start for JSPs and Servlets

To deploy Web applications on OC4J, do one of the following:

• Place your servlet classes and JSP pages in the j2ee/home/default-web-app directory.

• Deploy J2EE applications using the admin.jar tool. The J2EE application must be archived in the EAR format.

Placing servlets and JSP pages in the default-web-app directory is the easiest method to deploy applications or to migrate J2EE applications from previous versions of OC4J.

Do the following for quick deployment of servlets or JSPs:

1. Place your servlet classes in the j2ee/home/default-web-app/WEB-INF/classes subdirectory--in a directory corresponding to their Java package. The servlet is accessible from URLs of the form: http://oc4j_host:8888/servlet/class-name

   For example, place the servlet class my.HelloServlet, as follows:

   j2ee/home/default-web-app/Web-INF/classes/my/HelloServlet.class
   
   

   Then it is accessible from the following URL:

   http://oc4j_host:8888/servlet/my.HelloServlet
   
   

2. Place JSP pages anywhere in the j2ee/home/default-web-app directory. They are accessible with URLs of the form: http://oc4j_host:8888/path-to-JSP

   For example, a JSP page in j2ee/home/default-web-app/examples/Hello.jsp is accessible as http://oc4j_host:8888/examples/Hello.jsp.

Creating the Development Directory

When developing your application, Oracle recommends that you use consistent and meaningful naming conventions. As an example, you could develop your application as modules within a directory named after your application. All the subdirectories under this directory could be consistent with the structure for creating JAR, WAR, and EAR archives. Thus, when you have to archive the source, it is already in the required archive format. Figure 1-1 demonstrates this structure.

Figure 1-1 Development Application Directory Structure

Text description of the illustration config2.gif

Consider the following points regarding Figure 1-1:

• You cannot change the following directory names and XML filenames: META-INF, WEB-INF, application.xml, ejb-jar.xml, web.xml, and application-client.xml.

• Separate directories clearly distinguish modules of the enterprise Java application from each other. The application.xml file, which acts as the standard J2EE application descriptor file, defines these modules.

• The directories containing the separate modules (<ejb_module>, <web_module>, and <client_module>) can have arbitrary names. However, these names must match the values in the standard J2EE application descriptor file--the local application.xml file.

• The top of the module represents the start of a search path for classes. As a result, classes belonging to packages are expected to be located in a nested directory structure beneath this point. For example, a reference to an EJB package class 'myapp.ejb.Demo' is expected to be located in appname/ejb_module/myapp/ejb/Demo.class.

Configuring the FAQ Application Demo

This section describes how to configure the FAQ J2EE demo application, which provides support for managing Frequently Asked Questions (FAQs) and storing/retrieving these FAQs from an Oracle database. FAQs are broadly categorized into Specialization Areas. Each Specialization Area is further sub-categorized into Topics. Each FAQ can be associated with multiple Specialization Areas, where each area has one or more Topics associated with them.

You can generate a list of FAQs (in HTML format) for a given Specialization Area for internal or external publication.

• Internal: FAQs that are published for internal users only. These include all external and internal FAQs.

• External: FAQs that are published on external forums.

Within the demo, Areas, Topics, and FAQs are entered or updated in the database through Input/Update screens or through a Web service interface. Each Area, Topic and FAQ is uniquely identified by a primary key, which is automatically generated by the system.

This application is a J2EE 1.3 compliant application, developed utilizing the following technologies:

• HTML (including MS-HTML for creating a Rich-Text Editor)

• JavaScript

• Cascade Style Sheets

• Java Server Pages 1.2

• Servlet 2.3

• JSP Standard Tag Library (JSTL) 1.0

• Oracle JSP 1.2 Utility Tag Libraries

• Enterprise JavaBeans 2.0 (using Local Interfaces, Abstract Classes, CMR and EJB-QL)
  • Entity Bean (CMP)

  • Session (Facade) Bean (stateless)

• Oracle Application Server Java Authentication and Authorization Service

• Oracle Application Server Web Services

The following sections detail how to configure and deploy the FAQ demo application. In addition, the last section demonstrates how these steps relate to any application that you may wish to configure and deploy to OC4J:

• Environment Setup for FAQ Demo

• OC4J System Configuration for FAQ Demo

• Deploy the FAQ Demo

• Deployment Details Explained

Environment Setup for FAQ Demo

Before you configure OC4J and deploy the FAQ demo, modify the back-end database to contain tables that are necessary for executing the FAQ demo.

Oracle Database

Add the FAQ user and tables, as follows:

1. Add the faq user with password of faq in your database.

2. Create the database tables for the FAQ demo by executing the SQL table creation script CreateTables.sql script, which is located at <FAQApp_home>/faq/sql/CreateTables.sql or can be downloaded with the rest of the FAQ application from OTN in the FAQApp.zip file.

   In an Oracle database environment, you can execute the SQL script through SQL*Plus, connecting to the database and schema where you want the tables to be installed and executing @CreateTables. Please refer to the Oracle database documentation for further instructions on how to use SQL*Plus, running install scripts, creating database users/schemas, and so on.

OC4J System Configuration for FAQ Demo

In order for the FAQ demo to execute properly, the following system modification must be implemented:

• Modify the default data source, OracleDS, to point to the back-end database.

• Add the FAQ user to the jazn.com realm and assign it to the users role.

The directions for each of these steps are covered in the following sections:

• Data Source Configuration

• Security Configuration

Data Source Configuration

In order to execute the FAQ application, you must have an Oracle database with the corresponding FAQ application database schema installed on it. The FAQ Application uses the default global data source named OracleDS that ships with the application server, which must be configured so that it connects to the database in which you created the FAQ tables.

Note: An I/O exception is thrown if you do not update the global OracleDS data source appropriately.

If your back-end database uses the thin JDBC driver, is located at myhost:1521:ORCL, and uses the username/password of faq/faq, then the j2ee/home/config/data-sources.xml file is modified to point to the database at the URL of jdbc:oracle:thin:@myhost:1521:ORCL, as follows:

<data-source
  class="com.evermind.sql.DriverManagerDataSource"
  name="OracleDS"
  location="jdbc/OracleCoreDS"
  xa-location="jdbc/xa/OracleXADS"
  ejb-location="jdbc/OracleDS"
  connection-driver="oracle.jdbc.driver.OracleDriver"
  username="faq"
  password="faq"
  url="jdbc:oracle:thin:@myhost:1521:ORCL"
  inactivity-timeout="30"
/>

See Chapter 3, "Data Sources Primer" for more information on data sources.

Security Configuration

The FAQ demo uses Oracle Application Server Java Authentication and Authorization Service for authentication and user access control capabilities. An application user is added to the default jazn.com realm through the jazn.jar command line tool, as follows:

> java -jar jazn.jar -adduser jazn.com <username> <passwd>

> java -jar jazn.jar -grantrole users jazn.com <username>

The previous adds your user (given the username and password) to the jazn.com realm and then grants the users role to the new user. See the Oracle Application Server Containers for J2EE Security Guide for complete information on using OracleAS JAAS Provider as your security provider.

Deploy the FAQ Demo

Download the FAQ demo application from OTN in the FAQApp.zip file.

1. Unzip this file to a working directory, which is referred to as <FAQApp_Home>.

2. Deploy the FAQ application using by either copying the EAR file to the j2ee/home/applications directory or by the admin.jar tool. The following sections explain each method.

3. Start the OC4J server by executing java -jar oc4j.jar

4. Execute the FAQ application in your browser, where the default port is 8888.

   http://oc4j_host:8888/FAQApp 
   

Deploy Using Automatic Deployment in a Development Environment

As discussed in "Restarting OC4J", OC4J supports automatic deployment and redeployment of applications, which allows you to make changes to the application EAR file, which are picked up by the server without stopping and restarting OC4J. You enable this through the check-for-updates attribute in the server.xml file.

When automatic deployment is enabled, simply modify the XML configuration files, rearchive the application with its XML files into an EAR file, and copy the EAR file to the applications directory. The OC4J server notices the modified date and will redeploy the application, as necessary.

Warning: Automatic deployment should only be used in a development environment. The task manager that checks for updates can be time consuming. Turn off automatic deployment in a production environment by setting the check-for-updates attribute to false.

For the first deployment of the FAQ application (locally), do the following:

1. Copy the <FAQApp_Home>/faq/dist/FAQApp.ear file to the j2ee/home/applications directory.

2. Modify the j2ee/home/config/server.xml and http-web-site.xml files to register the FAQ application in the j2ee/home/applications directory, as follows:
   1. In the j2ee/home/config/server.xml file, add the FAQApp entry, as follows:

      <application name="FAQApp" path="../applications/FAQApp.ear" />
      

      This step deploys the FAQ application on OC4J. The path is relative to j2ee/home/config. Since the FAQApp.ear file is in j2ee/home/applications, this makes the path ../applications/FAQApp.ear.

      For full details on the server.xml configuration file, see "Elements in the server.xml File".

   2. In the j2ee/home/config/http-web-site.xml file, bind the FAQ Web application by adding the FAQApp entry, as follows:

      <web-app application="FAQApp" name="FAQAppWeb" root="/FAQApp" 
      />
      
      

      This step makes FAQ accessible from the /FAQApp URL on the OC4J server.

      For full details on the http-web-site.xml configuration file, see the Oracle Application Server Containers for J2EE Servlet Developer's Guide.

For more information, see "Manually Adding Applications in a Development Environment", "OC4J Automatic Deployment for Applications", and "What Happens When You Deploy?".

Deploy Using the Admin.JAR Tool in All Environments

In the production environment, you should set the check-for-updates attribute to false (see "Restarting OC4J") and then use the admin.jar tool for deploying all applications. The admin.jar tool deploys the application and modifies all of the appropriate XML files. This provides for remote deployment.

Use the admin.jar command-line tool for registration and deployment, as follows:

java -jar admin.jar

      ormi://oc4j_host:oc4j_ormi_port 

      admin welcome -deploy 

      -file d:\j2ee\home\FAQAPP_Home\faq\dist\FAQApp.ear

      -deploymentName FAQApp 

The default port number for oc4j_ormi_port is 23791.

This step creates the entry in the server.xml file for the FAQ application. For a complete description of the admin.jar command-line tool, see "Options for the OC4J Administration Management JAR".

You can bind any Web application through the admin.jar tool, as follows:

java -jar admin.jar

   ormi://oc4j_host:23791

   admin welcome -bindWebApp 

   FAQApp FAQAppWeb http_web_site /FAQApp

This creates the <web-app> entry in the http-web-site.xml configuration file. For a complete description of the admin.jar command-line tool, see "Options for the OC4J Administration Management JAR".

For more information on configuring and managing Web applications, see the http-web-site.xml file, see the Oracle Application Server Containers for J2EE Servlet Developer's Guide.

Deployment Details Explained

Although the development of J2EE applications is standardized and portable, the XML configuration files are not. You may have to configure multiple XML files before deploying any application to OC4J. The necessary server configuration depends on the services that your application uses. For example, if your application uses a database, you must configure its DataSource object in the data-sources.xml file.

For basic applications, such as the FAQ demo, you configure the following OC4J XML files:

• META-INF/application.xml--The standard J2EE application descriptor for the application is contained within the application.xml file. This file must be properly configured and included within the J2EE EAR file that is to be deployed.

• server.xml and http-web-site.xml--The application is registered in the server.xml file; the Web application and the context it uses are registered in the http-web-site.xml file (or any other *-web-site.xml file that you choose).

• data-sources.xml--You must configure the DataSource object in the data-sources.xml file for each database used within the application.

To create and deploy simple J2EE applications, perform the following basic steps:

Basic Step	FAQ Application Step Description
Create or obtain the application.	Download the FAQApp.zip from OTN
Make any necessary server environment changes.	Set the JAVA_HOME variable
Modify any application XML configuration files.	The deployment descriptors, such as web.xml and ejb-jar.xml, are provided in the FAQApp.EAR file. For your application, you may have to create these XML files.
Update the application standard J2EE application descriptor file.	The application.xml file is included in the FAQApp.EAR file. For your application, you may have to create this XML file.
Build an EAR file including the application--if one does not already exist.	If you want to modify the FAQ demo, modify within the src directory, and use ANT to build an EAR file.
Register the application in the appropriate server XML files.	Modify the server.xml and http-web-site.xml files or use the admin.jar tool, which will modify these files for you.
Configure the database used.	Modify the data-sources.xml file.

The following steps describe what modifications to make to deploy the FAQ demo application into OC4J.

1. We asked you to download the FAQ demo application from the Oracle OTN site.

2. Make any necessary server environment changes. You must set the JAVA_HOME variable to the base directory of the Java 2 SDK.

3. All of the application XML files, such as web.xml, are provided for you in the ZIP file, correctly configured.

4. Update the standard J2EE application descriptor file. The application.xml in the FAQ demo application is provided for you in the ZIP file. OC4J uses the application.xml file as the standard J2EE application descriptor file.

5. Build an EAR file including the application. You can modify the FAQ demo application and rebuild it using the ANT command. To rebuild and deploy the FAQ demo, execute the following:

   ant deploy
   
   

   The ANT build.xml is included in the FAQ ZIP download. To learn more about the ANT file, go to the following Jakarta site:

   http://jakarta.apache.org/ant/
   
   

   If you do not want to rebuild, you can copy the FAQApp.ear from the ZIP file into j2ee/home/applications. This step places the FAQ application in the OC4J server.

6. Configure the OC4J DataSource for an Oracle database. Modify the default data source, OracleDS, to point to your back-end database, with the correct URL, username, and password.

7. Register the J2EE application in the server.xml file and its Web application in the http-web-site.xml or use the admin.jar tool to deploy, which will modify these files for you.

8. Start OC4J by executing the following command from the j2ee/home/ directory:

   java -jar oc4j.jar
   
   

For a complete description of all the OC4J starting options, see "Starting OC4J".

Open your Web browser and then specify the following URL:

http://oc4j_host:8888/FAQApp

See "Overview of OC4J and J2EE XML Files" for more information on OC4J XML configuration files.

Deploying Applications

This section describes how to deploy a J2EE application to the OC4J server and how to bind that application to the server so that you can access the application from OC4J.

• Archive Application into an EAR File

• Deployment In a Production Environment Using ADMIN.JAR

• Deploy your Application Manually in a Development Environment

• Verifying Deployment

Archive Application into an EAR File

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 1-2 Archive Directory Format

Text description of the illustration configa.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 standard J2EE application descriptor file.

Deployment In a Production Environment Using ADMIN.JAR

OC4J contains a command-line deployment tool for deploying J2EE applications--the admin.jar command. The options for this command are listed in "Standalone OC4J Command-Line Options and Properties". Ensure that automatic deployment is disabled by setting the check-for-updates attribute to false (see "Restarting OC4J").

To deploy a J2EE application with the EAR file to a remote node, execute admin.jar, as follows:

java -jar admin.jar ormi://host:port 

	username password 

	-deploy 

		-file filename -deploymentName app_name 

		-targetPath path/destination

where

• The host:port is the host and port of the OC4J server.

• The username password is the administration username and password for the OC4J server.

• The -file path/filename indicates the local directory and filename for the EAR file.

• The -deploymentName app_name variable is a user-defined name of the application.

• The -targetPath path/destination indicates what path on the server node in which to deploy the EAR file. Provide a target path to the directory where the EAR file is copied for deployment. The default path is the applications/ directory. Oracle recommends that you provide a target path.

  Note: If you have a Web application within the EAR file, bind the Web application using the admin.jar -bindWebApp option.

This deployment step creates a new entry in server.xml for the application, as follows:

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

where

• The name attribute is the name of the application.

• The path indicates the directory and filename for the EAR file.

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

For a description of the elements in server.xml, see "Elements in the server.xml File".

Binding the Web Application in a Production Environment

To make your J2EE Web application accessible from the OC4J Web server, bind the Web application to the OC4J server using the -bindWebApp option as follows:

java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port 

	username password 

-bindWebApp app_name web_app_name web_site_name context_root

where the following are the values for -bindWebApp:

• app_name is the application name, which is the same name used in -deploymentName on the -deploy option. In addition, note that this is the same name that is saved in the <application name=app_name /> attribute in the server.xml file.

• web_app_name is the name of the WAR file contained within the EAR file--without the .war extension.

• web_site_name is the name of the *-web-site.xml file that denotes the Web site to which this Web application should be bound. This is the file that will receive the Web application definition.

• context_root is the root context for the Web module. The Web context defines how the Web application is accessed.

This step creates an entry in the OC4J *-web-site.xml configuration file that is denoted in the web_site_name variable. For a listing of all the options for admin.jar, see "Options for the OC4J Administration Management JAR".

Deploy your Application Manually in a Development Environment

To deploy your application in a development environment, you can modify the XML files by hand. Ensure that automatic deployment is enabled by setting check-for-updates attribute to true (see "Restarting OC4J").

In server.xml, add a new or modify the existing <application name=... path=... auto-start="true" /> entry for each J2EE application. The path should be the full directory path and EAR filename. For our employee example, add the following to the server.xml file:

<application name="employee" 

	path="/private/applications/Employee.ear" 

	auto-start="true" />

If you included a Web application portion, you must do the following to bind the Web application to the Web server. In *-web-site.xml, add a <web-app ...> entry for each Web application. The application attribute should be the same value as provided in the server.xml file. The name attribute should be the WAR file, without the WAR extension, for the Web application.

For Web application binding for the employee Web application, add the following:

<web-app application="employee" name="Employee-web" 

	root="/employee" /> 

Verifying Deployment

OC4J detects the addition of your application to server.xml. The OC4J server displays a message that your application has been deployed. After the message is displayed, you can invoke requests against your application.

Undeploying Web Applications

You can remove a J2EE Web application from the OC4J Web server using the -undeploy option with the admin.jar command-line tool. The syntax is as follows:

java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port 

	admin adminpassword 

-undeploy applicationName -keepFiles 

This command removes the deployed J2EE application known as applicationName and 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. If you do not want these files to be removed, use the -keepFiles switch.