Skip Headers
Oracle® Application Server Containers for J2EE User's Guide
10g Release 2 (10.1.2)
Part No. B14011-02
  Go To Documentation Library
Library
Go To Product List
Product
Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
Next
Next
 

2 Configuration and Deployment

This chapter demonstrates how to configure and execute OC4J as simply and quickly as possible. You installed OC4J with the Oracle Application Server installation.

Within OC4J, you can execute servlets, JSP pages and EJBs. 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:

2.1 OC4J Home Page Overview

Most of the configuration and management of your OC4J instance occurs off its OC4J Home Page. When you create an OC4J instance off of the Oracle Application Server Instance Home Page, it creates an OC4J Home Page for configuration and management of your OC4J instance. Each OC4J instance has its own OC4J Home Page.

Off the Oracle9iAS Console, you can drill down to any of the running OC4J instances by selecting the name of the instance (home, for example) in the System Components table. The Oracle9iAS Console displays the OC4J Home Page for that instance.

Figure 2-1 shows portions of the OC4J Home Page for the home instance.

Figure 2-1 Oracle Application Server Console OC4J Home Page

Description of Figure 2-1  follows
Description of "Figure 2-1 Oracle Application Server Console OC4J Home Page"

The OC4J Home Page shows metrics on your OC4J instance and its applications. In addition, you can start, stop, and restart all OC4J processes configured to this instance.

From the OC4J Home Page, you can navigate to the following pages:

2.1.1 Applications Page

Figure 2-2 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 configuration for each application. See "Deploying Applications" for more information.

Figure 2-2 Deployed Applications

Description of Figure 2-2  follows
Description of "Figure 2-2 Deployed Applications"

As an example, you can see how the FAQ application demo is configured and deployed to OC4J in "Configuring the FAQ Application Demo".

2.1.2 Administration Page

Figure 2-3 shows the Administration page. You can modify the following:

  • Instance Properties, which are global configuration values for a specific OC4J instance. This includes configuration of OC4J services, such as RMI, JMS, and Web sites.

  • Application defaults, including default data sources and security that can be used by all deployed applications in this OC4J instance.

Figure 2-3 Administration Section

Description of Figure 2-3  follows
Description of "Figure 2-3 Administration Section"

Details for each of these options are covered in "Configuring OC4J Using Enterprise Manager".

2.2 Starting and Stopping OC4J

OC4J is installed with a default configuration that includes a default Web site and a default application. Therefore, you can start OC4J immediately without any additional configuration.


Important:

Due to a logging implementation dependency issue, OC4J fails to start when using JDK 1.3. The solution to this problem is to remove or comment out the following entry in the ORACLE_HOME/j2ee/home/config/server.xml configuration file:
<j2ee-logging-config path="./j2ee-logging.xml" />

From the Oracle Enterprise Manager Web site, you can start, stop, and restart OC4J with one of the following methods:

OC4J automatically detects changes made to deployed applications and reloads these applications automatically. Therefore, you do not need to restart the server when redeploying an application. However, you may have to restart OC4J if you modify fields in any of the options off of the Administration page.

You can also start, stop, and restart using the DCM control command. See the Distributed Configuration Management Administrator's Guide for directions.

2.2.1 Testing the Default Configuration

Start OC4J with the defaults, as follows:

  1. From the Oracle Application Server Instance Page, start either the whole Oracle Application Server instance or—at least—the Oracle HTTP Server and OC4J components. To start, click the Start All button for the Oracle Application Server instance or select the components and click the Start button.

  2. Test OC4J by specifying the following from a Web browser:

    http://<ohs_host>:7777/j2ee/j2ee-index.html
    
    

    Substitute the name of the host where the OHS is installed for <ohs_host>.

  3. Test a servlet deployed in OC4J during installation by specifying the following in a Web browser:

    http://<ohs_host>:7777/j2ee/servlet/HelloWorldServlet
    
    

    This command returns a "Hello World" page. The HelloWorldServlet is automatically deployed with the OC4J installation.


    Note:

    The examples and URLs in this guide use port 7777, which is the default port for the OHS Web listener. If you change the default port number of the OHS, then specify the new port number after the hostname, as follows:

    http://<ohs_host>:<ohs_port>/j2ee/


2.3 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 2-4 demonstrates this structure.

Figure 2-4 Development Application Directory Structure

Shows the application development directory structure. All the subdirectories under this directory could be consistent with the structure for creating JAR, WAR, and EAR archives.
Description of "Figure 2-4 Development Application Directory Structure"

Consider the following points regarding Figure 2-4:

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

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.

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:

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:

2.4.1 Environment Setup for FAQ Demo

In order to run the FAQ demo, you must modify the back-end database to contain tables that the demo uses.

2.4.1.1 Oracle Database

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

2.4.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:

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

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

  2. Select the Administration tab at the top of the page.

  3. Select Data Sources under the Application Defaults section. The default application is the automatic parent of each application and it holds global configuration for all deployed applications, such as the data sources used. You are going to modify the default data source that the FAQ application uses.

  4. For the OracleDS data source, click the Edit button. This brings up the configuration information for this data source. Modify the JDBC URL, driver, username, and password to point to your back-end database.

    When finished, click the Apply button.

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 service at the URL jdbc:oracle:thin:@myhost:1521/MYSERVICE, 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/MYSERVICE"
  inactivity-timeout="30" />

2.4.2.2 Security Configuration

The FAQ demo uses Oracle's JAAS Provider, JAZN, for authentication and user access control capabilities.

  1. Select the Administration tab at the top of the OC4J Home Page.

  2. Select Security under the Application Defaults section. The default configures global configuration for all deployed applications. You are going to add the user that the FAQ application uses to the jazn.com realm.

  3. On the Security page, scroll down to the Users section

  4. Click Add User. A configuration screen appears that allows you to add information about the new user. Supply the following information:

    • Name and password of the user

    • Check the box next to the jazn.com/users realm

    When finished, click the Apply button.

Alternatively, 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 JAZN as your security provider.

2.4.3 Deploy the FAQ Demo

Download the FAQ demo application from OTN at http://www.oracle.com/technology/tech/java/oc4j/demos/index.html in the FAQApp.zip file.

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

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

  3. Select the Applications tab at the top of the screen.

  4. Click on the Deploy EAR File button. This starts the application deployment wizard.

  5. Provide the EAR file and the name of your application in the Select Application page. Click the Browse button to find the FAQApp.ear file that you unzipped on your system. Type "FAQApp" in the application name field. Click the Continue button.

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

  7. At this point, the FAQApp demo does not need any additional configuration through the wizard. You can jump to the Summary page by clicking Finish.

  8. Read the summary of the FAQApp application deployment. Click the Deploy button to complete the application deployment.

  9. On the OC4J Home Page, select "FAQApp" in the Name column of the Applications section. This shows the configuration and all deployed modules of the FAQApp demo application. If the OC4J server is started, the application is automatically started.

  10. Execute the FAQApp application in your browser by accessing the OHS, where the default port is 7777.

    http://<ohs_host>:7777/FAQApp 
    
    

    The FAQApp screen appears.

2.4.4 Deployment Details Explained

Although the development of J2EE applications is standardized and portable, the non-application (server) configuration is not. 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.

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

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

  • DataSource objects—You must configure the DataSource object in the Data Source configuration page for each database used within the application.

  • When you deploy any application, you configure the name of the application, the Web contexts, and any application-level data sources or security, as well as other services.

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

Basic Step FAQ Application Step Description
  1. Create or obtain the application.
Download the FAQApp.zip from OTN
  1. Make any necessary server environment changes.
Set the JAVA_HOME variable
  1. Modify any global configuration modifications.
Modified the default data source, OracleDS, and added a user to the default JAZN security.
  1. Provide the application deployment descriptors.
The deployment descriptors, such as web.xml and ejb-jar.xml, are provided in the FAQApp.EAR file.
  1. Update the application standard J2EE application descriptor file.
The application.xml file is included in the FAQApp.EAR file.
  1. 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.
  1. Register the application in the appropriate server XML files.
The application is registered when you deploy the application through the deployment wizard.

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


Note:

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

  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. Modify the global configuration:

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

    2. Add the OracleAS JAAS Provider user to the jazn.com realm.

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

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

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

  1. Register the J2EE application and its Web application within the deployment wizard. When you deploy, the wizard asks for information that is necessary to register the application, such as the name of the application and the Web context.

  2. Start OC4J. For a complete description of all the OC4J starting options, see "Starting and Stopping OC4J".

  3. Open your Web browser and then specify the following URL:

    http://oc4j_host:8888/FAQApp
    

2.5 Deploying Applications

This section describes how to deploy a J2EE application to the OC4J server. When you deploy an application using the deployment wizard, the application is deployed to the OC4J instance and any Web application is bound to a URL context so that you can access the application from OC4J.

This section includes the following topics:

To deploy your application, drill down to the OC4J Home Page and scroll to the Deployed Applications section. Figure 2-2 shows this section.


Note:

You can also deploy simple applications with the dcmctl command. See the Distributed Configuration Management Administrator's Guide for directions.

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

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.

  • To deploy a J2EE application packaged within an EAR file, click the Deploy Ear File button on the Applications page.

  • To deploy a J2EE Web application packaged within a WAR file, click the Deploy WAR File button on the Applications page.

Both of these buttons start an eight-step application deployment wizard, which guides you through deploying an application. In the case of the WAR file, the application.xml file is created for the Web application. Whereas, 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.

2.5.1.1 Select Application

Figure 2-5 shows the first page, which enables you to provide the following:

  • Browse your system for the EAR file to be deployed.

  • 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 Applications page.

  • Designate a parent application. A child application can see the namespace of its parent application. Thus, setting up an application as a parent is used to share services among children. The default parent is the global application. The parent application must already be deployed to be seen in the pull-down menu.

Figure 2-5 Designate EAR File

Description of Figure 2-5  follows
Description of "Figure 2-5 Designate EAR File"

When the application is deployed, the information in this step enables the following:

  1. Copies the EAR file to the /applications directory.

  2. Creates a new entry in server.xml for the application, as follows:

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

    where

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

    • The parent is the name of the optional parent application. The default is the global application. Children see the namespace of its parent application. This setting is used to share services, such as EJBs among multiple applications.

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

    • The auto-start variable 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".

Click the Continue button to go to the next step in the wizard deployment process. The wizard uploads your EAR file and examines the application. Based on your configuration files and deployment descriptors, the wizard dynamically presents only the configuration screens your application needs. These screens are a subset of the steps presented in the following sections:

2.5.1.2 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 this 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.

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

2.5.1.3 IIOP Stub Generation

The EJBs in your application can have IIOP stubs generated by selecting Generate IIOP Stubs. See the "Interoperability and RMI Tunneling" chapter in the Oracle Application Server Containers for J2EE Services Guide for information on IIOP stubs.

Figure 2-7 IIOP Stub Generation

Description of Figure 2-7  follows
Description of "Figure 2-7 IIOP Stub Generation"

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

2.5.1.4 Provide Any Resource Reference Mappings

Map any references resources 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 this 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 will be using.

Figure 2-8 Resource Reference Mappings

Description of Figure 2-8  follows
Description of "Figure 2-8 Resource Reference Mappings"

If you have any MDBs in your EAR file, you may be required to add information about the subscriptions or topics. If you are defining DataSource objects for CMP entity beans, you are given the option to add a JNDI location for those DataSource objects.

Figure 2-9 Resource Reference Mappings for CMP Entity Beans

Description of Figure 2-9  follows
Description of "Figure 2-9 Resource Reference Mappings for CMP Entity Beans"

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

2.5.1.5 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 2-10 User Manager Choices

Description of Figure 2-10  follows
Description of "Figure 2-10 User Manager Choices"

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

  • 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 principals.xml file.

  • 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 the Oracle Application Server Containers for J2EE Security Guide.

2.5.1.6 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 2-11 Security Role Mappings

Description of Figure 2-11  follows
Description of "Figure 2-11 Security Role Mappings"

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

For more information on security roles, see the Oracle Application Server Security Guide and the Oracle Application Server Containers for J2EE Enterprise JavaBeans Developer's Guide.

2.5.1.7 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 shown in the following screen:

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

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

2.5.1.8 Deployment Review

At this point, you will receive a review of your application deployment modules and configuration, as follows:

In order to deploy this application, click on the Deploy button. A message will be displayed that tells you that your application deployed.

2.5.1.9 Post-Deployment Application Modifications

You can modify any fields and add additional configuration by returning to the OC4J Home page, select 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.

2.5.2 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 to clients.

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

  • In an Oracle Application Server environment, Oracle HTTP Server will be restarted to remove the mount point defined for the application. This will result in the loss of existing HTTP sessions.

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.

2.5.3 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 library. 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 existing 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. For guidelines on addressing this issue in a clustered environment, see the Oracle Application Server High Availability Guide.

2.6 What Happens When You Deploy?

When you become more proficient with OC4J and deploying applications, you should acquaint yourself with what OC4J does for you. The following sections help you understand these tasks:

2.6.1 OC4J Tasks During Deployment

When you deploy your application, the following occurs:

OC4J opens the EAR file and reads the descriptors.

  1. OC4J opens, parses the application.xml that exists in the EAR file. The application.xml file lists all of the modules contained within the EAR file. OC4J notes these modules and initializes the EAR environment.

  2. OC4J reads the module deployment descriptors for each module type: Web module, EJB module, connector module, or client module. The J2EE descriptors are read into memory. If OC4J-specific descriptors are included, these are also read into memory. The JAR and WAR file environments are initialized.

  3. OC4J notes any unconfigured items that have defaults and writes these defaults in the appropriate OC4J-specific deployment descriptor. Thus, if you did not provide an OC4J-specific deployment descriptor, you will notice that OC4J provides one written with certain defaults. If you did provide an OC4J-specific deployment descriptor, you may notice that OC4J added elements.

  4. OC4J reacts to the configuration details contained in both the J2EE deployment descriptors and any OC4J-specific deployment descriptors. OC4J notes any J2EE component configurations that require action on OC4J's part, such as wrapping beans with their interfaces.

  5. After defaults have been added and necessary actions have been taken, OC4J writes out the new module deployment descriptors to the application-deployments/ directory. These are the descriptors that OC4J uses when starting and restarting your application. But do not modify these descriptors. Always change your deployment descriptors in the "master" location.

  6. OC4J copies the EAR file to the "master" directory. This defaults to the applications/ directory. You can change the "master" directory in the Server Properties page off of the OC4J Home Page. In the General section, modify the Application Directory field to the new location of the "master" directory. The location of the directory is relative to /j2ee/home/config.


    Note:

    Each time you deploy this EAR file without removing the EAR file from the applications/ directory, the new deployment renames the EAR file prepended with an underscore. It does not copy over the EAR file. Instead, you can copy over the EAR file. OC4J notices the change in the timestamp and redeploys the EAR.

  7. Finally, OC4J updates the server.xml file with the notation that this application has been deployed.

2.6.2 Verifying the Configuration of Deployed J2EE Applications

After deployment, you can see your application configuration in the server.xml and default-web-site.xml files, as follows:

  • In server.xml, each existing application contains a line with an <application name=... path=... auto-start="true" /> entry. The auto-start attribute designates that you want this application automatically started when OC4J starts. The path is either the location of the EAR file to be deployed or the exploded directory where the application has been built. See "Basic Deployment" or "Building and Deploying Within a Directory" for more information.

  • In default-web-site.xml, a <web-app...> entry exists for each Web application that is bound to the Web site upon OC4J startup. Because the name attribute is the WAR filename (without the.WAR extension), there is one line for each WAR file included in your J2EE application.

    For each Web application binding included in a WAR file, the following line has been added:

    <web-app application="myapp" name="myapp-web" root="/myapp" /> 
    
    
    • The application attribute is the name provided in the server.xml as the application name.

    • The name attribute is the name of the WAR file, without the.WAR extension.

    • The root attribute defines the root context for the application off of the Web site. For example, if you defined your Web site as "http://<ohs_host>:7777/j2ee", then to initiate the application, point your browser at "http://<ohs_host>:7777/j2ee/myapp".


      Note:

      Wait for automatic startup to complete before trying to access the client. The client fails on lookup if it tries to access before the completion of these processes.

2.7 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 /var/tmp, on your system. The deployment wizard uses 20 MB in swap space of the temp directory for storing information during the deployment process. At completion, the deployment wizard cleans up the temp directory of its additional 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.

To change the temp directory, set the command-line option for the OC4J process to java.io.tmpdir=<new_tmp_dir>. You can set this command-line option in the Server Properties page. Drill down to the OC4J Home Page. Scroll down to the Administration Section. Select Server Properties. On this page, Scroll down to the Command Line Options section and add the java.io.tmpdir variable definition to the OC4J Options line. All new OC4J processes will start with this property.

2.8 Undeploying Web Applications

You can remove a J2EE Web application from the OC4J Web server by selecting the application in the Applications section of the OC4J Home Page (see Figure 2-2) and clicking the Undeploy button. This command removes the deployed J2EE application and results in the following: