7 Packaging an Application for Deployment Into OC4J

This chapter provides guidelines for packaging J2EE-compliant applications and modules for deployment into OC4J. It includes the following sections:

• Overview of J2EE Application Packaging

• Packaging Deployment Descriptors

Overview of J2EE Application Packaging

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. An EAR is essentially a meta-container that may include one or more of the J2EE modules described below:

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

• J2EE Application Structure within OC4J

• Application Module (EAR File and WAR File) Structures

J2EE Application Structure within OC4J

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)
   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 files for dependency classes

   EJBModuleName.jar
      EJB classes, according to package
      META-INF/
         ejb-jar.xml (standard J2EE descriptor)
         orion-ejb-jar.xml (optional OC4J descriptor)
         lib/
             JAR files for dependency classes

   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 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)
         lib/
             JAR files for dependency classes

   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

Application Module (EAR File and WAR File) Structures

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

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

Notes: 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, or through an IDE such as Oracle JDeveloper, or by using the ant utility and a build.xml file. See the following site for information about ant: http://ant.apache.org The MANIFEST.MF files are created automatically by the JAR utility.

Packaging Deployment Descriptors

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.

Deployment Descriptors Overview

The following table 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
application.xml 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 /META-INF directory of the application's EAR file.	orion-application.xml 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 application.xml descriptor. The format of this file is defined by orion-application-10_0.xsd.
web.xml 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.	orion-web.xml 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 orion-web-10_0.xsd.
ejb-jar.xml 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.	orion-ejb-jar.xml 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 orion-ejb-jar-10_0.xsd.
application-client.xml Describes the EJB modules and other resources used by a J2EE application client packaged in an archive.	orion-application-client.xml 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 orion-application-client-10_0.xsd.
ra.xml Contains information on implementation code, configuration properties and security settings for a resource adapter packaged within a RAR file.	oc4j-ra.xml 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 oc4j-connector-factories-10_0.xsd. oc4j-connectors.xml 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 oc4j-connectors-10_0.xsd.
webservices.xml Describes a Web service, including WSDL information and JAX-RPC mapping data, for a Web Service application packaged within a WAR file.	oracle-webservices.xml 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 oracle-webservices-10_0.xsd.

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
data-sources.xml	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 data-sources-10_1.xsd.
jazn-data.xml	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, roles, policy and LoginModules. The format of this file is defined by jazn-data-10_0.xsd.

Packaging a J2EE Standard Application Descriptor (application.xml)

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>

Packaging an OC4J-Specific Application Descriptor (orion-application.xml)

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. See the Oracle Containers for J2EE Deployment Guide for details on creating or editing deployment plans at deployment time.

This data can optionally be edited at deployment time using the deployment plan editor functionality provided by 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/home/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 within in the EAR file.

See "J2EE Application Structure within OC4J" for information about where orion-application.xml fits in the application structure.

Note: When OC4J generates orion-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="&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>