1 Configuration and Deployment

1.2.1 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.

1.2.2 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.

1.2.3 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://hostname:8888/" from a Web browser. If you changed the default port number, access the Web server using "http://hostname:portnumber/".

For example, test the Web server by connecting a Web browser to http://hostname: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".

1.3.1 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.

<j2ee-logging-config path="./j2ee-logging.xml" />

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.

1.3.2 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.

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

1.3.3 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.

1.3.4 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.

1.3.5 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.

1.5.1 Environment Setup for FAQ Demo

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

1.5.2 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
  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/MYSERVICE"
  inactivity-timeout="30"
/>

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

1.5.3 Deploy the FAQ Demo

Download the FAQ demo application from OTN at 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://your_machine_name:8888/FAQApp 
   

java -jar admin.jar      ormi://oc4j_host:oc4j_ormi_port       admin welcome -deploy        -file d:\j2ee\home\applications\FAQApp.ear       -deploymentName FAQApp        -targetPath applications/

java -jar admin.jar    ormi://oc4j_host:oc4j_ormi_port   admin welcome -bindWebApp    FAQApp FAQAppWeb http_web_site /FAQApp

1.5.4 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:

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.

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.

1.6.1 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:

Archive Directory Format

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.

1.6.2 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.

  
  

  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".

java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port username password 
	-bindWebApp app_name web_app_name web_site_name context_root

<application name="employee"  	path="/private/applications/Employee.ear"  	auto-start="true" />

<web-app application="employee" name="Employee-web" root="/employee" /> 

1.6.3 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.

1.6.4 Impact of Undeploying/Redeploying an Application

Undeploying a J2EE application from an OC4J instance results in the following:

• The application is removed from the OC4J runtime and is no longer accessible.

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

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

During a redeployment, OC4J removes the existing application (EAR/WAR) before redeploying the new EAR. This means, for example, that attempts to access an HTML file that was included in the previous application, but not the new one, will result in "File Not Found" errors.

Also note that a redeployed WAR file overlays the previously expanded WAR, meaning that some older files may persist in the new deployment and will need to be deleted. For example, static HTML files from the previous deployment that are not included in the new WAR may continue to reside in the expanded WAR directory structure, and we would have to be manually deleted.

1.6.5 Impact of "Hot Deploying" an Application

The term hot deployment refers to the process of deploying archive files - EARs, WARs, JARs, etc. - and their associated XML descriptor files on a production application server without re-starting or "bouncing" the server.

When an EAR is redeployed or "hot redeployed" on a running OC4J instance, the status of the classes loaded in the JVM from the previous application may vary. In some cases a classloader may recognize that a class or JAR file in the file system has changed, and reload the class or libary. In other cases whether a new class definition is loaded may depend on whether the JVM tuning allows the garbage collector to flush the existing class definition.

Issues may also exist with respect to serialized objects containing session data. If the class related to a session object changes, it may not be possible to cast the generic session object back to the class, since the class has changed and its variables may occupy a different memory footprint. This may result in lost session data.

Deploying a new Web module to an active OC4J instance also has a negative impact on exising sessions. Specifically, the HTTP sessions for every Web application running within the server instance will be lost by default.

You can avoid this issue on non-clustered OC4J instances by defining a "persistence directory" in each Web application's orion-web.xml file. Existing HTTP sessions will be stored in this temporary location across application deployments.

Specify a relative path to this directory as the value of the persistence-path attribute in the root <orion-web-app> element within each orion-web.xml file. For example:

<orion-web-app ...
  persistence-path="persistDir"
  ...>
</orion-web-app>

Note that this feature is not applicable for OC4J instances within a clustered environment.