Overview
Geronimo uses the OpenEJB container for providing EJB services. With the advent of JAVA EE, the EJB container services such as transaction management, security, life cycle management can be declared in the EJB class itself using annotations. However, the EJB deployment descriptor can still be provided via usage of the ejb-jar.xml file. When both annotations and the ejb-jar.xml file are provided, the ejb-jar.xml file takes precedence over the annotations.
The Geronimo-specific deployment plan for an EJB application, which is usually packaged as an EJB JAR file, is called "openejb-jar.xml". The openejb-jar.xml deployment plan is used to in conjunction with the ejb-jar.xml JAVA EE deplopyment plan to deploy enterprise applications to the Geronimo application server. The openejb-jar.xml deployment plan is an optional file, but is typically used when deploying a EJB JAR file. It is used to map roles and resource (e.g., security roles, EJB names, database resources, JMS resources, etc.) declared in the openejb-jar.xml deployment plan to corresponding entities deployed in the server. Also, if there are any EJB container specific configurations required those setting are configured in this deployment plan as well. If the EJB module depends on any third party libraries or other services running in the server, all these third party libraries and the services are specified in the openejb-jar.xml file. Some EJB applications require class loading requirements different from the default class loading behavior. The openejb-jar.xml file allows the application deployer to configure this as well. There are many more configurations that could be done through openejb-jar.xml file depending on the requirements of the EJB application.
Packaging
The openejb-jar.xml Geronimo-specific deployment plan can be packaged as follows:
- Embedded in an EJB JAR file. In this case, the openejb-jar.xml file must be placed in the /META-INF directory of the JAR, which is the same place where the ejb-jar.xml file must be located.
- Maintained separately from the EJB JAR file. In this case, the path to the file must be provided to the appropriate Geronimo deployer (e.g., command-line or console) when the EJB JAR file is deployed. Note that in this case, the filename may be named something other than openejb-jar.xml but must adhere to the same schema. Also note that this will not work if the EJB JAR file is to be embedded in an enterprise application EAR file (see below).
- Embedded in an enterprise application EAR file: In one case, the high-level element <ejb-jar> can be embedded outside the EJB JAR file in the EAR file's geronimo-application.xml file
- Embedded in an enterprise application EAR file: In another case, the actual openejb-jar.xml file can be embedded outside the EJB JAR file and placed elsewhere in the EAR and referenced with an alt-dd element in the geronimo-application.xml deployment plan file.
Schema
The openejb-jar.xml deployment plan is defined by the openejb-jar-2.1.xsd schema located in the <geronimo_home>/schema/ subdirectory of the main Geronimo installation directory. The openejb-jar-2.1.xsd schema is shown here:
Schema top-level elements
The root XML element in the openejb-jar-2.2.xsd schema is the <openejb-jar-2.2> element. The top-level XML elements of the <openejb-jar> root element are described in the sections below. The deployment plan should always use the OpenEJB namespace, and it typically requires elements from the Geronimo Naming, Geronimo Security, and Geronimo System namespaces. Additionally, it has a required attribute to identify its configuration name. A typical deployment for openejb-jar.xml can be presented as follows:
<openejb-jar xmlns:openejb="http://www.openejb.org/xml/ns/openejb-jar-2.2" targetNamespace="http://www.openejb.org/xml/ns/openejb-jar-2.2" xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.2" xmlns:security="http://geronimo.apache.org/xml/ns/security-2.0" xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.2" xmlns:pkgen="http://www.openejb.org/xml/ns/pkgen-2.1" version="1.0"> ... </openejb-jar>
<sys:environment>
The <sys:environment> XML element uses the Geronimo System, which is used to specify the common elements for common libraries and module-scoped services, and is described at http://geronimo.apache.org/schemas-2.1/docs/geronimo-module-1.2.xsd.html. The <sys:environment> element contains the following elements:
- The <moduleId> element is used to provide the configuration name for the EJB JAR application as deployed in the Geronimo server. It contains elements for the groupId, artifactId, version and module type. Module IDs are normally printed with slashes between the four components, such as GroupID/ArtifactID/Version/Type.
- The <dependencies> element is used to provide the configurations and third party libraries on which the EJB module is dependent upon. These configurations and libraries are made available to the EJB module via the Geronimo classloader hierarchy.
- The <hidden-classes> element can be used to specify a list of classes which will never be loaded from parent ClassLoaders of this module. For example, if Log4J was listed here, the module would never see Geronimo's copy of Log4J. If the module provided it's own Log4J JAR it would use that, otherwise it would not be able to load Log4J at all.
- The <non-overridable-classes> element can be used to specify a list of classes which will only be loaded from parent ClassLoaders of this module (never from the module's own ClassLoader). For example, this is used to prevent a EJB application from redefining "javax.servlet", so those classes will always be loaded from the server instead of from the EJB application's own ClassPath.
- The <inverse-classloading> element can be used to specify that standard classloader delegation is to be reversed for this module.
- The <suppress-default-environment> element can be used to suppress inheritance of environment by module (i.e., any default environment built by a Geronimo builder when deploying the plan will be suppressed).
An example openejb-jar.xml file is shown below using the <sys:environment> elements:
<openejb-jar xmlns="http://openejb.apache.org/xml/ns/openejb-jar-2.2"
xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.2">
<sys:environment>
<sys:moduleId>
<sys:groupId>default</sys:groupId>
<sys:artifactId>openejb-jar-1</sys:artifactId>
<sys:version>2.0</sys:version>
<sys:type>ear</sys:type>
</sys:moduleId>
<sys:dependencies>
<sys:dependency>
<sys:groupId>org.apache.geronimo.testsuite</sys:groupId>
<sys:artifactId>agent-ds</sys:artifactId>
<sys:version>2.2-SNAPSHOT</sys:version>
<sys:type>car</sys:type>
</sys:dependency>
<sys:dependency>
<sys:groupId>org.apache.geronimo.configs</sys:groupId>
<sys:artifactId>tomcat6</sys:artifactId>
<sys:version>2.2-SNAPSHOT</sys:version>
<sys:type>car</sys:type>
</sys:dependency>
</sys:dependencies>
</sys:environment>
</openejb-jar>
CMP Entity Beans XML Elements:
<naming:cmp-connection-factory>
The <naming:cmp-connection-factory> XML element uses the Geronimo Naming namespace, which is used to identify the common elements for resolving EJB references, resource references, and Web services references, and is described at http://geronimo.apache.org/schemas-2.1/docs/geronimo-naming-1.2.xsd.html. It is used to specify a JDBC connection pool that should be used by Container Managed Persistence (CMP) entity beans to connect to a database. Since the <naming:cmp-connection-factory> element points to a database pool using the same syntax a resource reference uses, there are multiple methods available to refer to the connection pool. It can be specified by a simple name using the <resource-link> element, by pattern using the <pattern> element, or finally by URL using the <url> element. The resource-link handles most common resource situations where the JDBC pools are deployed as J2EE connectors in the same application, or deployed standalone in the same server. But pattern or URL can be use for any. An example openejb-jar.xml using all three techniques is shown:
<openejb-jar xmlns="http://openejb.apache.org/xml/ns/openejb-jar-2.2"
xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.2"
xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.2">
<sys:environment>
<sys:moduleId>
<sys:groupId>default</sys:groupId>
<sys:artifactId>openejb-jar-1</sys:artifactId>
<sys:version>2.0</sys:version>
<sys:type>ear</sys:type>
</sys:moduleId>
<sys:dependencies>
<sys:dependency>
<sys:groupId>org.apache.geronimo.testsuite</sys:groupId>
<sys:artifactId>agent-ds</sys:artifactId>
<sys:version>2.2-SNAPSHOT</sys:version>
<sys:type>car</sys:type>
</sys:dependency>
<sys:dependency>
<sys:groupId>org.apache.geronimo.configs</sys:groupId>
<sys:artifactId>tomcat6</sys:artifactId>
<sys:version>2.2-SNAPSHOT</sys:version>
<sys:type>car</sys:type>
</sys:dependency>
</sys:dependencies>
</sys:environment>
<!-- Begin configuration for Container Managed Persistence (CMP) -->
<naming:cmp-connection-factory>
<naming:pattern>
<naming:groupId>resourcelocator-pattern-groupid</naming:groupId>
<naming:artifactId>resourcelocator-pattern-artifactid</naming:artifactId>
<naming:version>resourcelocator-pattern-version</naming:version>
<naming:module>resourcelocator-pattern-module</naming:module>
<naming:name>resourcelocator-pattern-name</naming:name>
</naming:pattern>
<naming:resource-link>resourcelocator-resourcelink</naming:resource-link>
<naming:url>resourcelocator-url</naming:url>
</naming:cmp-connection-factory>
<!-- End configuration for Container Managed Persistence (CMP) -->
</openejb-jar>
<ejb-ql-compiler-factory>
The <ejb-ql-compiler-factory> XML element uses the OpenEJB default namespace for a openejb-jar.xml file that is described at http://www.openejb.org/xml/ns/openejb-jar-2.2. It is used to specify the name of a Java class that can compile EJB-QL (Query Language) queries into SQL statements for a particular database product. This must be the fully-qualified class name of a class that implements org.tranql.sql.EJBQLCompilerFactory. The default is for the Derby database, which ships with Geronimo, although it may work for other database products as well. An example openejb-jar.xml using the <ejb-ql-compiler-factory> XML element is shown:
<openejb-jar xmlns="http://openejb.apache.org/xml/ns/openejb-jar-2.2"
xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.2"
xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.2">
<sys:environment>
<sys:moduleId>
<sys:groupId>default</sys:groupId>
<sys:artifactId>openejb-jar-1</sys:artifactId>
<sys:version>2.0</sys:version>
<sys:type>ear</sys:type>
</sys:moduleId>
<sys:dependencies>
<sys:dependency>
<sys:groupId>org.apache.geronimo.testsuite</sys:groupId>
<sys:artifactId>agent-ds</sys:artifactId>
<sys:version>2.2-SNAPSHOT</sys:version>
<sys:type>car</sys:type>
</sys:dependency>
<sys:dependency>
<sys:groupId>org.apache.geronimo.configs</sys:groupId>
<sys:artifactId>tomcat6</sys:artifactId>
<sys:version>2.2-SNAPSHOT</sys:version>
<sys:type>car</sys:type>
</sys:dependency>
</sys:dependencies>
</sys:environment>
<!-- Begin configuration for Container Managed Persistence (CMP) -->
<naming:cmp-connection-factory>
<naming:pattern>
<naming:groupId>resourcelocator-pattern-groupid</naming:groupId>
<naming:artifactId>resourcelocator-pattern-artifactid</naming:artifactId>
<naming:version>resourcelocator-pattern-version</naming:version>
<naming:module>resourcelocator-pattern-module</naming:module>
<naming:name>resourcelocator-pattern-name</naming:name>
</naming:pattern>
<naming:resource-link>resourcelocator-resourcelink</naming:resource-link>
<naming:url>resourcelocator-url</naming:url>
</naming:cmp-connection-factory>
<ejb-ql-compiler-factory>ejbqlcompilerfactory</ejb-ql-compiler-factory>
<!-- End configuration for Container Managed Persistence (CMP) -->
</openejb-jar>
<db-syntax-factory>
The <db-syntax-factory> XML element uses the OpenEJB default namespace for a openejb-jar.xml file that is described at http://www.openejb.org/xml/ns/openejb-jar-2.2. It is used to specify the name of a Java class that can customize CMP SQL statements for a particular database product. This must be the fully-qualified class name of a class that implements org.tranql.sql.DBSyntaxFactory. The default is for the Derby database, which ships with Geronimo, although it may work for other database products as well. An example openejb-jar.xml using the <db-syntax-factory> XML element is shown:
<openejb-jar xmlns="http://openejb.apache.org/xml/ns/openejb-jar-2.2"
xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.2"
xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.2">
<sys:environment>
<sys:moduleId>
<sys:groupId>default</sys:groupId>
<sys:artifactId>openejb-jar-1</sys:artifactId>
<sys:version>2.0</sys:version>
<sys:type>ear</sys:type>
</sys:moduleId>
<sys:dependencies>
<sys:dependency>
<sys:groupId>org.apache.geronimo.testsuite</sys:groupId>
<sys:artifactId>agent-ds</sys:artifactId>
<sys:version>2.2-SNAPSHOT</sys:version>
<sys:type>car</sys:type>
</sys:dependency>
<sys:dependency>
<sys:groupId>org.apache.geronimo.configs</sys:groupId>
<sys:artifactId>tomcat6</sys:artifactId>
<sys:version>2.2-SNAPSHOT</sys:version>
<sys:type>car</sys:type>
</sys:dependency>
</sys:dependencies>
</sys:environment>
<!-- Begin configuration for Container Managed Persistence (CMP) -->
<naming:cmp-connection-factory>
<naming:pattern>
<naming:groupId>resourcelocator-pattern-groupid</naming:groupId>
<naming:artifactId>resourcelocator-pattern-artifactid</naming:artifactId>
<naming:version>resourcelocator-pattern-version</naming:version>
<naming:module>resourcelocator-pattern-module</naming:module>
<naming:name>resourcelocator-pattern-name</naming:name>
</naming:pattern>
<naming:resource-link>resourcelocator-resourcelink</naming:resource-link>
<naming:url>resourcelocator-url</naming:url>
</naming:cmp-connection-factory>
<ejb-ql-compiler-factory>ejbQlCompilerFactory</ejb-ql-compiler-factory>
<db-syntax-factory>dbSyntaxFactory</db-syntax-factory>
<!-- End configuration for Container Managed Persistence (CMP) -->
</openejb-jar>
<enforce-foreign-key-constraints>
The <enforce-foreign-key-constraints> XML element uses the OpenEJB default namespace for a openejb-jar.xml file that is described at http://www.openejb.org/xml/ns/openejb-jar-2.2. This is effectively a true/false element – if it's present that means true, and if it's not present, that means false. If true, then Geronimo will make a special effort to execute insert, update, and delete statements in an order consistent with the foreign keys between tables. If false, then Geronimo will execute statements in any order, though still within the same transaction. This element should be present if the underlying database enforces foreign keys at the moment a statement is executed instead of at the end of the transaction. An example openejb-jar.xml setting the <db-syntax-factory> XML element to "true" is shown:
<openejb-jar xmlns="http://openejb.apache.org/xml/ns/openejb-jar-2.2"
xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.2"
xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.2">
<sys:environment>
<sys:moduleId>
<sys:groupId>default</sys:groupId>
<sys:artifactId>openejb-jar-1</sys:artifactId>
<sys:version>2.0</sys:version>
<sys:type>ear</sys:type>
</sys:moduleId>
<sys:dependencies>
<sys:dependency>
<sys:groupId>org.apache.geronimo.testsuite</sys:groupId>
<sys:artifactId>agent-ds</sys:artifactId>
<sys:version>2.2-SNAPSHOT</sys:version>
<sys:type>car</sys:type>
</sys:dependency>
<sys:dependency>
<sys:groupId>org.apache.geronimo.configs</sys:groupId>
<sys:artifactId>tomcat6</sys:artifactId>
<sys:version>2.2-SNAPSHOT</sys:version>
<sys:type>car</sys:type>
</sys:dependency>
</sys:dependencies>
</sys:environment>
<!-- Begin configuration for Container Managed Persistence (CMP) -->
<naming:cmp-connection-factory>
<naming:pattern>
<naming:groupId>resourcelocator-pattern-groupid</naming:groupId>
<naming:artifactId>resourcelocator-pattern-artifactid</naming:artifactId>
<naming:version>resourcelocator-pattern-version</naming:version>
<naming:module>resourcelocator-pattern-module</naming:module>
<naming:name>resourcelocator-pattern-name</naming:name>
</naming:pattern>
<naming:resource-link>resourcelocator-resourcelink</naming:resource-link>
<naming:url>resourcelocator-url</naming:url>
</naming:cmp-connection-factory>
<ejb-ql-compiler-factory>ejbQlCompilerFactory</ejb-ql-compiler-factory>
<db-syntax-factory>dbSyntaxFactory</db-syntax-factory>
<enforce-foreign-key-constraints/>
<!-- End configuration for Container Managed Persistence (CMP) -->
</openejb-jar>
Entity, Session, Message-driven EJB XML Elements:
<enterprise-beans>
The <enterprise-beans> XML element uses the OpenEJB default namespace for a openejb-jar.xml file that is described at http://www.openejb.org/xml/ns/openejb-jar-2.2. It is used to specify references by <entity>, <session>, and <message-driven> EJB's.
<relationships>
The <relationships> XML element uses the OpenEJB default namespace for a openejb-jar.xml file that is described at http://www.openejb.org/xml/ns/openejb-jar-2.2. Container-managed relationships are initially defined in the ejb-jar.xml deployment descriptor, but the mappings to specific database elements are defined in the openejb-jar.xml file using the <relationship> element.
<naming:message-destination>
The <naming:message-destination> XML element uses the Geronimo Naming namespace, which is used to identify the common elements for resolving EJB references, resource references, and Web services references, and is described at http://geronimo.apache.org/schemas-2.1/docs/geronimo-naming-1.2.xsd.html. It is used to configure a JMS queue or topic which acts like a destination for the messages delivered.
<app:security>
The <app:security> XML element uses the Geronimo Applicaiton namespace described at
http://geronimo.apache.org/schemas-2.1/docs/geronimo-application-2.0.xsd.html
. It is used to maps roles specified in the WAR file to roles or principals in the security realm that will be used when deploying the module.
<sys:service>
The <sys:service> XML element uses the Geronimo System namespace described at
http://geronimo.apache.org/schemas-2.1/docs/geronimo-module-1.2.xsd.html. It is an empty generic element to be extended by GBean and other module types.
Samples
For example, the below XML content is the deployment descriptor (ejb-jar.xml) of a stateless session bean that connects to a back end DB2 database.
<?xml version="1.0" encoding="UTF-8" ?>
<ejb-jar xmlns="http://java.sun.com/xml/ns/javaee" version="3.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/ejb-jar_3_0.xsd">
<description>Stateless Session Bean Example</description>
<display-name>Stateless Session Bean Example</display-name>
<enterprise-beans>
<session>
<ejb-name>RetrieveEmployeeInfoBean</ejb-name>
<business-remote>examples.session.stateless_dd.RetrieveEmployeeInfo</business-remote>
<ejb-class>examples.session.stateless_dd.RetrieveEmployeeInfoBean</ejb-class>
<session-type>Stateless</session-type>
<transaction-type>Container</transaction-type>
<resource-ref>
<res-ref-name>jdbc/DataSource</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<res-auth>Container</res-auth>
<res-sharing-scope>Shareable</res-sharing-scope>
</resource-ref>
</session>
</enterprise-beans>
<interceptors>
<interceptor>
<interceptor-class>
examples.session.stateless_dd.RetrieveEmployeeInfoCallbacks
</interceptor-class>
<post-construct>
<lifecycle-callback-method>construct</lifecycle-callback-method>
</post-construct>
<post-activate>
<lifecycle-callback-method>activate</lifecycle-callback-method>
</post-activate>
<pre-passivate>
<lifecycle-callback-method>passivate</lifecycle-callback-method>
</pre-passivate>
</interceptor>
</interceptors>
<assembly-descriptor>
<interceptor-binding>
<ejb-name>RetrieveEmployeeInfoBean</ejb-name>
<interceptor-class>
examples.session.stateless_dd.RetrieveEmployeeInfoCallbacks
</interceptor-class>
</interceptor-binding>
</assembly-descriptor>
</ejb-jar>
The default namespace of the above XML document is http://java.sun.com/xml/ns/javaee. The XML elements that do not have a namespace prefix belong to the default namespace.
In EJB3.0, most of the deployment descriptor declarations can be done through the corresponding annotations in the bean class. However, if a deployment descriptor is supplied (ejb-jar.xml), the declarations in the deployment descriptor will override the annotations.
The ejb module connects to back end datasource using its JNDI name jdbc/DataSource as declared in the ejb-jar.xml. It also declares that the ejb is a stateless session bean and provides an interceptor class for the bean. The interceptor class will have callback methods which container calls when the corresponding events occur in the bean's life cycle.
For the above deployment descriptor, we will have to provide a corresponding deployment plan file (openejb-jar.xml) that maps the declared datasource to actual datasource deployed in the server. The following is the deployment plan.
<openejb-jar xmlns="http://openejb.apache.org/xml/ns/openejb-jar-2.2"
xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.2"
xmlns:sec="http://geronimo.apache.org/xml/ns/security-2.0"
xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.2">
<sys:environment>
<sys:moduleId>
<sys:groupId>samples</sys:groupId>
<sys:artifactId>EmployeeDemo-ejb-dd</sys:artifactId>
<sys:version>3.0</sys:version>
<sys:type>jar</sys:type>
</sys:moduleId>
<sys:dependencies>
<sys:dependency>
<sys:groupId>console.dbpool</sys:groupId>
<sys:artifactId>jdbc/FEmployeeDatasource</sys:artifactId>
<sys:version>1.0</sys:version>
<sys:type>rar</sys:type>
</sys:dependency>
</sys:dependencies>
</sys:environment>
<enterprise-beans>
<session>
<ejb-name>RetrieveEmployeeInfoBean</ejb-name>
<naming:resource-ref>
<naming:ref-name>jdbc/DataSource</naming:ref-name>
<naming:resource-link>jdbc/EmployeeDatasource</naming:resource-link>
</naming:resource-ref>
</session>
</enterprise-beans>
</openejb-jar>
The default namespace of the above XML document is http://openejb.apache.org/xml/ns/openejb-jar-2.2. The XML elements that do not have a namespace prefix belong to the default namespace.
Observe the various XML tags and corresponding namespaces used in the deployment plan for various purposes.
<sys:environment> .. </sys:environment> : These elements provide the moduleId configuration and the dependencies. The moduleId elements provide the configuration name for the ejb module. So, when the ejb module is deployed, it is given the configuration name samples/EmployeeDemo-ejb-dd/3.0/jar. The dependencies elements provide the configurations and third party libraries on which the ejb module is dependent on. These configurations and libraries will be available to the ejb module via a classloader hierarchy. In this case, the ejb module is dependent on console.dbpool/jdbc/FEmployeeDatasource/1.0/jar which is the configuration of the deployed Datasource that connects to a back end DB2 database. The Datasource deploys a database connection pool (javax.sql.Datasource) with name jdbc/EmployeeDatasource.
<enterprise-beans> .. </enterprise-beans> : These elements help us to configure the enterprise beans. In this case, the datasource reference jdbc/DataSource is mapped to jdbc/EmployeeDatasource.
In the ejb bean class, the following java code is used to obtain a connection from the datasource.
....
....
Context initContext = new InitialContext();
Context envContext = (Context)initContext.lookup("java:comp/env");
DataSource ds = (DataSource)envContext.lookup("jdbc/DataSource");
Connection con = ds.getConnection();
....
....
The above descriptor and plan are the simple illustrations that explain how ejb modules are developed and assembled for Apache Geronimo. Similarly, many other configurations can be performed in the openejb-jar.xml. The schema for the plan is openejb-jar-2.1.xsd