JBoss to Geronimo - Hibernate Migration

Migrating to Apache Geronimo

JBoss to Geronimo - Security Migration

This article will help you migrate JDBC applications developed for JBoss v4.0.5 to Apache Geronimo v1.1 and is part of a series of migration articles covering different types of applications migration.

This article provides details on the JDBC implementation differences between these two application servers as well as a detailed step-by-step migration procedure for porting JDBC applications from JBoss v4.0.5 to Apache Geronimo. To define a common starting point (the source environment), this article provides steps for deploying the Online Brokerage sample application into the JBoss source environment. Then, you will be guided through the application migration and deployment process in Apache Geronimo.

This article is organized in the following sections:

• JDBC implementation analysis
• Sample application
• The JBoss environment
• The Geronimo environment
• Step-by-step migration
• Summary

JDBC implementation analysis

JDBC implementation may vary from one vendor to another. The purpose of this section is to provide a JDBC specific feature-to-feature comparison between JBoss and Apache Geronimo so you can clearly identify the differences and plan accordingly before migration.

Given that JBoss and Geronimo both use J2CA connectors for accessing JDBC resources, there will be an overlap of some J2CA features when comparing the platform specific JDBC features.

Sample application

This article contains a sample application to demonstrate the migration of an application from JBoss to Geronimo, called Online Brokerage. It represents an online trading scenario in which users can buy and sell stocks. The application has the following five pages:

• Login Page
• Registration Page
• User Information Page
• Available Stocks Page
• User Portfolio Page

The following figure illustrates the application flow:

First, the user accesses the Login page. From the Login page the user enters the username and password. If the username or password is not valid the application throws an error message and rejects the user's login attempt. If the username and password are correct, the user is taken to the Available Stocks page where he/she can view all the stocks that are present for sale at that time.

The user can choose to buy as many stocks as required, depending on the funds availabe in the account, by clicking the Buy button.

After the transaction completes successfully the user is brought back to the Available Stocks page where he/she can buy more stocks if required.

If the user has insufficient funds to buy stocks the application will throw an error and will not process the transaction. The error message is shown at the top of the Available Stocks page. There is a User Info button on this page. On clicking this button the user is taken to the User Info page and shown the user details.

From the Available Stocks page there is a View your Portfolio link that shows all the stocks that the user owns. In that page, the user can select the stocks and quantity to sell. This page also shows the user's available cash in the User Cash field. If the user tries to sell more stocks than he has, the application will throw an error. The error message will be shown on the same page. For each successful sale the sale amount is added to the user's cash balance.

The quantity text box shows the quantity of stocks of a particular company that the user has. The Quantity to Sell field allows the user to enter the quantity of stocks to sell for a specific company. For selling and buying the radio button should be checked. This should be done after entering the values. If either the quantity to sell textbox is not filled or the selection box is not checked and you press on sell, a JavaScript alert will be triggered saying that the required field is empty. On entering non numeric characters for quantity another alert will be triggered. This behavior is similar for the Available Stocks page as well.

New users can register by clicking the Register button in the login page. In the Registration page, the user will enter a user ID, user name, password, address and available cash.

Application classes and JSP pages

The Online Brokerage sample application consists of the following packages:

• org.apache.geronimo.samples.brokerage.bo
  • Stock- Represents the stock of a company.
  • User- Represents the user.
• org.apache.geronimo.samples.brokerage.dao
  • TradeDAO - Contains all the database access methods.
• org.apache.geronimo.samples.brokerage.exception
  • DBException - Custom exception class that is thrown for all database exceptions.
• org.apache.geronimo.samples.brokerage.web
  • TradeDispatcherServlet - Dispatches all the requests to the JSPs after performing required database functions.

The Online Brokerage also includes the following JSP pages:

• login.jsp - The login page of the application.
• error.jsp - The default error page of the application.
• register.jsp - The user registration page.
• stocks.jsp - The Available Stocks page from where the user can buy stocks.
• userstocks.jsp - The user portfolio page which shows the user's stocks. The user can sell stocks from this page.

Tools used

The tools used for developing and building the Online Brokerage application are:

Eclipse

The Eclipse IDE was used for development of the sample application. This is a very powerful and popular open source development tool. Integration plug-ins are available for both JBoss and Geronimo. Eclipse can be downloaded from the following URL:
http://www.eclipse.org

Apache Ant

Ant is a pure Java build tool. It is used for building the war files and populating the database for the Online Brokerage application. Ant can be downloaded from the following URL:
http://ant.apache.org

Sample database

The database used for demostrating this application is MySQL. The name of the sample database is tradedb and it consists of the following three tables; STOCKS, USERS and TRADINGACCOUNT. The fields for each of these tables are described below.

The TRADINGACCOUNT table is used to store the stocks that are owned by each user. The USERS and STOCKS tables are used to store the user and stock details. Because this is just a sample application the amount of money that a user has is entered during user registration by the user itself.

The DDL file used for populating this database is db.sql and it is located in the brokerage/config/sql directory.

Back to Top

The JBoss enviroment

This section shows you how and where the sample JBoss reference environment was installed so you can map this scenario to your own implementation.

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.

1. Download and install JBoss v4.0.5 as explained in the product documentation guides. From now on the installation directory will be referred as <jboss_home>.
2. Create a copy of the default JBoss v4.0.5 application server. Copy recursively <jboss_home>/server/default to <jboss_home>/server/<your_server_name>
3. Start the new server by running the run.sh -c <your_server_name> command from the <jboss_home>/bin directory.
4. Once the server is started, you can verify that it is running by opening a Web browser and pointing it to this URL: http://localhost:8080. You should see the JBoss Welcome window and be able to access the JBoss console.
5. Once the application server is up and running, the next step is to install and configure all the remaining prerequisite software required by the sample application. This step is described in the following section.

Install and configure prerequisite software

In order to build and run the Online Brokerage application included in this article, you need to install and configure the build tool and the database that is used by the application.

Install the database

As mentioned earlier in the article, this application is using the MySQL database and that can be downloaded from the following URL:
http://www.mysql.com
The installation and configuration of MySQL is fairly intuitive and it is well documented in the MySQL Reference Manual available at the following URL:

http://dev.mysql.com/doc/mysql/en

During the instance configuration I modified the security settings and specified "password" as the password for the root user. This user ID and password will later be used for accessing the database from the sample application.

Create sample database

Once the MySQL instance is configured you need to create the sample database that will be used by the Online Brokerage application. From command line, type the following command to start the MySQL monitor:

mysql -u root -p

Then enter your password to enter log in to the MySQL command interface as shown in the following example:

Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 15 to server version: 4.1.15-Debian_1ubuntu5-log

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

mysql>

From the MySQL command interface create the tradedb sample database by typing the following command:

mysql> create database tradedb;

Configure Ant

As mentioned before, Apache Ant is used to build the binaries for the Online Brokerage application. If you do not have Ant installed this is a good time for doing it and make sure that <ant_home>/bin directory is added to the system's path variable.

Apache Ant can be downloaded from the following URL:

http://ant.apache.org

Configure resources

In order to successfully build and deploy the Online Brokerage application and database, you will first need to configure some resources. This section describes how to configure a MySQL data source in JBoss.

Data source

The Online Brokerage application is a Web application that uses a data source to connect to the MySQL database. To use JBoss with MySQL you need to copy the MySQL driver into the JBoss server classpath. The driver, which is provided by the database vendor, is called Connector/J 3.0 and can be downloaded from the following URL:
http://dev.mysql.com/downloads/connector/j/3.0.html

After downloading and extracting the driver, copy the mysql-connector-java-3.0.17-ga-bin.jar file to the <jboss_home>/server/<your_server_name>/lib directory.

The data source configuration in JBoss is done through an XML configuration file. The JBoss installation contains sample configuration files for many popular databases including MySQL.

The sample data source configuration file for MySQL is mysql-ds.xml and it is located in the <jboss_home>/docs/examples/jca directory:

Copy the mysql-ds.xml file to the deploy directory of your JBoss server (<jboss_home>/server/<your_server_name>/deploy) and edit it as shown in the following example:

<?xml version="1.0" encoding="UTF-8"?>

<datasources>

  <local-tx-datasource>
        <jndi-name>jdbc/TradeDB</jndi-name>
        <connection-url>jdbc:mysql://localhost:3306/tradedb</connection-url>
        <driver-class>com.mysql.jdbc.Driver</driver-class>
        <user-name>root</user-name>
        <password></password>
        <exception-sorter-class-name>org.jboss.resource.adapter.jdbc.vendor.MySQLExceptionSorter</exception-sorter-class-name>        
  </local-tx-datasource>
</datasources>

Delete all the other tags inside the <local-tx-datasource> tag and save the file. JBoss will automatically deploy the data source.

Build the sample application

The Online Brokerage application included with this article provides an Ant script that you will use in order to build the application and populate the database. Download the Online Brokerage application from the following link:

Online Brokerage

After extracting the zip file, a brokerage directory is created. In that directory open the build.properties file and edit the properties to match your environment as shown in the following example:

## Set the Geronimo 1.1 home here
geronimo.home=<geronimo_home>

#Fully qualified name of the JDBC driver class
db.driver=com.mysql.jdbc.Driver

#database url
db.url=jdbc:mysql://localhost:3306/tradedb

#database userId
db.userid=root

#database password
db.password=password

##location of the jdbc driver jar.
driver.classpath=<jboss_home>/server/<your_server_name>/lib/mysql-connector-java-3.0.17-ga-bin.jar

When specifying the driver.classpath in the build.properties file, make sure to use just the forward slash "/" , otherwise the build will not find the jar file.

From a command prompt or shell go to the brokerage directory and run ant war-jboss. This will build the war file and place it directly in the brokerage directory. The war created by the ant build contains a JBoss specific deployment descriptor, the jboss-web.xml file in the WEB-INF directory of the WAR is shown in the following example.

<?xml version="1.0" encoding="UTF-8"?>
<jboss-web>
  <context-root>/brokerage</context-root>
  <resource-ref>
      <res-ref-name>jdbc/TradeDB</res-ref-name>
      <res-type>javax.sql.DataSource</res-type>
      <jndi-name>java:jdbc/TradeDB</jndi-name>
  </resource-ref>
</jboss-web>

The resource-ref element is used to map the resource referred to by the name jdbc/TradeDB in the web.xml file to the resource with the JNDI name java:jdbc/TradeDB i.e. the MySQL datasource.

Deploy the sample application

To deploy the sample application just copy the brokerage.war will be created under the brokerage/releases/jboss folder to the <jboss_home>/server/<your_server_name>/deploy folder.

If JBoss is already started, it will automatically deploy and start the application; otherwise, the application will be deployed and started at the next startup.

Test the sample application

To test the application, open a Web browser and access the following URL:

http://localhost:8080/brokerage

This brings up the login screen of the Online Brokerage application. Enter j2ee as the user name and password as the password and click on login. This takes you to the available stocks page illustrated in the following figure. The application is now configured and running.

Tip If you want to use another root password for the database, replace the occurrences of 'password' with the required password. This has to be changed in the following three places: MySQL instance configuration. Data source configuration file. build.properties file used by the Ant build script.

The Geronimo enviroment

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.

Configure resources

In Geronimo the JDBC resources are implemented using J2EE connectors. Therefore, you need to write a Geronimo specific deployment plan for deploying a JDBC datasource. Additionally, while doing the deployment you need to provide the deployer with the tranql-connector-1.2.rar file. This RAR file contains the connection pool management logic for Geronimo.

For running the Online Brokerage application in Geronimo, you will be using the same MySQL database that was used with JBoss. So the only task you need to do in order to prepare the Geronimo environment is to configure the data source.

Configure the data source

First part of the configuration is to upload the mysql-connector-java-3.0.17-ga-bin.jar library to the application server. Using the Geronimo console is the easiest way to achieve this task without much of configuration issues.

1. Travel Common Libs from the Console Navigation.
2. Load mysql-connector-java-3.0.17-ga-bin.jar to the File input box.
3. Add the following properties to the archive before installing it in the Geronimo.
   • Group - mysql
   • Artifact - mysql-connector
   • Version - 1.0
   • Type - jar
4. Press the Install button to deploy jar file in the application server.

Different types of data sources There are three types of data sources that Geronimo supports: Global data source - Visible to all the applications on a Geronimo Instance. Application scoped data source - Visible to a single application within which it is defined. Module scoped data source - Visible to a single module within which it is defined.

Create the data source deployment plan

Next user have to deploy database connection pool of the Geronimo. Given is the sample database pool deployment plan comes with this application. This configuration file is going to deploy as a Global datasource in the Geronimo server.

<?xml version="1.0" encoding="UTF-8"?>
<connector xmlns="http://geronimo.apache.org/xml/ns/j2ee/connector-1.1">
    <dep:environment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.1">
        <dep:moduleId>
            <dep:groupId>console.dbpool</dep:groupId>
            <dep:artifactId>TradeDS</dep:artifactId>
            <dep:version>1.0</dep:version>
            <dep:type>rar</dep:type>
        </dep:moduleId>
	<!-- Add the Correct Dependency Here -->
        <dep:dependencies>			
            <dep:dependency>
                <dep:groupId>mysql</dep:groupId>
                <dep:artifactId>mysql-connector</dep:artifactId>
                <dep:version>1.0</dep:version>
                <dep:type>jar</dep:type>
            </dep:dependency>
        </dep:dependencies>
    </dep:environment>
    <resourceadapter>
        <outbound-resourceadapter>
            <connection-definition>
                <connectionfactory-interface>javax.sql.DataSource</connectionfactory-interface>
                <connectiondefinition-instance>
                    <name>TradeDS</name>
                    <config-property-setting name="Driver">com.mysql.jdbc.Driver</config-property-setting>
                    <config-property-setting name="UserName">root</config-property-setting>
                    <config-property-setting name="ConnectionURL">jdbc:mysql://localhost:3306/tradedb</config-property-setting>
                    <connectionmanager>
                        <local-transaction/>
                        <single-pool>
                            <max-size>10</max-size>
                            <min-size>0</min-size>
                            <match-one/>
                        </single-pool>
                    </connectionmanager>
                </connectiondefinition-instance>
            </connection-definition>
        </outbound-resourceadapter>
    </resourceadapter>
</connector>

First part of this xml deployment plan is more of a Maven 2 configuration file. Following are some of the other important parts of the above deployment plan.

• connectionfactory-interface - Must be javax.sql.DataSource.
• connectiondefinition-instance - Contains the configuration properties required to connect to the database.
• connectionmanager - Contains the configuration settings for the geronimo connection manager.
• config-property-setting - Specifies the value of a single configuration property of the connector.
• name - Name of the data source.
• local-transaction - The presence of this element enables the resource adapter to support local transactions. If the 'no-transaction' element is present instead of 'local-transaction', then the resource adapter will not support transactions. If the 'xa-transaction' element is present instead of 'local-transaction', then the resource adapter will support xa-transactions.
• single-pool - Contains the connection pool configuration properties such as max-size and min-size for a single pool. If the 'no-pool' element is present instead of 'single-pool', then the connections will not be pooled. If 'partitioned-pool' element is present instead of 'single-pool', then there will be a number of connection pools based on the partition type.
• max-size - Maximum number of connections allowed simultaneously.
• min-size - Minimum size of the connection pool.
• blocking-timeout-milliseconds - Time for which a caller will be made to wait for a connection, if all the connections in the pool are currently in use, before throwing an exception.
• idle-timeout-minutes - Time in minutes after which a connection will timeout if it is idle.

The following table shows the configuration properties that are specified by the config-property-setting element.

To deploy the Database connection pool follow the given steps in the Geronimo console.

1. Click on Deploy New from the Console Navigation.
2. Load the tranql-connector-1.2.rar to the Archive input box from the <geronimo_home>/repository/tranql/tranql-connector/1.2/tranql-connector-1.2.rar location.
3. Load the InventoryPool.xml to the Plan input box from brokerage/config/plan/mysql-geronimo-plan.xml directory.
4. Press Install button to deploy connection pool in to the server.

Now you are ready to proceed with the migration.

Step-by-step migration

Geronimo does not support accessing external resources(JDBC datasources) by setting JNDI properties at runtime.
This is because reference resolution is done at deploy time and is based on the JSR-77 object names of the target component. In order to migrate the Online Brokerage application to Geronimo, you first need to replace the jboss-web.xml file with a geronimo-web.xml file which is the Geronimo-specific descriptor file.

The geronimo-web.xml file is located in the brokerage/web/WEB-INF directory and looks like the following example. Note that naming:resource-ref element maps the TradeDS data source to the name jdbc/TradeDB in this deployment plan.

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.1" xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.1">
  <dep:environment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.1">
    <dep:moduleId>
      <dep:groupId>org.apache.geronimo.samples</dep:groupId>
      <dep:artifactId>brokerage</dep:artifactId>
      <dep:version>1.0</dep:version>
      <dep:type>car</dep:type>
    </dep:moduleId>
    <dep:dependencies>
	<dep:dependency>
           <dep:groupId>console.dbpool</dep:groupId>
           <dep:artifactId>TradeDS</dep:artifactId>
        </dep:dependency>
    </dep:dependencies>		
    <dep:hidden-classes/>
    <dep:non-overridable-classes/>
  </dep:environment>
  <context-root>/brokerage</context-root> 
  <naming:resource-ref>
	  <naming:ref-name>jdbc/TradeDB</naming:ref-name>
	  <naming:resource-link>TradeDS</naming:resource-link>
  </naming:resource-ref>	
</web-app>

To build the Geronimo version of the application use ant war-geronimo in your command prompt. It will create the brokerage.war under the brokerage/releases/geronimo folder.

Deploy the migrated sample application

To deploy the migrated Online Brokerage application, make sure the Geronimo server is up and running.

Open Geronimo console in your browser and follow the given steps:

1. Scroll down to Deploy New from the Console Navigation.
2. Load brokerage.war from brokerage/releases/geronimo folder in to the Archive input box.
3. Press Install button to deploy application in the server.

Once the application is deployed, open a Web browser and access the following URL:
http://localhost:8080/brokerage

Login with the same user name and password you used when testing the application from JBoss.

Summary

This article has shown you how to migrate a sample application, from JBoss to the Apache Geronimo application server. You followed step-by-step instructions to build the application, deploy and run it, and then migrate it to the Geronimo environment.

The following list summarizes the major differences found during this sample application migration.

1. In the Geronimo specific deployment descriptor the resource reference name is mapped to the name of the datasource unlike in the JBoss specific deployment descriptor where the resource name is mapped to the JNDI name of the datasource.
2. In order to deploy a datasource in JBoss you need to just copy the configuration file to the deploy directory but in Geronimo you need to use the deployer tool.
3. At this time, Geronimo does not support accessing external resources (i.e.:JDBC datasources) by setting JNDI properties at runtime. This resources need to be specified at deployment time.