|
|
| Home > Apache Geronimo v1.0 > Documentation > Apache Geronimo v1.0 - User's Guide > Migrating to Apache Geronimo > JBoss to Geronimo - JCA Migration |
This article will help you migrate applications that are based on Java Connector Architecture (JCA) and developed for JBoss v4 to Apache Geronimo. It is part of a series of migration articles covering different types of applications migration.
This article provides some details on the differences between these two application servers as well as a detailed step-by-step migration procedure for porting JCA applications from JBoss v4 to Apache Geronimo. To define a common starting point (the source environment) we provide steps for deploying the sample File Retriever JCA application into the JBoss source environment. Then you will be guided through the application migration and deployment process onto Apache Geronimo.
This article is organized in the following sections:
Connectors implementation, also know as Resource Adapters, may vary from one vendor to another. The purpose of this section is to provide a JCA specific feature-to-feature comparison between JBoss and Apache Geronimo so you can clearly identify the differences and plan accordingly before migration.
The most common features related to support of Connectors are summarized in the following table:
| Features | JBoss v4 | Apache Geronimo |
|---|---|---|
| Basic JCA architecture support | Supports resource adapters. However, requires that the ra.xml deployment descriptor file specifies a class implementing javax.resource.spi.ResourceAdapter interface. Such an implementation is optional according to the specification. | Supports resource adapters exactly as it is expected according to the JCA specification |
| Location of classes | Compiled Java classes are to be put into the root of corresponding RAR archive similar to JAR files. | Fails to find classes just located in a RAR file. It needs the classes to be packed in an intermediate JAR file which in its time should be put into the root of the RAR archive. |
| Server-specific deployment descriptors | Uses *-ds.xml name convention and expects to find such a file in the deployment directory of the respective server outside corresponding EAR or RAR archive. | Allows to put additional deployment parameters into the geronimo-ra.xml file inside the META-INF folder of corresponding RAR archive. Also allows to specify external deployment plan files during deployment of resource adapters. |
As it is shown in this table, JBoss requires an implementation of the ResourceAdapter interface. The fully-qualified name of a corresponding class should be specified in the ra.xml file, note the <resourceadapter-class> tags in the following example:
<connector xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/connector_1_5.xsd" version="1.5"> <display-name>MyAdapter</display-name> <vendor-name>...</vendor-name> <eis-type>...</eis-type> <resourceadapter-version>...</resourceadapter-version> <resourceadapter> <resourceadapter-class> org.jboss.resource.deployment.DummyResourceAdapter </resourceadapter-class> <outbound-resourceadapter> ... </outbound-resourceadapter> </resourceadapter> </connector>
The class org.jboss.resource.deployment.DummyResourceAdapter is the dummy implementation of the interface provided by JBoss that can be used in those cases when the supplier of the adapter does not provide its own specific implementation. This implementation does nothing and returns null when invoked.
On the other hand, Geronimo follows the J2EE specification and does not require the resourceadapter-class element. However, Geronimo throws a java.lang.NullPointerException when attempting to use the dummy implementation of the interface which copies the stub provided by JBoss.
This article contains a File Retriever JCA
sample application to demonstrate the migration from JBoss to Geronimo. This application consists of two modules that, for this sample purposes, are deployed separately and not as a single EAR archive.
The first module is a simple file system resource adapter that conforms to the JCA architecture without any server-specific extensions. The adapter provides only two functions:
The second module is a Web application that uses the adapter and provides online access to the files.
The user views a list of directories and files located in the repository and clicks a file to download it from the server. By default the resource adapter is configured so that the root directory of an application server is used as the repository.
The JCA sample application consists of the following packages:
In addition to these packages, the Web module consists of a single JSP page which is located in the web directory. This JSP shows structure of the repository and provides hyperlinks to the File Retriever servlet for downloading contents of the files.
The tools used for developing and building the File Retriever sample application are:
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
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
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.
. You should see the JBoss Welcome window and be able to access the JBoss console.Compiling the source code of the sample application requires Java libraries that provide J2EE API interfaces. Build scripts included with the sample application package are configured for using JAR files provided by a JBoss installation.
The only additional software required for building the application is Apache Ant. If you still 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:
The File Retriever JCA sample application included with this article provides an Ant script that you will use in order to build modules of the application. Download the File Retriever JCA application package from the following link:
After extracting the zip file, a jca directory is created. From now on this directory will be referred as <jca_home>. In that directory open the build.properties file and edit the properties which starts from the prefix jboss to match your environment as shown in the following example. The remaining properties are not relevant at this point in time, you will use them later to build the Geronimo version of this sample application.
# Name of the server to build the application for: server.name = jboss # Home directory of JBoss 4.0.2 J2ee Application Server # and name of the server instance on which the application # should be deployed (JBoss is also used for building # purposes): jboss.home = <jboss_home> jboss.server = <your_server_name> # Home directory of Geronimo Application Server # and its administrator credentials: geronimo.home = <geronimo_home> geronimo.user = system geronimo.password = manager
 | When specifying the directories and paths in the build.properties file, make sure to use just the forward slash "/" , otherwise the build will not locate the required files. |
From a command prompt or shell go to the <jca_home> directory and run ant. This will create the RAR and WAR archives and place them directly into the <jca_home> directory.
The RAR archive contains a JBoss version of the resource adapter deployment descriptor. The ra.xml file, located in the META-INF directory is shown in the following example.
<?xml version="1.0" encoding="UTF-8"?> <connector xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/connector_1_5.xsd" version="1.5"> <display-name>FileRetriever</display-name> <vendor-name>IBM</vendor-name> <eis-type>File system</eis-type> <resourceadapter-version>1.0</resourceadapter-version> <resourceadapter> <resourceadapter-class> org.jboss.resource.deployment.DummyResourceAdapter </resourceadapter-class> <outbound-resourceadapter> <connection-definition> <managedconnectionfactory-class> com.ibm.j2g.jca.connector .impl.FileRetrieverManagedConnectionFactory </managedconnectionfactory-class> <config-property> <description> Path to the directory being the file repository </description> <config-property-name> RepositoryPath </config-property-name> <config-property-type> java.lang.String </config-property-type> </config-property> <connectionfactory-interface> com.ibm.j2g.jca.connector .FileRetrieverConnectionFactory </connectionfactory-interface> <connectionfactory-impl-class> com.ibm.j2g.jca.connector .impl.FileRetrieverConnectionFactoryImpl </connectionfactory-impl-class> <connection-interface> com.ibm.j2g.jca.connector.FileRetrieverConnection </connection-interface> <connection-impl-class> com.ibm.j2g.jca.connector .impl.FileRetrieverConnectionImpl </connection-impl-class> </connection-definition> <transaction-support>NoTransaction</transaction-support> <reauthentication-support>false</reauthentication-support> </outbound-resourceadapter> </resourceadapter> </connector>
This file provides general information about the resource adapter, specifies its interfaces and classes, defines repository path configuration parameter and declares that the adapter does not support transaction. In particular, since JBoss requires that the descriptor defines a class implementing javax.resource.spi.ResourceAdapter interface the dummy implementation org.jboss.resource.deployment.DummyResourceAdapter provided by JBoss itself is specified.
To deploy the adapter you also need a deployment descriptor specific to JBoss which is not included into the RAR archive because it may be updated just before deployment in order to provide the correct configuration for the adapter. The file <jca_home>/meta/jboss/jca-ds.xml providing the required configuration looks like the following example.
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE connection-factories PUBLIC "-//JBoss//DTD JBOSS JCA Config 1.5//EN" "http://www.jboss.org/j2ee/dtd/jboss-ds_1_5.dtd"> <connection-factories> <no-tx-connection-factory> <jndi-name>FileRetriever</jndi-name> <rar-name>jca.rar</rar-name> <connection-definition> com.ibm.j2g.jca.connector.FileRetrieverConnectionFactory </connection-definition> <config-property name="RepositoryPath" type="java.lang.String">..</config-property> </no-tx-connection-factory> </connection-factories>
This descriptor defines the JNDI name of the factory that is responsible for the resource adapter instance creation, it specifies that the adapter classes are contained by the jca.rar archive and provides value of the repository path configuration parameter. By default the adapter is configured so that the root directory of the JBoss server is used as the repository.
The WEB-INF directory of the WAR archive created by ant contains the standard web.xml deployment descriptor as well as a descriptor specific to JBoss, jboss-web.xml.
<?xml version="1.0" encoding="UTF-8"?> <web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" version="2.4"> <servlet> <servlet-name>FileRetrieverServlet</servlet-name> <servlet-class> com.ibm.j2g.jca.web.FileRetrieverServlet </servlet-class> </servlet> <servlet-mapping> <servlet-name>FileRetrieverServlet</servlet-name> <url-pattern>/retrieve</url-pattern> </servlet-mapping> <resource-ref> <res-ref-name>ra/FileRetriever</res-ref-name> <res-type> com.ibm.j2g.jca.connector.FileRetrieverConnectionFactory </res-type> <res-auth>Container</res-auth> <res-sharing-scope>Shareable</res-sharing-scope> </resource-ref> </web-app>
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE jboss-web PUBLIC "-//JBoss//DTD Web Application 2.3//EN" "http://www.jboss.org/j2ee/dtd/jboss-web_3_2.dtd"> <jboss-web> <context-root>/jca</context-root> <resource-ref> <res-ref-name>ra/FileRetriever</res-ref-name> <jndi-name>java:/FileRetriever</jndi-name> </resource-ref> </jboss-web>
The web.xml file defines a servlet used for retrieving contents of files and locally used reference to the resource adapter which the main JSP page and the servlet refer to. The jboss-web.xml file defines the context root for the Web module and maps the locally used reference to the JNDI name defined by the resource adapter descriptor specific to JBoss, the jca-ds.xml file.
To deploy the modules of the File Retriever JCA application on JBoss, place the jca.rar and jca.war files that you just built with ant, along with the <jca_home>/meta/jboss/jca-ds.xml file into the following directory:
<jboss_home>\server\<your_server_name>\deploy
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.
To test the application, open a Web browser and access the following URL:
This brings up the main page of the sample application. Click a file to download it from the repository.
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. |
To migrate the File Retriever sample application from JBoss to Geronimo you just need to update deployment descriptors and replace descriptors specific to JBoss with ones specific to Geronimo for both modules as described in the following sections.
Geronimo follows the specification and does not require the resourceadapter-class element to be specified in the resource adapter deployment descriptor in case no implementation is available.
The Geronimo version of the ra.xml file is located in the <jca_home>/meta/geronimo directory. It is almost identical to the descriptor used by JBoss which is located in the <jca_home>/meta/jboss directory and was listed above. The only difference is that the Geronimo version does not include the following lines from the JBoss version.
<resourceadapter-class> org.jboss.resource.deployment.DummyResourceAdapter </resourceadapter-class>
To deploy the adapter on Geronimo you also need a deployment plan specific to this server. Such a plan can be either named geronimo-ra.xml and be placed into the META-INF folder of the corresponding RAR archive, or can have any name and stay outside the archive. In the latter case, the path to the plan should be specified during the deployment of the resource adapter.
The deployment plan used by the sample application contains the repository path configuration parameter that may be updated before the deployment. Because of this, the jca-plan.xml file is not included in the RAR archive but it is placed into the <jca_home>/meta/geronimo directory instead. The content of this file is listed in the following example.
<?xml version="1.0" encoding="UTF-8"?> <!-- This is Geronimo-specific descriptor --> <connector xmlns="http://geronimo.apache.org/xml/ns/j2ee/connector" version="1.5" configId="com/ibm/j2g/jca.rar" parentId="org/apache/geronimo/Server"> <resourceadapter> <outbound-resourceadapter> <connection-definition> <connectionfactory-interface>com.ibm.j2g.jca.connector.FileRetrieverConnectionFactory</connectionfactory-interface> <connectiondefinition-instance> <name>FileRetriever</name> <!-- The following path refers to the Geronimo home directory --> <config-property-setting name="RepositoryPath">..</config-property-setting> <connectionmanager> <no-transaction/> <no-pool/> </connectionmanager> </connectiondefinition-instance> </connection-definition> </outbound-resourceadapter> </resourceadapter> </connector>
In this deployment plan the attribute configId specifies the unique name com/ibm/j2g/jca.rar used to identify the RAR module in Geronimo. The attribute parentId specifies that this module is deployed on the server as a separate component. Both attributes are required in this case.
The descriptor also:
By default, the adapter is configured so that the root directory of the Geronimo server is used as the repository.
To deploy the WAR module on Geronimo you need to replace the jboss-web.xml file with a similar descriptor specific to this server. The geronimo-web.xml file is located in the <jca_home>/web/WEB-INF directory and its contents is listed the following example.
<?xml version="1.0" encoding="UTF-8"?> <!-- This is Geronimo-specific descriptor --> <web-app xmlns="http://geronimo.apache.org/xml/ns/web" configId="com/ibm/j2g/jca.war" parentId="com/ibm/j2g/jca.rar"> <context-root>/jca</context-root> <resource-ref xmlns="http://geronimo.apache.org/xml/ns/naming"> <ref-name>ra/FileRetriever</ref-name> <resource-link>FileRetriever</resource-link> </resource-ref> </web-app>
In first place, this file specifies the unique name com/ibm/j2g/jca.war used to identify the WAR module in Geronimo and refers to the RAR module as to a parent configuration. This relation is required because the WAR module uses Java-interfaces defined in the RAR module.
Then, similar to JBoss, this descriptor also defines the context root for the Web application and maps the locally used reference ra/FileRetriever to the name of the resource adapter specified in its deployment plan (jca-plan.xml).
These are the only changes required to run modules of the JCA application in Geronimo.
In order to build the modules of the File Retriever JCA application for Geronimo, you need to update the build.properties file so that the server.name property value is set to geronimo and properties that start with the prefix geronimo match your environment as shown in the following example.
# Name of the server to build the application for: server.name = geronimo # Home directory of JBoss 4.0.2 J2ee Application Server # and name of the server instance on which the application # should be deployed (JBoss is also used for building # purposes): jboss.home = <jboss_home> jboss.server = <your_server_name> # Home directory of Geronimo Application Server # and its administrator credentials: geronimo.home = <geronimo_home> geronimo.user = system geronimo.password = manager
| Modifying the source code If you modify the Java source code of this application, ensure that the properties which start with the prefix jboss still match your environment. The build scripts still refer to JBoss libraries for J2EE API interfaces required for the source code compilation. Alternatively, you can update the classpath specified in the build.xml file so that it refers to the library <geronimo_home>/repository/geronimo-spec/jars/geronimo-spec-j2ee-1.4-rc5.jar instead of JBoss JARs. |
Now run the command ant build. This will create the Geronimo version of the RAR and WAR archives with the proper deployment descriptors and place them directly into the <jca_home> directory.
You can ensure that Java classes and interfaces for the resource adapter in the Geronimo version are packed into an intermediate JAR library which is placed into the RAR archive (while in the JBoss version the compiled Java code is placed into the archive directly). The reason for this is described in the beginning of this article.
To deploy the migrated File Retriever JCA application, make sure the Geronimo server is up and running.
From a command line, change directory to <jca_home> and type the following commands:
java -jar <geronimo_home>/bin/deployer.jar --user system --password manager deploy meta/geronimo/jca-plan.xml jca.rar
java -jar <geronimo_home>/bin/deployer.jar --user system --password manager deploy jca.war
Another way to deploy the modules on Geronimo (that is running on the default port 8080) is to update the build.properties file so that the properties which start with geronimo match with your environment and invoke the ant deploy command. The script executed by Ant will uninstall the modules if installed and deploy their latest builds created on the previous step.
E:\jca>ant deploy
Buildfile: build.xml
deploy:
deploy.geronimo:
[java] Module com/ibm/j2g/jca.war stopped.
[java] Module com/ibm/j2g/jca.war unloaded.
[java] Module com/ibm/j2g/jca.war uninstalled.
[java] Undeployed com/ibm/j2g/jca.war
[java] Module com/ibm/j2g/jca.rar stopped.
[java] Module com/ibm/j2g/jca.rar unloaded.
[java] Module com/ibm/j2g/jca.rar uninstalled.
[java] Undeployed com/ibm/j2g/jca.rar
[java] Deployed com/ibm/j2g/jca.rar
[java] Deployed com/ibm/j2g/jca.war @ http://hcunico:8080/jca
BUILD SUCCESSFUL
Total time: 7 seconds
E:\jca>
Once the JCA application is deployed, open a Web browser and access the following URL:
You should see the JSP page of the application which is similar to the page of the JBoss version which you have already tested. The only difference should be an actual contents of the repository.
This article showed how to migrate a JCA (resource adapter) application from JBoss v4 to the Apache Geronimo application server. It showed that the migration requires you to update deployment descriptors (provide descriptors specific to Geronimo server). This takes minimum efforts.
