5 Deployment and Configuration Overview

Summary of Server, Global, and Web Site Configuration Files

The server.xml file is located in the j2ee/home/config directory and specifies locations of the other server configuration files and the Web site configuration files, which are also in j2ee/home/config by default.

Summary of Application-Level Configuration Files

J2EE configuration files are included within the standard application structure. If you include OC4J application-level configuration files in your EAR or WAR file, they also go within the application structure. See "J2EE Application Structure". Upon deployment of a J2EE application, the OC4J files are either copied (if you included them) or generated (if you did not include them) in the deployment directory, typically under j2ee/home/application-deployments.

Standard J2EE Application Descriptors

The J2EE standard defines the concept and DTD of an application descriptor, called application.xml, that you must include in the /META-INF directory of the EAR file of a J2EE application. The application descriptor acts as a manifest of the modules contained in the application, possibly with additional configuration information as well, and in some development environments can be created automatically for you. See the J2EE specification for more information.

Here is an example for an application with an EJB module, a Web module, and a client module:

<?xml version="1.0" ?> 
<!DOCTYPE application (View Source for full doctype...)> 
<application>
  <display-name>stateful, application:</display-name> 
  <description>
    A sample J2EE application that uses a remote stateful session
    bean to call a local entity bean.
  </description> 
  <module>
    <ejb>stateful-ejb.jar</ejb> 
  </module>
  <module>
    <web>
      <web-uri>stateful-web.war</web-uri> 
      <context-root>/stateful</context-root> 
    </web>
  </module>
  <module>
    <java>stateful-client.jar</java>
  </module>
</application>

OC4J Global Application Descriptor

The OC4J-specific global application descriptor is defined by an OC4J-specific DTD, orion-application.dtd. This is the descriptor for the OC4J global application, as specified by the <global-application> element in the server.xml file. This element specifies the global application name, default by default, and the global application descriptor name, application.xml by default and usually located in the same directory as server.xml.

The OC4J global application is usually referred to as the "default application" and, by default, is the parent application of all other applications in the OC4J instance.

Following is an abbreviated sample application.xml file for the OC4J default application. Note that it specifies the name of a Web application, defaultWebApp, which by convention is bound to one or more Web sites as the default Web application.

Do not confuse the OC4J default J2EE application with the default Web application that it contains. See "OC4J Default Application and Default Web Application" for related information.

<?xml version="1.0" standalone='yes'?>
<!DOCTYPE orion-application PUBLIC "-//Evermind//DTD J2EE Application runtime
 1.2//EN" "http://xmlns.oracle.com/ias/dtds/orion-application.dtd">

<!-- The global application config that is the parent of all the other
  applications in this server. -->

<orion-application autocreate-tables="true"
                   default-data-source="jdbc/OracleDS">
  <web-module id="defaultWebApp" path="../../home/default-web-app" />
  <connectors path="./oc4j-connectors.xml"/>

  <!-- Path to the libraries that are installed on this server.
  These will accesible for the servlets, EJBs etc -->
  <library path="../../home/lib" />
  <!-- Path to the taglib directory that is shared
        among different applications. -->
  <library path="../../home/jsp/lib/taglib" />

  <log>
    <file path="../log/global-application.log" />
  </log>

  <data-sources path="data-sources.xml" />
  <namespace-access>
    <read-access>
      <namespace-resource root="">
        <security-role-mapping>
          <group name="administrators" />
        </security-role-mapping>
      </namespace-resource>
    </read-access>
    <write-access>
      <namespace-resource root="">
        <security-role-mapping>
          <group name="administrators" />
        </security-role-mapping>
      </namespace-resource>
    </write-access>
  </namespace-access>
</orion-application>

OC4J-Specific Application Descriptors

In addition to the standard application descriptor, application.xml, there is an OC4J-specific application-level application descriptor, orion-application.xml. This descriptor is defined by the same DTD as the OC4J global application descriptor. You can provide an orion-application.xml file as well as an application.xml file, also in the /META-INF directory of your EAR file. The orion-application.xml file can add OC4J-specific configuration.

Including an orion-application.xml file in your EAR file is optional. If you include it, OC4J copies it into the deployment directory during deployment (under j2ee/home/application-deployments by default). Otherwise, OC4J generates one for you in the deployment directory, using default settings from the OC4J global application descriptor (assuming the OC4J default application is the parent application, as is the case by default) and the application.xml file in the EAR file. See "J2EE Application Structure" for information about where orion-application.xml fits in the application structure.

In most circumstances, you should use orion-application.xml only to define OC4J-specific configuration such as security role mappings. Also note that if OC4J generates the file, it creates <web-module> elements to reflect the modules specified in the J2EE application.xml file.

The following example shows some OC4J-specific configuration and defines the same EJB, Web, and client modules as defined in the example of the standard application.xml file in "Standard J2EE Application Descriptors":

<?xml version="1.0"?>
<!DOCTYPE orion-application PUBLIC "-//Evermind//DTD J2EE Application runtime
 1.2//EN" "http://xmlns.oracle.com/ias/dtds/orion-application.dtd">

<orion-application default-data-source="jdbc/OracleDS">
  <ejb-module remote="false" path="stateful-ejb.jar" />
  <web-module id="stateful-web" path="stateful-web.war" />
  <client-module path="stateful-client.jar" auto-start="false" />
  <persistence path="persistence" />
  <log>
    <file path="application.log" />
  </log>
  <namespace-access>
    <read-access>
      <namespace-resource root="">
        <security-role-mapping name="&lt;jndi-user-role&gt;">
          <group name="users" />
        </security-role-mapping>
      </namespace-resource>
    </read-access>
    <write-access>
      <namespace-resource root="">
        <security-role-mapping name="&lt;jndi-user-role&gt;">
          <group name="users" />
        </security-role-mapping>
      </namespace-resource>
    </write-access>
  </namespace-access>
</orion-application>

Summary of Relationships Between Application Descriptors

To summarize the relationship between J2EE application descriptors, the OC4J global application descriptor, and OC4J application-level application descriptors:

• For a typical J2EE application, the key application descriptor is the standard J2EE application descriptor, application.xml. This file acts as a manifest for the modules of a J2EE application and must be placed in the /META-INF directory of the J2EE application EAR file.

• If you want to deploy a standalone WAR file (rather than a WAR file within an EAR file), you can use the OC4J default application, or global application, as the containing application. (See "OC4J Default Application and Default Web Application".) In this case, the OC4J global application descriptor, also called application.xml but defined by an OC4J-specific DTD, becomes relevant because no J2EE standard application.xml file is associated with a standalone WAR file.

• You can optionally include an orion-application.xml descriptor for additional OC4J configuration, such as for security role mappings. The orion-application.xml file may also specify additional modules, beyond those specified in the J2EE application.xml file, and can even override modules specified in application.xml (though this is not advisable). The orion-application.xml file would also be in the /META-INF directory of the EAR file. If you do not include this file, it is created automatically during deployment, using defaults from the OC4J global application descriptor (assuming the default application is the parent of your application, which is true by default). The orion-application.xml descriptors are defined according to the same DTD as the OC4J global application descriptor.

Standard J2EE Web Descriptors

The servlet specification defines the concept and DTD of a Web descriptor, called web.xml, that you must include in the /WEB-INF directory of the associated WAR file. The web.xml file specifies and configures the Web components of the WAR file, as well as other components, such as EJBs, that the Web components may call. See the servlet specification for more information.

Here is a sample web.xml file specifying, among other things, a servlet, the servlet mapping, and a local EJB lookup:

<?xml version="1.0"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
 "http://java.sun.com/dtd/web-app_2_3.dtd">

<web-app>
   <display-name>stateful, web-app:</display-name>
   <description>no description</description> 
   <welcome-file-list>
      <welcome-file>index.html</welcome-file>
   </welcome-file-list>

   <ejb-local-ref>
      <ejb-ref-name>CartBean</ejb-ref-name>
      <ejb-ref-type>Session</ejb-ref-type>
      <local-home>cart.CartHome</local-home>
      <local>cart.Cart</local>
   </ejb-local-ref>

   <servlet>
      <servlet-name>cart</servlet-name>
      <servlet-class>cart.CartServlet</servlet-class>
      <init-param>
         <param-name>param1</param-name>
         <param-value>1</param-value>
      </init-param>
   </servlet>
   <servlet-mapping>
      <servlet-name>cart</servlet-name>
      <url-pattern>/cart</url-pattern>
   </servlet-mapping>
   <security-role>
      <role-name>users</role-name>
   </security-role>
</web-app>

OC4J Global Web Application Descriptor

The server.xml file, through its <global-web-app-config> element, specifies the OC4J global Web application descriptor. It is typically global-web-application.xml, in the same directory as server.xml. This descriptor defines default behavior for Web applications in OC4J.

The global Web application descriptor is defined by the DTD orion-web.dtd. This is the same DTD as for the application-level OC4J-specific Web descriptor, orion-web.xml, described in the next section, "OC4J-Specific Web Descriptors".

The orion-web.dtd is a superset of the standard DTD for web.xml. There is a <web-app> subelement of the <orion-web-app> top-level element in orion-web.dtd, which has the same specification as the top-level <web-app> element of web.xml. There are also many other subelements of <orion-web-app> for specifying and configuring OC4J-specific features.

For any default settings you specify within the <web-app> element in global-web-application.xml, you can add to or, optionally, override these settings through <web-app> settings in web.xml. You can then add to or, optionally, override the resulting settings through <web-app> settings in orion-web.xml.

For any default settings you specify outside the <web-app> element in global-web-application.xml, you can add to or, optionally, override these settings through parallel settings in orion-web.xml.

For detailed information about the elements and attributes of the OC4J global Web application descriptor, including the DTD and a hierarchical representation, see "Configuration for global-web-application.xml and orion-web.xml".

See "Sample global-web-application.xml Settings" for an abbreviated sample global-web-application.xml file.

OC4J-Specific Web Descriptors

In addition to the standard Web descriptor, web.xml, and the OC4J global Web application descriptor, global-web-application.xml (which establishes default behavior), there is an OC4J-specific application-level Web descriptor, orion-web.xml.

The orion-web.xml descriptor is defined by the DTD orion-web.dtd. This is the same DTD as for the global Web application descriptor that was described in the previous section, "OC4J Global Web Application Descriptor".

You can provide an orion-web.xml file as well as the web.xml file, also in the /WEB-INF directory of your WAR file. Use orion-web.xml to add to or, optionally, override any default settings in global-web-application.xml, as well as to add to or override any settings in web.xml.

Including an orion-web.xml file in your WAR file (inside the EAR file) is optional. If you include it, OC4J copies it into the deployment directory during deployment (under the j2ee/home/application-deployments directory by default). Otherwise, OC4J generates orion-web.xml for you in the deployment directory, using default settings from global-web-application.xml. Additionally, some web.xml settings will influence the generation of orion-web.xml. For example, <resource-ref> entries in web.xml will result in corresponding <resource-ref-mapping> entries in orion-web.xml. See "J2EE Application Structure" for information about where orion-web.xml fits in the application structure.

For detailed information about the elements and attributes of the OC4J-specific Web descriptor, including the DTD and a hierarchical representation, see "Configuration for global-web-application.xml and orion-web.xml".

A sample orion-web.xml file follows:

<?xml version="1.0" ?> 
<!DOCTYPE orion-web-app (View Source for full doctype...)> 
<orion-web-app jsp-cache-directory="./persistence" temporary-directory="./temp"
              servlet-webdir="/servlet/" default-buffer-size="2048"
              development="false" directory-browsing="deny"
              file-modification-check-interval="1000" jsp-timeout="0 (never)">
  <ejb-ref-mapping name="EmployeeBean" /> 
  <security-role-mapping name="users">
     <group name="users" /> 
  </security-role-mapping>
  <!-- 
  <web-app>
      There are no <web-app> entries in this sample. 
  </web-app>
  -->
</orion-web-app>

Summary of Relationships Between Web Descriptors

You can think of the relationship between global-web-application.xml, web.xml, and orion-web.xml as follows:

1. The global-web-application.xml file establishes defaults for any Web application in OC4J.

2. The web.xml file overlays anything defined in the <web-app> element of global-web-application.xml, adding to and possibly overriding any Web components and other settings defined there.

3. The orion-web.xml file overlays everything, adding to and possibly overriding any settings from global-web-application.xml and web.xml.

Sample EAR and WAR File

This example shows the structure of the archive files for a simple Web application. The EAR file contains a WAR file, which contains a single servlet.

Following are the contents of utility.ear. If there were EJB, client application, or resource adapter modules, the associated JAR files would be at the same level as the WAR file. Optionally, you could also include an orion-application.xml file in the /META-INF directory. Instead, in this example, one would be generated by OC4J during deployment.

META-INF/MANIFEST.MF
META-INF/application.xml
utility_web.war

Here are the contents of utility_web.war. Optionally, you could also include an orion-web.xml file in the /WEB-INF directory. Instead, in this example, one would be generated by OC4J during deployment.

META-INF/MANIFEST.MF
WEB-INF/classes/TestStatusServlet.class
WEB-INF/web.xml
index.html

http://ant.apache.org

Use of the Default Application and Default Web Application

OC4J is installed with a default configuration that includes a default application (also known as the global application). The default application is, by default, the parent of all other J2EE applications in OC4J.

In OC4J, a Web application must be contained within a parent J2EE application. Usually, a WAR file is deployed within an EAR file that defines the parent J2EE application. If you want to deploy an independent WAR file, you can deploy to the OC4J default application instead. By default, the OC4J server.xml file specifies the location and name of the global application descriptor that defines the default application.

In a typical OC4J installation, the default application contains a default Web application. The name and root directory path of the default Web application are specified in the global application descriptor, and the default Web application is bound to a Web site through the http-web-site.xml file for OC4J standalone (default-web-site.xml in Oracle Application Server). In OC4J standalone, the default context path for the default Web application is "/".

Also by default in OC4J standalone, the root directory of the default Web application is j2ee/home/default-web-app. To deploy to the default Web application, place your JSP pages and class files under this directory in the standard Web application directory structure: static pages and JSP pages at the top level, servlet classes under j2ee/home/default-web-app/WEB-INF/classes, and library JAR files in j2ee/home/default-web-app/WEB-INF/lib. Also see "Using a Web Application Directory Structure in the Default Web Application".

Configuration of the Default Application and Default Web Application

This section details the default configurations for the OC4J default application and default Web application.

<application-server ... >
   ...
   <global-application name="default" path="application.xml" />
   ...
</application-server>

<orion-application ... >
  ...
  <web-module id="defaultWebApp" path="../../home/default-web-app" />
  ...
</orion-application>

<web-site ... >
...
   <default-web-app application="default" name="defaultWebApp"
                    load-on-startup="true" shared="false" />
...
</web-site>

Using admin.jar to Deploy the EAR File

After you have packaged your application into an EAR file, you can use the OC4J admin.jar utility to deploy it, using the following syntax:

% java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port 
                      adminuser adminpassword
                      -deploy -file path/filename.ear
                      -deploymentName appname

This command uses RMI to communicate with OC4J. Note the following:

• See "Starting and Stopping OC4J Standalone" for information about the ORMI port.

• See "Setting Up an Administrative User and Password" for information about adminuser and adminpassword.

• For -file, specify the path to the EAR file, including the file name.

• For -deploymentName, specify the desired application name, by convention the same as the EAR file name without the .ear extension.

  
  

  Note: During development, assuming you develop and run on the same system, you will deploy locally. However, admin.jar is also capable of deploying remotely.

  
  

By default, a deployment results in the following:

• The EAR file is copied to the j2ee/home/applications directory. This directory is set as the default through the application-directory attribute of the <application-server> element in the server.xml file.

• The EAR file is unpacked beneath the j2ee/home/applications directory.

• The OC4J-specific descriptors—at a minimum, orion-application.xml and orion-web.xml for a Web application in an EAR file—are copied or generated under the j2ee/home/application-deployments directory. This directory is set as the default through the deployment-directory attribute of the <application-server> element in the server.xml file. These descriptors are copied from the EAR file if they exist there; otherwise, OC4J generates them.

• An <application> element is added to the server.xml file. This element specifies the application name, according to the -deploymentName setting in admin.jar, and specifies the path to where the EAR file was deployed, j2ee/home/applications by default.

See "Sample Deployment" for an example.

Using admin.jar to Bind the Web Application

After you have deployed your application, you can use the OC4J admin.jar utility to bind the associated Web application to a Web site:

% java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port 
                      adminuser adminpassword
                      -bindWebApp appname webappname websitename contextpath

As with the -deploy command, the -bindWebApp command uses RMI to communicate with OC4J. Note the following:

• See "Starting and Stopping OC4J Standalone" for information about the ORMI port.

• See "Setting Up an Administrative User and Password" for information about adminuser and adminpassword.

• The appname is the application name, according to the -deploymentName setting when you deployed it.

• The webappname is the name of the Web application. This is the WAR file name without the .war extension.

• The websitename is indicated by the Web site XML file name for the desired site, without the .xml extension (for example, http-web-site in OC4J standalone).

• Specify the desired context path portion of the URL for invoking the Web application.

  
  

  Note: A context path setting of "/", which overrides the OC4J default Web application, is disallowed by the admin.jar utility when binding a Web application to the Web site. A setting of null, which is converted to "/", is also disallowed.

  
  

As a result of this command, a <web-app> element is added to the specified Web site XML file, indicating the application name, the Web application name, and the context path.

See the next section, "Sample Deployment", for an example.

Sample Deployment

This example illustrates the result of deploying the utility.ear file shown in "EAR File and WAR File Structures", then binding its Web application. Here are the admin.jar commands, assuming % is the system prompt, j2ee/home is the current directory, and the EAR file is in j2ee/home/demo:

% java -jar admin.jar ormi://myhost:23791 admin welcome
  -deploy -file demo/utility.ear -deploymentName utility

% java -jar admin.jar ormi://myhost:23791 admin welcome
  -bindWebApp utility utility_web http-web-site /utilroot

Note the following:

• The OC4J host name in this example is myhost; the port setting is 23791 in j2ee/home/config/rmi.xml.

• In this example, the administrative account name is admin and the password is welcome.

• The Web application name within utility.ear is utility_web, based on the WAR file name, utility_web.war.

• The -bindWebApp command is to bind utility_web to the Web site defined by j2ee/home/config/http-web-site.xml. This assumes the following entry is in the server.xml file, as is the case by default:

  <web-site path="http-web-site.xml" />
  
  

• The desired context path portion of the URL to invoke the Web application is "/utilroot".

The -deploy command results in the following entry in server.xml, as a subelement of the top-level <application-server> element:

<application name="utility" path="../applications/utility.ear"
             auto-start="true" />

The auto-start attribute specifies whether this application should be automatically restarted each time OC4J is restarted.

The -bindWebApp command results in the following entry in http-web-site.xml, as a subelement of the top-level <web-site> element:

<web-app application="utility" name="utility_web" root="/utilroot"
 load-on-startup="false" max-inactivity-time="no shutdown" shared="false" />

(See "Element Descriptions for Web Site XML Files" for information about the load-on-startup, max-inactivity-time, and shared attributes.)

After the deployment of utility.ear, the directory structure for key files is as follows, assuming default settings for the target directories:

j2ee/home/
   application-deployments/
      utility/
         orion-application.xml
         utility_web/
            orion-web.xml
   applications/
      utility.ear
      utility/
         utility_web.war
         META-INF/
            application.xml
         utility_web/
            index.html
            META-INF/
            WEB-INF/
               web.xml
               classes/
                  TestStatusServlet.class

The server.xml and http-web-site.xml files are in the j2ee/home/config directory.

If orion-application.xml and orion-web.xml exist in the EAR file, they are copied from there into the directories shown above. Otherwise, OC4J generates them into the directories shown above, using default settings from the corresponding OC4J global descriptors and J2EE descriptors.

Descriptors for Sample Deployment

The deployment in the preceding section uses the following descriptors. Passages of particular interest to servlet developers are marked in bold type.

<?xml version="1.0" ?> 
<!DOCTYPE application (View Source for full doctype...)> 
<application>
  <display-name>Web Services Demo</display-name> 
  <module>
    <web>
      <web-uri>utility_web.war</web-uri> 
      <context-root>/j2ee/utility</context-root> 
    </web>
  </module>
</application>

<?xml version="1.0" ?> 
<!DOCTYPE web-app (View Source for full doctype...)> 
<web-app>
  <display-name>Web Services Example</display-name> 
  <description>A few examples of web service publication</description> 
  <welcome-file-list>
    <welcome-file>index.html</welcome-file> 
  </welcome-file-list>
  <servlet>
    <servlet-name>TestStatus</servlet-name> 
    <servlet-class>TestStatusServlet</servlet-class> 
  </servlet>
  <servlet-mapping>
    <servlet-name>TestStatus</servlet-name> 
    <url-pattern>/TestStatusServlet</url-pattern> 
  </servlet-mapping>

</web-app>

<?xml version="1.0" ?> 
<!DOCTYPE orion-application (View Source for full doctype...)> 
<orion-application deployment-version="10.1.2.0.0"
                   default-data-source="jdbc/OracleDS" 
                   treat-zero-as-null="true" autocreate-tables="true" 
                   autodelete-tables="false">
  ...
  <web-module id="utility_web" path="utility_web.war" /> 
  ...
</orion-application>

Invoking the Sample Application

Given the information for the sample deployment in the preceding sections, in which /utilroot is specified as the context path in the admin.jar -bindWebApp command and /TestStatusServlet is specified as the servlet path in web.xml, you invoke the application as follows:

http://host:port/utilroot/TestStatusServlet

Using a Web Application Directory Structure in the Default Web Application

By default, OC4J is configured with a default application and with a default Web application contained in the default application. To use the default Web application for your test files, put them in the standard Web application directory structure under the j2ee/home/default-web-app directory (the default directory for the default Web application).

Perform the following steps:

1. Check relevant configuration in the server.xml file. First, you should see the following entry to define the name and specify the application descriptor for the default application:

   <global-application name="default" path="application.xml" />
   
   

   You should also see the following entry to specify the Web site XML file:

   <web-site path="./http-web-site.xml" />
   
   

2. Look in the OC4J global application.xml descriptor. You should see the following entry to define the default Web application name and specify its root directory:

   <web-module id="defaultWebApp" path="../../home/default-web-app" />
   
   

3. Look in the Web site XML file indicated in server.xml (http-web-site.xml, by default, in OC4J standalone). You should see the following entry to define defaultWebApp as the default Web application for the Web site. (As noted earlier, "/" is the context path for the default Web application in OC4J standalone, without the necessity of a root attribute in the <default-web-app> element.)

   <default-web-app application="default" name="defaultWebApp" />
   
   

4. Given this configuration, deploy your files as follows:

   j2ee/home/default-web-app/
      index.html
      WEB-INF/
         web.xml
         classes/
            TestServlet.class
   
   

   No further action is necessary before you invoke the servlet.

Using a Web Application Directory Structure in an Alternative Web Application

In the previous section, the OC4J default Web application, defaultWebApp, is used to deploy a Web application directory structure. Alternatively, you can define some other Web application that will also be contained in the OC4J default application. This is useful if you want functionality similar to that of the default Web application, but deploying to a clean directory.

Here are the steps to define a Web application, myDefaultWebApp, within the default application:

1. Add a <web-module> element to the OC4J global application.xml file. This defines the name and specifies the root directory of a new OC4J Web application. The entry for the OC4J default Web application is also shown for comparison:

   <web-module id="defaultWebApp" path="../../home/default-web-app" />
   <web-module id="myDefaultWebApp" path="../../home/my-default-web-app" />
   
   

2. Add a <web-app> element to the Web site XML file, http-web-site.xml. This ties the Web application to a context path. The <default-web-app> element for the OC4J default Web application is also shown for comparison:

   <default-web-app application="default" name="defaultWebApp" />
   <web-app application="default" name="myDefaultWebApp" root="/mydefroot" />
   
   

3. Given this configuration, deploy your files as follows. No further action is necessary before you invoke the servlet.

   j2ee/home/my-default-web-app/
      index.html
      WEB-INF/
         web.xml
         classes/
            TestServlet.class
   

Using admin.jar to Undeploy an Application

If you are finished using an application, you can use admin.jar to undeploy it as follows:

% java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port 
                      adminuser adminpassword
                      -undeploy appname

This removes associated entries in server.xml and the Web site XML file, as well as removing all directories and files that were created and copied. See "Starting and Stopping OC4J Standalone" for information about the ORMI port. See "Setting Up an Administrative User and Password" for information about adminuser and adminpassword.

To undeploy the utility.ear application shown in "Sample Deployment", for example:

% java -jar admin.jar ormi://myhost:23791 admin welcome -undeploy utility

Using admin.jar to Redeploy an Application

As when you initially deploy an application to OC4J standalone, use the admin.jar -deploy command to redeploy it. There is no difference to the user. The utility automatically effectively undeploys it first so that you will have a clean start. See "Deploying an EAR File to OC4J Standalone" for information about the -deploy command.

Before redeploying, you must repackage your EAR file to pick up any updated files. If you updated OC4J descriptors on the server, such as orion-web.xml and orion-application.xml, and want to keep the changes, then you must include these in the EAR file as well. Previously copied or generated OC4J descriptors are lost if there has been any update to the EAR file.

Manually Redeploying a WAR File

Deploying an independent WAR file to the OC4J default application is described in "Deploying an Independent WAR File to OC4J Standalone". If you want to redeploy, you must reverse the steps you took to deploy, repackage the WAR file, and repeat the deployment steps. This is an expert mode. (See "Using Oracle Deployment Tools Versus Expert Modes".)

To summarize:

1. Comment out your updates to the global application.xml file and the http-web-site.xml file (or other Web site XML file).

2. Update or repackage the WAR file with your updates. If there is anything in orion-web.xml that you want to save, then include it in the WAR file.

3. Place the new WAR file back in the original target directory, overwriting the original if it is still there.

4. Uncomment the updates in application.xml and http-web-site.xml. Updating application.xml causes OC4J to unpack the WAR file and copy or generate the orion-web.xml file as during the initial deployment.

Triggering Application Redeployment after File Manipulation

Depending on OC4J polling, which is enabled by default in OC4J standalone, there are several ways to trigger a redeployment of your application when you modify files in place on the server. (This is an expert mode. See "Using Oracle Deployment Tools Versus Expert Modes".)

• Modify servlet class files under /WEB-INF/classes.

  If you update a servlet .class file under /WEB-INF/classes, then upon the next request, the servlet and its dependency classes are reloaded and the Web application is redeployed, regardless of whether OC4J polling is enabled.

  
  

  Notes: A servlet and its dependency classes are reloaded immediately, instead of upon next request, if the servlet is set to be preloaded. This is according to load-on-startup settings. See "Servlet Preloading". Changing a servlet class file in a directory location specified in a <classpath> element in global-web-application.xml or orion-web.xml has the same effect as changing a servlet class file in /WEB-INF/classes. However, changing a JAR file or a dependency class (such as a JavaBean) in a <classpath> location has no effect. See the description of the <classpath> element in "Element Descriptions for global-web-application.xml and orion-web.xml".

  
  

• Modify standard descriptors (anything that changes the timestamp).

  If you modify web.xml while polling is enabled, the Web application is redeployed the next time the OC4J task manager runs, which by default is once each second. Servlets and dependency classes in the Web application are reloaded upon the next request.

  If you modify application.xml while polling is enabled, the J2EE application is redeployed. Servlets and dependency classes in the Web application are reloaded upon the next request.

• Modify library JAR files under /WEB-INF/lib.

  If you modify a JAR file in /WEB-INF/lib while polling is enabled, the Web application is redeployed the next time the OC4J task manager runs. Servlets and dependency classes in the Web application are reloaded upon the next request.

• Set the OC4J development flag to "true".

  The development flag is an attribute of the <orion-web-app> element in global-web-application.xml and orion-web.xml. If development is set to "true", then the OC4J server checks a particular directory (the application /WEB-INF/classes directory by default) for updates to servlet source files. If a source file has changed since the last request, then OC4J will, upon the next request, recompile the servlet, redeploy the Web application, and reload the servlet and any dependency classes. See the description of development under "Element Descriptions for global-web-application.xml and orion-web.xml" for further information.

• For JSP applications, set the JSP main_mode flag to "recompile".

  See the Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide for information.

• Stop and restart OC4J.

  See "Starting and Stopping OC4J Standalone".

In OC4J standalone, polling is controlled through the server.xml check-for-updates flag, which is set to "true" by default. Alternatively, you can use the admin.jar -updateConfig option to trigger one-time polling. See "Key OC4J Flags for Development".

Using Enterprise Manager to Undeploy an Application

If you are finished using a J2EE application in Oracle Application Server, you can undeploy it through the Application Server Control Console OC4J Applications Page in Enterprise Manager. Select the application from the applications list (using the corresponding radio button) and click the Undeploy button. This process removes all directories and files that were created and copied, and updates the server configuration appropriately.

See "Application Server Control Console OC4J Applications Page" to see what the page looks like and for further information.

Using Enterprise Manager to Redeploy an Application

You can redeploy a J2EE application in Oracle Application Server through the Application Server Control Console OC4J Applications Page in Enterprise Manager. Select the application from the applications list (using the corresponding radio button) and click the Redeploy button. You will be prompted for the path to the EAR file.

See "Application Server Control Console OC4J Applications Page" to see what the page looks like and for further information.

During redeployment, if you have not changed the EAR file since the previous deployment, then server configuration settings are maintained from the previous deployment. This is particularly relevant for settings in the OC4J descriptors, such as orion-application.xml and orion-web.xml, given that standard configuration, such as through application.xml and web.xml, is presumably in your EAR file anyway.

If you have changed the EAR file, however, then the previous server configuration is discarded. It is replaced with information from the EAR file, such as from the OC4J descriptors (if present) and applicable default values. In this scenario, if you have made OC4J-specific configuration changes on the server, then you should make the same changes to the OC4J descriptors in the EAR file, in order to keep those changes.

After redeployment, you can check the OC4J servlet and Web site configuration pages, described in Chapter 7, "Configuration with Enterprise Manager", to verify whether desired configurations settings have been maintained.