Enterprise JavaBeans(TM):  Getting Started with EJB, Part 5

Baldwin shows you how to use the New Enterprise Bean Wizard to package your Enterprise Bean in its jar file.  While not conceptually difficult, it is tedious, involving approximately ten separate operations that must be performed in the correct order.

Published  January 8, 2001
By Richard G. Baldwin

Java Programming, Lecture Notes # 1314


Preface

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

Fifth in a miniseries

This lesson is also the fifth lesson in a miniseries intended to get you up and running with Sun's Enterprise JavaBeans(TM) very quickly.

Preview

The following three steps are required to deploy your bean into the J2EE server:
  1. Create the J2EE Application
  2. Package the Enterprise Bean
  3. Deploy the J2EE Application
This lesson will show you how to accomplish the second of the three steps listed above.  This will require quite a few operations including the following: I will walk you through the steps necessary to accomplish these operations without attempting to explain the purpose of each operation.  Subsequent lessons will provide information that bears on the purpose of the operations.

Introduction

Writing, compiling, deploying and executing a simple bean

The lessons in this miniseries will show you the steps involved in writing, compiling, deploying and executing a simple bean.  The discussion will be 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 4 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

An earlier lesson entitled Getting Started with EJB, Part 1 contained a list of the required steps for writing, compiling, deploying and executing a simple bean.  Abbreviated versions of the first seven steps in that list are repeated below.

The last step is a big one

The last step shown above is a big one, so I have subdivided it into several sequential lessons, beginning with the lesson entitled Enterprise JavaBeans(TM), Getting Started with EJB, Part 3.  In this group of lessons associated with deployment, I am walking you through the detailed steps necessary to deploy your new bean in the J2EE server.  I am providing that information in cookbook fashion, meaning that I will tell you what to do but not necessarily why to do it.

Class and application files available

The previous lesson began the process of deploying your bean in the J2EE server.

I am assuming that you have completed the first six steps and part of the seventh step as described in the previous lesson entitled Enterprise JavaBeans(TM), Getting Started with EJB, Part 4.

Having completed those steps, you should have the class files necessary to deploy your bean into the J2EE server.  You should also have a J2EE application file named HelloApp.ear that you created in the previous lesson.

Viewing tip

This lesson provides screen shots of the critical steps in the process.  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 and figures, 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.

Sample Bean Program

Class files

At this point, you should have the following three class files available.  Make sure that you have them all located conveniently in the same directory.

A complete listing of the bean program and the two required interfaces is provided near the end of this lesson.

Creating the J2EE Application

As described in the previous lesson, you do not deploy an Enterprise Bean directly into the J2EE server.  Rather you must first create a J2EE application and then add the bean to the J2EE application.

Then, you then deploy the application into the J2EE server.

You created your J2EE application in the previous lesson and named the file containing that application HelloApp.ear.  You need to make certain that you have that file conveniently available also.

Starting the System

Assuming that you shut down the J2EE server and the deployment tool following the previous lesson, the first thing that you need to do is to open two Command Prompt windows.  I will refer to the Command Prompt windows simply as windows.

Start the J2EE server

To start the J2EE server running, enter the following command at the prompt in one of the windows:

j2ee -verbose

A large amount of text will appear on the screen.  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.

Starting the deployment tool

Once the server has been started successfully, you need to start the deployment tool.  To do this, enter the following command in another window:

deploytool

A splash screen will appear first followed by a screen that looks similar to Figure 1.  This is the main deployment screen.  (I'm sorry that the text in this screen shot isn't readable, but I had to reduce the size of the screen shot considerably to make it fit in this narrow publication format.)

Figure 1 The J2EE Deployment Tool Main Screen

My color coding scheme

Because the following text will be a mixture of action statements and explanatory text, I will color the actions statements the following color of blue to make them easy to separate from the explanatory text.

The first action statement

If the tree view in the left side of Figure 1 contains more than one entry, choose HelloApp, which is the application that we will be working on .

Packaging the Enterprise Bean

The next major step (and the primary topic of this lesson) in the deployment of your bean is to package your Enterprise Bean in a jar file so that it can be put into the application.  This involves the following steps. Although this is what will be happening, the separation between these individual steps isn't very obvious when using the deployment tool to package the Enterprise Bean.

Start the New Enterprise Bean Wizard

A tool called the New Enterprise Bean Wizard is used to create the bean by packaging everything necessary in a jar file.

To start the New Enterprise Bean Wizard

The wizard will then display two dialog boxes in succession.

Introduction Dialog Box

The first dialog box is solely for your information and should look something like Figure 2.

This screen explains what you can do with the wizard.  The wizard can be used to do lots of things that we won't be doing in this example.

Figure 2  First Screen for New Enterprise Bean Wizard

All that you need to do with this screen is to read the material and then click Next to proceed to the next screen.

EJB JAR Dialog Box

That will produce a screen that looks something like Figure 3.

Figure 3  Second Screen for New Enterprise Bean Wizard

Selecting the application

Near the top of the screen shown in Figure 3, you will find a combo box entitled Enterprise Bean will Go In.   This is where you specify the application that your new bean will be installed in. (If this is the first application deployed on your server, you will have only one choice.)

Select HelloApp in this combo box.

The jar display name

To the right of the combo box, you will find a field entitled JAR Display Name.

Enter HelloJAR in this field.

This name will represent the EJB jar file that contains the bean in the tree view at the left on the main deployment tool screen shown in Figure 1.  You can access the jar file later if need be by clicking on this name in the tree view.  Note, however, that this will not be the name of the actual jar file.

Describe the bean

Moving on down the screen, there is a text area entitled Description.  It is initialized with the words "no description."  If you want to, you can enter a text description of the bean here.  The description will later appear in the XML file that is the deployment descriptor for the bean.

Adding files to the jar file

In this example we are going to skip over the material for the Manifest Classpath and Icons near the center of the screen.

Skip on down and click the Add button to the right of the Contents text area in Figure 3.

This will cause a smaller dialog box similar to that shown in Figure 4 to appear.  (Because it is physically smaller, I didn't need to reduce the screen shot so much.  As a result, you can probably read the text in the screen shot in Figure 4.)

Figure 4  Screen Used to Add Files to the jar File

Where are your class files located?

This dialog is divided into three parts:

Enter the name of the directory containing your class files in the text field entitled Root Directory near the top.

In doing this, you may either type the directory name in the Root Directory field or locate it by clicking Browse.

A caution

If you use the Browse button, be sure to highlight the directory that contains your class files and then click Choose Root Directory.

Don't double click the directory name.  That doesn't produce the desired result because when you double click on a directory name, only subdirectories of that directory are displayed in the text area.

Clicking Choose Root Directory on the correct directory name should cause your class files (plus possibly a lot of other files) to appear in the large text area in the center of the dialog.

Selecting and adding your class files

Select each of the following classes from the text area by highlighting them:

Then click Add to cause the files to be added to the jar file.

Confirm the results

The list of class files that you have selected should then be visible in the text area near the bottom of the dialog.  These are the files that will later be added to the jar file.  Confirm that they are the correct files.  If not, use the Remove and Add buttons to get it right.

Then Click OK to actually add the files to the jar file.

Proceeding to the next screen

This will cause the screen shown in Figure 3 to once again become the active screen.

Click Next on the screen shown in Figure 3 to proceed to the next screen.

This should cause a new screen to appear that looks something like Figure 5.

Figure 5  New Enterprise Bean Wizard - General Screen

The bean, the remote interface, and the home interface

There are three combo boxes near the top of the screen shown in Figure 5.  These combo boxes are used to identify the class files for the bean, the remote interface, and the home interface.

Entity bean or session bean?

Now you must specify whether your bean is an Entity bean or a Session bean.  If it is a Session bean, you must specify whether it is a Stateless bean or a Stateful bean.  This is done using the radio buttons in the upper right of the dialog.  (I will have a lot more to say later about the different kinds of beans and what they are used for.)

A stateless session bean

For this example, we have a Stateless Session bean.

Identifying the bean in the tree view

Next enter HelloBean in the text field entitled Enterprise Bean Display Name field near the center of the dialog.

This name will represent the Enterprise Bean in the tree view.

Another description and the next screen

Now you have an opportunity to enter another description in the large text area if you choose to do so.

After entering the description, click Next to proceed to the next screen.

This will cause a screen to appear that looks something like Figure 6.

Figure 6  New Enterprise Bean Wizard - Environment Entries Screen

We don't need this screen

At this point, we have finished packaging the Enterprise Bean for this simple application.  The remaining screens that can be exposed will be used later as we develop more complex beans.

There is nothing for us to do with the screen shown in Figure 6.  If you would like to do so, you can click the next button a few times to move through the successive screens just to take a look at them.

For this bean, however, you can simply click Finish.

Back to the screen of Figure 1

When you click Finish, the Application Deployment Tool screen, shown in Figure 1 will once again become the active screen.

If you take a look at the tree view on the left, you should see your new application named HelloApp showing.  If you click the little button to the left of the application name, you should see the display name of your Enterprise Bean jar file, which is HelloJAR.

Terminate for now

At this point, you can terminate the deployment tool by choosing Exit on the File menu.  Then you can terminate the J2EE server by entering j2ee -stop at the command prompt.

Summary

In this lesson, I showed you how to package your Enterprise Bean in its jar file.  This involved quite a few operations: Hopefully, these instructions have been sufficiently clear that you were able to follow along, even if the purpose of each operation wasn't obvious.  I will provide more information in subsequent lessons dealing with the purpose of these operations.

Where To From Here?

The previous lesson showed you how to accomplish the first step in the following list of three required steps.  This lesson showed you how to accomplish the second step.
  1. Create the J2EE Application
  2. Package the Enterprise Bean
  3. Deploy the J2EE Application
In the next lesson, I will show you how to accomplish the third step.  After that, I will show you how to create a client application that can be used to execute your Enterprise Bean.

Complete Program Listings

A complete listing of the bean program is shown in Listing 1 below.  Complete listings of the remote and home interfaces are shown in Listing 2 and Listing 3.
 
/* File HelloBean.java
Copyright 2000 R.G.Baldwin
Rev 9/15/00

This bean receives and returns a String object
via a single business method.  It also displays
information about its life cycle in the 
System.out log file or on the system comsole
depending on whether or not System.out has been
directed to the log files.

This is a stateless session bean.  According to
Sun, a session bean must meet the following
reuirements:

Implement the SessionBean interface.
Class is defined as public.
Class cannot be defined as abstract or final.
Implements one or more ejbCreate methods.
Implements the business methods.
Contains a public constructor with no 
  parameters.
Must not define the finalize method.

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

public class HelloBean implements SessionBean{
  SessionContext ctx;

  public void ejbCreate(){
    System.out.println("HelloBean Created " 
                                  + new Date());
  }//end ejbCreate()

  public String aBusinessMethod(String str){
    return "Hello " + str;
  }//end aBusinessMethod()

  public void ejbRemove(){
    System.out.println("HelloBean Removed " 
                                  + new Date());
  }//end ejbRemove()

  public void ejbActivate(){
    System.out.println("HelloBean Activated " 
                                  + new Date());
  }//end ejbActivate()

  public void ejbPassivate(){
    System.out.println("HelloBean Passivated " 
                                  + new Date());
  }//ejbPassivate()

  public void setSessionContext(
                            SessionContext ctx){
    this.ctx = ctx;
    System.out.println(
      "HelloBean got SessionContext " 
                                  + new Date());
  }//setSessionContext()

  public HelloBean(){}//public constructor

}//end class HelloBean
 

Listing 1


 
/* File HelloHome.java 
Copyright 2000 R.G.Baldwin
Rev 9/15/00
***********************************************/
import javax.ejb.*;

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

Listing 2


 
/* File Hello.java
Copyright 2000 R.G.Baldwin
Rev 9/15/00
***********************************************/
import javax.ejb.*;
import java.rmi.*;

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

Listing 3


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

-end-