|
|
| Home > Apache Geronimo v1.0 > Documentation > Apache Geronimo v1.0 - User's Guide > Migrating to Apache Geronimo > JBoss to Geronimo - EJB-MDB Migration |
Before looking at Message Driven Beans (MDBs) a brief overview of the Java Messaging Service (JMS) API is in order. JMS is a way for applications to send and receive messages.
There are three distinct components in JMS:
For more details on the JMS API see the JCP Specification at the following URL:
http://jcp.org/aboutJava/communityprocess/final/jsr914/index.html
MDBs are different from other Enterprise JavaBeans because clients/users of MDBs, typically do not interact directly with MDBs. Instead they send messages to a JMS Destination and, if the MDB is a registered listener of this destination, the MDB recieves the message and acts accordingly.
This article is organized in the following sections:
EJB implementations may vary from one vendor to another. The purpose of this section is to provide an EJB specific feature-to-feature comparison between JBoss v4 and Apache Geronimo so you can clearly identify the differences and plan accordingly before migration.
Given that MDBs are dependent on parts of the Java Messaging Service API (JMS), there will be an overlap of some JMS features when comparing the platform specific MDB features.
| Features | JBoss v4 | Apache Geronimo |
|---|---|---|
| EJB Container | JBoss AS 4.0 comes with its own EJB Container implementation. | Geronimo uses OpenEJB as its EJB Container. |
| JMS implementation | JBoss AS 4.0 is packaged with JBoss MQ. | Geronimo uses ActiveMQ as its JMS implementation. |
The MDB Sample Application
creates an Entity Bean from the information stored in the messages that it recieves. There is also a sample "client" that sends messages to a destination. This sample application implements javax.ejb.MessageDrivenBean and javax.jms.MessageListener. All of the work is done in the onMessage method, which is called by the container when a message is received.
The following figure illustrates the application flow:
The user accesses the command line client and is prompted for the appropriate information. The information is then packaged into a JMS message and sent to a JMS destination. The Message Driven Bean then recieves messages that are sent to the JMS Destination that it is configured to listen to and creates an entity bean based on the information from the message. The entity bean then adds it's information to the data souce.
The MDB application consists of the following packages:
The MDB sample application also provides a Web Application client messaging-ejb.war. This application client allows you to create (create.jsp) and list (list.jsp) customers.
The tools used for developing and building all the applications are:
The Eclipse with JBoss IDE plug-ins was used for development of Java-source code of the sample applications. Eclipse is a very powerful and popular open source development tool. Eclipse can be downloaded from the following URL:
Maven is a software project management and comprehension tool. Based on the concept of a project object model (POM). Maven can manage a project's build, reporting and documentation from a central piece of information.
For this migration example Maven 1.0.2 was used. Maven can be downloaded from the followinf URL:
The sample database for the MDB sample application has only one table. This is an in-memory table. The MEMORY storage engine creates tables with contents that are stored in just in memory. These were formerly known as HEAP tables.
The following table describes the fields of the CUSTOMER table.
| Field | data type |
|---|---|
| id | INTEGER |
| name | VARCHAR(45) |
| birthdate | DATE |
| sss_no | VARCHAR(25) |
| address | VARCHAR(60) |
| annual_salary | DOUBLE |
| loan_amount | DOUBLE |
This section shows you how and where the sample JBoss reference environment was installed so you can map this scenario to your own implementation. Note that for this migration example JBoss v4.0.2 was used.
Detailed instructions for installing, configuring, and managing JBoss are provided in the product documentation. Check the product Web site for the most updated documents.
The following list highlights the general tasks you will need to complete to install and configure the initial environment as the starting point for deploying the sample application.
. You should see the JBoss Welcome window and be able to access the JBoss console.In order to build and run the Loan BMP application included in this article, you need to install and configure the build tool and the database that is used by the application.
This application is using the HSQL database that comes as part of the JBoss bundle. You need to modify the script for creating the database. Edit the localDB.script file located in the following directory:
<jboss_home>\server\<your_server_name>\data\hypersonic
Add at the top of the localDB.script file the content of the following example in order to create the sample HSQL database.
 | Make sure JBoss is not running at the time of modifying this file. |
CREATE MEMORY TABLE CUSTOMER(ID INTEGER NOT NULL PRIMARY KEY,NAME VARCHAR(45),BIRTHDATE DATE,SSS_NO VARCHAR(25),ADDRESS VARCHAR(60),ANNUAL_SALARY DOUBLE,LOAN_AMOUNT DOUBLE)
As mentioned before, Apache Maven is used to build the binaries for the Loan BMP application. If you do not have Maven installed this is a good time for doing it.
Apache Maven can be downloaded from the following URL:
In order to build the MDB application a Maven script has been provided. Download the MDB sample application from the following link:
After extracting the zip file, a mdb directory will be created. From now on, this directory will be referred as <mdb_home>. In that directory open the project.properties file. Edit the maven.jboss.home property to match your environment.
maven.multiproject.type=ejb maven.ejb.src=dd maven.jboss.home=<jboss_home>
From a command prompt or shell go to the <bmp_home> directory and run the following command:
maven
This will build the jar file and put it in the <bmp_home>/target folder. The jar created by the Maven build contains a JBoss specific deployment descriptor, the jboss.xml file in located the META-INF directory of the JAR is shown in the following example:
<?xml version='1.0' encoding='UTF-8' ?> <jboss> <enterprise-beans> <entity> <ejb-name>CustomerEJB</ejb-name> <jndi-name>CustomerHomeRemote</jndi-name> <resource-ref> <res-ref-name>jdbc/ibm-demo</res-ref-name> <jndi-name>java:/DefaultDS</jndi-name> </resource-ref> </entity> <message-driven> <ejb-name>SampleMDB</ejb-name> <destination-jndi-name>queue/testQueue</destination-jndi-name> <ejb-ref> <ejb-ref-name>CustomerHomeRemote</ejb-ref-name> <jndi-name>CustomerHomeRemote</jndi-name> </ejb-ref> </message-driven> </enterprise-beans> </jboss>
The resource-ref element is used to map the resource referred to by the name jdbc/ibm-demo in the ejb-jar.xml file to the resource with the JNDI name java:/DefaultDS and also the CustomerHomeRemote name in ejb-jar.xml to the JNDI name CustomerHomeRemote (The Customer EJB).
To deploy the Loan BMP application in JBoss, copy the messaging-ejb-SNAPSHOT.jar and messaging-ejb.war files from the <mdb_home>/target directory to the following directory:
<jboss_home>\server\<your_server_name>\deploy
If JBoss is already started, it will automatically deploy and start the applications; otherwise, the applications will be deployed and started at the next startup.
To test this sample application you can use the command line client or a Web Application client also provided with the sample application download.
To test the sample client application type the following command from the <mdb_home>/target/classes directory:
java -cp ".;<jboss_home>\client\jbossall-client.jar" com.ibm.demo.mdb.client.MessageSenderJBoss
The user will then be prompted for information to populate the message as in the following example:
E:\mdb\target\classes>java -cp ".;e:\jboss-4.0.2\client\jbossall-client.jar" com.ibm.demo.mdb.client.MessageSenderJBoss
Enter information for new customer.
Enter customer id (Integer):10
Enter name:Hernan Cunico
Enter sss number:123456
Enter address:101 My Home
Enter birhtdate (mm/dd/yyyy):10/10/1980
Enter annual salary:1000000
Enter loan amount:10000
Enter the appropriate information the press enter. When you have filled up all of the fields the message will be sent.
Look in the JBoss console for the INFO: SUCCESS!!! message, this is the indication that the message was sent successfully.
20:21:39,637 INFO [STDOUT] Oct 26, 2005 8:21:39 PM com.ibm.demo.mdb.ejb.SampleMDB onMessage
INFO: Received TextMessage: add customer
20:21:39,647 INFO [STDOUT] XAConnectionFactory: org.jboss.mq.SpyXAConnectionFactory
20:21:39,647 INFO [STDOUT] UIL2ConnectionFactory: javax.naming.LinkRef
20:21:39,647 INFO [STDOUT] UserTransactionSessionFactory: $Proxy11
20:21:39,647 INFO [STDOUT] HTTPConnectionFactory: org.jboss.mq.SpyConnectionFactory
20:21:39,647 INFO [STDOUT] console: org.jnp.interfaces.NamingContext
20:21:39,647 INFO [STDOUT] UIL2XAConnectionFactory: javax.naming.LinkRef
20:21:39,647 INFO [STDOUT] UUIDKeyGeneratorFactory: org.jboss.ejb.plugins.keygenerator.uuid.UUIDKeyGeneratorFactory
20:21:39,647 INFO [STDOUT] HTTPXAConnectionFactory: org.jboss.mq.SpyXAConnectionFactory
20:21:39,647 INFO [STDOUT] topic: org.jnp.interfaces.NamingContext
20:21:39,647 INFO [STDOUT] CustomerHomeRemote: $Proxy52
20:21:39,647 INFO [STDOUT] queue: org.jnp.interfaces.NamingContext
20:21:39,647 INFO [STDOUT] ConnectionFactory: org.jboss.mq.SpyConnectionFactory
20:21:39,647 INFO [STDOUT] UserTransaction: org.jboss.tm.usertx.client.ClientUserTransaction
20:21:39,647 INFO [STDOUT] jmx: org.jnp.interfaces.NamingContext
20:21:39,647 INFO [STDOUT] HiLoKeyGeneratorFactory: org.jboss.ejb.plugins.keygenerator.hilo.HiLoKeyGeneratorFactory
20:21:39,647 INFO [STDOUT] UILXAConnectionFactory: javax.naming.LinkRef
20:21:39,647 INFO [STDOUT] UILConnectionFactory: javax.naming.LinkRef
20:21:39,707 INFO [STDOUT] Oct 26, 2005 8:21:39 PM com.ibm.demo.mdb.ejb.SampleMDB onMessage
INFO: SUCCESS!!!
To test the Web application client open a Web browser and access the following URL:
http://localhost:8080/messaging-ejb
If you tested via the command line before you should be able to see the entries you just entered.
From this Web Application client you can also enter new customers. Click on Add Customer to call the create.jsp, the following page will prompt you to enter the new customer info.
Enter the new customer information then click Create. This will take you back to the first page and show you the updated list of customers.
Download and install Geronimo from the following URL:
http://geronimo.apache.org/downloads.html
The release notes available there provide clear instructions on system requirements and how to install and start Geronimo. Throughout the rest of this article we will refer to the Geronimo installation directory as <geronimo_home>.
 | TCP/IP ports conflict If you are planning to run JBoss and Geronimo on the same machine consider to change the default service ports on, at least, one of these servers. |
For this scenario the MDB application will use directly the SystemDatabase from Geronimo. In this case there is no need to set up a new connector for the SystemDatabase since it is already configured as the DefaultDatasource.
Ensure that Geronimo is up and running. If the server has not been started yet, do so by typing the following command:
<geronimo_home>/bin/startup.sh
Once the server is started you should see a screen similar as the one illustrated in the following example:
E:\geronimo\bin>startup
Booting Geronimo Kernel (in Java 1.4.2_09)...
Starting Geronimo Application Server
[*************] 100% 32s Startup complete
Listening on Ports:
1099 0.0.0.0 RMI Naming
1527 0.0.0.0 Derby Connector
4201 0.0.0.0 ActiveIO Connector EJB
4242 0.0.0.0 Remote Login Listener
8019 0.0.0.0 Tomcat Connector AJP
8080 0.0.0.0 Jetty Connector HTTP
8090 0.0.0.0 Tomcat Connector HTTP
8443 0.0.0.0 Jetty Connector HTTPS
8453 0.0.0.0 Tomcat Connector HTTPS
61616 0.0.0.0 ActiveMQ Message Broker Connector
Started Application Modules:
EAR: org/apache/geronimo/Console
WAR: org/apache/geronimo/applications/Welcome
Web Applications:
http://hcunico:8080/
http://hcunico:8080/console
http://hcunico:8080/console-standard
Geronimo Application Server started
Access the Geronimo Console by pointing your Web browser to the following URL:
Enter system as the username and manager as the password, click Login.
Once logged in, on the bottom left corner from the left navigation panel click on DB Manager. In the text area labeled SQL Command/s enter the following SQL statement and click Run SQL; this will create the table used by the Entity Bean.
CREATE TABLE CUSTOMER(ID INTEGER NOT NULL PRIMARY KEY,NAME VARCHAR(45),BIRTHDATE DATE,SSS_NO VARCHAR(25),ADDRESS VARCHAR(60),ANNUAL_SALARY DOUBLE,LOAN_AMOUNT DOUBLE)
In this migration example application, the same jar file you deployed in JBoss can also be deployed in Geronimo. This is because the build step packaged both the JBoss jboss.xml and Geronimo openejb-jar.xml specific deployment plans in the jar file.
You can see both of these files in the META-INF folder of the jar file or in the <mdb_home>/dd/META-INF directory. The openejb-jar.xml should look like the following example:
<openejb-jar
xmlns="http://www.openejb.org/xml/ns/openejb-jar"
xmlns:naming="http://geronimo.apache.org/xml/ns/naming"
xmlns:security="http://geronimo.apache.org/xml/ns/security"
xmlns:sys="http://geronimo.apache.org/xml/ns/deployment"
configId="MDBDemo" parentId="org/apache/geronimo/SystemJMS">
<enterprise-beans>
<message-driven>
<ejb-name>SampleMDB</ejb-name>
<resource-adapter>
<target-name>geronimo.server:J2EEApplication=null,J2EEServer=geronimo,
JCAResource=org/apache/geronimo/SystemJMS,j2eeType=JCAResourceAdapter,
name=ActiveMQ RA</target-name>
</resource-adapter>
<activation-config>
<activation-config-property>
<activation-config-property-name>destination</activation-config-property-name>
<activation-config-property-value>SendReceiveQueue</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.Queue</activation-config-property-value>
</activation-config-property>
</activation-config>
<ejb-ref>
<ref-name>CustomerHomeRemote</ref-name>
<ejb-link>CustomerEJB</ejb-link>
</ejb-ref>
</message-driven>
<entity>
<ejb-name>CustomerEJB</ejb-name>
<jndi-name>CustomerHomeRemote</jndi-name>
<local-jndi-name></local-jndi-name>
<resource-ref>
<ref-name>jdbc/ibm-demo</ref-name>
<resource-link>SystemDatasource</resource-link>
</resource-ref>
</entity>
</enterprise-beans>
</openejb-jar>
As shown in the example, the parent for this configuration is the org/apache/geronimo/SystemJMS connector. Then follows the definition of the EJBs.
The message-driver element defines the message driven bean. The child element resource-adapter/target-name specifies the Gbean name of the resource adapter that will be used to connect to JMS. The activation-config element and its children define the Queue that the MDB will listen to. Here it is used the SendReceiveQueue that is deployed in Geronimo by default. The ejb-ref element and its children define the EJBs that the MDB will access.
The entity element defines an entity bean. The resource ref element defines the datasource that this EJB will be using.
The Web Application client can also be direclty deployed in Geronimo. This is because the build step packages both the JBoss jboss-web.xml and Geronimo geronimo-web.xml specific deployment plans in the war file. You can see both of these files in the <mdb_home>\src\webapp\WEB-INF directory.
The geronimo-web.xml deployment plan should look like the following example.
<web-app xmlns="http://geronimo.apache.org/xml/ns/web" xmlns:naming="http://geronimo.apache.org/xml/ns/naming" configId="MDBDemoWebApp" parentId="MDBDemo"> <context-root>messaging-ejb</context-root> <ejb-ref> <ref-name>ejb/CustomerHome</ref-name> <target-name> geronimo.server:EJBModule=MDBDemo,J2EEApplication=null, J2EEServer=geronimo,j2eeType=EntityBean,name=CustomerEJB </target-name> </ejb-ref> <resource-ref> <ref-name>jms/broker</ref-name> <resource-link>DefaultActiveMQConnectionFactory</resource-link> </resource-ref> <resource-env-ref> <ref-name>jms/queue/DefQueue</ref-name> <message-destination-link>SendReceiveQueue</message-destination-link> </resource-env-ref> </web-app>
Ensure that Geronimo server is up and running. From a command line change directory to <geronimo_home>/bin and type the following command:
java -jar deployer.jar --user system --password manager deploy <mdb_home>/target/messaging-ejb-SNAPSHOT.jar
To deploy the sample Web Application client type the following command:
java -jar deployer.jar --user system --password manager deploy <mdb_home>/target/messaging-ejb.war
Once the application is deployed, you can test it by running the application client from a command line or using the sample Web Application client just like you tested the application in JBoss.
From a command line change directory to the <mdb_home>/target/classes directory and type the following command:
java -cp ".;<geronimo_home>/repository/activemq/jars/activemq-core-3.2-M1.jar;<geronimo_home>/repository/geronimo-spec/jars/geronimo-spec-j2ee-1.4-rc4.jar;<geronimo_home>/lib/commons-logging-1.0.4.jar;<geronimo_home>/repository/concurrent/jars/concurrent-1.3.4.jar" com.ibm.demo.mdb.client.MessageSenderAMQ
You will then be prompted for information to populate the message as in the following example. Enter the appropriate information the press Enter. When you have filled up all of the fields the message will be sent.
...
Oct 27, 2005 5:12:29 PM org.activemq.ActiveMQConnection statusChanged
INFO: channel status changed: Channel: TcpTransportChannel: Socket[addr=localhost/127.0.0.1,port=61616,localport=1176] has connected
Enter information for new customer.
Enter customer id (Integer):10
Enter name:Hernan Cunico
Enter sss number:123456789
Enter address:101 My Home
Enter birhtdate (mm/dd/yyyy):11/11/1999
Enter annual salary:1000000
Enter loan amount:10000
Message sent.
To verify that the data has been added to the database, from the DB Manager page on the Geronimo Consloe click on the Application link under View Tables section for the SystemDatabase . On the following page, click on View Contents for the Customer table. You should see something like the following figure.
Additionally, in the command line window/shell where you started Geronimo you should be able to see the confirmation that the message was sent.
...
Oct 27, 2005 5:13:03 PM com.ibm.demo.mdb.ejb.SampleMDB onMessage
INFO: Received TextMessage: add customer
JMXConnector: java.lang.Object
Oct 27, 2005 5:13:03 PM com.ibm.demo.mdb.ejb.SampleMDB onMessage
INFO: SUCCESS!!!
Open a Web browser and poit it to the following URL:
http://hcunico:8080/messaging-ejb
Repeat the same steps you did when testing on JBoss.
The sample application used for this migration exercise, while simple, provides you with detailed instructions on how to migrate an application that uses MDB from JBoss V4.0.2 to Apache Geronimo. The modifications to make this happen were restricted to the xml configuration files with no java code changes necessary.