|Home > Documentation > Apache Geronimo v1.1 - User's Guide > Migrating to Apache Geronimo > JBoss to Geronimo - Security Migration|
|JBoss to Geronimo - JDBC Migration||Migrating to Apache Geronimo||JBoss to Geronimo - Servlets and JSPs Migration|
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:
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.|
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:
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:
After extracting the ZIP file, a document_manager directory is created, from now on this directory will be referred as <document_manager_home>.
The Application contains the following JSP pages:
Additionally following major J2EE components are also in the part of the application.
The tools used for developing and building the 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:
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:
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:
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.
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.
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:
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:
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:
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.
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.
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.
To test the application, open a Web browser and access the following URL:
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.
Download and install Geronimo from the following URL:
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:
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:
|Note that in contrast to JBoss, application roles must be explicitly defined in the deployment plan.|
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.
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:
Once the application is deployed, open a Web browser and access the following URL:
You should see the same JSP page of the application as you tested when running the Web services sample on JBoss.
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.