IBM WebSphere Developer Technical Journal: Leverage existing WebSphere Application Server J2EE resources from WebSphere Application Server Community Edition

By accessing the IBM® WebSphere® Application Server JNDI tree, WebSphere Application Server Community Edition (IBM's free, lightweight J2EE™ application server built on Apache Geronimo technology) can interact with and reuse virtually any of the J2EE resources that are housed there.

Robert Peterson (rrpeters@us.ibm.com), WebSphere Enablement, Austin, TX, EMC

Author photoRobert R. Peterson is part of the enablement team under IBM Software Services for WebSphere. He works to ensure that the WebSphere portfolio of products brings IBM's clients the greatest value possible. Robert is an accomplished inventor and co-author of WebSphere Application Server V6: Performance and Scalability. He is an alumni of IBM's prestigious Extreme Blue Program and holds a M.S. in Computer Engineering from the University of Florida.



Kulvir Singh Bhogal (kbhogal@us.ibm.com), Software Services for WebSphere, Fort Worth, TX, EMC

Kulvir Bhogal photoKulvir Singh Bhogal works as an IBM consultant, devising and implementing Java-centric solutions at customer sites across the nation.



22 February 2006

From the IBM WebSphere Developer Technical Journal.

Introduction

It is not uncommon for enterprises to leverage different application server flavors throughout their organization to accommodate a variety of business objectives. A case in point might be a company that primarily runs IBM WebSphere Application Server V6, but has a business need to run IBM’s cost-free WebSphere Application Server Community Edition as well to power the myriad of J2EE applications running throughout the enterprise. Code reusability is a key programming principle that supports such an environment, enabling you to lower programming costs and exploit existing code assets at the same time.

In this article, we will show you how to leverage existing J2EE code artifacts running in WebSphere Application Server V6 from a J2EE application server that is not WebSphere Application Server. Namely, we will show how to use WebSphere Application Server Community Edition, which is based on Apache Geronimo, the J2EE server project of the Apache Software Foundation, to interact with a J2EE resource powered by WebSphere Application Server V6.

This article assumes a basic knowledge of WebSphere Application Server Community Edition or Apache Geronimo, and general familiarity with J2EE and WebSphere Application Server programming concepts. See Resources for helpful introductory information.

In this article:

  • Community Edition refers to WebSphere Application Server Community Edition.
  • WebSphere Application Server refers to WebSphere Application Server - Express, WebSphere Application Server Base, and WebSphere Application Server Network Deployment.

Before you continue: This article was written for WebSphere Application Server Community Edition V1.0, which was the current version at the time the article was published. Some of the information in this article may not be applicable to later versions. To follow along with this article, be sure to use the product version on which this article is based. If you wish, you can download the current version of WebSphere Application Server Community Edition, or you can download an earlier version by visiting the product archive page.


Our cross application server scenario

We will illustrate how to use a J2EE resource -- specifically, a stateless session EJB component running in a WebSphere Application Server EJB container -- via a servlet that resides in a Community Edition servlet container. In other words, as shown in Figure 1, a consuming servlet running on Community Edition will be used to hit an EJB component running on WebSphere Application Server V6.

Figure 1. Topology of our cross application server example
Figure 1. Topology of our cross application server example

Prerequisites

To follow along with the steps in this article, you must have the following software properly installed and running:

  • Application Client for WebSphere Software - Also known as the "thin client," this is a set of resources and an IBM JVM specifically designed for client access to WebSphere Application Server applications. This is available through the same install wizard or launchpad wizard in any WebSphere Application Server product. It is also available separately as a trial download. When installing the Application Client, you will need to install the J2EE and Java™ thin application client, as shown in Figure 2.

    Figure 2. Install Application Client
    Figure 2. Install Application Client
  • WebSphere Application Server Community Edition v1.0.0.1 - A lightweight J2EE application server built on Apache Geronimo open source technology, designed to help you accelerate your development and deployment efforts by being quick to download and easy to implement. You can download and use the Community Edition product free of charge.

  • IBM Rational® Application Developer V6 - This is the development environment we will use to implement both the Geronimo and WebSphere code. Be sure to download the optional Integrated Test Environment for WebSphere Application Server V6. A trial version of Rational Application Developer is available for download.

You will need to run WebSphere Application Server Community Edition using the IBM JRE that installs with WebSphere Application Client V6. If using Windows®, be sure to install Community Edition to a directory that does not contain spaces (for example, not c:\Program Files).

For the purpose of this article, all of the prerequisite software described above can reside on the same physical machine. In a production environment, however, Community Edition would likely reside on a separate machine than that of an actual WebSphere Application Server cluster, rather than the test WebSphere Application Server instance running in Rational Application Developer that we will use here.

Regardless, the WebSphere Application Client must be installed on the same machine as Community Edition because we will be importing JAR files from the WebSphere Application Client installation as common libraries in Community Edition.


Create a simple EJB component for WebSphere Application Server

First, using Rational Application Developer, we will create a simple stateless session EJB to run in the WebSphere Application Server EJB container. We will power our EJB with the Rational Application Developer test environment. The simplicity of this EJB is intentional, since we are focusing on the ability to invoke the EJB's remotely exposed methods, rather than on the EJB itself.

  1. In Rational Application Developer, create a new workspace. You can switch workspaces by selecting File => Switch Workspace... or by specifying a new one at startup.

  2. In the J2EE perspective, right-click EJB Projects and select New => EJB Project.

  3. Enter or select the following values (Figure 3):

    • Name: SimpleEJBProject
    • EJB version: 2.1
    • Target Server: WebSphere Application Server v6.0
    • EAR project name: SimpleEJBProjectEAR

    then select Finish.

    Figure 3. New EJB project definition
    Figure 3. New EJB project definition
  4. Expand SimpleEJBProject => Deployment Descriptor: SimpleEJBProject. Right-click Session Beans, then select New => Session Bean.

    Figure 4. New session bean
    Figure 4. New session bean
  5. Enter or select the following values (Figure 5):

    • Bean name: SimpleEJB
    • Default package: devworks.example

    then select Finish.

    Figure 5. Create Session Bean wizard
    Figure 5. Create Session Bean wizard
  6. Select EJB Projects => SimpleEJBProject => Deployment Descriptor: SimpleEJBProject => Session Beans => SimpleEJB, and then click the plus icon to expand the SimpleEJB bean. Modify the remote interface class (SimpleEJB) as follows:

    public String retrieveText() {
    	return "G-E-R-O-N-I-M-O!!!";
    }

    The implementation of the SimpleEJB project is complete. We now need to export an EJB client JAR that includes stubs for calling the remote EJB. This client JAR will be used by our consuming application running on Community Edition.

  7. If you expand Other Projects you should see SimpleEJBProjectClient. If not, create one by right-clicking SimpleEJBProject and then select EJB Client JAR => Create EJB Client JAR Project. Name the new client SimpleEJBProjectClient.

  8. Right-click SimpleEJBProjectClient and select Export... => JAR file => Next. Select a location, name it EJBClient.jar, save it under JAR file, then Finish.

  9. Finally, we need to deploy our simple EJB on WebSphere Application Server. Select the Servers tab, right-click WebSphere Application Server and select Start.

  10. Right-click WebSphere Application Server and select Add and Remove Projects => SimpleEJBProjectEar => Add and then Finish.

At this point, we now have our J2EE resource, a stateless session EJB component. We want to invoke a remote method of this EJB component via a consuming servlet (running on Community Edition) which we will build shortly. Use the Universal Test Client to test your EJB.

Figure 6. Universal Test Client
Figure 6. Universal Test Client

Before we build our invoking servlet, we will need to determine where our J2EE resource resides in the WebSphere Application Server JNDI tree. That is next.


Determine the fully-qualified JNDI name for the simple EJB

To determine where the EJB we just created resides in our JNDI tree, we can use a script facility called dumpNameScript.

Navigate to the bin directory of the integrated WebSphere Application Server and execute the dumpNamespace script. For example, under Windows, this may be C:\IBM\RAD6\runtimes\base_v6\bin\dumpNameSpace.bat, or for Linux®, /opt/IBM/RAD6/runtimes/base_v6/bin/dumpNameSpace.sh.

Figure 7. Initial name space
Figure 7. Initial name space

In practice, there are several choices when considering administered JNDI resources (such as our simple EJB) from WebSphere Application Server Network Deployment: cell, cluster, node, and server level. For instance, if there are several node and cluster members, a JNDI name qualified to the cell or cluster level is recommended to facilitate workload management of that resource.

In our case, we only have one server, the integrated test server, and thus we will use the shortest JNDI name available, which is qualified to the server level. From the initial namspace dump, copy the JNDI name for the server itself without the first forward-slash. In our case, it is nodes/localhostNode01/servers/server1. Run dumpNameSpace again with the -startAt switch. For example:

dumpNameSpace.sh -startAt nodes/localhostNode01/servers/server1

Figure 8. Name space for Server1
Figure 8. Name space for Server1

Notice that the JNDI name for SimpleEJBHome is now shorter. The name highlighted in Figure 8 without the first forward-slash, ejb/devworks/example/SimpleEJBHome, is what we will use in our Community Edition servlet code to look up our WebSphere Application Server resource.


Create Community Edition Web project

We are now ready to build our servlet that will run in the Community Edition servlet container. We will use Rational Application Developer to build our consumer servlet.

  1. Create a new workspace in Rational Application Developer. You can switch workspaces by selecting File => Switch Workspace... or by specifying a new one at startup.

  2. In the Web Perspective, right-click Dynamic Web Projects and select New => Dynamic Web Project.

  3. Enter or select the following values for the new project (Figure 9):

    • Name: GeronimoWebApp
    • Servlet version: 2.4
    • Target server: WebSphere Application Server v6.0 (We will actually be deploying to Community Edition, but this is the valid value here.)
    • EAR project: GeronimoWebAppEAR

    and then select Finish.

    Figure 9. Dynamic Web project definition
    Figure 9. Dynamic Web project definition

    To call the remote EJB running on WebSphere Application Server, the servlet needs to have the EJB client JAR that we created from the simple EJB project added to its classpath. In the next steps, we will use the standard J2EE convention of adding utility JARs to the /WEB-INF/lib directory of the GeronimoWebApp Web Application Resource (WAR) file.

  4. Expand Dynamic Web Projects => GeronimoWebApp => Web Content => WEB-INF and then right-click on lib. Select Import... => File System => Next.

  5. Browse... to the directory of the EJB client JAR for SimpleEJB, select EJBClient.jar, and then Finish.

  6. The /WEB-INF/lib directory should be similar to Figure 10.

Figure 10. Web project utility JAR
Figure 10. Web project utility JAR

Create servlet to call the simple EJB

We are now ready to write our consuming servlet whose job is to call the EJB running and residing on WebSphere Application Server V6. Again, we will use the Rational Application Developer wizards to aid us in developing our code.

  1. Right-click on Deployment Descriptor: GeronimoWebApp and select New => Servlet. Name the servlet TestEJBServlet and then Next.

    Figure 11. Create a new servlet
    Figure 11. Create a new servlet
  2. For the Java package name, enter devworks.example and then press Next.

    Figure 12. Specify package
    Figure 12. Specify package
  3. Uncheck doPost and then Finish.

    Figure 13. Finish servlet
    Figure 13. Finish servlet
  4. Insert the code below for the doGet method:

    protected void doGet(HttpServletRequest request, HttpServletResponse response) throws 
    ServletException, IOException {
    	String text = "";
    	final String jndiName = "ejb/devworks/example/SimpleEJBHome"; [A]
    	Properties env = new Properties();
    	env.setProperty(Context.PROVIDER_URL, "iiop://localhost:2809"); [B]
    	env.setProperty(Context.INITIAL_CONTEXT_FACTORY, 
    		"com.ibm.websphere.naming.WsnInitialContextFactory");
    	
    	try {
    		
    		InitialContext ctx = new InitialContext(env); [C]
    		Object obj = ctx.lookup(jndiName); [D]
    		SimpleEJBHome ejbHome =
    			(SimpleEJBHome) 
    			javax.rmi.PortableRemoteObject.narrow(obj, SimpleEJBHome.class); [E]
    		SimpleEJB myEJB = ejbHome.create(); [F]
    		
    		text = myEJB.retrieveText(); [G]
    		
    	} catch(NamingException ne) { [H]
    		System.err.println("TestEJBServlet failed to lookup SimpleEJBHome. JNDI 
    String="+jndiName);
    		ne.printStackTrace(System.err);
    		// Recovery strategy omitted (i.e. try again with a different host/port)
    	} catch(CreateException ce) {
    		System.err.println("TestEJBServlet failed to create SimpleEJB instance.");
    		ce.printStackTrace(System.err);
    		// Recovery strategy omitted (i.e. clear the JNDI resource cache on the 
    		// context factory and try again)
    	}
    	response.getWriter().println("Text from WebSphere Server: " + text); [I]

    The notes here provide a detailed summary of this code; the lettered steps refer to the bracketed letters in the code sample.

    1. This is the JNDI string used to locate the SimpleEJBHome remote administered object. Notice that this is the JNDI string we determined using our dumpnamespace script earlier.
    2. Two properties are required to initialize the JNDI context, the IIOP URL of the server and the class for the context factory. For additional properties, such as turning off the default lookup cache, see the WebSphere Application Server Information Center.
    3. The initial context is created using the properties.
    4. Our remote administered object, the SimpleEJBHome interface, is retrieved using the JNDI name.
    5. The object must be "narrowed" (which is effectively the casting of a remote reference) to the SimpleEJBHome interface.
    6. A SimpleEJB instance is created from the EJB Home interface.
    7. The retrieveText() remote method is called and the result is bound to the text String variable.
    8. The remote call requires that two exceptions be caught, NamingException and CreateException. Both these exceptions have subclasses to consider and handling them takes careful care in real enterprise applications. (For the purpose of this article, this example is necessarily brief.)
    9. The contents of the text string are outputted to the browser.
  5. As a final task, we must export the WAR to be deployed on Geronimo. Right-click GeronimoWebApp and select Export... => War file.

  6. Name the new file GeronimoWebApp.war.


Creating a deployment plan for Community Edition deployment

Before deploying our WAR file to Community Edition, we must create a deployment plan. To do this, create a text file called geronimo-jetty.xml that contains this code as its contents:

<web-app xmlns="http://geronimo.apache.org/xml/ns/web/jetty"
   configId="/devworks10/geronimo/testejb">
    <dependency>
        <uri>upload/jars/naming.jar</uri>
    </dependency>
    <dependency>
        <uri>upload/jars/wsexception.jar</uri>
    </dependency>
    <dependency>
        <uri>upload/jars/ras.jar</uri>
    </dependency>
    <dependency>
        <uri>upload/jars/bootstrap.jar</uri>
    </dependency>
    <dependency>
        <uri>upload/jars/emf.jar</uri>
    </dependency>
    <dependency>
        <uri>upload/jars/namingclient.jar</uri>
    </dependency>
    <dependency>
        <uri>upload/jars/ecutils.jar</uri>
    </dependency>
    <dependency>
        <uri>upload/jars/iwsorb.jar</uri>
    </dependency>
    <dependency>
        <uri>upload/jars/idl.jar</uri>
    </dependency>
    <dependency>
        <uri>upload/jars/ffdc.jar</uri>
    </dependency>
    <dependency>
        <uri>upload/jars/stubs.jar</uri>
    </dependency>

    <context-root>/testejb</context-root>
    <context-priority-classloader>false</context-priority-classloader>

</web-app>

This XML file is known as a deployment plan. In this code:

  • Configid is a unique application name that appears in the Community Edition administrative console.
  • Context-root is the same as the context-root in the EAR deployment descriptor of a J2EE application. We will use this context-root when we access our servlet from a Web browser.
  • The classloader property is set to false so there will be no heightened priority in classloader behavior for this application (which is the default).
  • Pay particular note to the dependency tags. Each tag refers to WebSphere Application Client JAR files that we will be adding as common libraries; these JAR files will be needed by Community Edition when our TestEJBServlet accesses our WebSphere Application Server instance.

Add WebSphere Application Client JARs to Community Edition as common libraries

As noted above, Community Edition will need certain JARs from our WebSphere Application Client installation added to its running environment as common libraries. These are needed to facilitate the communication between our Community Edition environment and the WebSphere Application Server EJB container. To add these common libraries, we need to fire up Community Edition and use its administrative console:

  1. Start Community Edition. For Windows, select Start => All Programs => IBM WebSphere => Application Server Community Edition => Start the Server. For Linux/UNIX®, execute startup.sh from the bin directory of your Community Edition installation. In our case, for example, it was located at: /opt/IBM/WASCE/bin/startup.sh

  2. Open the Community Edition administration console by opening a Web browser and navigating to http://localhost:8080/console/.

  3. For the username, enter system, and for the password, enter manager.

  4. To add common libraries, go to the Community Edition admin console and select Services =>Common Libaries.

  5. Use the Add File to Repository facility to add the files listed below from the WebSphere Application Client installation directory's lib directory. (The JAR files here get added to the upload directory, which is why the deployment plan we created earlier refers to the files below in <dependency> tags.)

    • bootstrap.jar
    • ecutils.jar
    • emf.jar
    • ffdc.jar
    • idl.jar
    • iwsorb.jar
    • naming.jar
    • namingclient.jar
    • ras.jar
    • stubs.jar
    • wsexception.jar
Figure 14. Repository viewer
Figure 14. Repository viewer

Deploy the WAR file to Community Edition

We can now deploy our WAR file to Community Edition:

  1. Under Applications, choose All Configurations.

  2. Use the Install New Applications section of the page (Figure 15) to browse to the GeronimoWebApp.war (Archive) and geronimo-jetty.xml (Plan) files we created earlier.

    Figure 15. Install Web application
    Figure 15. Install Web application
  3. The application should start automatically. Make sure the integrated WebSphere Application Server is started.

  4. To test our cross-server scenario, we will test the Geronimo servlet's ability to invoke our WebSphere Application Server remotely-exposed EJB method. Simply open this location in a browser running on the Community Edition machine: http://localhost:8080/testejb/TestEJBServlet.

    Figure 16. TestEJBServlet output
    Figure 16. TestEJBServlet output
  5. You should see a response similar to that shown in Figure 16, generated courtesy of our WebSphere Application Server EJB entity.


Reviewing our approach

Not just for EJBs!

Although this article demonstrated how to access an EJB component, there is no restriction as to what type of J2EE resource can be accessed from a third party application server. For example, you could even access a JDBC data source object externally. The core concept to take with you is how you can access the JNDI tree of WebSphere Application Server via a third party application server. From there, you can interact with virtually any of the resources housed in the JNDI tree.

Why not use Web services?

Why take this approach rather than use Web services to bridge the two application servers in question together? With our method, we are specifically talking Java to Java. Accordingly, there is no need to take on the performance burden of Web services when we can talk from container to container without having to pay the costs of SOAP serialization/deserialization. Also, you cannot assume that you will always have access to the WebSphere container running your J2EE resource and that you will be able to wrap a resource, such as an EJB, as a Web service.

Clustering considerations

An organization might find benefit from using their J2EE resources, like Enterprise JavaBeans residing in WebSphere Application Server, from a third party application server, as described in this article. However, if this approach is to be used in production, you need to pay careful attention to the high availability aspects of the target J2EE resources being hit on WebSphere Application Server. An application on the consuming application server hitting WebSphere Application Server should not hit a specific instance of the application server cluster. Rather, as stated earlier, you should use a JNDI name qualified to the cell or cluster level for the target resource to facilitate workload management of the resource.


Conclusion

This article demonstrated how to access a J2EE resource contained in a WebSphere Application Server container for organizations that would like to leverage their WebSphere Application Server J2EE resources from any non-WebSphere-based application servers that may also be running in their data centers. Specifically, we showed how to enable WebSphere Application Server Community Edition, IBM's J2EE application server based on Apache Geronimo, to access a J2EE resourse running under WebSphere Application Server.

Resources

Learn

Get products and technologies

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 WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere, Open source
ArticleID=104379
ArticleTitle=IBM WebSphere Developer Technical Journal: Leverage existing WebSphere Application Server J2EE resources from WebSphere Application Server Community Edition
publish-date=02222006