Oracle® Containers for J2EE Developer's Guide 10g (10.1.3.1.0) Part Number B28952-01 |
|
|
View PDF |
This chapter provides guidelines for packaging J2EE-compliant applications and modules for deployment into OC4J. It includes the following sections:
The proper packaging of J2EE applications and modules is critical to successful deployment of your creations into OC4J. As a fully J2EE 1.4-compliant container, OC4J supports the packaging of J2EE applications into different modules which can then be deployed together or separately. Modules can be categorized as belonging to one of two types:
Application modules containing a complete J2EE application or a Web application
Standalone modules containing Enterprise JavaBeans (EJBs), application clients, or resource adapters
A complete J2EE application is assembled and delivered as an Enterprise Archive (EAR) file, a standard Java Archive (JAR) file ending in a .ear
extension. The file includes a J2EE application descriptor and may optionally include an OC4J-specific descriptor and, with JDK 5.0, a lib
directory. An EAR is essentially a metacontainer that includes one or more of the following J2EE modules:
A Web application module is packaged as a Web Application Archive (WAR) file. A WAR typically contains the servlet class files, JSP files, any supporting class files (such as resource bundles), images, and HTML files that comprise a Web application. A J2EE Web deployment descriptor and an optional OC4J-specific Web descriptor are also included.
Note that Web services are packaged in a WAR file for deployment.
EJB modules, which contain class files for enterprise beans, are packaged as JAR files. An EJB JAR will also include an EJB deployment descriptor.
Resource adapter modules containing all Java interfaces, classes, native libraries, and the resource adapter deployment descriptor are packaged as JAR files with a .rar
(Resource Adapter Archive) extension.
Application client modules containing class files and an application client deployment descriptor are packaged as JAR files.
Note that any of the preceding modules can be deployed individually into OC4J, rather than having to be packaged within an EAR file as part of a complete J2EE application. This makes it possible to deploy updated modules without having to redeploy the entire application.
Note: Web services can be packaged as a WAR file or as an EJB JAR file containing stateless session beans. |
The proper packaging of J2EE applications and modules is critical to successful deployment of your creations into OC4J. The following sections review the structure of these files:
The following is the standard J2EE application structure, which you can use as your development and packaging structure as appropriate.
This discussion also shows the relative locations of optional OC4J-specific descriptors, such as orion-application.xml
. As noted previously, if you do not include the OC4J-specific descriptors in your deployment, OC4J generates them for you when you deploy a J2EE application, using values inherited from corresponding OC4J configuration files and J2EE descriptors as defaults.
J2EEApplicationName.ear WAR file(s) JAR file(s) RAR file(s) lib/ JAR and ZIP files for shared classes META-INF/ MANIFEST.MF application.xml (standard J2EE application descriptor) orion-application.xml (optional OC4J application descriptor) WebModuleName.war static HTML files, such as index.html JSP pages images WEB-INF/ web.xml (standard J2EE Web descriptor) orion-web.xml (optional OC4J Web descriptor) classes/ servlet classes, according to package lib/ JAR and ZIP files for shared classes EJBModuleName.jar EJB classes, according to package META-INF/ ejb-jar.xml (standard J2EE descriptor) orion-ejb-jar.xml (optional OC4J descriptor) WebServiceWebModuleName.war WEB-INF/ web.xml (standard J2EE Web descriptor) orion-web.xml (optional OC4J Web descriptor) webservices.xml (standard J2EE descriptor) oracle-webservices.xml (optional OC4J descriptor) mapping_file.xml wsdl/ wsdl_file.wsdl classes/ class files lib/ JAR and ZIP files for dependency classes ApplicationClientModuleName.jar client classes, according to package META-INF/ application-client.xml (standard J2EE descriptor) orion-application-client.xml (optional OC4J descriptor) ResourceAdapterModuleName.rar JAR files for required classes required static files or other files META-INF/ ra.xml (standard J2EE descriptor) orion-ra.xml (optional OC4J descriptor)
Note: This structure is defined in the J2EE specification and related specifications. The J2EE specification is at the following location:http://java.sun.com/j2ee/docs.html |
In J2EE, a WAR file is typically contained within an EAR file. In the example in the preceding section, the EAR file, J2EEAppName
.ear
, would have its /META-INF
directory at the top level, along with Web module WAR files, EJB module JAR files, client application JAR files, and resource adapter RAR files (zero or more of each, as applicable):
META-INF/ application.xml orion-application.xml (optional) EJBModuleName.jar WebModuleName.war ClientModuleName.jar ResourceAdapterModuleName.rar
The following examples show the structure of the archive files for a simple Web application. The EAR file contains a WAR file, which contains a single servlet.
Note: This document assumes you have some J2EE development experience and a means of creating EAR and WAR files, either by using the JAR utility directly, through an IDE such as Oracle JDeveloper, or by using theant utility and a build.xml file. For information about using the OC4J Ant tasks, see the Oracle Containers for J2EE Deployment Guide. For information about ant , see the following Web site :
http://ant.apache.org |
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
Note: TheMANIFEST.MF files are created automatically by the JAR utility. |
The initial configuration data required to deploy an application or module into a J2EE container is specified in an XML-formatted configuration file known as a deployment descriptor. The format of a deployment descriptor is defined in a Document Type Definition (DTD) document or an XML Schema Definition (XSD).
Each deployable module has a standard J2EE deployment descriptor that is required for deployment into a J2EE-compatible server. In addition, J2EE containers such as OC4J utilize a number of vendor-specific deployment descriptor files that extend the standard J2EE deployment descriptors. For example, the OC4J-specific orion-application.xml
descriptor extends the J2EE standard application.xml
descriptor with configuration data specific to OC4J.
You can create and package the appropriate OC4J-specific descriptor with a deployable archive. However, this is not required; if OC4J does not find a packaged descriptor at deployment time, a deployment plan is automatically generated using default values inherited from corresponding OC4J configuration files and J2EE descriptors as defaults. See the Oracle Containers for J2EE Deployment Guide for more on deployment plans.
Table 7-1 provides a description of each J2EE standard deployment descriptor and its corresponding OC4J extension. The XML Schema Definition (XSD) file that describes each OC4J-specific descriptor is also noted. You can view the current Oracle XSDs at the following link:
http://www.oracle.com/technology/oracleas/schema/index.html
Note that OC4J now provides the ability to create a deployment plan that consolidates all of the OC4J-specific configuration data that is persisted within the various OC4J descriptor files. You can use the deployment plan editor functionality to set or edit configuration data at deployment time. See the Oracle Containers for J2EE Deployment Guide for more on working with deployment plans.
Table 7-1 J2EE and OC4J Deployment Descriptors
J2EE Standard Descriptors | OC4J Proprietary Descriptors |
---|---|
Specifies the components of a J2EE application, such as EJB and Web modules, and can specify additional configuration for the application as well. This descriptor must be included in the |
Generally defines OC4J-specific configurations such as security role mappings, data source definitions, JNDI namespace access and shared library replacements. Can also be used to specify additional modules, beyond those specified in the J2EE The format of this file is defined by |
Specifies and configures a set of J2EE Web components, including static pages, servlets, and JSP pages. It also specifies and configures other components, such as EJBs, that the Web components might call. The Web components might together form an independent Web application and be deployed in a standalone WAR file. |
Extends the standard J2EE descriptor with application-level OC4J-specific configuration data such as whether or not OC4J features like developer mode or auto-reload of JSPs are enabled. The format of this file is defined by |
Defines the specific structural characteristics and dependencies of the Enterprise JavaBeans within a JAR, and provides instructions for the EJB container about how the beans expect to interact with the container. If you are using EJB 3.0, this deployment descriptor file is optional; you can use annotations instead. In this release, OC4J supports the use of both EJB 3.0 annotations and |
Defines OC4J-specific configuration data for all EJBs within an archive, including EJB pool settings, time-out and retry settings, JNDI mappings and finder method specifications. Also includes properties for the TopLink persistence manager. The format of this file is defined in |
Defines one or more persistence units in an EJB 3.0 application that uses entities. In this release, you can define |
|
Describes the EJB modules and other resources used by a J2EE application client packaged in an archive. |
Contains OC4J deployment data, including JNDI mappings to an EJB's home interface or to external resources such as a data source, JMS queue or mail session. The file format is defined in |
Contains information on implementation code, configuration properties and security settings for a resource adapter packaged within a RAR file. |
Contains deployment configurations for deploying resource adapters into OC4J. It contains EIS connection information, JNDI name to be used, connection pooling parameters, and resource principal mappings. The file format is defined by
In an OC4J instance with standalone resource adapters deployed, contains an enumeration of those standalone resource adapters. In a J2EE application with embedded resource adapters deployed, contains a list of embedded resource adapters that have been bundled with the application. This file is formatted according to |
Describes a Web service, including WSDL information and JAX-RPC mapping data, for a Web Service application packaged within a WAR file. |
Defines properties used by the OC4J Web services container, such as whether to expose the WSDL file. It also defines endpoint addresses and data specific to EJBs implemented as Web services. The file can be packaged in a WAR or an EJB JAR. This file is formatted according to |
In addition to the extensions noted above, additional OC4J-specific descriptors are provided to allow data sources and security role mappings to be defined. The J2EE specification does not provide standard descriptors for defining such resources. As with the OC4J specific descriptors described above, these descriptors can optionally be packaged with an application for deployment into OC4J.
Table 7-2 Additional OC4J-Specific Descriptors
Descriptor | Overview |
---|---|
|
Defines one or more data sources to be used by the application to connect to one or more databases. Data sources offer a portable, vendor-independent method for creating connections to databases. A data source's properties are set so that it represents a particular database. The format of this file is defined by |
|
Can optionally be supplied with an application or module when the XML provider type is specified. Stores JAAS (Java Authentication and Authorization Service) data on users and roles For more information about the |
|
Contains the security configuration for the OC4J instance. The For more information about the |
The J2EE standard defines the concept and format of an application descriptor, called application.xml
, that you must include in the /META-INF
directory of the EAR file containing 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 an application 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>
The J2EE standard application descriptor, application.xml
, is extended by an OC4J-specific application-level application descriptor, orion-application.xml
, which contains additional OC4J-specific configuration data. You can optionally provide an orion-application.xml
file with the application.xml
file in the /META-INF
directory of your EAR file.
If you include an orion-application.xml
file in your EAR file, OC4J initializes the deployment plan created during the application deployment process with the values specified in the file. For details on creating or editing deployment plans at deployment time, see the Oracle Containers for J2EE Deployment Guide.
This data can optionally be edited at deployment time using the deployment plan editor functionality provided by the Oracle Enterprise Manager 10g Application Server Control Console and JDeveloper. The finalized data is then written out to a generated orion-application.xml
file in the ORACLE_HOME
/j2ee/
instance
/application-deployments
directory.
If the EAR file does not contain an orion-application.xml
file, OC4J generates the file in the deployment directory as noted above, using default settings inherited 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 is within the EAR file.
See "J2EE Application Structure Within OC4J" for information about where orion-application.xml
fits in the application structure.
Note: When OC4J generatesorion-application.xml , it may make changes to the file but these changes are transparent. For example, an attribute setting that specifies the default value may be ignored or removed. |
In most circumstances, you should use orion-application.xml
only to define OC4J-specific configuration such as security role mappings. Also note that when 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 "Packaging a J2EE Standard Application Descriptor (application.xml)":
<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="<jndi-user-role>"> <group name="users" /> </security-role-mapping> </namespace-resource> </read-access> <write-access> <namespace-resource root=""> <security-role-mapping name="<jndi-user-role>"> <group name="users" /> </security-role-mapping> </namespace-resource> </write-access> </namespace-access> </orion-application>