Convert Java-based applications to the OSGi framework with Rational Application Developer tools

Use included tools to convert projects to use the OSGi application framework

Gain flexibility, control, and efficiency when you convert Java-based enterprise applications to the OSGi framework. New tools in IBM® Rational® Application Developer Version 8.0 help you create OSGi bundles to export services, run processes, and manage dependencies. This article describes different approaches.

Ken McClamroch (klmcclam@us.ibm.com), Senior Software Engineer, IBM

Author photoKen is a system and integration test architect for IBM Rational software. He spent the last seven years focused on scenario-based testing, building end-to-end applications using a variety of technologies, including Java Enterprise Edition (JEE), SCA, and OSGi.



Jarett Stein (jastein@us.ibm.com), Staff Software Engineer, IBM

Jarett SteinJarett Stein is a member of the Rational Application Developer System Verification Test team. He emulates customer use of IBM Rational products by designing end-to-end applications using OSGi, web, and JPA (Java Persistence API) technology tools.



14 December 2010

Also available in Chinese

What developers can learn from this article

This article describes how to use the new OSGi development tools included with IBM® Rational® Application Developer Version 8.0 to convert existing Java Enterprise Edition (JEE) applications to OSGi applications. (OSGi meant "Open Service Gateway initiative" before the scope expanded beyond service gateways.) These tools, combined with the WebSphere Application Server Version 7 Feature Pack for OSGi Applications, provide the support to develop and deploy OSGi enterprise applications with capabilities similar to that of Java EE applications.

An OSGi application can consist of the same modules deployed in a Java EE project, but includes OSGi metadata that enables the modules to be loaded as OSGi bundles, thereby benefiting from the bundle management mechanisms provided by the OSGi framework. There are several reasons why Java EE developers might choose to move toward OSGi for enterprise application development:

  • Applications can be deployed as bundles that contain only the application-specific content, along with the metadata that references any dependent, shared libraries. As a result, the application space is reduced, because it leverages the single copies of common libraries managed by the bundle repository. This capability removes the tendency of Java EE applications to have the same JAR (Java Archive) files embedded within many enterprise applications.
  • At development time, the OSGi development tools included with Rational Application Developer v8.0 enforce OSGi visibility rules to ensure that package dependencies are explicitly declared, which minimizes potential runtime issues when deployed.
  • Multiple versions of classes can be loaded simultaneously in the same application using standard OSGi mechanisms.
  • Applications can use their own versions of common utility classes, so you do not need to configure application Java EE classloader policies (for example, PARENT_LAST mode).
  • Deployed applications can be dynamically updated at the bundle level without redeploying the entire enterprise archive.

The purpose of this article is to help Java EE developers begin to leverage these OSGi capabilities by converting existing Java EE applications to OSGi-based applications. To that end, we will use the "JPA JSF Employee List" sample included with Rational Application Developer to demonstrate how to take an existing Java EE web project and use the OSGi conversion tools to organize the application into OSGi bundles for deployment as an OSGi application. The article demonstrates the following three separate OSGi configurations, each of which can be deployed and tested on a WebSphere Application Server:

  • Single converted OSGi bundle containing JPA
  • Multiple converted OSGi bundles separating web and data persistence layers
  • Java EE web project (.war) with converted JPA OSGi bundle

The article also discusses these Rational Application Developer OSGi development tools:

  • OSGi project conversion tools to convert existing modules to OSGi bundles
  • OSGi manifest editors
  • OSGi application and bundle-creation wizards
  • OSGi deployment to IBM WebSphere Application Server

Requirements

Before proceeding with the steps that follow, you need the following configuration installed and launched on your workstation:

  • IBM Rational Application Developer v8.0 with the "OSGi Development Tools" feature already installed
  • IBM WebSphere Application Server v7.0 with the OSGi Applications feature pack already installed

Import the JPA JSF Employee List sample application

Begin by importing the "JPA JSF Employee List" sample application:

  1. Select Help menu > Help Contents.
  2. In the Help window's Contents section, expand Samples > Faces and select JPA JSF Employee List application.
  3. Click Import the Sample and an Import Projects window will launch.
  4. In the Import Projects window, click Finish.

The EmployeeListWeb and EmployeeListWebEAR projects will import to your workspace.

  1. (Optional) Switch to the web perspective when you are prompted.

If you cannot access the sample application from the Help, you will find a .zip of the sample below in the file EmployeeListSample.zip

Verify the JPA JSF Employee List sample application functions as expected:

  1. After it is imported, the EmployeeListWeb application will have an error on the persistence.xml file. This error will appear in the Errors view. Double-click the error to open persistence.xml file.
  2. Locate the ConnectionURL property in the persistence.xml file:
    <property name="openjpa.ConnectionURL" value="jdbc:derby:<workspace_location>\EmployeeListWeb\WebContent\sample" />
  3. Change the <workspace_location> text to the location of your workspace, for instance:
    <property name="openjpa.ConnectionURL" value="jdbc:derby:c:\osgiDevWorksTutorial1\EmployeeListWeb\WebContent\sample" />
  4. Run index.jsp inside the EmployeeListWeb application on a WebSphere Application Server v7.0. In the Web Content folder in EmployeeListWeb, right-click the index.jsp file, and select Run > Run on Server.
  5. Select WebSphere Application Server v7.0 and click Finish.
  6. The sample site should launch in the internal browser at this location:
    http://localhost:<port>/EmployeeListWeb/index.faces
  7. The site should be functional. For instance, you should be able to click List all employee records and see a list of employees.
  8. Remove the application from the server before proceeding to the next section.

Single converted OSGi bundle containing JPA

First, we will demonstrate the example where an existing Web Application containing JPA is converted to an OSGi Web Application Bundle and deployed with an OSGi Application. Now that the sample application is working, we will use the OSGi tools to convert the sample JEE web project to an OSGi application containing a single OSGi bundle with web and JPA support.

Convert the sample application to an OSGi bundle

  1. Right click EmployeeListWeb and from the context menu select Configure > Convert to OSGi Bundle Project.

You will be prompted with this warning shown in Figure 1.

Figure 1. Project conversion to OSGi warning
The conversion cannot be undone. Proceed?
  1. Select OK to confirm the conversion from a JEE web project to an OSGi bundle.
  2. The following will occur:
    1. A bundle manifest has been created at WebContent/META-INF/manifest.mf.
    2. In the EmployeeListWeb project's properties, an OSGi Bundle facet has been added.
    3. The EmployeeListWeb project is no longer a module in EmployeeListWebEAR

The bundle manifest is listed in the EmployeeListWeb project. You can double-click Manifest: EmployeeListWeb to open the Bundle Manifest Editor.

Figure 2. Converted EmployeeListWeb project, now a bundle
Web bundle showing Manifest and bundle icon
  1. The bundle manifest automatically adds JSF project JARs (contained in WebContent/WEB-INF/lib) to the bundle-classpath and adds the necessary java class imports to the list of import packages

Comparison of the manifest before and after the conversion

Before conversion:

Listing 1. Web project manifest
Manifest-Version: 1.0
Ignore-Scanning-Archives: jsf-ibm.jar, icu4j_3_4_1.jar

After conversion:

Listing 2. Web bundle manifest after conversion
Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: EmployeeListWeb
Bundle-SymbolicName: EmployeeListWeb
Bundle-Version: 1.0.0.qualifier
Bundle-ClassPath: WEB-INF/classes,
    WEB-INF/lib/icu4j_3_4_1.jar,
    WEB-INF/lib/jsf-ibm.jar,
    WEB-INF/lib/sitelib.jar,
    WEB-INF/lib/web-jpa.jar
Ignore-Scanning-Archives: jsf-ibm.jar,
    icu4j_3_4_1.jar
Bundle-RequiredExecutionEnvironment: JavaSE-1.6
Meta-Persistence: 
Web-ContextPath: /EmployeeListWeb
Import-Package: javax.faces.application,
    javax.faces.validator,
    org.apache.commons.logging;resolution:=optional,
    javax.faces.convert,
    javax.faces.render,
    javax.servlet.jsp;version="2.0",
    javax.persistence;resolution:=optional,
    javax.servlet.http;version="2.5",
    javax.faces.event,
    javax.faces.component.html,
    javax.servlet;version="2.5",
    javax.faces.component,
    javax.servlet.jsp.tagext;version="2.0",
    javax.servlet.jsp.el;version="2.0",
    javax.faces.el,
    javax.faces.model,
    javax.faces.lifecycle,
    javax.faces.webapp,
    javax.faces,
    javax.faces.context,
    javax.el;version="2.0";resolution:=optional

Create the OSGi application

In order to deploy the OSGi bundle to WebSphere Application Server, first you need to create an OSGi application to contain the OSGi bundle for deployment.

  1. Select File > New > Other.
  2. In the New Project dialog, expand OSGi and select OSGi Application Project. Click Next.
  3. Enter a project name, for instance EmployeeListApp, verify that WebSphere Application Server v7.0 is set as the runtime target, and click Finish.

EmployeeListApp will be listed in the Enterprise Explorer view, expand it and double click Manifest: EmployeeListApp to open the OSGi Application Manifest editor. There will be a warning on the manifest until a bundle is added in the next step.

Figure 3. OSGi Application Manifest editor
OSGi Application Manifest editor for EmployeeListApp
  1. In the Contained Bundles section, click Add.
  2. Select EmployeeListWeb 1.0.0 and click OK. The warning will resolve.
  3. Save and close the EmployeeListApp manifest editor.

Create a data source on the server

Data sources need to be manually created on WebSphere Application Server before deploying the OSGi application. In the imported sample JEE application, Rational Application Developer includes the data source when publishing the EAR to the WebSphere Application Server. However, for the OSGi variant, Rational Application Developer Version 8.0 does not currently support publishing data sources when deploying OSGi applications. Additionally, both a JTA and non-JTA datasource must be specified to make this application portable across JPA providers.

  1. If WebSphere Application Server v7.0 is not started, start it.
  2. In the Servers view, right click WebSphere Application Server v7.0 and, from the drop-down menu, select Administration > Run Administrative Console to launch the console.
  3. In the Administrative Console, on the left side, expand Resource > JDBC and then click JDBC Providers.
  4. Click the existing Derby JDBC Provider resource to verify that t has been created by default on your application server.
  5. Click the Data sources link.
  6. Click New to create a new data source.
  7. Create the new JTA data source with the following properties:
    1. In Step 1 of the Data Source wizard, set JNDI Name to jdbc/sample.
    2. In Step 2 of the Data Source wizard, set the Database Name to the location of the sample database in your workspace, for example: c:\osgiDevWorksTutorial1\EmployeeListWeb\WebContent\sample
    3. Accept the default settings for all other entries, and finish the new Data Source wizard.
  8. Create the new non-JTA data source with the following properties:
    1. In Step 1 of the Data Source wizard, set JNDI Name to jdbc/sample-nonjta.
    2. In Step 2 of the Data Source wizard, set the Database Name to the location of the sample database in your workspace, for example: c:\osgiDevWorksTutorial1\EmployeeListWeb\WebContent\sample
    3. Accept the default settings for all other entries, and finish the new Data Source wizard.
    4. Open the non-jta data source configuration page, click WebSphere Application Server data source properties, select the checkbox Non-transactional data source, and save your changes.
  9. Test the data source connection to verify that it has been created successfully.

Set up the bundle to access the server

Now that the data source is set up in the WebSphere server, the OSGi bundle needs to be set up to access it. To do this, set up EmployeeListWeb bundle to access data source on server by modifying persistence.xml in the EmployeeListWeb project to point to a data source defined on the server. Follow these steps:

  1. In the Enterprise Explorer view, expand EmployeeListWeb > JPA Content, double click persistence.xml to open it in the Persistence XML Editor.
  2. Click to the Design tab if you see the persistence.xml source.
  3. In the Overview section on the left side of the editor, expand Persistence and click Persistence Unit (EmployeeListWeb).
  4. Set the Details section:
    • JTA Data Source: jdbc/sample
    • Non JTA Data Source:jdbc/sample-nonjta
  5. In the Overview, expand Persistence > Persistence Unit > Properties.
  6. Remove the three properties by highlighting the property and clicking the Remove button.
  7. Add a property by selecting Properties, click the Add button, select Property and press OK.
  8. Set the properties:
    • Name:openjpa.jdbc.Schema
    • Value:SAMP
  9. Click to the Source view.

Listing 3 shows what the persistence source now looks like.

Listing 3. Persistence.xml after modification
<?xml version="1.0" encoding="UTF-8" ?>
    <persistence version="2.0"
        xmlns="http://java.sun.com/xml/ns/persistence" 
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://java.sun.com/xml/ns/persistence 
     http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd">
        <persistence-unit name="EmployeeListJPA">
            <jta-data-source>jdbc/sample</jta-data-source>
            <non-jta-data-source>jdbc/sample-nonjta</non-jta-data-source>
            <class>employee.list.Department</class>
            <class>employee.list.Employee</class>
            <properties>
                <property name="openjpa.jdbc.Schema" value="SAMP" />
            </properties>
        </persistence-unit>
    </persistence>
  1. Save and close the Persistence XML editor.

Deploy and run the OSGi application

Now everything is set up to deploy and run the EmployeeListWeb sample application after conversion to an OSGi application and contained bundle. Because everything is contained in a single web bundle, the JPA runtime will work as it would in any JEE module created in Rational Application Developer.

  1. Publish EmployeeListApp to the WebSphere Application Server v7.0. Notice that the contained bundle is displayed beneath the OSGi application.
Figure 4. Add and Remove to server dialog
EmployeeListApp in the Add to Server dialog

Note:
EmployeeListWebEAR will still exist as a project in your workspace and will contain errors saying that the EmployeeListWeb.war file cannot be found. You can either ignore or delete the EAR file.

  1. Run index.jsp inside the EmployeeListWeb application on WebSphere Application Server v7.0. In the Web Content folder in EmployeeListWeb, right-click index.jsp and select Run > Run on Server.
  2. Select WebSphere Application Server v7.0, and click Finish.
  3. The sample site should launch in the internal browser at this location:
    http://localhost:<port>/EmployeeListWeb/index.faces

The site should be functional. For instance, you should be able to click List all employee records and see a list of employees.

Figure 5. Example page, which lists all employees
all_employees JSF page showing list from database
  1. Remove the application from the server and delete all projects in your workspace before proceeding to the next section. Alternative: Keep the existing variation in the current workspace and continue with the next variation in a new Rational Application Developer workspace.

JPA in a separate bundle

In this example, the persistence layer will be contained in its own OSGi JPA bundle and accessed from the OSGi web bundle. In general it is better to have the JPA persistence layer in its own bundle (and hence project). That way, JPA entities are managed in one place and can be used as a data layer by many projects, rather than each project containing its own JPA entities and manager beans. When separating web and persistence concerns it is desirable to have an application container continue to manage the lifecycle of JPA resources such as EntityManagers. In an OSGi application this can be achieved using POJO Blueprint components, whose JPA resources may be injected into them by their container.

OSGi modules, like Java EE modules, may choose to manage their own JPA resources and the JSF JPA Employee List sample we are building from uses unmanaged JPA in its Web module. The focus of this section of the article is to describe how to use application-managed JPA to provide the same capabilities to an application converted to OSGi bundles.

Import the sample modified to split JPA

Import the EmployeeListSample-Part2Begin.zip file (see Downloads) to your Rational Application Developer workspace as an existing project:

  1. Select File > Import.
  2. Select General > Existing Projects into Workspace.
  3. In the Import dialog window, select the Select Archive File radio button.
  4. Click Browse and locate the EmployeeListSample-Part2Begin.zip file. Select the file and click Open. You should see the full path to the .zip file in the field beside the Browse button.
  5. Click Finish.

In these projects, the JPA entities have already been copied into a separate JPA project and persistence unit. This is essentially the JPA JSF Employee List sample application, but the JPA entities and manager beans are in their own project. Additionally, the persistence.xml file in the EmployeeListJPA project has already been set up to use the jdbc/sample data source on the server you created in the section above. Assuming the data source is configured on the server to access the sample database contained in the EmployeeListWeb project and you are using the sample workspace location, the project is ready to deploy and test by running index.jsp on your server like was done above.

Convert projects to OSGi bundles

First, convert the JPA project to an OSGi JPA bundle:

  1. Right click the EmployeeListJPA project and, from the drop-down menu, select Configure > Convert to OSGi Bundle Project.

You will be prompted with the warning shown in Figure 6.

Figure 6. Project conversion to OSGi warning
Converting to OSGi cannot be undone. Proceed?
  1. Select OK to confirm the conversion from JPA project to OSGi bundle.

The following will then occur:

  • In src/META-INF, there is now a bundle manifest file, MANIFEST.MF.
  • An OSGi Bundle facet has been added to this project. This makes the JPA project a JPA bundle.
  • In the MANIFEST.MF file:
    • The entity and entity manager bean packages have been added as export-packages. This makes it so they are available to import by other bundles and, in this case, so the JPA entities can be accessed and data manipulated.
    • Necessary imports for the existing classes have been added to the import-packages.

The resulting manifest should look similar to what Listing 4 shows.

Listing 4. JPA bundle manifest after conversion
Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: EmployeeListJPA
Bundle-SymbolicName: EmployeeListJPA
Bundle-Version: 1.0.0.qualifier
Bundle-RequiredExecutionEnvironment: JavaSE-1.6
Meta-Persistence: 
Export-Package: employee.list.controller,
    employee.list
Import-Package: javax.persistence;resolution:=optional,
javax.faces.model;resolution:=optional

Convert the web project

Next, convert the web project to an OSGi web bundle:

  1. Right-click EmployeeListWeb and, from the drop-down menu, select Configure > Convert to OSGi Bundle Project.

Again, you will be prompted with the warning that the conversion cannot be undone and asked to confirm that you want to proceed (Figure 7).

Figure 7. Project conversion to OSGi warning
Converting to OSGi cannot be undone. Proceed?
  1. Select OK to confirm the conversion from JEE web project to an OSGi bundle.

The following will occur:

  • In the EmployeeListWeb project's properties, an OSGi Bundle facet has been added.
  • A bundle manifest has been created at WebContent/META-INF/manifest.mf.
  • The EmployeeListWeb project is no longer a module in EmployeeListWebEAR

Note:
EmployeeListWebEAR will still exist as a project in your workspace and will contain errors saying "A Java EE Enterprise Application must contain one or more modules."

  • The bundle manifest is listed in the EmployeeListWeb project. You can double-click Manifest: EmployeeListWeb to open the Bundle Manifest Editor.
  • The bundle manifest automatically adds JSF project JAR files (contained in WebContent/WEB-INF/lib) to the bundle-classpath.
  • The bundle manifest automatically adds Java class imports to the list of import packages, including imported entity classes that are resolved to the exports from the JPA bundle.

The resulting bundle manifest should look similar to Listing 5.

Listing 5. Web bundle manifest after conversion
Manifest-Version: 1.0
    Bundle-ManifestVersion: 2
    Bundle-Name: EmployeeListWeb
    Bundle-SymbolicName: EmployeeListWeb
    Bundle-Version: 1.0.0.qualifier
    Bundle-ClassPath: WEB-INF/classes,
     WEB-INF/lib/icu4j_3_4_1.jar,
     WEB-INF/lib/jsf-ibm.jar,
     WEB-INF/lib/sitelib.jar,
     WEB-INF/lib/web-jpa.jar,
     WEB-INF/lib/EmployeeListJPA.jar
    Ignore-Scanning-Archives: jsf-ibm.jar,
      icu4j_3_4_1.jar
    Bundle-RequiredExecutionEnvironment: JavaSE-1.6
    Web-ContextPath: /EmployeeListWeb
    Import-Package: javax.faces.application,
     javax.faces.validator,
     org.apache.commons.logging;resolution:=optional,
     javax.faces.convert,
     javax.faces.render,
     javax.servlet.jsp;version="2.0",
     javax.servlet.http;version="2.5",
     javax.faces.event,
     employee.list.controller;resolution:=optional,
     javax.faces.component.html,
     javax.servlet;version="2.5",
     javax.faces.component,
     javax.servlet.jsp.tagext;version="2.0",
     javax.servlet.jsp.el;version="2.0",
     javax.faces.el,
     javax.faces.model,
     javax.faces.lifecycle,
     javax.faces.webapp,
     javax.faces,
     employee.list;resolution:=optional,
     javax.faces.context,
javax.el;version="2.0";resolution:=optional

The Bundle Manifest editor also provides visual representation of the manifest. Figure 8 shows an example of the Imported Packages from EmployeeListWeb's bundle manifest.

Figure 8. Bundle manifest editor Dependencies page
Imported packages shown in manifest editor

Finally, you need to remove the project dependency between the EmployeeListWeb and EmployeeListJPA projects. When the projects were JEE projects there was a dependency between EmployeeListWeb and EmployeeListJPA defined in the Web project's properties so JPA entities could be resolved by the web project. As the projects were converted to bundles the entity classes were added as export-packages in the JPA bundle and import-packages in the Web bundle. This duplicate dependency between projects, as an OSGi and Plug-in dependency, needs to be resolved. Follow these steps:

  1. Right-click EmployeeListWeb, and select Properties.
  2. In the Properties dialog window, go to the Deployment Assembly page.
  3. Select the EmployeeListJPA.jar entry and click Remove.
  4. Click OK in the Properties dialog window to accept this change.

Now the dependency only exists as a plug-in dependency between bundles.

Modify JPA Manager Beans

Inside the EmployeeListJPA bundle, the JPA manager beans, which are essentially facade beans for the JPA entity beans, need to be modified for the OSGi environment. In this OSGi example, where application-managed JPA entity manager beans will be used, we need to obtain an application-managed persistence unit via an OSGi service lookup. In a managed JPA example, a Java EE application's persistence unit can be injected by the container through the @PersistenceUnit annotation. Similarly, an OSGi application making use of blueprint managed JPA beans, would inject the persistence units into its blueprint component. A practical application and example of a managed JPA Java EE application moving to OSGi blueprint container managed beans is outside the scope of this article.

In the application-managed JPA example we are exploring, if the OSGi service registry lookup was not added to the JPA entity manager bean, WebSphere would not be able to resolve the persistence unit, and you would see the error shown in Listing 6 at runtime as your web page tried to access JPA data and lookup the persistence unit.

Listing 6. Error if @PersistenceUnit is used in the JPA manager bean
Error 500: javax.servlet.ServletException: javax.faces.el.EvaluationException: 
javax.el.ELException: <openjpa-2.0.0-r422266:935683 fatal user error> 
org.apache.openjpa.persistence.ArgumentException: A JDBC Driver or Data source 
class name must be specified in the ConnectionDriverName property.

In addition, because the original sample application creates unmanaged EntityManagerFactory instances, the persistence-unit transaction-type defaults to RESOURCE_LOCAL rather than JTA. Because we are now using application-managed JPA, which has a different default, we now need to specify this in the persistence.xml file. See Listing 7 below for what the persistence.xml file looks like after transaction-type="RESOURCE_LOCAL" (in bold) is added to the persistence.unit.

Listing 7. Perstistence.xml after adding type="RESOURCE_LOCAL"
<?xml version="1.0" encoding="UTF-8"?>
<persistence version="2.0" xmlns="http://java.sun.com/xml/ns/persistence" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://java.sun.com/xml/ns/persistence 
http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd">
	<persistence-unit name="EmployeeListJPA" transaction-type="RESOURCE_LOCAL">
			<jta-data-source>jdbc/sample</jta-data-source>
			<non-jta-data-source>jdbc/sample-nonjta</non-jta-data-source>
		<class>employee.list.Department</class>
		<class>employee.list.Employee</class>
		<properties>
			<property name="openjpa.jdbc.Schema" value="SAMP"/>
		</properties>
	</persistence-unit>
</persistence>

To modify the JPA manager beans:

  1. Open the Employee entity manager bean, EmployeeManager.java, which you can find at EmployeeListJPA/src/employee/list/controller.
  2. In the EmployeeManager class, locate the getEntityManager() method.

Perform an OSGi service registry lookup on the JPA EntityManagerClass, and set the persistence unit so that it is accessible in the OSGi context.

  1. In the getEntityManager() method, replace the contents with the code in Listing 8.
Listing 8. New getEntityManager() method contents
try  {
                emf = (EntityManagerFactory) new 
InitialContext().lookup("osgi:service/javax.persistence.EntityManagerFactory/
(osgi.unit.name=EmployeeListJPA)");
                } catch (NamingException e) {
                    // TODO Auto-generated catch block
                    e.printStackTrace();
                }
                    returnemf.createEntityManager();
  1. Correct the error on the emf variable by selecting the "create field emf" quickfix (to add the field declaration: private EntityManagerFactory emf;).
  2. Quickfix the errors on InitialContext() and NamingException, too, and add the necessary imports to the class.
  3. Repeat Steps 5 through 9 for the DepartmentManager.java JPA manager bean, also found in the same package at EmployeeListJPA/src/employee/list/controller.

Create an OSGi application

In order to deploy the OSGi bundle to WebSphere Application Server, you need to create an OSGi application to contain the OSGi bundle for deployment first.

  1. Select File > New > Other.
  2. In the New Project dialog window, expand OSGi and select OSGi Application Project.
  3. Click Next.
  4. Enter a Project Name, for example EmployeeListApp.
  5. Verify that WebSphere Application Server v7.0 is set as the target runtime, and click Finish.
Figure 9. New OSGi application wizard
Creating the EmployeeListApp OSGi application
  1. EmployeeListApp will be listed in the Enterprise Explorer view. Expand it and double- click Manifest: EmployeeListApp to open the OSGi Application Manifest editor. There will be a warning on the manifest until a bundle is added in the next step.
  2. In the Contained Bundles section, click Add.
  3. Select EmployeeListWeb 1.0.0 and EmployeeListJPA 1.0.0, and click OK. The warning will resolve.
Figure 10. OSGi Application Manifest Editor overview page
Bundles added to OSGi App Manifest editor

Note:
Bundles can also be added to OSGi applications in the new OSGi application wizard.

  1. Save and close the EmployeeListApp manifest editor.

Create a data source on WebSphere and deploy

The data source needs to be created on your IBM WebSphere Application Server. See the Create a data source on the server section for how to create the Derby data source on the server, pointing to the sample database in the EmployeeListWeb project. If you are using the same server profile, you can reuse the data source created on the server in the previous section for this configuration.

EBA import-export support

The import and export EBA functionality is also worth exploring. EBA files contain OSGi applications and included bundles. They can be exported from Rational Application Developer and manually imported to WebSphere by using the Administrative Console.

Everything is now set up to deploy and run the EmployeeListWeb sample application when it is configured as an OSGi web bundle to access JPA data from another OSGi bundle contained in the OSGi application.

  1. Publish EmployeeListApp to WebSphere Application Server v7.0. Notice that the contained bundles are displayed beneath the OSGi application (see Figure 11).
Figure 11. Add and Remove to Server dialog window
EmployeeListApp and bundles in Add to Server dialog

Note:
EmployeeListWebEAR will still exist as a project in your workspace and will contain an error "A Java EE Enterprise Application must contain one or more modules." You can either delete or ignore this EAR file

  1. Run index.jsp inside the EmployeeListWeb application on WebSphere Application Server v7.0. In the Web Content folder in EmployeeListWeb, right-click the index.jsp file and select Run > Run on Server.
  2. Select WebSphere Application Server v7.0 and click Finish.
  3. The sample site should launch in the internal browser here:
    http://localhost:<port>/EmployeeListWeb/index.faces.
  4. The site should be functional. For instance, you should be able to click List all employee records and see a list of employees.
Figure 12. Example page listing all employees, with web and JPA as separate bundles
all_employees page showing list from database
  1. Remove the application from the server and delete all projects from your workspace before proceeding to the next section.

Variation on deploying the web project as a JEE module

OSGi applications can include dynamic web projects as JEE modules. This gives Rational Application Developer users the option to use web projects as they begin to develop OSGi applications. The following steps will show how to use the "JSF JPA Employee List Sample" with the OSGi application including a dynamic web project in the OSGi application deployment.

Organize your application modules

To organize the EmployeeListApp to use a dynamic web project rather than a Web Application Bundle for the web front end in the OSGi application, follow these steps:

Setting the target platform

In the case where the interim project .zip files are imported into your workspace, you might have to explicitly set the target platform to resolve compile errors. In imported archives, compared to imported OSGi applications (.eba), the target platform is set to the workspace default target platform. To resolve this, set the target platform to the appropriate target server by selecting Window > Preferences > Plug-in development > Target Platform and changing the selection from Running Platform to your targeted server platform.

  1. Import the results from the second configuration variation (the Single converted OSGi bundle containing JPA section of this article), or use the EmployeeListSample-Part2Complete.zip file (from the Download section), exception for the EmployeeListWeb project. Do not import the EmployeeListWeb bundle with the other resource. You will import a web project in later steps.

Your workspace should now contain two projects:

  • EmployeeListJPA
  • EmployeeListApp
  1. There will be a warning on EmployeeListApp: "Bundle EmployeeListWeb with version 1.0.0 cannot be resolved." Resolve the warning:
    1. Expand EmployeeListApp.
    2. Open the OSGi Application Manifest editor by double-clicking Manifest: EmployeeListApp.
    3. In the Contained Bundles section, select EmployeeListWeb 1.0.0 and click Remove.
    4. Save and close the manifest editor.
  2. Import the EmployeeList-Part2Begin.zip file (see the Download section):
    1. File > Import.
    2. Select General > Existing Projects into Workspace.
    3. In the Import dialog window, choose the Select Archive File radio button.
    4. Click the Browse button, and locate the EmployeeList-Part2Begin.zip file.
    5. Select only the EmployeeListWeb project to import.
    6. Click Finish.
    7. There will be a new web project in your workspace: EmployeeListWeb.

In the current configuration, there is a dependency between the EmployeeListWeb project and the EmployeeListJPA bundle. This needs to be removed to avoid runtime errors. Additionally, the src folder from EmployeeListJPA needs to be added to the build path of the EmployeeListWeb project to avoid development-time compilation errors.

  1. In the EmployeeListWeb project properties, go to the Deployment Assembly page.
  2. Remove the EmployeeListJPA.jar entry from this page.
  3. In the EmployeeListWeb project properties, go to the Java Build Path page and click the Libraries tab.
  4. Click the Add Class Folder button.
  5. Select to add the src folder under the EmployeeListJPA project. This will add the following folder entry to the build path:
    EmployeeListJPA/src (class folder).
  6. Click OK to save the changes to the project properties.

The Java EE web module, EmployeeListWeb, can be added to the OSGi application manifest as a dynamic web project. OSGi support of web modules allows users to slowly transition their Java EE applications to OSGi and also provides the added benefit of the web modules being supported in both Java EE and OSGi containers with minimal change. When a dynamic web project is published in an OSGi application, it is actually converted to an OSGi web bundle by the server at run time. For optimal performance and bundle versioning support, users are encouraged to convert their JEE web projects to OSGi bundles. However, to add a dynamic web project as a JEE module to an OSGi application, follow these steps.

  1. Expand EmployeeListApp in the Enterprise Explorer view.
  2. Open the OSGi Application Manifest editor by double-clicking Manifest: EmployeeListApp.
  3. In the OSGi Application Manifest editor, expand the Dynamic web projects section, and click Add.
  4. In the Select a dynamic web project dialog window, select EmployeeListWeb and click OK. This will add the following to the manifest file:
    Application-WebModules: EmployeeListWeb

The OSGi Application Manifest editor will look like Figure 13.

Figure 13. OSGi Application Manifest editor showing web project
Web project added in OSGi manifest editor

Create data source on WebSphere and deploy

OSGi applications containing dynamic web project modules can be successfully deployed to WebSphere Application Server only when the server is configured to "Run server with resources on server." This is not the default setting. To set this configuration:

  1. Open the Servers view.
  2. Double-click WebSphere Application Server v7.0 to open the Server Overview editor.
  3. Expand the Publishing setting of the WebSphere Application Server section.
  4. Select the publishing setting, Run server with resources on Server (Figure 14).
Figure 14. Publish settings to use resource on server
Server editor resource location settings
  1. Save and close the Server Overview editor.

The data source needs to be created on your IBM WebSphere Application Server. See the first section above for steps on how to create the Derby data source on the server pointing to the sample database in the EmployeeListWeb project.

Deploy and run the OSGi Application, EmployeeListApp

Now everything is set up to deploy and run the EmployeeListWeb sample application when it is configured as an OSGi application with an OSGi JPA bundle and a dynamic web project.

  1. Publish EmployeeListApp to the WebSphere Application Server v7.0. Notice the contained bundle and JEE web project are displayed beneath the OSGi application:
Figure 15. Add and Remove Server dialog window
OSGi app with web module being added to server

Run index.jsp inside the EmployeeListWeb application on WebSphere Application Server v7.0:

  1. In the Web Content folder in EmployeeListWeb, right-click the index.jsp file, and select Run > Run on Server.
  2. Select WebSphere Application Server v7.0, and click Finish.
  3. The sample site should launch in the internal browser at this location:
    http://localhost:<port>/EmployeeListWeb/index.faces
  4. The site should be functional. For instance, you should be able to click List all employee records and see a list of employees.
Figure 16. Example page that lists all employees, with web module in OSGi app
all_employees page showing list from database

This article demonstrated how Java EE developers can leverage the capability provided by IBM Rational Application Developer OSGi development tools by converting their existing Java EE applications to OSGi-based apps. You have seen three ways to convert and organize a simple dynamic web and JPA application, using application-managed JPA, as an OSGi application:

  • Single converted OSGi web bundle that contains a JPA
  • Multiple converted OSGi bundles, separating web and data persistence layers
  • Java EE web module (dynamic web project) with converted JPA OSGi bundle

Several capabilities of the new OSGi development tools were used to create these OSGi application variations, including these features:

  • OSGi project conversion wizard to convert the dynamic web project to an OSGi web application bundle (WAB) and the JPA project to an OSGi bundle
  • OSGi bundle manifest editor to describe the bundle metadata, including bundle dependencies
  • OSGi application project, which creates the Enterprise Bundle Archive (EBA), replacing the Java EE EAR file.
  • Enable JPA access within an OSGi context, using JNDI to perform OSGi service registry lookup
  • Server integration, supporting seamless publication and deployment of OSGi applications in a manner very similar to that of Java EE applications
  • Import/Export support for Enterprise Bundle Archive (EBA) to share OSGi applications or export for manual deployment into WebSphere Application Server

There are other OSGi-related capabilities that are outside the scope of this article, but we encourage you to explore these capabilities further now that you have a basic understanding of OSGi:

  • Plug-in Development Environment (PDE) project conversion to OSGi
  • OSGi composite bundles
  • Blueprint container with a dependency injection model
  • OSGi life cycle management that enables applications to be installed, updated, started, stopped, and uninstalled without a server restart

See the Resources section for additional resources describing these and other OSGi-related concepts.


Acknowledgements

Many thanks to Tim DeBoer, Zina Mostafia, and Jim Zhang for their technical and editorial contributions to this article.


Downloads

DescriptionNameSize
Employee List SampleEmployeeListSample.zip788KB
Employee List Sample - Part 2 BeginEmployeeListSample-Part2Begin.zip5445KB
Employee List Sample - Part 2 CompleteEmployeeListSample-Part2Complete.zip5439KB

Resources

Learn

Get products and technologies

Discuss

  • Join the Development Tools forum to ask questions and participate in discussions.
  • Get involved in the My developerWorks community. Connect with other developerWorks users while exploring the developer-driven blogs, forums, groups such as the Rational Café, and wikis.

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational
ArticleID=600064
ArticleTitle=Convert Java-based applications to the OSGi framework with Rational Application Developer tools
publish-date=12142010