This article will help you migrate security applications developed for JBoss v4.0.5 to Apache Geronimo. This article 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 security application from JBoss v4.0.5 to Apache Geronimo. To define a common starting point (the source environment), this article provide steps for deploying the sample 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:

Security implementation analysis

Support of J2EE features may vary from one vendor to another and different vendors provide different ways to extend respective specifications and default behaviors with custom ones. The purpose of this section is to provide comparison of similar JBoss and Geronimo features which were applied for the implementation of sample applications. You can use the information below to clearly identify the differences of these two servers and plan accordingly before migration from one to another.

Features	JBoss v4.0.5	Apache Geronimo
Custom login modules	Supports custom login modules. Custom login modules can be installed as part of the service archive (SAR).	Supports custom login modules.
J2EE security	Supports both declarative and programmatic J2EE security.	Supports both declarative and programmatic J2EE security.
Deploying realm configuration	Supports deployment of realm configuration as part of the service archive (SAR).	Realm configuration can be deployed as part of the module or as part of the application.

Back to Top

Sample application

The Document manager application represents a sample application that exploits security related features in the JBoss. It gives the features to the users both view and upload documents. It consists of the following three pages:

Login Page
Documents Page
Login Error Page

The application starts with the Login page. After logging in the user is redirected to the Documents page. There are two types of users - viewers and editors. Both kinds can view documents, but only the editor can upload them.

If a user has "editor" role, the upload form is displayed below the documents list. When the user selects a document and presses the "upload" button, the upload method of the DocumentManagerBean session bean is invoked through the execution of the "Upload" servlet. The Security application will throw an exception if a non-authorized user attempts to call the upload servlet.

Users are defined through the property files j2g_users.properties and it is located in the <document_manager_home>/config directory.

Two predefined users are "user" with password "1" and "editor" with password "2".

Download the Document manager application from the following link:
Document Manager

After extracting the ZIP file, a document_manager directory is created, from now on this directory will be referred as <document_manager_home>.

Application classes and JSP pages

The Application contains the following JSP pages:

login.jsp - The login page of the application.
loginError.jsp - The default error page of the application.
main.jsp - The main application page with documents list

Additionally following major J2EE components are also in the part of the application.

LogoutServlet - Servlet which handles user logout functionality.
UploadServlet - Servlet that handles the uploads
DocumentManagerBean - Stateless Session EJB that handles document uploads.

Tools used

The tools used for developing and building the sample 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

XDoclet

XDoclet is a tool for generating various artifacts (deployment descriptors, source code) basing on the JavaDoc tags. XDoclet can be downloaded from the following URL:

http://xdoclet.sourceforge.net

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

Compilation of source code of the sample applications is based on Java libraries distributed along with JBoss. The only additional software which is required for building the applications is Apache Ant.

Apache Ant

If you do not have Ant installed, this is a good time for doing so and making sure that <ant_home>\bin directory is added to the path system environment variable. Apache Ant can be downloaded from the following URL:
http://ant.apache.org

XDoclet

If you do not have XDoclet installed, this is a good time for doing so. Although XDoclet installation is not required to build the sources at this time. It will be required for modifying the source code. The XDoclet can be downloaded from the following URL:
http://xdoclet.sourceforge.net

Build the sample application

The Document Management sample application included with this article provides an Ant script that you will use in order to build modules of the application. If you have not downloaded the sample application yet, this is a good time for doing it. Download the Document Management Application from the following link:

Document Manager

After extracting the zip file, a document_manager directory is created. From now on this directory will be referred as <document_manager_home>. In the <document_manager_home>/config directory open the build.properties file and edit the geronimo.home & xdoclet.home as given in below.

build.properties

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

## Set the XDoclet 1.2.3 home here 
xdoclet.home=<xdoclet_home>

From a command prompt or shell go to the <document_manager_home> directory and run the ant jboss command. This will create the EAR file and place it directly into the <document_manager_home>/releases/jboss directory.

Deploy the sample application

To deploy the sample application just copy the DocumentManager.ear will be created under the <document_manager_home>/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/document

It will try to access secured resource in the application and forward user in to login page as below. Then the user has to provide valid credentials to access that resource.

If the user provides valid credentials and it belongs to the editor he will get the access to upload documents to the system as below.

Back to Top

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.

Download and install Geronimo from the following URL:
http://geronimo.apache.org/downloads.html

Back to Top

Step-by-step migration

Geronimo does not have an equivalent of the JBoss service archives (SARs). In the Security sample application, this archive is used for deploying the realm configuration on JBoss. In the case of Geronimo, this configuration can be placed in the application-wide Geronimo deployment plan geronimo-application.xml.

The following steps were performed to migrate the sample application:

Developed a Geronimo specific deployment plan for the Enterprise application. The geronimo-application.xml deployment plan is located in the <document_manager_home>/config/geronimo directory. During the build process, this deployment plan is placed in the META-INF subdirectory in the EAR archive and should look like the following:

<?xml version="1.0" encoding="UTF-8"?>
<application xmlns="http://geronimo.apache.org/xml/ns/j2ee/application-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>DocumentManager</dep:artifactId>
			<dep:version>1.0</dep:version>
			<dep:type>car</dep:type>
		</dep:moduleId>
		<dep:dependencies>
			<dependency>
                <groupId>geronimo</groupId>
                <artifactId>j2ee-security</artifactId>
                <type>car</type>
            </dependency>
		</dep:dependencies>
		<dep:hidden-classes/>
		<dep:non-overridable-classes/>
	</dep:environment>
	<security xmlns="http://geronimo.apache.org/xml/ns/security">
        <default-principal realm-name="j2g">
            <principal class="org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal" name="system"/>
        </default-principal>
        <role-mappings>
            <role role-name="authenticated">
                <realm realm-name="j2g">
                    <principal class="org.apache.geronimo.security.realm.providers.GeronimoGroupPrincipal" name="authenticated"/>
                </realm>
            </role>
            <role role-name="uploader">
                <realm realm-name="j2g">
                    <principal class="org.apache.geronimo.security.realm.providers.GeronimoGroupPrincipal" name="uploader"/>
               </realm>
            </role>
        </role-mappings>
    </security>
	<gbean name="j2g" class="org.apache.geronimo.security.realm.GenericSecurityRealm">
        <attribute name="realmName">j2g</attribute>
        <reference name="ServerInfo">
            <name>ServerInfo</name>
        </reference>
        <reference name="LoginService">
            <name>JaasLoginService</name>
        </reference>
        <xml-reference name="LoginModuleConfiguration">
            <log:login-config xmlns:log="http://geronimo.apache.org/xml/ns/loginconfig-1.1">
                <log:login-module control-flag="REQUIRED" server-side="true" wrap-principals="false">
                    <log:login-domain-name>j2g</log:login-domain-name>
                    <log:login-module-class>org.apache.geronimo.security.realm.providers.PropertiesFileLoginModule
                    </log:login-module-class>
                    <log:option name="usersURI">var/security/j2g_users.properties</log:option>
                    <log:option name="groupsURI">var/security/j2g_groups.properties</log:option>
                </log:login-module>
            </log:login-config>
        </xml-reference>
    </gbean>
 </application>

Note that in contrast to JBoss, application roles must be explicitly defined in the deployment plan.

Created a Geronimo specific deployment plan for the EJB module openejb-jar.xml. This deployment plan is located in the <document_manager_home>/config/geronimo directory. During the build the file is copied to the META-INF subdirectory of the DocumentMangerEJB.jar EJB module. This deployment plan should look like the following example:

<?xml version="1.0" encoding="UTF-8"?>
<openejb-jar xmlns="http://www.openejb.org/xml/ns/openejb-jar-2.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>DocumentManagerEJB</dep:artifactId>
			<dep:version>1.0</dep:version>
			<dep:type>car</dep:type>
		</dep:moduleId>
		<dep:dependencies/>
		<dep:hidden-classes/>
		<dep:non-overridable-classes/>
	</dep:environment>
	<enterprise-beans>
		<session>
			<ejb-name>DocumentManager</ejb-name>
		</session>
	</enterprise-beans>
</openejb-jar>

Created a Geronimo specific deployment plan for the Web module geronimo-web.xml. This plan is located in the <document_manager_home>/web/WEB-INF directory. During the build, this file is retained to the WEB-INF subdirectory of the DocumentMangerWeb.war Web module and remove unnecessay files from this folder. This file linked with geronimo-application.xml with security realm information contained in it. This deployment plan should look like the following example:

<?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>DocumentManagerWeb</dep:artifactId>
      <dep:version>1.0</dep:version>
      <dep:type>car</dep:type>
    </dep:moduleId>
    <dep:dependencies/>    
    <dep:hidden-classes/>
    <dep:non-overridable-classes/>
  </dep:environment>
  <context-root>/document</context-root> 
  <security-realm-name>j2g</security-realm-name>
</web-app>

Rewrited the properties files with users to group mapping. JBoss login module have mapping in the form of "user=group1,group2" and Geronimo have mapping in the form of "group=user1,user2".

Build the sample application

Now run the command ant geronimo. This will create the Geronimo version of the EAR file in which the <document_manager_home>/releases/geronimo directory.

Deploy the migrated sample application

To deploy the migrated document manager application, make sure the Geronimo server is up and running.

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

Scroll down to Deploy New from the Console Navigation panel.
Load DocumentManager.ear from <document_manager_home>/releases/geronimo folder in to the Archive input box.
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/document

You should see the same JSP page of the application as you tested when running the Web services sample on JBoss.

Back to Top

Summary

This article showed you how to migrate a Security application that exploits some of the J2EE security-related features such as EJB declarative security, Web declarative security and Web programmatic security.

In both environments built-in login module was used. This article showed that such kind of applications require minimal migration efforts, although in more complex cases there could be more time-consuming issues.