October 30, 2014
Hot Topics:
RSS RSS feed Download our iPhone app

Enterprise JavaBeans: Helper Classes

  • April 4, 2001
  • By Richard G. Baldwin
  • Send Email »
  • More Articles »

Java Programming, Lecture Notes #1322


Preface

This is one in a series of lessons designed to teach you about Sun's Enterprise JavaBeans (EJB).

A cookbook approach

Previous lessons in this series provided accelerated instructions to help you get your first enterprise bean up and running as quickly as possible.

In working through the accelerated lessons, I provided the information more or less in a cookbook fashion.

A change of pace

Now that you have your first enterprise bean running successfully in your J2EE server, it is time to slow down the pace, and embark on the task of understanding Enterprise JavaBeans (not only what, but also how and why).

The purpose of the remaining lesson in this series on EJB will be to help you really understand what enterprise beans are, how to write them, and how to use them to advantage.

From this point on, I intend to go much more slowly explaining things more carefully as I proceed.  Along the way, I will show you lots of sample bean programs, each of which will be as simple as I can make it while still illustrating the concept that the program is intended to illustrate.

Recommended supplementary reading

It is strongly recommended that you study the previous lesson entitled Enterprise JavaBeans:  Middle-Tier Servers and J2EE 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.

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.

Preview

In this lesson, I will present a sample enterprise bean program that you can use to hone your skills in the deployment of enterprise beans into the J2EE server.

This sample program will require deployment procedures that are a little different than those that I have shown you in previous lessons.  In particular, this program includes a helper class that the primary bean class uses to accomplish the objectives of its business method.  You must make certain that you cause the class file representing the helper class to be included in the bean's jar file when you deploy the bean.

Sample Program

The name of the source file for this enterprise bean class is HelperBean.java.  Complete listings of the source code for the bean class and a simple client program that exercises the bean are provided in the listings near the end of the lesson.

Helper classes

The purpose of this bean is to illustrate the use of helper classes.  Helper classes are classes that the primary bean class calls upon to successfully execute its business methods.

This bean receives and returns a String object via a single business method named aBusinessMethod().  When the business method is invoked by the client, the business method instantiates an object of another class named AHelperClass and invokes a method on that object named getTheDate().  The method named getTheDate() returns a String representation of the current date and time.

(Obviously, this could be accomplished without a helper class, but the objective here is to illustrate the use of helper classes and this is one way to do that.)

Business method returns the date and time

The business method concatenates the string Hello onto the incoming String producing a new String.  It concatenates the date string onto that String with a newline character separating the two, producing the final String.  It then returns the final String that results from the concatenation process.

The string that is returned is:

"Hello" + <incoming string> + 'n' +
                          <date/time>

where the material in angle brackets varies from one invocation of the business method to another invocation of the business method.

A little more complicated...

This bean is slightly more complicated than the bean that I used to teach you how to write, compile, deploy, and run a stateless session bean in the previous lessons.  I am providing this bean to give you additional practice in deploying a bean.

The punch line

Class files for helper classes must be encapsulated in the jar file that contains the primary bean class files along with the class files for the remote and home interfaces, the manifest, etc.

After you deploy the bean, it would be a good exercise for you to unzip the resulting J2EE application file, and the bean's jar file to confirm that you did successfully encapsulate the class file for the helper class in the bean's jar file.

My results

My J2EE application file (produced by the deployment process) was named Helper01.ear.  The bean's jar file contained within the application file was named ejb-jar-ic.jar.  The contents of the bean's jar file are shown in Listing 1 below (META-INF. indicates a sub directory).
 

META-INF.ejb-jar.xml
META-INF.MANIFEST.MF
AHelperClass.class
HelperRemote.class
HelperBean.class
HelperHome.class

Listing 1

Four class files were encapsulated

As you can see, the bean's jar file contained class files for the bean, the remote interface, the home interface, and the helper class.  It also contained a deployment descriptor file named ejb-jar.xml, and a manifest file named MANIFEST.MF.

The deployment descriptor file

Listing 2 below shows the contents of the deployment descriptor file (note that I had to manually enter some line breaks and use a very small font to make it fit in this narrow presentation format).  You might find it useful to examine the contents of your deployment descriptor file to see if you can correlate various elements in the file with actions that you took during the deployment process.
 

<?xml version="1.0" encoding="Cp1252"?>

<!DOCTYPE ejb-jar PUBLIC '-//
Sun Microsystems, Inc.//DTD Enterprise 
JavaBeans 1.1//EN' 'http://java.sun.
com/j2ee/dtds/ejb-jar_1_1.dtd'>

<ejb-jar>
  <description>This bean illustrates 
  the use of helper classes.
  </description>
  <display-name>Helper01JAR
  </display-name>
  <enterprise-beans>
    <session>
      <description>no description</description>
      <display-name>Enterprise Bean</display-name>
      <ejb-name>Enterprise Bean</ejb-name>
      <home>HelperHome</home>
      <remote>HelperRemote</remote>
      <ejb-class>HelperBean</ejb-class>
      <session-type>Stateless</session-type>
      <transaction-type>Bean</transaction-type>
    </session>
  </enterprise-beans>
</ejb-jar>

Listing 2

The contents of your deployment descriptor file may not match mine exactly, because you may use different names and different descriptions during deployment.  However, everything highlighted in boldface in Listing 2 should probably match.

The manifest file

Listing 3 below shows the contents of the manifest file.
 

Manifest-Version: 1.0

Listing 3

The output

When the business method was executed on the bean by the simple client program shown in Listing 11, the following output was produced on my client screen.  Obviously, your date and time will be different.

Bean returned: Hello Dick Baldwin
Mon Jan 08 18:19:34 CST 2001

The bean was tested using Sun J2EE and JDK 1.3 under WinNT 4.0.

Interesting Code Fragments

In keeping with my normal approach, I will break this program down and discuss it in fragments.  As mentioned earlier, you can view a complete listing of the program in Listing 10 near the end of the lesson.

The bean class declaration

The first fragment, shown in Listing 4 below, shows import directives, along with the declaration of the bean class, and the declaration of an instance variable, capable of storing a reference to a SessionContext object.
 

import javax.ejb.*;
import java.util.Date;

public class HelperBean 
                implements SessionBean{
  SessionContext ctx;

Listing 4

Recall that a class file from which a session bean will be instantiated must implement the SessionBean interface.

Nothing in Listing 4 above is particularly interesting.  I included it here simply for completeness.

The business method

Listing 5 below shows the only business method belonging to the bean.
 

  
  public String aBusinessMethod(
                           String str){
    return "Hello " + str + 'n' + 
       new AHelperClass().getTheDate();
  }//end aBusinessMethod()

Listing 5

The interesting thing about this method is the fact that it instantiates an object of the helper class, and invokes a method on that object to get a String representation of the current date and time.  It concatenates that string onto another string and returns the fully-concatenated String object to the client program.

Remaining code in the bean class

Listing 6 below shows the remaining code in the bean class.  It might be worthwhile to point out that the four callback methods that are used to deal with the life cycle events of the bean are defined as empty methods. (I didn't need to do anything special when the life cycle events occurred.)

Otherwise, there is nothing particularly interesting in Listing 6.  I included this fragment for completeness also.
 

  public void setSessionContext(
                  SessionContext ctx){
    this.ctx = ctx;
  }//setSessionContext()

  //Note that the following 
  // callback methods are empty.
  public void ejbCreate(){}
  public void ejbRemove(){}
  public void ejbActivate(){}
  public void ejbPassivate(){}

  //public constructor
  public HelperBean(){}

}//end class HelperBean

Listing 6

The helper class

Finally, Listing 7 below shows the simple definition of the helper class that the business method uses to get a String representation of the current date and time.
 

class AHelperClass{
  String getTheDate(){
    return new Date().toString();
  }//end method getTheDate();
}//end class AHelperClass

Listing 7

The most interesting thing about the code shown in Listing 7 is the fact that it exists, and the fact that the class file that results from the compilation of AHelperClass must be contained in the bean's jar file.  You accomplish that by including it in the set of class files that you specify for inclusion in the bean's jar file on the deployment screen shown in Figure 1 below.

Figure 1.  Deployment screen used to add files to a bean's jar file.

(You should recognize Figure 1 as one of the screens that appears when you use Sun's J2EE deployment tool.  If you don't recognize it, you will need to review the previous lessons in this series, including the lesson entitled Enterprise JavaBeans(TM):  Getting Started with EJB, Part 5.)

The home interface

The source code for the home interface is shown in Listing 8.  Hopefully, you will remember that every bean must have a home interface, and a remote interface, and that the home interface must declare one or more overloaded create() methods for the bean.
 

/* File HelperHome.java 
Copyright 2001 R.G.Baldwin           
**************************************/
import javax.ejb.*;

public interface HelperHome 
                       extends EJBHome{
  public HelperRemote create() 
       throws java.rmi.RemoteException,
             javax.ejb.CreateException;
}//end interface

Listing 8

The remote interface

The source code for the remote interface is shown in Listing 9 below.  Again, hopefully, you will remember that the remote interface must declare all the business methods belonging to the bean.
 

/* File HelperRemote.java
Copyright 2000 R.G.Baldwin
**************************************/
import javax.ejb.*;
import java.rmi.*;

public interface HelperRemote 
                     extends EJBObject{
  String aBusinessMethod(String s) 
                throws RemoteException;
}//end interface

Listing 9

The client program

A complete listing of the client program that I used to exercise this bean is shown in Listing 11 near the end of the lesson.  There is nothing new in that program, so I won't discuss it further in this lesson.  If you don't understand what you see there, you should go back and study the lesson entitled Enterprise JavaBeans(TM):  Getting Started with EJB, Part 7.

Summary

In this lesson, I provided a sample enterprise bean program for you to use in further honing your ability to deploy enterprise beans in the J2EE server.  This program includes a helper class that the primary bean class uses to accomplish the objectives of its business method.

During deployment, you must make certain that you cause the class file representing that helper class to be included in the bean's jar file.  You do that using the deployment screen shown in Figure 1 above.

Other than the existence of the helper class, the sample bean program provided in this lesson is no more complicated than the bean program that I used to teach you how to deploy stateless session beans in the previous lessons.

Where To From Here?

In the next lesson, I will discuss the two different flavors of enterprise beans:  session beans and entity beans.  After that, I will continue providing discussions and sample programs on a variety of topics that remain to be covered in developing your understanding of EJB.

Complete Program Listings

A complete listing of the source code for the bean class is shown in Listing 10 below.  A listing of a client program that can be used to test the bean is shown in Listing 11.  Listing for the home and remote interfaces are shown in Listings 8 and 9 above.
 
/* File HelperBean.java
Copyright 2001 R.G.Baldwin           
Rev 1/6/01

The purpose of this bean is to 
illustrate the use of helper classes.  
Helper classes are classes that the 
primary bean class calls upon to 
successfully execute its business 
methods.

This is a stateless session bean.

This bean receives and returns a String
object via a single business method.  
When the method is invoked by the 
client, it instantiates an object of a 
class named AHelperClass and invokes
a method on that object named 
getTheDate().  That method returns a 
String representation of the current 
date and time.

The business method concatenates the 
String Hello to the incoming String.  
It concatenates the date string onto 
that String with a newline character 
separating the two.  It then returns
the String that results from the 
complete concatenation operation.

The String that is returned is:
  
"Hello" + <incoming string> + 'n' + 
                            <date/time>

The class files for helper classes must
be encapsulated in the jar file that 
contains the primary bean class files 
along with the class files for the 
remote and home interfaces, the
manifest, etc.

When the business method was executed
on the bean by a simple client, the
following output was produced on the
client screen:

Bean returned: Hello Dick Baldwin
Mon Jan 08 18:19:34 CST 2001

Tested using Sun j2ee and JDK 1.3 under
WinNT 4.0 workstation.
**************************************/
import javax.ejb.*;
import java.util.Date;

public class HelperBean 
                implements SessionBean{
  SessionContext ctx;
  
  public String aBusinessMethod(
                           String str){
    return "Hello " + str + 'n' + 
       new AHelperClass().getTheDate();
  }//end aBusinessMethod()

  public void setSessionContext(
                  SessionContext ctx){
    this.ctx = ctx;
  }//setSessionContext()

  //Note that some of the following 
  // callback methods are empty.
  public void ejbCreate(){}
  public void ejbRemove(){}
  public void ejbActivate(){}
  public void ejbPassivate(){}

  //public constructor
  public HelperBean(){}

}//end class HelperBean
//===================================//

//This class is a helper class.  The
// class file for this class must be
// encapsulated into the bean's jar 
// file.
class AHelperClass{
  String getTheDate(){
    return new Date().toString();
  }//end method getTheDate();
}//end class AHelperClass

Listing 10

 
/* File HelperClient.java
Copyright 2001 R.G.Baldwin           
Rev 1/6/01

This client program was tested with 
the bean named HelperBean.  That is a 
simple session bean that receives and 
returns a String object.

The purpose of HelperBean is to 
illustrate the use of helper classes by
the primary bean class to execute its 
business methods.

The following output was produced in 
the client window:
  
Bean returned: Hello Dick Baldwin
Mon Jan 08 18:19:34 CST 2001

Tested using Sun JDK1.3 with J2EE1.2.1
under WinNT WkStn 4.0.
**************************************/
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.rmi.PortableRemoteObject;

import HelperRemote;
import HelperHome;

public class HelperClient{
  public static void main(
                 String[] args) 
                     throws Exception {
    //Get a reference to the bean's 
    // home interface.  MyHelper01 is 
    // the JNDI name for the bean.
    try {
      Context initial = 
                  new InitialContext();
      Object objRef = initial.lookup(
                         "MyHelper01");
      HelperHome refToHome = 
          (HelperHome)
                  PortableRemoteObject.
                    narrow(objRef, 
                     HelperHome.class);

      //Use the home reference to 
      // create the bean object and get
      // a remote reference.
      HelperRemote 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
      refToRemote.remove();
    }catch (Exception ex) {
      System.err.println("Exception!");
                  ex.printStackTrace();
    }//end catch
  }//end main
}//end class

Listing 11



Trademarks:  The following terms (and possibly some other terms used in this lesson as well) are trademarks of Sun Microsystems:  Enterprise JavaBeans, EJB, Java, Java 2 Platform Enterprise Edition, J2EE, Java Naming and Directory Interface, JNDI, and JDBC


Copyright 2001, 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






Comment and Contribute

 


(Maximum characters: 1200). You have characters left.

 

 


Sitemap | Contact Us

Rocket Fuel