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

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

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

---

Back to top

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

---

Back to top

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.

5. (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:

6. 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.
7. Locate the ConnectionURL property in the persistence.xml file:
   <property name="openjpa.ConnectionURL" value="jdbc:derby:<workspace_location>\EmployeeListWeb\WebContent\sample" />
8. 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" />
   
9. 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.
10. Select WebSphere Application Server v7.0 and click Finish.
11. The sample site should launch in the internal browser at this location:
    http://localhost:<port>/EmployeeListWeb/index.faces
12. The site should be functional. For instance, you should be able to click List all employee records and see a list of employees.
13. Remove the application from the server before proceeding to the next section.

---

Back to top

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

2. Select OK to confirm the conversion from a JEE web project to an OSGi bundle.
3. 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

4. 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

4. In the Contained Bundles section, click Add.
5. Select EmployeeListWeb 1.0.0 and click OK. The warning will resolve.
6. 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>

10. 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

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.

2. 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.
3. Select WebSphere Application Server v7.0, and click Finish.
4. 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

5. 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.

---

Back to top

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

2. 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

2. 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

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:

5. Open the Employee entity manager bean, EmployeeManager.java, which you can find at EmployeeListJPA/src/employee/list/controller.
6. 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.

7. 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(); } return emf.createEntityManager();

8. Correct the error on the emf variable by selecting the "create field emf" quickfix (to add the field declaration: private EntityManagerFactory emf;).
9. Quickfix the errors on InitialContext() and NamingException, too, and add the necessary imports to the class.
10. 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

6. 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.
7. In the Contained Bundles section, click Add.
8. 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

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

9. 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

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

5. Remove the application from the server and delete all projects from your workspace before proceeding to the next section.

---

Back to top

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

2. 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.
3. 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.

4. In the EmployeeListWeb project properties, go to the Deployment Assembly page.
5. Remove the EmployeeListJPA.jar entry from this page.
6. In the EmployeeListWeb project properties, go to the Java Build Path page and click the Libraries tab.
7. Click the Add Class Folder button.
8. 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).
9. 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.

10. Expand EmployeeListApp in the Enterprise Explorer view.
11. Open the OSGi Application Manifest editor by double-clicking Manifest: EmployeeListApp.
12. In the OSGi Application Manifest editor, expand the Dynamic web projects section, and click Add.
13. 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

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

5. 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

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

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

---

Back to top

Summary and related capabilities to explore
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.

---

Back to top

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

---

Back to top

Downloads

Description	Name	Size	Download method
Employee List Sample	EmployeeListSample.zip	788KB	HTTP
Employee List Sample - Part 2 Begin	EmployeeListSample-Part2Begin.zip	5445KB	HTTP
Employee List Sample - Part 2 Complete	EmployeeListSample-Part2Complete.zip	5439KB	HTTP

Information about download methods

Resources
Learn

• Find out more about OSGI and the Blueprint specification:
  • Building OSGi applications with the Blueprint Container specification, an IBM® developerWorks® article by Jarek Gawor (November 2009)
  • Developing enterprise OSGi applications for WebSphere Application Server, a developerWorks article by Ian Robinson and Holly Cummins (July 2010)
  • Best practices for developing and working with OSGi applications, a developerWorks article by Graham Charters, Jeremy Hughes, Tim Mitchell and others (July 2010)
  • About the OSGi Service Platform, a technical white paper from the OSGi Alliance (June 2007)
  
  
• Find out more about Rational Application Developer:
  • Browse the Rational Application Developer for WebSphere Software page on developerWorks for links to technical articles and many related resources.
  • Explore the Information Center.
  
  
• Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products.
  • Stay current with developerWorks technical events and webcasts focused on a variety of IBM products and IT industry topics.
  • Attend a free developerWorks Live! briefing to get up-to-speed quickly on IBM products and tools, as well as IT industry trends.
  • Follow developerWorks on Twitter.
  • Watch developerWorks on-demand demos, ranging from product installation and setup demos for beginners to advanced functionality for experienced developers.
  
  
• Check the Rational training and certification catalog, which includes many types of courses on a wide range of topics. You can take some of them anywhere, any time, and many of the "Getting Started" ones are free.

Get products and technologies

• Try Rational Application Developer for WebSphere Software, free
  
  
• Evaluate IBM software in the way that suits you best: Download it for a trial, try it online, use it in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement service-oriented architecture efficiently.

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.