IBM Lotus Expeditor is an offering from IBM that eases Java™ Platform, Enterprise Edition application extension to clients with a familiar programming model. IBM Lotus Expeditor Toolkit enables rapid application development and deployment by eliminating the need to rewrite Java EE projects to run on the Lotus Expeditor runtime. In this article, we demonstrate how you can achieve this.

To get the most from this article you should be familiar with Java™ and Java EE as well as plug-in development using Eclipse 3.x technology. Keep in mind that Java EE projects are not plug-in projects, but Lotus Expeditor projects are. Lotus Expeditor projects have bundle manifest and plugin.xml files that are specific to plug-in projects, so you must understand how these files should be handled.

This article teaches you:

• How to migrate existing Java EE Enterprise JavaBean (EJB) projects to Lotus Expeditor
• Which Java EE features Lotus Expeditor does not support
• How to deploy the migrated project on the Lotus Expeditor runtime

Before starting the steps in this article, you must have IBM Rational Application Developer V7.0, Lotus Expeditor Toolkit V6.1, and Lotus Expeditor Client V6.1 installed. You can download a free trial version of Rational Application Developer for WebSphere Software from developerWorks.

Migrating existing Java EE EJB projects to Lotus Expeditor

Developing Java EE applications is beyond the scope of the article. Instead, to simplify the process, we import an existing Java EE sample project that is later migrated. Before you start, make sure that you download the sample code (sampleJava EEProject.zip) provided in the Downloads section of this article.

Let's get started by importing the sample Java EE project into Rational Application Developer:

1. In Rational Application Developer, switch to the Java EE perspective by choosing Window - Open Perspective - Other - Java EE.
2. Import sampleJava EEProject.zip by choosing File - Import.
3. In the Import wizard, select "Existing projects into workspace," and then click Next.
4. In the Import Projects wizard shown in figure 1, select the Select archive file option, browse to the ZIP file sampleJava EEProject.zip you downloaded, and then click Finish.
   
   Figure 1. Import Projects wizard
   
   
   
5. Open the New Project wizard by choosing File - New - Project.
6. In the New Project dialog box, expand Client Services. Several types of wizards used to create different kinds of Client Services projects appear. Select the "Convert Project to Client Services Project" option, and then click Next as shown in figure 2.
   
   Figure 2. New Project wizard
   
   
   
7. The Convert Existing Project wizard shown in figure 3 contains a list of non-Client Services projects for conversion. Note that after you migrate a Java EE project to Client Services, you cannot reverse this step; there is no way to revert to the pre-converted Java EE project state. Lotus Expeditor Toolkit provides a "Copy project before conversion" option to make a new copy of the existing Java EE project and to convert the new copy to Client Services. Select this option and specify the name for the new project copy, if needed. You can select only one project at a time for conversion. Click Next.
   
   Figure 3. Convert Existing Project wizard
   
   
   
8. In the Target Definition panel as shown in figure 4, you see a list of additional services, for example, Java Message Service (JMS) APIs, Managed Settings, and MQ Everyplace. Leave the selection of these services to the default because we do not use any of these additional services. Click Finish to convert the selected EJB project to a Client Services project.
   
   Figure 4. Convert Existing Project: Target Definition panel
   
   
   
9. After you click Finish, the wizard runs a pre-conversion test and displays any errors and warnings based on elements of the existing EJB that may require modification when running against the Lotus Expeditor runtime. If any errors or warning conditions are found, a dialog box appears that asks whether the conversion should continue or be cancelled. Click OK to continue with the conversion as shown in figure 5.
   
   Figure 5. Convert Existing Project: Warning
   
   
   

EJB projects that are migrated to Client Services are known as Client Services embedded transaction container (ETC) projects.

Follow the same steps to convert the sample Web project, BankWeb, to a Client Services project. Web projects that are migrated to Client Services projects are known as Client Services Web projects.

Back to top

Developing embedded transaction container logic

The embedded transaction container is targeted for more constrained devices than typical Java EE EJB servers/containers. Even though the programming models of the two are very similar, some aspects are unique to the embedded transaction container. The following sections describe tasks that involve embedded transaction specific considerations.

Implementing finder methods

ETC uses a different approach to implement the custom finder function. For each finder method declared on the home interface (other than findByPrimaryKey), you must provide the business logic required to build the corresponding collection. Implementation of EJB finder methods in the bean class is not supported by this runtime. The tool requires that this logic be packaged in an abstract finder helper class extending BaseJDBCFinder, which the tool extends in a concrete JDBC finder helper implementation class.

Configuring data sources

Client Services provide three ObjectFactory implementations for using declarative JNDI. The factory provides an Eclipse extension point (described by a schema definition file) that allows for the description of Java objects bound into JNDI upon a client JNDI look-up.

Add an extension point to instantiate an IBM DB2 Everyplace data source object as shown in listing 1.

<extension
         point="com.ibm.pvc.jndi.provider.java.genericobject">
         <object 
         	jndi-name="BANKING" 
         	class="com.ibm.db2e.jdbc.DB2eDataSource">
         	<method name="setUrl">
		  		<method-parameter	type="String"
		    		value="jdbc:db2e:${_workspace}\\ejb\\BANKDb\">
		  		</method-parameter>
	       </method>
         </object>
</extension>

The embedded transaction container requires that a specific data source, TxnDataSource, is used when connecting to the database for Container Managed Persistence (CMP). This specific data source is created using the TxnDataSourceFactory. The TxnDataSource is used only for CMP access to the database. All other database access should be done using a data source.

This wrapping of the vendor-specific DataSource can be done before JNDI binding or after lookup. Wrapping before JNDI binding is the best practice because this is done once as opposed to wrapping after every lookup. You can add an extension point as shown in listing 2 to do this wrapping.

<extension
          point="com.ibm.pvc.jndi.provider.java.binding">
   <binding jndi-name="BANKING"
    objectFactory-id="com.ibm.pvc.txncontainer.TxnDataSourceObjectFactory">
   </binding>
</extension>

Providing custom bundle activator

The ETC tooling creates projects that reference the default bundle activator, com.ibm.pvc.txncontainer.GenericActivator. This activator registers the EJB's home interface. To create a custom bundle activator for an existing project, you must create a class that extends com.ibm.pvc.txncontainer.GenericActivator class and calls the start() and stop() methods of GenericActivator inside its own start() and stop() methods. Update this class name in the bundle's manifest as shown in figure 6. This step updates the EJB manifest file META-INF/MANIFEST.MF by setting the Bundle-Activator property to the custom bundle activator class.

Creating local database and tables

Make sure that you create a local database and tables for entity beans before invoking them. The best place to add logic when creating the database and tables is the start() method of the ETC project's Bundle Activator.

Supporting relationships

Container-managed relationships (CMRs) are supported between entities in accordance with the EJB specification. ETC uses the link-table approach to implement the container-managed relationship functions. Consider two EJBs, A and B, on which a relationship R is defined such that a CMR field is defined on A, B, or both. When these EJBs are deployed, no persistent CMR state is associated with the database tables that provide persistent CMP state for A and B. Instead, persistent CMR state is maintained in a separate relational database link-table on a per-relationship basis.

Relationship data is stored in a separate database table (the link-table). Each row of the link-table represents a relationship between two entities. The link-table contains a set of columns for the primary key of the first entity, a set of columns for the primary key of the second entity, and an optional discriminator column. A link-table's column names must follow the naming schema specified by the custom deployment information for the corresponding CMP primary key columns, except that every column is prefixed by either r1_ or r2_, depending upon whether the column is associated with the role 1 or role 2 EJB. Make sure that these link-tables exist for each EJB relationship before invoking entity beans.

Back to top

Developing Web project logic

The following tasks involve considerations specific to the Client Services Web project; they are needed to migrate from the Java EE project to the Client Services Web project:

• Providing the required libraries. The jclDesktop runtime doesn't provide the java.rmi package, so a reference to PortableRemoteObject.narrow() is flagged as an error. ETC never allows access to EJBs on other servers, so we can replace PortableRemoteObject.narrow() with a simple JNDI lookup.
• Providing a short-cut menu to launch a Web application in Lotus Expeditor runtime. Add an extension point as shown in listing 3 to the BankWeb project's plugin.xml, so that it can be launched in the Lotus Expeditor runtime using the short-cut menu.

<extension id="kw4qri0g1j4t" point="com.ibm.eswe.workbench.WctWebApplication">
      <WEBApplication DisplayName="XYZ Banking">
         <WebApplicationUrl local="true" secured="false" url="/BankWeb/Banking.html">
         </WebApplicationUrl>
         <BrowserConfiguration showAddressbar="true" showToolbar="false">
         </BrowserConfiguration>
      </WEBApplication>
   </extension>

Back to top

Java EE features not supported in Lotus Expeditor

Lotus Expeditor does not support the following Java EE features:

• Stateful session beans.
• Pass-by-copy semantics for mutable serializable objects when running in a single address space.
• For EJB 1.1, the embedded transaction container does not persist references to an EJB's remote or remote home interfaces. Note that this capability is not required of EJB 2.1.
• Message-driven beans.
• Java security support.
• EJB Query Language.
• Home methods.
• Select methods.
• Bean-managed transactions.
• Enumeration return type for finders. Collection return type is supported.
• Specification of transaction isolation level.
• Support for collections and iterators outside of the transactions in which they were created.
• The setTransactionTimeOut() method.
• BigDecimal, which is not supported in J2ME (JSR169).

Back to top

Deploying the migrated project on the Client Services Lotus Expeditor runtime platform

Client Services applications run on the Lotus Expeditor runtime. Lotus Expeditor Toolkit automatically handles these bundle-specific details; therefore, it is recommended that projects that are targeted for the Lotus Expeditor runtime or that depend upon other OSGi services be developed through the Client Services Project Creation wizard. Lotus Expeditor runtime does not support deploying enterprise applications through an EAR file. Instead, applications are directly deployed to the runtime.

Now that you have completed the migration of the Java EE project to Client Services, let's deploy the migrated project to the Lotus Expeditor runtime. Follow these steps to deploy the migrated project:

1. In the Project Explorer, right-click the BankWeb project, then choose Run - Run on Server.
2. In the Run On Server dialog box shown in figure 8, do the following:
   
   • Select the "Manually define a new server" option.
   • Select Client Services v6.1.
   • Click Next.
   • Leave the defaults for the Client Services Server and click Next.
   • Add the BankEJB project to the configured projects list.
   • Click Finish to launch the Client Services Lotus Expeditor runtime.

You can find the migrated project (migratedSampleJ2EEProject.zip) for reference in the Downloads section of this article.

Back to top

Testing the application

Now that you have deployed the Java EE project, let's make sure that you were successful. After the Lotus Expeditor runtime starts, select the Open icon on the left, and then select XYZ Banking. A banking page appears as shown in figure 9.

Click Submit to see the resulting page as shown in figure 10.

Back to top

Conclusion

With Lotus Expeditor, you can move key components of your applications from the server to the desktop, to the laptop, to the tablet, and to handheld clients by using standard APIs and services. Moving application components to run on a client can have dramatic results for business. Users benefit from improved application response time because applications perform business operations locally on the client. As a result, network traffic between client and servers is reduced, and server workload is eased. Furthermore, mobile users can continue to use their applications productively from their clients even when they are at a location that doesn't have network connectivity.

This article shows you how to migrate from a Java EE project to a Client Services project. You converted an EJB project and a dynamic Web project to Client Services. Migrate your Java EE applications to Lotus Expeditor and access your applications anytime, anywhere – with or without network connectivity.

Back to top

Downloads

Information about download methods

Resources

Learn

• Read the developerWorks Lotus article, "End-to-end integration with pervasive messaging and IBM Lotus Expeditor micro broker."
  
  
• Read the developerWorks Lotus article, "Building an offline application in IBM Lotus Expeditor."
  
  
• Read the developerWorks Lotus article, "Developing and deploying rich client applications on desktops and mobile devices using IBM Lotus Expeditor V6.1."
  
  
• Read the developerWorks Lotus article, "Migrating Eclipse RCP applications to IBM Lotus Expeditor."
  
  
• Read the developerWorks Lotus article, "Creating collaborative components for IBM Lotus Expeditor Property Broker."
  
  
• Read the developerWorks Lotus article, "Developing an OSGi service as a Web service in IBM Lotus Expeditor."
  
  
• Read the developerWorks Lotus article, "Building and deploying a simple Web Services Resource in IBM Lotus Expeditor."
  
  
• Read the IBM Redbooks publication, Building Composite Applications in Lotus Expeditor V6.1 .
  
  
• Read the developerWorks Lotus Expeditor page.
  
  
• Refer to the IBM Lotus Expeditor Education Assistant.
  
  
• Refer to the IBM Lotus Expeditor Information Center.
  
  

Discuss

• Participate in the discussion forum.
  
  
• Participate in the developerWorks Lotus team blog.
  
  

About the author

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Migrating existing Java EE EJB projects to Lotus Expeditor
• Developing embedded transaction container logic
• Developing Web project logic
• Java EE features not supported in Lotus Expeditor
• Deploying the migrated project on the Client Services Lotus Expeditor runtime platform
• Testing the application
• Conclusion
• Downloads
• Resources
• About the author
• Comments

Next steps from IBM

• Try: Lotus Expeditor toolkit
• Webcast: A Smart Approach to Core Banking Renovation in a Tough Economic Climate
• Briefing: Smarter collaboration with IBM Lotus solutions
• Buy: Lotus Expeditor toolkit

My developerWorks community

Dig deeper into Lotus on developerWorks

Calling all developers

Download no charge Lotus Domino Designer

Special offers