Introduction

J2EE application clients were introduced to the J2EE specification last year without a lot of fanfare. Amid confusion over the purpose and function of application clients, many developers have overlooked them in favor of regular Java^TM applications, applets, or Web applications. This article explains the use of application clients and the benefits of using them, to help you decide whether they are right for your application. It also provides information on setting up application clients and developing them inside WebSphere® Studio Application Developer.

Application clients are much like regular Java applications. They contain a main() method that is executed, and they continue executing until the virtual machine terminates. They can be run as typical "fat client" applications, to display a GUI that connects to a set of EJB beans for persistence and business logic, or as server applications that provide services over the network. However, an application client has several advantages over a regular Java applications, because it runs within a lightweight server container. This container can provide the application client with services that used to be available only to the other J2EE components.

Benefits of using J2EE application clients instead of regular Java applications include:

• Ability to run inside a server container, providing richer APIs.
• Use of the java:comp namespace to indirectly reference EJB beans.
• Use of J2EE security, including authentication and server-specific functions, which might include features such as single-sign-on.
• Guaranteed Java 2 platform APIs available, as well as container extensions.
• Simple JNDI lookup, because initial context properties are picked up from the container.
• Packaged like other J2EE components, providing portability, easy deployment, and clean packaging. This also supports the J2EE notion of a deployer being able to modify the deployment information in order to move to a different server without changing code.

This article is based on Application Developer, Version 4.02. If you are using version 4.0, you must upgrade before making use of the topics discussed in this article.

Back to top

Creating application client resources

In Application Developer, you create an application client using an application client project. Like Web and EJB projects, this project contains the expanded contents of an application client. As you make changes within the appClientModule folder, your changes are automatically copied (and Java classes compiled) into the bin folder.

This article assumes that you have already created an EAR application with an EJB project containing an EJB that your application client needs to connect to. Once you have created the application client project, the first thing you should do is update the application client so that it can see all of the EJB classes or utility JARs that it will require. You can use the Edit Module Dependencies dialog to update the Java build path (for compile time) and create a MANIFEST.MF file (for run time). Take the following steps:

1. Right-click on the application client project and select Edit Module Dependencies.
2. Check the EJB projects or utility JAR files that this application client will depend on.
3. Click OK. This will update the build classpath of the application client to include the EJB projects or utility JAR files from the EAR projects. It will also generate a manifest file within the application client project. This manifest file sets the run-time classpath to include the EJB projects or utility JAR files so that they can be found at run time.

You can now create a Java application class within the application client project. Listing 1 below shows a sample application containing a main() method and invoking a method on a HelloWorld EJB bound to the JNDI name of test/HelloWorld. Notice that the sample does not set up a Properties object containing the InitialContextFactory or ProviderURL, as would normally be the case. Since this class will be run as an application client, it will obtain these properties automatically from the application client container.

package com.test; 
 
import javax.naming.InitialContext; 
import javax.rmi.PortableRemoteObject; 
import com.ejb.hello.*; 
 
public class ClientApplication { 
   public static void main(String[] args) { 
      try { 
         InitialContext context = new InitialContext(); 
         Object obj = context.lookup("test/HelloWorld"); 
 
         HelloWorldHome home = (HelloWorldHome)  
            PortableRemoteObject.narrow(obj, HelloWorldHome.class); 
         HelloWorld bean = home.create(); 
         System.out.println("The HelloWorld bean says " +  
            bean.sayHello("Tim")); 
      } catch (Exception e) { 
         e.printStackTrace(); 
      } 
   } 
}

After you have created the class containing the main() method, you'll need to add the main class to the manifest file of the application client. If you do not set the main class, the application client container will not be able to find the starting class and start your application. Take the following steps:

1. Open the MANIFEST.MF file contained within the appClientModule/META-INF folder. (This file was automatically created from the Edit Module Dependencies dialog.) Add the following line, where com.test.ClientApplication is the name of your class containing the main() method:

   Main-Class: com.test.ClientApplication

   
   
2. Listing 2 below shows an example manifest file. Your manifest should look similar to this.
3. Save and close the editor.

Manifest-Version: 1.0 
Class-Path: HelloWorldEJB.jar 
Main-Class: com.test.ApplicationClient

Back to top

Using the java: JNDI namespace (optional)

One of the key benefits of using application clients is the option to use the java: JNDI namespace when looking up EJB beans from the JNDI namespace. The java: namespace provides an extra level of indirection between your application code and the EJB bean. One of the main purposes is to allow you to switch to using a new JNDI name (if the EJB bean was moved, for instance) by modifying the binding files and not making any changes to the Java code.

Application Developer, Version 4.0 does not contain any editor support for the application-client.xml or WebSphere-specific binding file that is contained with an application client. However, these files are fairly small, and you can use a text editor to modify them by hand. The application-client.xml file is part of the J2EE specification and it contains the information on EJB beans that are referred to using java:comp. At deployment time, these EJB references are bound to specific EJB beans via the WebSphere-specific ibm-application-client-bnd.xmi file. To update these files:

1. Using a text editor, open the application-client.xml file found in the appClientModule/META-INF folder.
2. Listing 3 below shows an example application-client.xml file. Add the section highlighted in blue to your copy of this file.

   Listing 3. Sample application-client.xml file

   <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE application-client PUBLIC "-//Sun Microsystems, Inc.// DTD J2EE Application Client 1.2//EN" "http://java.sun.com/j2ee/dtds/application-client_1_2.dtd"> <application-client id="Application-client_ID"> <display-name>Sample Application Client</display-name> <ejb-ref id="EjbRef_1"> <description>HelloWorldExample</description> <ejb-ref-name>ejb/Hello</ejb-ref-name> <ejb-ref-type>Session</ejb-ref-type> <home>com.ejb.hello.HelloWorldHome</home> <remote>com.ejb.hello.HelloWorld</remote> </ejb-ref> </application-client>

   
   
3. Change the ejb-ref-name element to the name that your application client will use to look up the EJB bean. The convention is to start with ejb/, but this is optional.
4. Specify the home and remote interface class names or your EJB bean by changing the home and remote elements respectively.
5. If you have more than one EJB reference in this file, increment the id on each one.
6. Save and close the editor.
7. Create an ibm-application-client-bnd.xmi file within the appClientModule/META-INF folder.
8. Open the file using a text editor.
9. Listing 4 below shows some example contents of this file. You may copy the example into your editor and modify the jndiName attribute to the actual JNDI name of the EJB bean. If there is more than one EJB reference, the href parameter of the bindingEjbRef element should end with the id specified in the application-client.xml file.
10. Save and close the editor.

<clientbnd:ApplicationClientBinding xmi:version="2.0" 
   xmlns:xmi="http://www.omg.org/XMI" xmlns:clientbnd="clientbnd.xmi" 
   xmlns:commonbnd="commonbnd.xmi" xmlns:common="common.xmi" 
   xmlns:client="client.xmi" xmi:id="Application-client_ID_Bnd"> 
   <ejbRefs xmi:id="EjbRefBinding_1" jndiName="test/HelloWorld"> 
      <bindingEjbRef href="META-INF/application-client.xml#EjbRef_1"/> 
   </ejbRefs> 
   <applicationClient  
      href="META-INF/application-client.xml#Application-client_ID"/> 
</clientbnd:ApplicationClientBinding>

The final step is to modify the Java application to use the java:comp lookup instead of directly referencing the EJB. Change the Java code performing the lookup as shown in Listing 5 below, where ejb/Hello is the ejb-ref-name you entered in the application-client.xml file.

Object object = context.lookup("java:comp/env/ejb/Hello");

You have now finished adding the java:comp lookup to your application client. The project should now look like Figure 1 below.

Back to top

Running application clients

Before you can run a J2EE application client inside Application Developer, you will need an e-fix for the WebSphere Test Environment. Without this e-fix, WebSphere does not support loose modules (where the modules are not directly contained within the Enterprise Application, as in the Application Developer workspace) when running application client projects. Take the following steps:

1. Use a Web browser to navigate to the WebSphere support Web site, and follow the link for All e-fixes, fixpaks, and tools. (or go directly to the e-fixes)
2. Download the e-fix for PQ58388. (At the time this article was published, this e-fix was not yet available. It will be posted on the WebSphere support site as soon as possible. If the e-fix is not yet available, you can run your application client as a regular J2EE client.)
3. Follow the instructions in the online help section WebSphere Application Server maintenance releases to apply the e-fix.

Although application clients have a main() method that can be invoked just like any other Java application, executing it directly will not give the server container a chance to initialize the security and namespace support. Executing it directly would also use the regular Java classloader, instead of the server's application client classloader. To run an application client correctly, use the application client launcher in Application Developer. This launcher starts the server and points it at the EAR file that contains the application client. Once the server has initialized the application client container and is ready to start the code, it automatically invokes the main() method of your application client. From this point on, your application client executes normally and can make use of all of the container's services.

To set up launching an application client:

1. If the Debug/Run buttons are not available on the toolbar, switch to a different perspective or take the following steps to add them to the current perspective:
   
   
   1. Select the Perspective => Customize... menu.
   2. Expand Other and select Run/Debug.
   3. Click OK.
      
      
2. Select the application client project from within the Navigator. Right-click and select Properties.
3. Select Launcher on the left side of the dialog, and use the combo box to select Application Client Launcher.
4. Click OK.

The above steps only need to be performed once. Now that the project is ready, you can launch your application client:

1. Select the main class of the application client project.
2. Click the Run or Debug toolbar buttons to start the Application Client Launcher. This should launch the application client container and invoke your main class. Listing 6 below shows the sample output within the console after running the application client.

IBM WebSphere Application Server, Release 4.0  
J2EE Application Client Tool, Version 1.0 
Copyright IBM Corp., 1997-2001 
 
WSCL0012I: Processing command line arguments. 
WSCL0001I: Command line, property file,  
   and system property arguments resolved to:  
   File to launch         = C:\wsad\eclipse\workspace\AppClientEAR 
   CC Property File       = C:/wsad/eclipse/plugins/ 
                            com.ibm.etools.websphere.tools/client.properties 
   Client Jar File        = <default> 
   BootstrapHost          = localhost 
   BootstrapPort          = <default> 
   Trace enabled          = false 
   Tracefile              = null 
   Init only              = false 
   Classpath Parameter    = C:\wsad\eclipse\workspace\AppClient\bin 
   Application Parameters =  
 
WSCL0013I: Initializing the J2EE Application Client Environment. 
WSCL0025I: Binding EJB reference object: 
   JNDI name: ejb/Hello ==> test/HelloWorld 
   Description: HelloWorldExample 
WSCL0031I: The object was bound successfully. 
 
resourceUrlString= [C:\wsad\eclipse\workspace\AppClient\bin,  
   C:\wsad\eclipse\workspace\AppClientEJB\bin,  
   C:\wsad\eclipse\workspace\AppClient\bin] 
WSCL0035I: Initialization of the J2EE Application  
   Client Environment has completed. 
WSCL0014I: Invoking the Application Client class ClientApplication 
The HelloWorld bean says Hello, Tim!</default></default>

If you require additional properties to be passed into WebSphere's application client launcher, note the property file used: C:/wsad/eclipse/plugins/com.ibm.etools.websphere.tools/client.properties. You may find this file within your installation and add additional properties.

Back to top

Running regular J2EE clients inside Application Developer

Perhaps you've decided that application clients are not the right solution for your application, and you just want to create a regular Java application that connects to a WebSphere server. In this case, note that WebSphere requires Java client applications to run on the same JDK level as the server. If you're using incompatible JDK levels, you may receive an error like the following when trying to connect to the server:

java.lang.NoClassDefFoundError: com/ibm/rmi/iiop/GIOPVersionException

To work around the problem and use the same JDK in the Java application:

1. Select Window => Preferences.
2. Select Java => Installed JREs.
3. Click New to add the WebSphere JRE to the JRE list. The WebSphere JRE is located in eclipse/plugins/com.ibm.etools.server.jdk/bin.
4. Right-click on the Java project and select Properties.
5. Select JRE and then select Use custom JRE for launching.
6. Select the server JRE that you have just added.

Your Java application should now be able to connect to WebSphere without the error shown above.

Back to top

Conclusion

J2EE application clients provide extra services and support for developers writing applications that connect to EJB beans. They allow your application to use the java: JNDI namespace and security features provided by the J2EE specification.

About the author

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Creating application client resources
• Using the java: JNDI namespace (optional)
• Running application clients
• Running regular J2EE clients inside Application Developer
• Conclusion
• About the author
• Comments

Next steps from IBM

Rational Application Developer features provide the comprehensive Integrated Development Environment (IDE) used to develop J2EE applications requiring Servlets and JavaServer Pages (JSPs).

---

• Try: Try the free Rational Application Developer, which helps developers quickly design, develop, test, analyze, and deploy high-quality Java, Javaserver pages, and J2EE applications.
• Article: Learn how you can deliver accurate, higher-quality J2EE apps with Rational Application Developer, open source JUnit and JUnitEE test frameworks.
• Tutorial: Build a Facebook application using PHP, the Spring framework, and J2EE.
• Buy: Rational Application Developer

My developerWorks community

Dig deeper into WebSphere on developerWorks

DB2 pureScale

See how true transparent scaling architecture can be achieved on distributed platforms

Special offers