THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
An enterprise application archive (EAR) can consist of several application modules. The application modules can be several web application archives (WAR) , EJB modules (JAR), application client modules (JAR) or resource archive modules (RAR). User can either deploy these modules individually or bundle them into a single EAR file and deploy that file.
When deployed individually, each application module should accompany a Geronimo deployment plan to map declared resources names, ejb names, security roles, JMS roles (if any) to actual resources in the server. The Geronimo deployment plans also contain any Geronimo specific settings and configurations. When deployed as a single bundle (EAR), user can create a single Geronimo deployment plan accomplish to perform all the mappings/settings and configurations.
The following table summarizes different JEE5 modules and corresponding Geronimo deployment plans accompany them.
JEE module |
JEE deployment descriptor (DD) |
Geronimo deployment plan |
|---|---|---|
web application archive (WAR) |
|
|
EJB application archive (JAR) |
|
|
resource adapter archive (RAR) |
|
|
enterprise application archive (EAR) |
|
|
enterprise application client archive (JAR) |
|
JEE Application Client deployment plan
JEE application client modules run in client container and also have access to server environment. Usually, JEE client applications are created to administer the running enterprise applications in the server. Client modules run in a separate JVM and connect to enterprise application resources but have access to all the application resources in standard JEE way.
The JEE client module requires application-client.xml as deployment descriptor and geronimo-application-client.xml as deployment plan. In the application-client.xml, the required ejb names, security role names, resources names etc., are declared while in geronimo-application-client.xml, the declared names are mapped to actual resources in server.
The following is the deployment descriptor of the JEE application client module that looks up an ejb and calls a method on it. The ejb converts the Indian Rupess (Rs.) into American Dollars ($). The client sends a double value which is Indian Rupees to ejb. The ejb returns equivalent American Dollars as double value.
application-client.xml
<?xml version="1.0" encoding="UTF-8"?>
<application-client xmlns="http://java.sun.com/xml/ns/javaee"
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/application-client_5.xsd"
version="5">
<ejb-ref>
<ejb-ref-name>ejb/Converter</ejb-ref-name>
<ejb-ref-type>Session</ejb-ref-type>
<remote>examples.appclient.Converter</remote>
</ejb-ref>
</application-client>
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. Hence, in the above XML document, all the XML elements belong to the default namespace.
The application client declares the ejb name ejb/Converter through <ejb-ref>> .. </ejb-ref> elements.
Following is the corresponding deployment plan of the JEE client module.
geronimo-application-client.xml
<?xml version="1.0" encoding="UTF-8"?>
<application-client xmlns="http://geronimo.apache.org/xml/ns/j2ee/application-client-2.0"
xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.2"
xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.2"
xmlns:security="http://geronimo.apache.org/xml/ns/security-2.0"
xmlns:connector="http://geronimo.apache.org/xml/ns/j2ee/connector-1.2">
<sys:client-environment>
<sys:moduleId>
<sys:groupId>Converter</sys:groupId>
<sys:artifactId>Converter-app-client</sys:artifactId>
<sys:version>3.0</sys:version>
<sys:type>jar</sys:type>
</sys:moduleId>
</sys:client-environment>
<sys:server-environment>
<sys:moduleId>
<sys:groupId>Converter</sys:groupId>
<sys:artifactId>Converter-app-client-server</sys:artifactId>
<sys:version>3.0</sys:version>
<sys:type>jar</sys:type>
</sys:moduleId>
</sys:server-environment>
<ejb-ref>
<ref-name>ejb/Converter</ref-name>
<naming:pattern>
<naming:groupId>Converter</naming:groupId>
<naming:artifactId>ConverterEAR</naming:artifactId>
<naming:version>5.0</naming:version>
<naming:module>ConverterEJB.jar</naming:module>
<naming:name>ConverterBean</naming:name>
</naming:pattern>
</ejb-ref>
</application-client>
The default namespace of the above XML document is http://geronimo.apache.org/xml/ns/j2ee/application-client-2.0. The XML elements that do not have a namespace prefix belong to the default namespace. Hence, in the above XML document, <application-client>, <ejb-ref> and <ref-name> elements belong to the default namespace.
Observe the various xml elements and schemas to which they belong. The plan defines the client environment and the server environment configurations. The server environment configuration runs in the server where as the client environment configuration runs in the client JVM. In the above plan, the ejb name ejb/Converter is mapped to ConverterBean ejb in the ConverterEAR.
The below is the client code that looks up the ejb and calls the method on it.
ConverterClient.java
package examples.appclient.client;
import javax.naming.Context;
import javax.naming.InitialContext;
import examples.appclient.Converter;
public class ConverterClient {
//The remote interface of the ConverterBean packaged with the
//JEE client jar
private static Converter converter;
private static double amount = 50;
public static void main(String[] args) {
amount = Double.parseDouble(args[0]);
doConversion();
}
public static void doConversion() {
try {
Context context = new InitialContext();
converter = (Converter)
context.lookup("java:comp/env/ejb/Converter");
double dollars = converter.getDollars(amount);
System.out.println("Rs " + amount + " is " + dollars + " Dollars.");
System.exit(0);
} catch (Exception ex) {
System.err.println("Caught an unexpected exception!");
ex.printStackTrace();
}
}
}
The META-INF/MANIFEST.MF file should contain the following entry for the client to run.
MANIFEST.MF
Manifest-Version: 1.0 Main-Class: examples.appclient.client.ConverterClient
Do not forget to insert a new line after the Main-Class: entry in the MANIFEST.MF file.
The JEE client is created by packaging META-INF/application-client.xml, META-INF/geronimo-application-client.xml, ConverterClient.class, Converter.class and META-INF/MANIFEST.MF files into a jar file.
The following command illustrates the packaging.
C:\temp\ConverterEJBClient>jar -cvf ConverterEJBClient.jar *
added manifest
adding: examples/(in = 0) (out= 0)(stored 0%)
adding: examples/appclient/(in = 0) (out= 0)(stored 0%)
adding: examples/appclient/client/(in = 0) (out= 0)(stored 0%)
adding: examples/appclient/client/ConverterClient.class(in = 1716) (out= 936)(deflated 45%)
adding: examples/appclient/Converter.class(in = 146) (out= 131)(deflated 10%)
adding: META-INF/application-client.xml(in = 510) (out= 252)(deflated 50%)
adding: META-INF/geronimo-application-client.xml(in = 2049) (out= 474)(deflated 76%)
ignoring entry META-INF/MANIFEST.MF
The following commands illustrates the deployment and running of the client module.
C:\\Geronimo-2.1\bin>deploy.bat --user system --password manager deploy C:\temp\ConverterEJBClient.jar
Using GERONIMO_BASE: C:\Geronimo-2.1
Using GERONIMO_HOME: C:\Geronimo-2.1
Using GERONIMO_TMPDIR: var\temp
Using JRE_HOME: C:\JDK\jre
Deployed Converter/Converter-app-client-server/3.0/jar
C:\Geronimo-2.1\bin>java -Djava.endorsed.dirs="C:\Geronimo-2.1\lib\endorsed" -jar
C:\Geronimo-2.1\bin\client.jar Converter/Converter-app-client/3.0/jar 4000
Rs 4000.0 is 100.0 Dollars.
Message Driven Bean deployment plan.
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
-------------------------------------------