Contents


Making the move to the Liberty profile, Part 3

Migrating a JBoss application to Liberty

Comments

Content series:

This content is part # of # in the series: Making the move to the Liberty profile, Part 3

Stay tuned for additional content in this series.

This content is part of the series:Making the move to the Liberty profile, Part 3

Stay tuned for additional content in this series.

The purpose of this installment is to identify and resolve the incompatibilities in moving an old J2EE™ 1.4 application that uses heavyweight EJB2.x beans running on JBoss V5.0.1.GA to a lightweight Java™ EE 6 application using EJB3 running on the IBM WebSphere Application Server V8.5.5 Liberty profile.

This example outlines the steps involved in migrating these Java technologies and frameworks:

  • Java Servlet 2.4
  • JavaServer™ Pages (JSP) 2.0
  • Enterprise Java Beans (EJB) 2.x
  • Java Database Connectivity (JDBC) 4.0
  • Java Authentication and Authorization Service for Java SE 6
  • Classic Hibernate.

Sample application

The sample application used in this article is a modified version of the Document Manager application used in this JBoss to Geronimo - Security Migration article. This application is representative of existing J2EE applications that run on heavyweight containers like JBoss that organizations might encounter in making the move to lightweight Java EE containers like the Liberty profile.

The Document Manager application supports a couple of use cases that enable users to both view and upload documents. The application also has security constraints. It consists of three pages (Figure 1):

  • Login page
  • Documents page
  • Login Error page
Figure 1. Sample application overview
Sample application overview
Sample application overview

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 user types can view documents, but only the editor can upload new documents.

If a user has an 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.

The application has two predefined user IDs:

  • user with password 1
  • editor with password 2.

The download file included with this article contains the Document Manager application you need to follow along and perform the steps below. The application is contained in the OriginalDocumentManager.ear file and is made up of these components:

  • DocumentManager.ear - EAR archive that packages all JARs and modules for the DocumentManager application.
  • DocumentManagerWeb.war - Web archive that contains the servlets and JSP pages that process user actions and display the user documents.
  • DocumentManagerEJB.jar - EJB archive that contains stateless session beans and data access objects to retrieve user documents from the database.
  • DocumentManagerSAR.sar - JBoss proprietary service archive that contains the JBoss custom JAAS login module that handles the authentication and authorization for the DocumentManager application.
  • DocumentManagerHibernate.jar - Utility JAR that contains the hibernate configuration and class mappings.

The application is packaged as an Enterprise Application Archive (EAR) as shown in Figure 2.

Figure 2. Sample application EAR structure
Sample application EAR structure
Sample application EAR structure

The remainder of this tutorial shows you how to:

  1. Setup and run the sample application.
  2. Analyze suitability of the application for migrating to Liberty. This section leverages the Liberty Tech Preview described in Part 1.
  3. Migrate from JBoss to Liberty. This section addresses all of the porting issues that were identified by the analysis from step 2 and also uses the WebSphere Configuration Migration Toolkit.

Included with this tutorial

This tutorial contains a download file in .zip format that contains several sample components that are used throughout this exercise to illustrate the steps for migrating a JBoss application to the Liberty profile. Table 1 lists the items included in this file.

Table 1. Sample application components
File nameDescription
OriginalSampleApp.zipEclipse workspace that contains the sample application that runs on JBoss.
OriginalDocumentManager.earOriginal EAR file for the Document Manager.
MigratedSampleApp.zipEclipse workspace that contains the sample application that runs on Liberty.
MigratedDocumentManager.earMigrated EAR file for the Document Manager.
JBossConfig.zipJBoss Server configuration that contains the Derby driver and data source.
server.xmlLiberty Server configuration that contains the Derby driver and data source.
DerbySampleDB.zipDerby database files that are accessed by the sample application.

1. Set up and run the sample application

a. Install the Derby database server

The Derby database server is used by the sample application to maintain document information. To run the Document Manager application, you need a database to access the document data that is displayed by the application. To keep things simple, this database will use Derby, a very lightweight and easy to use database.

Download db-derby-10.11.1.1-bin.zip from the Apache Derby release page. Once downloaded, extract the compressed archive file. This will be referred to as the <DERBY_HOME> folder.

b. Import the sample database into Derby

From the download material included with this article, and unzip the contents of the DerbySampleDb.zip archive. The location of the extracted contents will be referred as <SAMPLE_DB> in this article.

To import the database into Derby:

  1. Copy the <SAMPLE_HOME> folder into <DERBY_HOME>/lib. You will see that a sampledb folder has been copied into <DERBY_HOME>/lib. That folder is where the Derby database files, accessed by the sample application, are located.
  2. To run Derby, go to the <DERBY_HOME>/lib directory and start the Apache Derby Network Server by running the java -jar ./derbyrun.jar server start command.

c. Install and configue the JBoss application server

  1. Download the JBoss server to deploy the sample application. Once downloaded, unzip the contents of the compressed JBoss archive. This location will be referred as <JBOSS_HOME>.
  2. From the download material included with this article, unzip the copy of the JBoss configuration required for this application from the JBossConfig.zip archive. The location of the extracted contents will be referred as <JBOSS_CONFIG>.
  3. Copy the <JBOSS_HOME>/server/default to a <JBOSS_HOME>/server/dworks folder.
  4. Copy the <JBOSS_CONFIG> folder into <JBOSS_HOME>/server . This will add the configurations to the dworks folder. Click OK when Windows asks if it should merge the folders.

    The following files (required for the sample application) have been added to the dworks configuration:

    • deploy/Derby-ds.xml - Derby datasource configuration in JBoss.
    • deploy/DocumentManager.ear - Application EAR file that is deployed to JBoss. 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.
    • lib/derby.jar and lib/derbyclient.jar - Derby database Java drivers.
  5. Start the new server by running the run.sh –c dworks (on Windows use run.bat) command from the <JBOSS_HOME>\bin directory.
  6. Once the server is started, verify that it is running by opening a web browser and pointing it to http://localhost:8080. You should see the JBoss Welcome window and be able to access the JBoss console.

d. Run the sample application on JBoss

Start JBoss server, if not already started, by navigating to <JBOSS_HOME>/bin and running run.bat. Open a web browser and access http://localhost:8080/document.

Login as an editor with username editor and password 2. A user with valid editor credentials will have access to see EditorXXX.doc documents and an option to upload documents to the system (for display purposes only), as shown in Figure 3.

Figure 3. Editor access
Editor access
Editor access

A user with basic valid user credentials will have access to see only UserXXX.doc documents (Figure 4).

Figure 4. User access
User access
User access

2. Analyze suitability of the application for migrating to Liberty

In this section, you set up the development environment to use for migrating, perform a migration analysis, and identify changes required to move the application to WebSphere Application Server Liberty profile.

a. Install the Eclipse IDE

You first need to establish the original development environment that was used to build the sample application. This same IDE will be used in subsequent sections to analyze the application for porting issues and to migrate the application from JBoss to Liberty.

  1. Download and install the Eclipse Luna for Java EE Developers IDE.
  2. If you don’t have Oracle Java 6 or 7 SDK already installed, download and install the Oracle Java 6 JDK for Linux or Windows.
  3. Set the JAVA_HOME and PATH environment variables.


    On Windows (from the command prompt):

    • Set JAVA_HOME=<jdk6-install-dir>
    • Export JAVA_HOME
    • Set PATH=%JAVA_HOME%\bin;%PATH%
    • Export PATH


    On Linux (from the terminal):

    • Export JAVA_HOME=<jdk6-install-dir>
    • Export PATH=$JAVA_HOME/bin:$PATH

b. Import the sample application

From the download material included with this article, unzip the contents of the OriginalSampleApp.zip archive. The location of the extracted contents will be referred as <SAMPLE_APP>. To import the application into Eclipse:

  1. Start the Eclipse IDE.
  2. From the Eclipse menu select File > Import > General > Existing Projects into Workspace and click Next (Figure 5).
    Figure 5. Import archive file
    Import archive file
    Import archive file
  3. In the Import Projects dialog, check Select archive file and browse to <SAMPLE_APP>. Click Finish (Figure 6).
    Figure 6. Import project
    Import project
    Import project

c. Analyze the application

An overview of the Application Migration Toolkit and Liberty Tech Preview was presented in Part 1 of this series. The Liberty Tech Preview runs on top of the Migration Toolkit and enables you to move from different applications servers - including JBoss, WebLogic Server, Oracle® Application Server, and Apache Tomcat – to the Liberty profile. It also enables you to move from older and current versions of traditional IBM WebSphere Application Server versions to the Liberty profile or to the cloud.

Download and install WebSphere Application Migration Toolkit in Eclipse by navigating to Help > Install New Software… and then click Add… Add this repository location URL:

https://public.dhe.ibm.com/ibmdl/export/pub/software/websphere/wasdev/updates/wamt/MigrationToolkitCompetitive

Eclipse might need to restart during the installation. After the toolkit has been installed, run the Liberty Technology Rule Set against the workspace:

  1. From the Eclipse menu, select the Run > Analysis option.
  2. Create a new Software Analyzer configuration.
  3. For Name, enter a name for the configuration; for example, Liberty Technology Rules.
  4. On the Scope tab, select Analyze entire workspace to scan all projects in the workspace or Analyze selected projects to scan a selection of projects in the workspace (Figure 7).
    Figure 7. Scope tab
    Scope tab
    Scope tab
  5. On the Rules tab, select JBoss Application Migration using the Rule Sets list, and click the Set… button (Figure 8).
    Figure 8. Rules tab
    Rules tab
    Rules tab
  6. For the Target application server, select Other Liberty Editions V8.5.5, and for Target Java version, select either IBM Java 6 or IBM Java 7, depending on your installed Java (Figure 9).
    Figure 9. Rule set configuration
    Rule set configuration
    Rule set configuration
  7. Click OK then Apply.
  8. Click the Analyze button. The tool will analyze the application and generate a list of problems and potential problems in the Software Analyzer Results view.
  9. Review the problems in the Software Analyzer Results view. (We will look at and address these issues later.) Be sure to review the problems in the XML File Review and the Java Code Review tabs.

Table 2 lists the findings detected by the analyzer.

Table 2. Software Analyzer results
TypeIssueComponentDescription
Java, XMLCheck for Hibernate framework DocumentManagerDAO.java, Hibernate.cfg.xml in DocumentManagerHibernate Hibernate framework is used by the application. In general, no further action is needed during migration, but it is recommended to make sure WebSphere Application Server best practices for Hibernate are used before going to production.
XMLJBoss specific files jboss.xml, jboss-web.xmlJBoss specific deployment descriptor information needs to be migrated to be used on Liberty.
XMLUse WebSphere bindings to define EJB JNDI namesjboss.xmlA JNDI name is defined for each EJB home object (as EJB 2.1 mandates). The binding definition needs to be migrated to WebSphere Application Server.
XMLUse WebSphere extensions to define web module context rootjboss.xmlContext root need to be migrated from the JBoss file to WebSphere Application Server web module extensions.
XMLRemote interfaces for Enterprise JavaBeans(EJB) are unavailableejb-jar.xmlRemote EJB interfaces are not supported in the Liberty profile.
XMLEnterprise JavaBeans (EJB) 1.x/2.x unavailableejb-jar.xmlEnterprise JavaBeans (EJB) 1.x/2.x are not supported in Liberty profile or Liberty Core. Upgrade the application to use the EJB 3.1 Lite specification.

3. Migrate from JBoss to Liberty

Next, you want to migrate the development environment, application source code and deployment descriptors, JBoss application server configuration, and JBoss custom JAAS login module. You can then run the application on the Liberty server.

Be aware that this application was migrated “in place,” meaning that the migrated application continued to use the existing database server. At the end of this section, the migrated application is shown running on the lightweight Liberty container.

a. Migrate the development environment

For this migration, you need to install the WebSphere Developer Tools so that you can “hot deploy” your application to Liberty. Begin by starting the JBoss workspace that you imported in the previous section.

  1. Download WebSphere Developer Tools and install into Eclipse.
  2. Next, download the Liberty runtime. Click the Download button to get the installation JAR for the IBM WebSphere Application Server V8.5.5.4 Liberty profile, then run the command java -jar wlp-runtime-8.5.5.5.jar to create a folder called wlp.
  3. Create a new server from Eclipse. From the Server view, right-click New > Server > IBM > WebSphere Application Server Liberty profile, then click Next.
  4. Select Choose an existing installation and browse to the wlp folder you just created. Click Next.
  5. Leave the default settings and click Finish. This will create a Liberty server called defaultServer.

b. Upgrade the specification levels

Upgrade the specification level for the modules in the application. You can modify the project facets to change the module level and Java version for the Eclipse project. These changes will result in the upgrade of deployment descriptors and will enable you to associate the project with a target runtime. Specifying a target runtime includes the supported runtime Java EE libraries to the project’s build path.

  1. To upgrade the EAR project by changing the project facets, right-click on the EAR project and select Document Manager > Properties > Project Facets (Figure 10).
  2. Set the EAR version to 6.0.
  3. From the Runtimes tab, select WebSphere Application Server Liberty Profile and click OK (Figure 10).
    Figure 10. Project facets
    Project facets
    Project facets
  4. To change the project facets for the EJB module, right-click on the EJB project and select DocumentManagerEJB > Properties > Project Facets (Figure 11). Change EJB Module to 3.1 and change Java to 1.7.
  5. From the Runtimes tab, select WebSphere Application Server Liberty Profile and click OK.
    Figure 11. Assign properties to runtime
    Assign properties to runtime
    Assign properties to runtime
  6. To change the project facets for the web module, right-click on DocumentManagerWeb > Properties > Project Facets (Figure 12).
  7. Change Dynamic Web Module to 3.0 and change Java to 1.7.
  8. From the Runtimes tab, select the Liberty Profile entry and click OK.
    Figure 12. Assign properties to runtime
    Assign properties to runtime
    Assign properties to runtime

b. Migrate the application code

EJB 1.x/2.x and JAX-RPC represent two of the major challenges when porting Java EE applications to the Liberty profile. Both of these technologies were pruned from the Java EE specification and have not yet been implemented in Liberty. Because we see many more clients using EJB 1.x/2.x than JAX-RPC, we will show the migration of EJB 1.x/2.x here. (You can read this article to learn more about migrating your JAX-RPC web services to JAX-WS.)

Let’s look at upgrading the stateless session bean from EJB 2.1 to EJB 3.1. There are many ways to upgrade EJBs from 2.x to 3.x. The steps below illustrate one such way with no interface view:

  1. Implement session bean changes

    The session bean class org.apache.geronimo.samples.document.ejb.DocumentManagerBean implements the SessionBean interface. The session bean class has an ejbCreate() method, three business methods (upload(), getFilesByUserid(), addUserFile()) and the callback methods, shown in Listing 1.

    Listing 1. EJB 2.x stateless session bean
    package org.apache.geronimo.samples.document.ejb;
           
           ...
           
           public class DocumentManagerBean implements javax.ejb.SessionBean {
           
           private static final long serialVersionUID = 5910882211249828856L;
           
           public String upload() {
           return "File successfully uploaded";
           }
           
           public List<UserFile> getFilesByUserid(String userid) {
            List<UserFile> list = null;
             try {
             DocumentManagerDAO dmDao = new DocumentManagerDAO();
             list = dmDao.getUserFilesByUserid(userid);
             } catch (Exception e) {
             // TODO Auto-generated catch block
             e.printStackTrace();
             }
             return list;
             }
             
             public void addUserFile(String userId, String filename) {
             DocumentManagerDAO dmDao;
             
             try {
             dmDao = new DocumentManagerDAO();
             dmDao.addUserFile(userId, filename);
             } catch (Exception e) {
             // TODO Auto-generated catch block
             e.printStackTrace();
             }
             }
             
             // Life cycle calls implementation
             ...
             }

    EJB 3.1 bean classes do not implement javax.ejb.SessionBean. Therefore, the lifecycle methods need not be implemented. A stateless session bean is specified with annotation @Stateless, and a stateful session bean with annotation @Stateful.

    The migrated EJB 3.1 session bean (DocumentManagerBean.java), corresponding to the EJB 2.1 stateless session bean, is shown in Listing 2. Be aware that since you are converting the EJB2.x bean to the EJB3 no interface view, there is no need to carry over the EJB2.x remote interface or the EJB2.x remote home interface, and therefore these interfaces can be deleted:

    • org.apache.geronimo.samples.document.ejb.DocumentManager
    • org.apache.geronimo.samples.document.ejb.DocumentManagerHome
    Listing 2. EJB 3.1 stateless session bean with no interface view
    package org.apache.geronimo.samples.document.ejb;
           import java.util.List;
           
           import javax.ejb.Stateless;
           
           import org.apache.geronimo.samples.document.dao.DocumentManagerDAO;
           import org.apache.geronimo.samples.document.hibernate.UserFile;
           
           @Stateless
           public class DocumentManagerBean{
           
           public String upload(String userId, String filename) {
           addUserFile(userId, filename);
           return "File successfully uploaded";
           }
           
           public List<UserFile> getFilesByUserid(String userid) {
            List<UserFile> list = null;
             try {
             DocumentManagerDAO dmDao = new DocumentManagerDAO();
             list = dmDao.getUserFilesByUserid(userid);
             } catch (Exception e) {
             // TODO Auto-generated catch block
             e.printStackTrace();
             }
             return list;
             }
             private void addUserFile(String userId, String filename) {
             DocumentManagerDAO dmDao;
             
             try {
             dmDao = new DocumentManagerDAO();
             dmDao.addUserFile(userId, filename);
             } catch (Exception e) {
             // TODO Auto-generated catch block
             e.printStackTrace();
             }
             }
             }
  2. Inject session bean into servlets

    There are two servlets in this application: UploadServlet and RetrieveServlet. The changes to these servlets are two-fold:

    • First, you annotated the servlet class with the @WebServlet annotation to indicate classes that are servlets.
    • Second, you used the @EJB annotation to inject the EJB rather than doing the JDBC lookup of the home interface. Homes are not required in EJB3.

    Another option would have been to annotate the EJB3 beans with the @LocalHome annotation and to continue doing the home lookup in the servlet. However, the Liberty Server does not currently support these annotations. Perhaps later versions of Liberty will support the EJB2 client view, but for now, you upgraded the servlets to use the @EJB annotation, instead of EJB2 home lookups. (See Related topics for more EJB2.x to EJB3 migration options.)

    Listing 3 illustrates the changes you made to the UploadServlet class: First, you added the @WebServlet annotation above the servlet class, added the @EJB annotation to inject the session bean into the servlet, and removed the JNDI home lookup in the init() method. You also removed the call to the create() method to create the EJB bean instance. The changes to the RetrieveServlet are similar and are not shown in this article. (You can the download the migrated workspace from the MigratedSampleApp.zip file to see both of these servlets.)

    Listing 3. UploadServlet
    package org.apache.geronimo.samples.document.web;
           
           import java.io.IOException;
           …
           
           @WebServlet({"/UploadServlet"})
           public class UploadServlet extends HttpServlet{
           
           private static final long serialVersionUID = -2773446199481416101L;
           @EJB
           private DocumentManagerBean docManager;
           
           protected void doGet(HttpServletRequest req, HttpServletResponse res) throws ServletException, IOException {
           String filename = req.getParameter("file");
           String userID = req.getUserPrincipal().getName();
           req.setAttribute("result", docManager.upload(userID, filename));
           req.getRequestDispatcher("jsp/main.jsp").forward(req, res);
           }
           
           protected void doPost(HttpServletRequest req, HttpServletResponse res) throws ServletException, IOException {
           doGet(req, res);
           }
           }

d. Migrate the JBoss configuration

Now that the application coding changes are complete, you can use the configuration migration toolkit from Part 2 to create the Liberty configuration from the JBoss configuration. (If you don’t already have the WebSphere Configuration Migration tool installed, you can get it here.)

  1. From the Migration Tools menu, choose WebSphere Application Server Migration > Configuration Migration > WebSphere Configuration Migration Tool for JBoss (Figure 13).
    Figure 13. WebSphere Configuration Migration
    WebSphere Configuration Migration
    WebSphere Configuration Migration
  2. In the WebSphere Configuration Migration dialog, click Browse… and choose your server home folder; for example, <JBOSS_HOME>\dworks. Click Next (Figure 14).
    Figure 14. WebSphere Configuration Migration Toolkit
    WebSphere Configuration Migration Toolkit
    WebSphere Configuration Migration Toolkit
  3. On the Specify target environment panel, select WebSphere Application Server Liberty profile and click Next.
  4. If you expand each item in the tree, you see its configuration resources. Some of those settings come from the default JBoss configuration, and you don’t need them for your application to work.
  5. Uncheck all resources except JDBCProvider: jdbc_DerbyDS and WebSphere Variables : VariableSubstitutionEntry: DERBY_JDBC_DRIVER_PATH. The other values are not needed by this application.
  6. In the VariableSubstitutionEntry:DERBY_JDBC_DRIVER_PATH, provide the folder that contains the Derby JDBC driver. The final selection should look something similar to Figure 15.
    Figure 15. Review issues found
    Review issues found
    Review issues found
  7. Click Next.
  8. The final screen of the wizard contains the generated server.xml. Click Save File… and save the server.xml file on your local disk. You will copy this file later to replace the server.xml file for the Liberty server.
  9. Click Finish to end the wizard. The generated server.xml should look like Listing 4.
    Listing 4. Server.xml
          <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
          <server>
          <featureManager>
          <feature>jsp-2.2</feature>
          <feature>jdbc-4.0</feature>
          </featureManager>
          <jdbcDriver id="jdbc_DerbyDS" javax.sql.DataSource="org.apache.derby.jdbc.ClientConnectionPoolDataSource">
          <library>
          <file name="${DERBY_JDBC_DRIVER_PATH}/derbyclient.jar"/>
          </library>
          </jdbcDriver>
          <dataSource id="jdbc_DerbyDS" jndiName="jdbc/DerbyDS" jdbcDriverRef="jdbc_DerbyDS">
          <properties.derby.client databaseName="sampledb" maxPoolSize="20" minPoolSize="5" jndiname="jdbc/DerbyDS" connectionUrl="jdbc:derby://localhost:1527/sampledb;create=false" driverClass="org.apache.derby.jdbc.ClientDriver" driver="org.apache.derby.jdbc.ClientDriver" URL="jdbc:derby://localhost:1527/sampledb;create=false" idleTimeoutMinutes="5" create="false" url="jdbc:derby://localhost:1527/sampledb;create=false"/>
          </dataSource>
          <variable name="DERBY_JDBC_DRIVER_PATH" value=" C:\db-derby-10.11.1.1-bin\lib"/>
          </server>

e. Update the Liberty Server configuration

Although the configuration migration toolkit gets you a server.xml file with the JBoss resources, you still need to add a few of the features that are required by the application. As a lightweight container, Liberty only adds those features that are required by your application. The configuration migration toolkit cannot determine the features that your application uses, so you must add them to the Liberty server.xml file as shown in Listing 5. The features that are required based on the configuration are added automatically, but the features required by the application (shown in bold) must be added manually.

Listing 5. Add features to server.xml
     <featureManager>
     <feature>ejbLite-3.1</feature>
     <feature>appSecurity-2.0</feature>
     <feature>servlet-3.0</feature>
     <feature>jsp-2.2</feature>
     <feature>jdbc-4.0</feature>
     </featureManager>

f. Map roles to users and groups in Liberty

The JBoss service archive defines the users and groups, and stores them in a couple of files. SAR is a proprietary JBoss archive that contains authentication and authorization configuration (for example, users, groups, and so on). In JBoss, there is no way to map the roles that are used in the web.xml file to the users and groups that are defined in the service archive. That is, the same names are used for both.

Mapping roles to users and groups in Liberty is a three step process. First, you define the users and groups (the user registry) in the server.xml file, then you define the mapping of the roles (defined in the web.xml file) to the groups defined in the ibm-application-bnd.xml file registry, and at that point you can then remove the proprietary JBoss SAR project:

  1. Configure a basic user registry with user and editor entries. The group and user information is coming from the j2g_groups.properties and the j2g_users.properties files in the SAR project (Listing 6).
    Listing 6. Add basicRegistry to server.xml
           <basicRegistry id="basic" realm="sampleRealm">
           <user name="user" password="1" />
           <user name="editor" password="2" />
           <group name="authenticated">
           <member name="user" />
           <member name="editor" />
           </group>
           <group name="uploader">
           <member name="editor" />
           </group>
           </basicRegistry>
  2. Configure the application bindings that map roles to users or groups in the user registry or to special subjects (Listing 7).
    Listing 7. Map security roles to groups using Server.xml
           <application type="ear" id="DocumentManager" name="DocumentManager"
           location="${server.config.dir}/apps/DocumentManager.ear">
           <application-bnd>
           <security-role name="authenticated">
           <special-subject type="ALL_AUTHENTICATED_USERS" />
           </security-role>
           <security-role name="uploader">
           <group name="uploader" />
           </security-role>
           </application-bnd>
           </application>
  3. Remove the SAR project from the EAR. Right click the DocumentManagerSAR project and click Delete. Select the Delete project contents on disk check box and click OK.

g. Migrate the Hibernate configuration

The final step it to migrate the Hibernate configuration. In this application, the Hibernate configuration is kept in a hibernate.cfg.xml file located in the DocumentManagerHibernate/src folder, along with the other Hibernate mapping files.

You need to make only minimal changes in the configuration to deploy the application to the Liberty profile:

  1. Open hibernate.cfg.xml in DocumentManagerHibernate/src and switch to the Source view.
  2. Change the connection.datasource property from java:jdbc/DerbyDS to jdbc/DerbyDS.
  3. Change the transaction.manager_lookup_class property to use the WebSphere lookup class org.hibernate.transaction.WebSphereExtendedJTATransactionLookup.

This article contains more details about using Spring and Hibernate with Liberty.

h. Deploy and test the application on Liberty

  1. Export the DocumentManager Project as an EAR file called DocumentManager.ear.
  2. Save the DocumentManager.ear file in the server’s apps folder (Figure 16).
    Figure 16. Deploy project
    Deploy project
    Deploy project
  3. Start the Liberty Server. In a web browser, navigate to the application URL: http://localhost:9080/document/. Make sure your Derby database is still running.
  4. Login as user or editor with the correct credentials, as specified in server.xml.
  5. After successful login, the application redirects to the Documents page. Observe that only the editor can upload the documents based on security role mappings (Figure 17).
    Figure 17. Editor login
    Editor login
    Editor login
    Figure 18. User login
    User login
    User login
    Figure 19. Invalid login
    Invalid login
    Invalid login

Conclusion

This tutorial showed you how to take an old heavyweight JBoss application that was coded to the J2EE 1.4 specification and move it without incident to the IBM WebSphere Application Server Liberty lightweight container profile. It also showed how to use the Liberty Technology Preview to identify any porting issues so you could very quickly make the decision as to whether or not this application was a good fit for the Liberty lightweight container. Finally, it showed you how to take an existing JBoss server configuration and move it to Liberty. This enables you to very quickly migrate not only the application code, but also the server configuration required for running that application.

You also took on a few of the challenging issues that you could face, such as migrating custom JAAS login modules or EJB2 beans and clients. In most cases, EJB2 can migrate fairly straightforward to EJB3, with the exception of CMP beans. In addition, links to other resources were provided that might help you with migrations to EJB3, migrations from JAX-RPC to JAX-WS, and migrations of Spring and Hibernate applications.

Following the guidelines in this article series can help you modernize your applications by moving them from old heavyweight containers like JBoss to the modern Liberty lightweight container.


Downloadable resources


Related topics


Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Middleware, Cloud computing
ArticleID=1008253
ArticleTitle=Making the move to the Liberty profile, Part 3: Migrating a JBoss application to Liberty
publish-date=06172015