| Oracle® Containers for J2EE Deployment Guide 10g (10.1.3.1.0) Part Number B28951-01 |
|
|
View PDF |
| Oracle® Containers for J2EE Deployment Guide 10g (10.1.3.1.0) Part Number B28951-01 |
|
|
View PDF |
This chapter describes deploying a J2EE application packaged within an EAR file into an OC4J instance and undeploying a J2EE application from an OC4J instance. The chapter includes the following sections:
OC4J provides a streamlined, user-friendly deployment process. A J2EE-compliant EAR file can be deployed as-is, with no changes or repackaging required. You simply have to point to the location of the EAR file; OC4J will automatically deploy the modules that compose the application, including EJB JAR and WAR files.
The following topics outline the general steps involved in deploying an EAR into OC4J:
|
Note: Deploying an EAR from a read-only shared directory is not recommended, as errors might occur. Copy the EAR file to a local directory first, then deploy it. |
Every application deployed into OC4J must have a designated parent application. The default parent is the global application packaged with OC4J, which is named default.
Designating an application as a parent enables classes and services to be shared among the child applications. A child application sees the namespace of its parent application and inherits the set of shared libraries imported by the parent. Configuration data is also imported from the parent, although it can be overridden at the child application level.
Once an application is deployed, any method within the child application can invoke any method within the parent application. This is a means to enable methods in one JAR to see EJBs that have been deployed in another JAR. This is useful for deploying all service EJBs in a single JAR file, for which its users declare the service application as its parent.
A Web application deployed as part of a J2EE application must be bound to the Web site that will be used to access it. This binding is accomplished by specifying the name portion of the name-web-site.xml configuration file that defines the Web site to bind the Web application to.
In most cases, applications will be bound to the default Web site, which is defined by the default-web-site.xml configuration file and listens for requests on port 8888. All Web site configuration files, including default-web-site.xml, are stored in the ORACLE_HOME/j2ee/instance/config directory.
The Web module context root, which will be appended to the URL used to access the application through a Web browser, is also set as part of this Web application enablement process. This value will typically be read from the application.xml deployment descriptor packaged with the application.
If Oracle HTTP Server is used, the context root value will be used in the mount point definition used to route incoming Web requests to an appropriate OC4J instance. See "Using Dynamic HTTP Server Mount Points in Oracle Application Server" for details.
If deploying through the Oracle Enterprise Manager 10g Application Server Control Console, you will apply a deployment plan, which is a client-side aggregation of all the configuration data needed to deploy an archive into OC4J, as the final step of the deployment process. You can either create a new deployment plan for the application or reuse an existing plan, which is especially useful during redeployment.
See Chapter 8, "Working with Deployment Plans" for more information on creating and using deployment plans.
In a configuration in which Oracle HTTP Server (OHS) is used, a Web request is received through an OHS instance, which then routes the request to an OC4J instance serving the requested application.
To route requests, OHS utilizes a list of application-specific mount points, which map the URLs supplied in requests with the OC4J instances that will service the requests.
Prior to Oracle Application Server 10g Release 3 (10.1.3.0.0), configuration of these application-specific mount points was completely manual. When a new application was deployed to an OC4J instance, a new mount point had to be added manually to mod_oc4j.conf, the configuration file for the mod_oc4j module within OHS that forwarded requests to OC4J instances. The OHS instance then had to be restarted.
In Oracle Application Server 10g Release 3 (10.1.3.1.0), mount point configuration is completely automated, eliminating the need for manual file configuration or OHS restarts. Every OC4J instance within a cluster topology sends mount point data for each of its deployed applications to OHS, which adds this information to its internal routing table.
When a new application is deployed to an OC4J instance, its mount point information is transmitted to OHS, enabling OHS to dynamically discover the application. Mount point information includes:
The OC4J host address
The Apache JServ Protocol (AJP) listener port
This value is the lowest available port assigned to AJP in the opmn.xml file on the OC4J node.
The Web application name
This value is defined in the *-web-site.xml configuration file for the Web site the application is bound to.
The Web context(s) defined for the application
This value is also set in the *-web-site.xml configuration file.
The sending and receiving of mount point notifications is managed by Oracle Notification Server (ONS), a component of Oracle Process Manager and Notification Server (OPMN) that is installed by default with every OC4J and OHS instance in an Oracle Application Server configuration
The following list describes what happens when you deploy an application packaged within an EAR file into OC4J:
If the application is being redeployed, the existing installation is first undeployed from OC4J.
OC4J copies the EAR file to the deployment directory, which defaults to the ORACLE_HOME/j2ee/instance/applications directory.
OC4J opens and parses the application.xml file packaged within the EAR file. This file is a standard J2EE descriptor that lists all of the modules contained within the EAR file. OC4J notes these modules and initializes the EAR environment.
OC4J reads the module deployment descriptors for each module type - Web module (WAR), EJB module, connector module, or client module - into memory. The JAR and WAR file environments are also initialized.
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 by OC4J, such as wrapping EJBs with their interfaces.
OC4J writes out new OC4J-specific configuration files to the ORACLE_HOME/j2ee/instance/application-deployments/app_name directory, according to the contents of the deployment plan. If one or more OC4J-specific deployment descriptors was supplied, you may notice that OC4J added additional elements to the generated files.
Any generated classes, such as EJB interface wrapper classes, are compiled and put into new subdirectories of this directory. For example, EJB wrapper classes are generated within an archive named deployment-cache.jar within the ORACLE_HOME/j2ee/instance/application-deployments/app_name/jar_name.jar directory, where jar_name.jar corresponds to the name of a deployed EJB JAR.
Finally, OC4J updates the OC4J server.xml configuration file with the notation that this application has been deployed.
When you deploy an application (including the OC4J default application) to OC4J running JDK 1.5 (Java 5), you cannot re-use that deployment on OC4J running JDK 1.4.
Code compiled with JDK 1.5 (Java 5) cannot be read by the JDK 1.4 VM. When OC4J is running under JDK 1.4 and tries to load a class that was compiled with JDK 1.5, a class-loading exception will be thrown with the following message:
Unsupported major.minor version 49.0
This can occur in scenarios such as these:
You deploy an application that contains EJBs to OC4J running under JDK 1.5, and then, without undeploying the application, you restart OC4J under JDK 1.4. The problem is that the generated code associated with the EJBs will have been compiled with the same JDK version that was used to start the server, and the generated code is cached between server restarts on the file system in the ORACLE_HOME/j2ee/home/application-deployments directory.
The workaround for this is to shut down the server, remove the contents of either the ORACLE_HOME/j2ee/home/application-deployments directory or just the application's subdirectory, and restart the server with JDK 1.4.
You deploy an EAR file that contains classes compiled with and targeted to JDK 1.5 to OC4J running under JDK 1.4.
The workaround for this is to recompile the contents of the EAR using JDK 1.4 and redeploy.
|
Note: To simplify this discussion, it was assumed that no cross-compilations were being used to target code to specific JDK versions. |
The following example shows the key areas of the exploded directory structure created when an archive named utility.ear is deployed, assuming default settings for the target directories. The EAR includes a Web module (utility_web.war) and an EJB JAR (utility_ejb.jar) containing a single stateful session EJB.
OC4J cleanly separates the standard J2EE content and the OC4J-specific files within the exploded directory structure. The original archives and the standard J2EE descriptors are copied to the j2ee/instance/applications directory, enabling these files to be used in a redeployment of the application. The OC4J-specific descriptors generated during deployment are written to the /j2ee/instance/application-deployments directory.
Also note the EJB wrapper class, UtilityManager_StatefulSessionBeanWrapper.class, is generated within the deployment-cache.jar archive. During deployment, OC4J generates a wrapper class for each EJB packaged within an EJB JAR. The wrapper classes generated for the EJBs within an EJB JAR are contained within an archive named deployment-cache.jar, which is in turn contained within a generated JAR file with the same name as the deployed EJB JAR.
j2ee/oc4j1/
application-deployments/
utility/
orion-application.xml
utility_web/
orion-web.xml
utility_ejb.jar/
orion-ejb-jar.xml
deployment-cache.jar/
UtilityManager_StatefulSessionBeanWrapper.class
applications/
utility.ear
utility/
utility_web.war
utility_ejb.jar
META-INF/
application.xml
utility_web/
index.html
META-INF/
WEB-INF/
web.xml
classes/
Example.class
Redeploying a J2EE application packaged within an EAR file prompts OC4J to undeploy the previous instance of the J2EE application, including any embedded resource adapters packaged with the application. Therefore, there is no need to undeploy the application before redeploying.
If you saved the deployment plan from the previous deployment, you can reuse it during the redeployment. By default, the deployment plan will be initialized using the existing application configuration and applied to the redeployment. The previously generated OC4J descriptors will be overwritten based on the content of the deployment plan.
After you redeploy an application, a restart of OC4J is required only in the following cases:
A change is made to the rmi.xml configuration file.
A manual edit is made to the server-level data-sources.xml or jms.xml configuration file. A restart is not required if the file is modified through Application Server Control, admin_client.jar, or an OC4J Ant task.
Other than in these cases, a restart of OC4J is not required after redeploying an application. For information about restarting OC4J, see the Oracle Containers for J2EE Configuration and Administration Guide.
The application is completely inaccessible during redeployment. Incoming requests will not be processed until the updated application is restarted by OC4J when deployment is complete.
After redeploying an application that is the parent of one or more child applications, you should ideally restart each child application. Restarting will ensure that the child applications are able to access any inherited classes or shared libraries provided through the parent.
An application can be removed from an OC4J instance using the following methods:
The Applications section of the Application Server Control Console.
The undeploy Ant task.
For instructions on using this task, see "Undeploying an Archive".
The -undeploy option provided through the admin_client.jar command-line utility.
For instructions on using this option, see "Undeploying an Archive".
Removing a J2EE application from an OC4J instance has the following results:
The application is removed from the OC4J runtime.
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.
When an application that is the parent of one or more child applications is undeployed, the child applications are also undeployed. All of the related applications, the parent as well as its dependent applications, must be redeployed.
If you manually edit the deployment descriptor for an application, a formatting error will cause undeployment of the application and any child applications it has. When OC4J starts up, if an application described in the <server.xml> file fails to load, all entries for the application and its child applications are removed from file. After you correct the formatting error, restarting OC4J will not load the application because it has been undeployed.
For example, the following lines are added to an orion-application.xml file for an application, with an extra slash (/) in the first line of a <jazn> element:
<jazn provider="LDAP" jaas-mode="doAsPrivileged"/>
<jazn-web-app auth-method="COREIDSSO"/>
</jazn>
When OC4J starts up, this application fails to load, and its <application> element is deleted from the server.xml file. Removing the extra slash from the <jazn> element in orion-application.xml and restarting OC4J does not load the application because it is no longer deployed.
Before OC4J can load an application that had an error in its deployment descriptor, you need to correct the error and restore the entry for the application, and the entries for any child applications, in <server.xml>. You can restore an <application> element by deploying the application from scratch or by manually editing the <server.xml> file. For more information, see "Options for Deploying Applications into OC4J" or "Appendix B, Configuration Files Used in OC4J" in the Oracle Containers for J2EE Configuration and Administration Guide.
