2 Configuration and Deployment

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 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 Administration Section"

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

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

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:

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

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

• Provide The URL Mappings For All Web Modules

• IIOP Stub Generation

• Provide Any Resource Reference Mappings

• Specify Any User Manager

• Provide Any Security Role Mappings

• Publish Web Services

• Deployment Review

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.

Figure 2-6 URL Mapping

Description of "Figure 2-6 URL Mapping"

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

Figure 2-12 Web Services

Description of "Figure 2-12 Web Services"

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:

Figure 2-13 Review

Description of "Figure 2-13 Review"

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