THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
Geronimo uses OpenEJB container for providing ejb services. An EJB application requires ejb-jar.xml as deployment descriptor and openejb-jar.xml as deployment plan. With the advent of Java EE 5, 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 through ejb-jar.xml file. When both annotations and ejb-jar.xml file are provided, the ejb-jar.xml file takes precedence over the annotations.
The openejb-jar.xml file contains deployment plan for ejb modules. In the openejb-jar.xml file, the application deployer maps the security roles, ejb names, database resources, JMS resources, etc. declared in ejb-jar.xml file to corresponding entities deployed in the server. In addition to that, if there are any ejb container specific configurations to be done, the required settings are configured as well here. 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 application deployer to configure this as well. There are many more configurations that could be done through openejb-jar.xml file depending on the needs of the ejb application. The following sections briefly explain how openejb-jar.xml file can be used to configure the ejb container and ejb applications.
Sample plan for a SSB application
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.
ejb-jar.xml
<?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.xml
<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.
examples.session.stateless_dd.RetrieveEmployeeInfoBean.java
....
....
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
Sample plan for a MDB application
Apache geronimo ships with ActiveMQ message broker and an inbound and outbound JMS resource adapter for the ActiveMQ broker. This sample illustrates deploying and running two MDBs that listen to a jms topic TextTopic. When the web client publishes a message to this topic, the two MDBs receive the message and process it. Because the message is published to the topic, all the configured listeners, in this case the two MDBs, receive a copy of the message. In addition to that, we will also illustrate how to deploy a JMS resource adapter within the application scope. Usually, the resource adapters are deployed at the server scope and can be used by all other applications as well. In this example, a JMS resource plan is embedded in the application deployment plan geronimo-application.xml and deployed while deploying the application archive.
ejb-jar.xml
<?xml version="1.0" encoding="UTF-8" ?>
<ejb-jar>
<enterprise-beans>
<message-driven>
<ejb-name>TextMessageBean1</ejb-name>
<ejb-class>
sample.mdb.TextMessageBean1
</ejb-class>
<messaging-type>
javax.jms.MessageListener
</messaging-type>
<transaction-type>Bean</transaction-type>
<message-destination-type>
javax.jms.Topic
</message-destination-type>
<activation-config>
<activation-config-property>
<activation-config-property-name>
destinationType
</activation-config-property-name>
<activation-config-property-value>
javax.jms.Topic
</activation-config-property-value>
</activation-config-property>
</activation-config>
</message-driven>
<message-driven>
<ejb-name>TextMessageBean2</ejb-name>
<ejb-class>
sample.mdb.TextMessageBean2
</ejb-class>
<messaging-type>
javax.jms.MessageListener
</messaging-type>
<transaction-type>Bean</transaction-type>
<message-destination-type>
javax.jms.Topic
</message-destination-type>
<activation-config>
<activation-config-property>
<activation-config-property-name>
destinationType
</activation-config-property-name>
<activation-config-property-value>
javax.jms.Topic
</activation-config-property-value>
</activation-config-property>
</activation-config>
</message-driven>
</enterprise-beans>
</ejb-jar>
The ejb-jar.xml declares the two MDBs sample.mdb.TextMessageBean1 and sample.mdb.TextMessageBean2 both listen to a javax.jms.Topic destination.
openejb-jar.xml
<?xml version="1.0" encoding="UTF-8"?>
<openejb-jar xmlns="http://openejb.apache.org/xml/ns/openejb-jar-2.2"
xmlns:nam="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>Sample</sys:groupId>
<sys:artifactId>MDB-EJB</sys:artifactId>
<sys:version>1.0</sys:version>
<sys:type>car</sys:type>
</sys:moduleId>
</sys:environment>
<enterprise-beans>
<message-driven>
<ejb-name>
TextMessageBean1
</ejb-name>
<nam:resource-adapter>
<nam:resource-link>
TradeJMSResources
</nam:resource-link>
</nam:resource-adapter>
<activation-config>
<activation-config-property>
<activation-config-property-name>
destination
</activation-config-property-name>
<activation-config-property-value>
TextMessageTopic
</activation-config-property-value>
</activation-config-property>
<activation-config-property>
<activation-config-property-name>
destinationType
</activation-config-property-name>
<activation-config-property-value>
javax.jms.Topic</activation-config-property-value>
</activation-config-property>
</activation-config>
</message-driven>
<message-driven>
<ejb-name>TextMessageBean2</ejb-name>
<nam:resource-adapter>
<nam:resource-link>
TradeJMSResources
</nam:resource-link>
</nam:resource-adapter>
<activation-config>
<activation-config-property>
<activation-config-property-name>
destination
</activation-config-property-name>
<activation-config-property-value>
TextMessageTopic
</activation-config-property-value>
</activation-config-property>
<activation-config-property>
<activation-config-property-name>
destinationType
</activation-config-property-name>
<activation-config-property-value>
javax.jms.Topic
</activation-config-property-value>
</activation-config-property>
</activation-config>
</message-driven>
</enterprise-beans>
</openejb-jar>
In the deployment plan openejb-jar.xml, the two MDBs are configured as end point listeners for the jms topic TextMessageTopic.
The code for the two MDBs are as follows.
TextMessageBean1.java
package sample.mdb;
import javax.jms.JMSException;
import javax.jms.Message;
import javax.jms.TextMessage;
public class TextMessageBean1 {
public TextMessageBean1() {
}
public void onMessage(Message msg) {
if (msg instanceof TextMessage) {
TextMessage tm = (TextMessage) msg;
try {
String text = tm.getText();
System.out.println("Received new message
in TextMessageBean1 : "
+ text);
System.out.println("CustomerId : " +
tm.getIntProperty("CustomerId"));
System.out.println("CustomerName : " +
tm.getStringProperty("CustomerName"));
} catch (JMSException e) {
e.printStackTrace();
}
}
}
}
TextMessageBean2.java
package sample.mdb;
import javax.jms.JMSException;
import javax.jms.Message;
import javax.jms.TextMessage;
public class TextMessageBean2 {
public TextMessageBean2() {
}
public void onMessage(Message msg) {
if (msg instanceof TextMessage) {
TextMessage tm = (TextMessage) msg;
try {
String text = tm.getText();
System.out.println("Received new message
in TextMessageBean2 : "
+ text);
System.out.println("CustomerId : " +
tm.getIntProperty("CustomerId"));
System.out.println("CustomerName : " +
tm.getStringProperty("CustomerName"));
} catch (JMSException e) {
e.printStackTrace();
}
}
}
}
After receiving the message, the MDBs just print the contents of the message.
The web client for the application is as follows.
web.xml
<?xml version="1.0" encoding="UTF-8"?>
<web-app
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
id="WebApp_ID" version="2.5">
<display-name>MDBSampleWEB</display-name>
<welcome-file-list>
<welcome-file>index.html</welcome-file>
<welcome-file>index.htm</welcome-file>
<welcome-file>index.jsp</welcome-file>
</welcome-file-list>
<servlet>
<description></description>
<display-name>Test</display-name>
<servlet-name>Test</servlet-name>
<servlet-class>sample.mdb.Test</servlet-class>
</servlet>
<resource-ref>
<description>jms broker</description>
<res-ref-name>jms/broker</res-ref-name>
<res-type>
javax.jms.TopicConnectionFactory
</res-type>
<res-auth>Container</res-auth>
</resource-ref>
<resource-env-ref>
<description>Predefined Topic</description>
<resource-env-ref-name>
jms/Topic/TextTopic
</resource-env-ref-name>
<resource-env-ref-type>
javax.jms.Topic</resource-env-ref-type>
</resource-env-ref>
<servlet-mapping>
<servlet-name>Test</servlet-name>
<url-pattern>/Test</url-pattern>
</servlet-mapping>
</web-app>
The web client declares the javax.jms.TopicConnectionFactory and the topic to which the servlet has to publish the message. The names declared here are mapped to actual resources in the geronimo-web.xml as follows.
geronimo-web.xml
<?xml version="1.0" encoding="UTF-8"?>
<web-app
xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-2.0.1"
xmlns:nam="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>sample</sys:groupId>
<sys:artifactId>MDB-Web</sys:artifactId>
<sys:version>1.0</sys:version>
<sys:type>car</sys:type>
</sys:moduleId>
</sys:environment>
<context-root>/MDBSampleWEB</context-root>
<nam:resource-ref>
<nam:ref-name>
jms/broker</nam:ref-name>
<nam:resource-link>
jms/TopicConnectionFactory
</nam:resource-link>
</nam:resource-ref>
<nam:resource-env-ref>
<nam:ref-name>
jms/Topic/TextTopic
</nam:ref-name>
<nam:message-destination-link>
TextMessageTopic
</nam:message-destination-link>
</nam:resource-env-ref>
</web-app>
Please note that the jms/TopicConnectionFactory and jms/Topic/TextTopic are the names of the actual connection factory and jms topic. These are deployed by a jms resource plan embedded in the EAR's deployment plan as follows.
application.xml
<?xml version="1.0" encoding="ASCII"?>
<application
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns=http://java.sun.com/xml/ns/javaee
xmlns:app="http://java.sun.com/xml/ns/javaee/application_5.xsd"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/application_5.xsd"
version="5">
<display-name>MDBSampleEAR</display-name>
<module>
<ejb>MDBSampleEJB.jar</ejb>
</module>
<module>
<web>
<web-uri>MDBSampleWEB.war</web-uri>
<context-root>MDBSampleWEB</context-root>
</web>
</module>
</application>
geronimo-application.xml
<?xml version="1.0" encoding="UTF-8"?>
<application
xmlns="http://geronimo.apache.org/xml/ns/j2ee/application-2.0"
xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.2"
application-name="MDBSampleEAR">
<sys:environment>
<sys:moduleId>
<sys:groupId>default</sys:groupId>
<sys:artifactId>MDBSampleEAR</sys:artifactId>
<sys:version>1.0</sys:version>
<sys:type>car</sys:type>
</sys:moduleId>
</sys:environment>
<ext-module>
<connector>TopicJMSSample</connector>
<external-path>
<sys:groupId>
org.apache.geronimo.modules
</sys:groupId>
<sys:artifactId>
geronimo-activemq-ra
</sys:artifactId>
<sys:version>2.1</sys:version>
</external-path>
<connector
xmlns="http://geronimo.apache.org/xml/ns/j2ee/connector-1.2">
<resourceadapter>
<!--how to connect to the JMS Server-->
<resourceadapter-instance>
<resourceadapter-name>
TradeJMSResources
</resourceadapter-name>
<config-property-setting name="ServerUrl">
tcp://localhost:61616
</config-property-setting>
<config-property-setting name="UserName">
not needed
</config-property-setting>
<config-property-setting name="Password">
not needed
</config-property-setting>
<workmanager>
<gbean-link>DefaultWorkManager</gbean-link>
</workmanager>
</resourceadapter-instance>
<!--defines a ConnectionFactory-->
<outbound-resourceadapter>
<connection-definition>
<connectionfactory-interface>
javax.jms.ConnectionFactory
</connectionfactory-interface>
<connectiondefinition-instance>
<name>jms/TopicConnectionFactory</name>
<implemented-interface>
javax.jms.TopicConnectionFactory
</implemented-interface>
<connectionmanager>
<xa-transaction>
<transaction-caching/>
</xa-transaction>
<single-pool>
<max-size>10</max-size>
<min-size>0</min-size>
<blocking-timeout-milliseconds>
5000
</blocking-timeout-milliseconds>
<idle-timeout-minutes>0</idle-timeout-minutes>
<match-one/>
</single-pool>
</connectionmanager>
</connectiondefinition-instance>
</connection-definition>
</outbound-resourceadapter>
</resourceadapter>
<adminobject>
<adminobject-interface>
javax.jms.Topic</adminobject-interface>
<adminobject-class>
org.activemq.message.ActiveMQTopic
</adminobject-class>
<adminobject-instance>
<message-destination-name>
TextMessageTopic
</message-destination-name>
<config-property-setting name="PhysicalName">
TextMessageTopic
</config-property-setting>
</adminobject-instance>
</adminobject>
</connector>
</ext-module>
</application>
The plan for resource adapter is provided under <ext-module> xml elements. Also, the resource adapter archive (rar) file to be used to deploy the plan is mentioned using external-path xml element; the resource adapter plan follows these elements. The plan deploys{{ jms/TopicConnectionFactory}} and TextTopic.
The reference to resource archive file is provided using the following xml elements in the above plan.
Referencing Libraries
<external-path>
<sys:groupId>
org.apache.geronimo.modules
</sys:groupId>
<sys:artifactId>
geronimo-activemq-ra
</sys:artifactId>
<sys:version>2.1</sys:version>
</external-path>
The above pattern is the way how geronimo references various libraries available in the server repository. Any external libraries can also be uploaded to server repository using admin console portlet. After starting the server, click on Console Navigation => Services => Repository to display Repository Viewer portlet. In this portlet, users can upload required third party libraries by providing proper groupId, artifactId and version values for the libraries being uploaded. The activeMQ rar file is also available in the repository as org.apache.geronimo.modules/geronimo-activemq-ra/2.1/rar. Click on this link to get the usage instructions on how to reference this library in other modules.
The web client that look up the connection factory and topic and sends messages is as follows.
Test.java
package sample.mdb;
import java.io.IOException;
import java.io.PrintWriter;
import javax.jms.DeliveryMode;
import javax.jms.Session;
import javax.jms.TextMessage;
import javax.jms.Topic;
import javax.jms.TopicConnection;
import javax.jms.TopicConnectionFactory;
import javax.jms.TopicPublisher;
import javax.jms.TopicSession;
import javax.naming.InitialContext;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.jms.Connection;
public class Test extends
javax.servlet.http.HttpServlet
implements javax.servlet.Servlet {
static final long serialVersionUID = 1L;
private TopicConnection connection;
private Topic topic;
public Test() {
super();
}
public void init()
throws ServletException {
String connectionFactoryName = "java:comp/env/jms/broker";
String topicName = "java:comp/env/jms/Topic/TextTopic";
try {
InitialContext naming = new InitialContext();
TopicConnectionFactory connectionFactory =
(TopicConnectionFactory)
naming.lookup(connectionFactoryName);
connection =
connectionFactory.createTopicConnection();
topic = (Topic) naming.lookup(topicName);
}catch(Exception e) {
e.printStackTrace();
throw new ServletException(e);
}
}
public void doGet(HttpServletRequest request,
HttpServletResponse response)
throws ServletException, IOException {
TopicSession publishSession = null;
PrintWriter out = response.getWriter();
try {
boolean transacted = false;
publishSession =
connection.createTopicSession(transacted,
Session.AUTO_ACKNOWLEDGE);
TopicPublisher sender =
publishSession.createPublisher(topic);
sender.setDeliveryMode(DeliveryMode.PERSISTENT);
TextMessage message =
publishSession.createTextMessage("Customer Info");
message.setIntProperty("CustomerId",
Integer.parseInt(request.getParameter("CustomerId")));
message.setStringProperty("CustomerName",
request.getParameter("CustomerName"));
sender.send(message);
out.println("Message is successfully sent...!!");
}
catch(Exception e) {
throw new ServletException(e);
}
finally {
try {
if (publishSession != null) {
publishSession.close();
}
}
catch (Exception e) {}
}
}
protected void doPost(HttpServletRequest request,
HttpServletResponse response)
throws ServletException, IOException {
}
public void destroy() {
if (connection != null) {
try {
if (connection != null) {
connection.close();
}
}
catch (Exception e) { }
}
}
}
When the above servlet is accessed on a browser window as http://localhost:8080/MDBSampleWEB/Test?CustomerId=10&CustomerName=Phani, the following output is displayed in the server console.
-------------------------------------------
Received new message in TextMessageBean1 : Customer Info
CustomerId : 10
CustomerName : Phani
-------------------------------------------
-------------------------------------------
Received new message in TextMessageBean2 : Customer Info
CustomerId : 10
CustomerName : Phani
-------------------------------------------