Java EJB Enterprise JavaBeans: Helper Classes

Enterprise JavaBeans: Helper Classes

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.

[email protected]

Latest Posts

Related Stories