|
Oracle® Containers for J2EE Deployment Guide
10g Release 3 (10.1.3) Part No. B14431-01 |
|
 Previous |
 Next |
|
Oracle® Containers for J2EE Deployment Guide
10g Release 3 (10.1.3) Part No. B14431-01 |
|
|
Previous |
Next |
This chapter describes the processes of deploying and undeploying a J2EE application packaged within an EAR file into an OC4J instance. It 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 comprise the application, including EJB JAR and WAR files.
The following section outlines the general steps involved in deploying an EAR into OC4J. The following topics are covered:
|
Note: Deploying an EAR from a read-only shared directory is not recommended, as errors may 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 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, where 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/home/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.
Note that 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 "Dynamic HTTP Server Mount Point Configuration in Oracle Application Server" for details.
If deploying through the Oracle Enterprise Manager 10g Application Server Control Console, you will apply a deployment plan—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 re-use 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, Web requests are received via an OHS instance, which then routes the requests to an OC4J instance serving the requested application.
To route requests, OHS utilizes a list of application-specific mount points that map the URL supplied in a request with the OC4J instance that will service the request.
Prior to Oracle Application Server Release 3 (10.1.3), 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 manually added to mod_oc4j.conf, the configuration file for the mod_oc4j module within OHS which forwards requests to OC4J instances. The OHS instance then had to be restarted.
In Oracle Application Server 10.1.3, mount point configuration is completely automated, eliminating the need for manual file configuration or OHS restarts. Every OC4J instance within the cluster 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
When you deploy an application packaged within an EAR, the following occurs:
If the application is being redeployed, the existing installation is first undeployed from OC4J.
OC4J copies the EAR file to the ÒmasterÓ deployment directory, which defaults to the ORACLE_HOME/j2ee/home/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/home/application-deployments/app_name directory, according to the contents of the deployment plan. Note that if one or more OC4J-specific deployment descriptors were 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/home/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.
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.
Note how 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 oc4j/j2ee/home/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 oc4j/j2ee/home/application-deployments/ directory.
Also note the EJB wrapper class, UtilityManager_StatefulSessionBeanWrapper.class, 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/home/
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 re-use 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.
If changes are made to any of the following configuration files as part of redeployment, OC4J must be restarted for the changes to take effect. Otherwise, a restart of OC4J is not required after redeploying an application. Note that this requirement applies only to configuration files that are already installed on the server.
data-sources.xml
jms.xml
rmi.xml
The application is completely inaccessible during redeployment, and 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:
The Applications section of the Application Server Control Console user interface.
The -undeploy option provided through the admin_client.jar command line utility. See "Undeploying an Archive" for instructions on using this option.
Removing a J2EE application from an OC4J instance results in the following:
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.
This means that all of the related applications - the parent as well as its dependent applications - must be redeployed. Bear this in mind before undeploying a parent application.
