Enterprise JavaBeans: Getting Started with EJB, Part 7

Developer.com content and product recommendations are editorially independent. We may make money when you click on links to our partners. Learn More.

Java Programming, Lecture Notes #1316

• Preface
• Preview
• Introduction
• A Brief Look at JNDI
• The Client Program
• Interesting Code Fragments
• The Compilation Batch File
• Starting the Server
• The Client jar File
• The Execution Batch File
• Stopping the Server
• When Things Don’t Work as Planned
• Summary
• Where To From Here?
• Complete Program Listing

Seventh in a miniseries

This lesson is also the last lesson in a miniseries of seven lessons intended to get you up and running with Sun’s Enterprise JavaBeans(TM) very quickly.

1. Download and install Java 2 Platform, Standard Edition from Sun.  As of the date of this writing, it can be found at the following URL:  http://java.sun.com/j2se/1.3/
2. Download and install the Java 2 Platform, Enterprise Edition.  As of the date of this writing it can be found at the following URL:  http://java.sun.com/j2ee/download.html
3. Write the bean class and any helper classes that the bean may need.
4. Write two interfaces known as the home and remote interfaces.
5. Write a batch file to control the compilation process for the bean and the interface files.
6. Use the batch file to compile the bean class, any helper classes, and the two interfaces.
7. Use Sun’s J2EE deploytool program to deploy the bean into the server, being careful to save the client jar file.  The client jar file contains some class files for stubs and skeletons that are required by the client.
8. Write the client program.
9. Write a batch file to control the compilation of the client program.
10. Use the batch file to compile the client program.
11. Copy the client jar file into the directory containing the client class files.
12. Write a batch file to control execution of the client program.
13. Start the server running.
14. Use the batch file to execute the client file, which in turn will cause the bean to be executed in the server.

Download and install Java tools

At this point, you shouldn’t need any help in accomplishing the first two steps.  Those steps simply involve downloading and installing software from Sun.

Write and deploy the bean

The six previous lessons, beginning with the lesson entitled Enterprise JavaBeans(TM): Getting Started with EJB, Part 1 showed you how to accomplish steps 3 through 7.

Writing and running a client program

This lesson will show you how to accomplish steps 8 through 14 (highlighted in boldface above).  This will entail writing and running a client program for the purpose of exercising the Enterprise Bean that you wrote and deployed in the previous six lessons.

I will walk you through the operations necessary to accomplish these steps without attempting to explain the purpose of every operation in detail.  Subsequent lessons will provide information that bears on the purpose of the operations.

The lessons in this miniseries show you the steps involved in writing, compiling, deploying and executing a simple bean.  The discussion has been brief, and is intended primarily to get you to the point that you can get something running very quickly.

More details in subsequent lessons

Subsequent lessons will come back and fill in the gaps to help you more-fully understand each of the steps.

Subsequent lessons will also teach you about the different kinds of beans and how to use those beans in different situations.

Recommended supplementary reading

It is strongly recommended that you study the previous lesson entitled Enterprise JavaBeans(TM), Getting Started with EJB, Part 6 before embarking on this lesson.

Additional supplementary material that I have written is available at Gamelan.  As of the date of this writing, Gamelan does not maintain a consolidated index to my Java tutorials.  Therefore, they may be difficult to locate on the Gamelan site.  A consolidated index with links to the tutorials on the Gamelan site is available at Baldwin’s Java Programming Tutorials.

The required steps

As mentioned above, our Enterprise Bean has now been deployed in the J2EE server.  We are down to the point where we need to deal with the client program.  This will involve carrying out steps 8 through 14 in the above list.

Viewing tip

You may find it useful to open another copy of this lesson in a separate browser window.  That will make it easier for you to scroll back and forth and refer to earlier material without losing your place.

Beans versus beans

Just in case you are reading this lesson without having read the earlier lessons in this series, I will tell you that an Enterprise Bean is not the same thing as a JavaBean Component(TM), as discussed in my series of tutorial lessons beginning with lesson number 500.

Naming systems

If you browse the web, or use the file system on your computer, you are familiar with naming systems.

The file system on your computer is a naming system that makes it possible for you to navigate the file system on the basis of directory and file names.

Whenever you type a URL into your browser in order to navigate the web, you are using a naming system commonly known as the Domain Name System, or DNS for short.

A standard interface to naming systems

The purpose of JNDI is to provide a standard Java interface to all naming systems, regardless of how they are constructed.

Similar to JDBC in concept

JNDI is very similar to JDBC in concept.  JDBC provides a standard Java interface to all SQL database systems for which JDBC class libraries are available.

In theory, the Java code that you write to manipulate the data in one SQL database can be used to manipulate the data in any SQL database for which you can obtain JDBC class libraries from the database vendor.

Uses interface definitions

Sun provides the definition of the standard interface through the publication of a set of Java interface definitions.  The database vendors provide the class libraries that implement those Java interfaces.

Once you install the vendor’s class libraries on your system, you can program to the standard interface, and the vendor’s class files will take care of the differences that exist from one brand of database to the next.

JNDI service providers

Similarly, JNDI provides a standard interface to a general naming or directory system.  This also consists primarily of a set of interface definitions.

Again, Sun provides the standard interface definition.  The designers of the specific naming and directory systems provide class libraries that implement the required Java interfaces.  In JNDI jargon, these class libraries are often referred to as service providers.

EJB clients use JNDI

EJB servers expose their beans to clients by way of a naming service, possibly of a proprietary design.

EJB clients use JNDI (along with the service providers from the EJB server vendors) to access the naming service.

The naming service is accessed for the ultimate purpose of gaining access to the home and remote interfaces for the beans.  Once the client programs have access to the home and remote interfaces, they can manipulate the beans by way of those interfaces.

What is a context?

If you read about JNDI, you will notice very heavy use of the term context (this will also show up in the client code).  According to Java Enterprise in a Nutshell by Flanagan, Farley, Crawford, and Magnusson, “A naming service associates names with objects.  An association between a name and an object is called a binding, and a set of such bindings is called a context.”

A walk through the program

I am going to walk you through this program, skipping certain parts involving JNDI that you don’t necessarily need to understand at this point in your learning process.  (I plan to come back and fill in those gaps in subsequent lessons.  In those lessons, I will attempt to help you understand some of the complex details involved in the interface between clients and EJB servers achieved through the use of JNDI.)

Contents of my directory

Before getting into the details of the client program, however, I want to show you the list of files that exist in a directory on my hard drive:

• After the deployment of the EJB is complete
• After deleting all class files associated with that deployment
• Prior to compiling the client program

This information may be useful to you in your efforts to duplicate my results.

Batch files

First, there are three batch files:

• compileEJB.bat – A batch file that was used to compile the Enterprise Bean.  This file was discussed in the lesson entitled Enterprise JavaBeans(TM): Getting Started with EJB, Part 2
• compileClient.bat – A batch file that will be used to compile the client program.  That file will be discussed in this lesson
• testClient.bat – A batch file that will be used to run the client program and execute the Enterprise Bean.  That file will also be discussed in this lesson

Archive files

There are two archive files in the directory, both produced by the deployment process discussed in the previous six lessons.

• HelloApp.ear – Archive file containing the J2EE application
• HelloAppClient.jar – Archive file required for execution of the client file.

Here is what Sun has to say about the file named HelloAppClient.jar
 

Contents of HelloAppClient.jar

The archive file named HelloAppClient.jar contains the following files:

• HelloHome.class
• Hello.class
• HelloBean.class
• _HelloHome_Stub.class
• _Hello_Stub.class
• ejb-jar-ic.jar
• META-INF.application.xml
• META-INF.Manifest.mf
• META-INF.sun-j2ee-ri.xml

I plan to come back and discuss all of these files in a subsequent lesson.  For the moment, however, I simply want to show you a list of the files contained in the jar file.  This jar file will later be placed on the classpath for execution of the client program.  (Interestingly, it is easy to demonstrate through a process of elimination that the only files required in the jar file for successful execution of this simple client program are the two stub files highlighted in boldface in the above list.)

Java source code files

Finally, my directory contains four Java source files.

• HelloBean.java – The source code for the Enterprise Bean, first discussed in the lesson entitled Enterprise JavaBeans(TM): Getting Started with EJB, Part 2
• Hello.java – The source code for the remote interface, first discussed in the lesson entitled Enterprise JavaBeans(TM): Getting Started with EJB, Part 2
• HelloHome.java – The source code for the home interface, first discussed in the lesson entitled Enterprise JavaBeans(TM): Getting Started with EJB, Part 2
• HelloClient.java – The source code for the client program, to be discussed in this lesson

The first fragment, shown in Listing 1 below, shows the beginning of the controlling class and the beginning of the main() method.  There is nothing remarkable about this fragment, and I show it here simply for completeness.
 

public class HelloClient{

  public static void main(

      String[] args) throws Exception {

Listing 1

Get reference to the home interface

The next fragment, shown in Listing 2 below, contains some code that I am not going to explain at this point, except in general terms.  This code uses the JNDI naming system to locate the Enterprise Bean on the J2EE server, and to get a reference to the bean’s home interface.  The reference is stored in the reference variable named initial.

The JNDI name for the bean is MyHello.  This was established when the bean was deployed as discussed in an earlier lesson.  (I briefly discussed the JNDI naming system in the lesson entitled Enterprise JavaBeans(TM):  Getting Started with EJB, Part 6.)

Note that the material shown in blue is likely to change from one EJB server vendor to the next, depending on how those vendors have implemented the standard interface.
 

    try {

      /********************************

      //#1 approach

      Context initial = 

                  new InitialContext();

      ********************************/

      //Disable everything between here

      // and The End Point below when

      // approach #1 is enabled.

      String url =

        //Enable only one of the 

        // following three String 

        // values

        //#2 approach

        //”iiop://localhost:1050/“;

        //#3 approach

        //”iiop://Baldwinlaptop:1050/“;

        //#4 approach

        “iiop://192.168.1.100:1050/“;

      Hashtable env = new Hashtable();

      env.put(

      Context.INITIAL_CONTEXT_FACTORY,

            “com.sun.jndi.cosnaming.” +

                       “CNCtxFactory“);
      env.put(Context.PROVIDER_URL, 

                                  url);

      Context initial = 

               new InitialContext(env);

      //The End Point
      //The following code is common to

      // all four approaches

      Object objRef = 

             initial.lookup(“MyHello“);

      HelloHome refToHome = 

       (HelloHome)PortableRemoteObject.

                narrow(objRef, 

                      HelloHome.class);
Listing 2

Four different approaches

The code in listing 2 shows four different approaches to accomplishing the same result:  getting the reference to the home interface.  The first three approaches are disabled by comment indicators in Listing 2.

Three of the four approaches are simply different ways to identify the machine on which the J2EE server (and the associated name server) is running.

The fourth approach, which is enabled, uses the IP address of the machine on which the name server is running.  In this particular case, that was the same machine on which the client program was running as well.

No matter which approach is enabled, the end result is the same.  The above code ends with a reference to the home interface stored in the reference variable named refToHome.  That reference will be used to create the bean and to get a reference to the remote interface in Listing 4 further on.

The session context

As explained in the lesson entitled Enterprise JavaBeans(TM): Getting Started with EJB, Part 2, execution of the above code causes the bean’s callback method named setSessionContext() to be invoked.  This, in turn, causes the text shown in Listing 3 below to appear on the screen in the process window where the J2EE server is running (note that a line break was manually entered for this display):
 

Getting the remote interface

The next fragment, shown in Listing 4 below, uses the reference to the home interface to create the bean object and to get a reference to the remote interface.
 

      Hello refToRemote = 

                    refToHome.create();

Listing 4

The create() method

I discussed the create() method of the home interface in the lesson entitled Enterprise JavaBeans(TM): Getting Started with EJB, Part 2.

The execution of the create() method in Listing 4 above causes the callback method named ejbCreate() to be invoked on the bean.  This, in turn, causes the text shown in Listing 5 below to appear on the screen in the process window where the J2EE server is running (again, a line break was manually entered for this display):
 

Note that the create() method is invoked on the reference to the home interface (not on a reference to the remote interface).

Invoking a business method

As explained in the lesson entitled Enterprise JavaBeans(TM): Getting Started with EJB, Part 2, all business methods of a bean are exposed to the client program through the remote interface.

The code fragment shown in Listing 6 below uses the reference to the remote interface to invoke a business method on the bean named aBusinessMethod(). (The behavior of the business method was discussed in the lesson entitled Enterprise JavaBeans(TM): Getting Started with EJB, Part 2.  Basically, it receives an incoming string parameter, concatenates a literal string onto it, and returns the new string produced by the concatenation of the two.)
 

     String returnValue = 

          refToRemote.aBusinessMethod(

                      “Dick Baldwin”); 

     System.out.println(

                     “Bean returned: ” 

                       + returnValue);

Listing 6

Display the results

The code in Listing 6 above also displays the string returned by the business method.

Execution of code in Listing 6 above causes the output shown in Listing 7 below to appear on the screen in the process window where the client program is running (this output appears on the client screen and not on the server screen as has been the case for output produced by the callback methods of the bean):
 

Note that the aBusinessMethod() method is invoked on the reference to the remote interface, not on the reference to the home interface.

Removing the bean

Finally, the code in Listing 8 below causes the bean to be removed.
 

      /********************************

      //Remove the bean using

      // refToRemote approach. Doesn’t

      // always work properly.

      refToRemote.remove();

      ********************************/

      //Remove the bean using

      // refToHome approach.  This also

      // doesn’t always work properly.

      Handle handle = 

               refToRemote.getHandle();

      refToHome.remove(handle);

Listing 8

Execution of either version of the remove() method shown in Listing 8 causes the callback method named ejbRemove() to be invoked on the bean.  This, in turn, causes the text in Listing 9 to appear on the screen in the process window where the J2EE server is running (again, a line break was manually entered for this display format).
 

Note that one version of the remove() method can be invoked on the remote interface and the other version can be invoked on the home interface.  According to Enterprise JavaBeans by Richard Monson-Haefel, “For session beans, remove() causes the session to be released and the EJB object reference to become invalid.  For entity beans, the actual entity data is deleted from the database and the remote reference becomes invalid.”

A caution

I have observed some erratic behavior when invoking the remove() method on either the home interface or the remote interface with J2EE version 1.2.1.  Sometimes the invocation of the remove() method doesn’t cause the bean to be removed.  In those cases, the ejbRemove() method is not invoked on the bean, and it is subsequently possible to invoke the business methods on the bean.  The fact that the reference to the bean doesn’t become invalid in those cases confirms that the bean really isn’t being removed.

The remaining code

The remaining code in the program is generally uninteresting.  You can view that code in the complete listing of the program shown near the end of the lesson.

Writing, deploying, and executing a bean

So, there you have it, the writing and deployment of a simple Enterprise Bean followed by the writing and execution of a simple client program that invokes a business method on the Enterprise Bean.  The client program also performs other actions on the bean that cause certain callback methods of the bean to be invoked.

There are a few more details to be dealt with, involving the compilation and execution of the client program.  Those details will be dealt with in the sections that follow.

Listing 10 below shows a batch file that I used to compile the client program. (Note that I had to manually insert a line break following the word javac to make the material fit into this narrow publication format.  You will need to remove that line break before you use this batch file.)
 

set J2EE_HOME=d:progfilej2sdkee1.2.1

set CPATH=.;%J2EE_HOME%libj2ee.jar

javac 

    -classpath %CPATH% HelloClient.java
Listing 10

Just some classpath manipulations

Hopefully, there is nothing in the batch file shown in Listing 10 that will come as a surprise to you.  The first line simply creates an environment variable named J2EE_HOME that specifies the installation location for the J2EE software on my system.

The second line creates an environment variable named CPATH whose value will later be used as a Java classpath.  This environment variable places the current directory on the classpath that it represents (note the single period followed by the semicolon) and also specifies the location of the jar file containing the class library files for J2EE.

Using the -classpath option

The third line uses the -classpath option of the javac program to set the user classpath to the value of the CPATH environment variable.  This replaces any classpath variable that may have been set earlier through other means such as the autoexec.bat file in Win95/98, or the system dialog in WinNT.

However, use of the option doesn’t prevent the compiler from knowing where to find the standard Java class libraries.  Assuming that you installed your Java tools as recommended by sun, the standard Java class libraries are located by the compiler on a relative path basis and not on the basis of a classpath variable.

Compiling the client program

The third line in the batch file also causes the client program named HelloClient.java to be compiled.

Execute the batch file to compile your client program.  Once you have compiled your client program, it is ready to be used to access and invoke business methods on the Enterprise Bean that was deployed into the J2EE server in the earlier lessons.  First, however, it is necessary to start the J2EE server running.

j2ee -verbose

A large amount of text will appear on the screen as the server starts running.  Make certain that the text on that screen ends with the following text.  Otherwise, the server hasn’t been properly started.

J2EE server startup complete.

set J2EE_HOME=d:progfilej2sdkee1.2.1

set CPATH=.;%J2EE_HOME%libj2ee.jar;

                     HelloAppClient.jar

java -classpath “%CPATH%” HelloClient

pause
Listing 11

Note that this batch file places the jar file named HelloAppClient.jar on the classpath so that the virtual machine can find the stub files, which are contained in that jar file.  These stub files were discussed earlier. (In this case, I had to insert a manual line break in the second line.  You will need to remove it before attempting to use a copy of Listing 11 as a batch file.)

There shouldn’t be anything in Listing 11 that you don’t understand. (The use of the pause at the end makes it possible to simply click on the name of the batch file in Windows Explorer in order to execute the batch file.)

Exercise the Enterprise Bean

Double-click on the name of the batch file shown in Listing 11 above to run the client program.  This will cause:

• The bean to be created
• Several of its callback methods to be executed
• A business method to be invoked on the bean
• The bean to be removed

Running the batch file should cause a new process window to appear.  After a pause, the text shown in Listing 12 below should appear in that process window.
 

Bean returned: Hello Dick Baldwin

D:… pause (path removed for brevity)

Press any key to continue . . .
Listing 12

Also, while the bean is running, you should see three lines of output produced by the bean’s callback methods appear on the server screen.

j2ee -stop

One of the things that makes EJB programming difficult is the fact that you really can’t test your bean until you have deployed it and have written a client program to test it.

Hopefully, everything will work as planned.  However, sometimes when you get to the stage of testing your bean using a client program, you will discover that the behavior of your bean is not exactly what you wanted it to be.  In that case, you will need to modify and redeploy your bean.

Edit and recompile source code

If you can correct your problem by making changes in the source code for your existing bean classes, redeployment is straightforward.  Just edit your source code and recompile it.  Then start the server and the deployment tool as described in the previous lessons.

Update and redeploy application

One of the buttons on the toolbar of the deployment tool has a tool tip that reads Update and Redeploy Application.  This selection also appears on the Tools menu.

Click the button, or make the selection from the Tools menu.  You should see the Deployment Progress Screen shown in Figure 7 of the lesson entitled Enterprise JavaBeans(TM):  Getting Started with EJB, Part 6.

If the green and blue bars on the progress screen make it all the way to the top and the text indicates that the deployment is complete, you should be able to test the modified version of your bean using your client program.

• Writing a simple Enterprise Bean
• Deploying the bean in the J2EE server
• Writing a client program to exercise the bean
• Running the client program

Hopefully, you have been able to follow along and duplicate the results shown above.

Future lessons in this series on EJB will fill in the details for this simple bean.  Future lessons will also show you how to write and use more complex beans, taking advantage of many of the powerful features that EJB has to offer.

/* File HelloClient.java

Copyright 2000 R.G.Baldwin

Rev 9/15/00

This client program was tested with the

bean named HelloBean.  That is a simple

session bean that receives and returns 

a String object.
The following output was produced in 

the windowwhere the client program was

running:

  

Bean returned: Hello Dick Baldwin
The following output was produced in 

the window where the j2ee server was 

running with the HelloBean installed on

the server (line breaks were manually

inserted in this display):

  

HelloBean got SessionContext 

Sat Sep 16 08:13:41 CDT 2000

HelloBean Created 

Sat Sep 16 08:13:41 CDT 2000

HelloBean Removed 

Sat Sep 16 08:13:41 CDT 2000

**************************************/

import javax.naming.Context;

import javax.naming.InitialContext;

import javax.rmi.PortableRemoteObject;

import java.util.Hashtable;
public class HelloClient{

  public static void main(

      String[] args) throws Exception {

    //Get a reference to the bean’s 

    // home interface.  Here are four

    // different ways to do it. MyHello

    // is the JNDI name for the bean.

    //The information required to

    // construct the last three was

    // obtained from a code sample at 

    // the following URL:

    // http://developer.java.sun.

    //   com/developer/codesamples/

    //   javax.naming/283.html

    try {

      /********************************

      //#1

      Context initial = 

                  new InitialContext();

      ********************************/
      //Disable everything between here

      // and The End Point below when

      // #1 is enabled.

      String url =

        //Enable only one of the 

        // following three String 

        // values

        //#2 

        //”iiop://localhost:1050/”;

        //#3

        //”iiop://Baldwinlaptop:1050/”;

        //#4

        “iiop://192.168.1.100:1050/”;

      Hashtable env = new Hashtable();

      env.put(

      Context.INITIAL_CONTEXT_FACTORY,

            “com.sun.jndi.cosnaming.” +

                       “CNCtxFactory”);

      env.put(Context.PROVIDER_URL, 

                                  url);

      Context initial = 

               new InitialContext(env);

      //The End Point
      //The following code is common to

      // all four approaches

      Object objRef = 

             initial.lookup(“MyHello”);

      HelloHome refToHome = 

       (HelloHome)PortableRemoteObject.

                narrow(objRef, 

                      HelloHome.class);
      //Use the home reference to

      // create the bean object and

      // get a remote reference.

      Hello refToRemote = 

                    refToHome.create();

      

      //Invoke a business method on the

      // remote reference to the bean

      String returnValue = 

           refToRemote.aBusinessMethod(

                       “Dick Baldwin”);

      System.out.println(

                      “Bean returned: ”
                        + returnValue);
      /********************************

      //Remove the bean using

      // refToRemote approach. Doesn’t

      // always work properly.

      refToRemote.remove();

      ********************************/
      //Remove the bean using

      // refToHome approach.  This also

      // doesn’t always work properly.

      Handle handle = 

               refToRemote.getHandle();

      refToHome.remove(handle);
    }catch (Exception ex) {

      System.err.println(“Exception!”);

                  ex.printStackTrace();

    }//end catch

  }//end main

}//end class
Listing 13

Copyright 2000, Richard G. Baldwin.  Reproduction in whole or in part in any form or medium without express written permission from Richard Baldwin is prohibited.

About the author

Richard Baldwin is a college professor and private consultant whose primary focus is a combination of Java and XML. In addition to the many platform-independent benefits of Java applications, he believes that a combination of Java and XML will become the primary driving force in the delivery of structured information on the Web.

Richard has participated in numerous consulting projects involving Java, XML, or a combination of the two.  He frequently provides onsite Java and/or XML training at the high-tech companies located in and around Austin, Texas.  He is the author of Baldwin’s Java Programming Tutorials, which has gained a worldwide following among experienced and aspiring Java programmers. He has also published articles on Java Programming in Java Pro magazine.

Richard holds an MSEE degree from Southern Methodist University and has many years of experience in the application of computer technology to real-world problems.

baldwin.richard@iname.com