Tutorials
EnterPrise Java Beans
Tutorial Index Page

Creating an Entity Bean

EJB's require an "EJB Container", commonly provided as part of an "application server". In this tutorial, we will be using the Blazix application server as the EJB container.  Before beginning, download and install the server from the link above if you don't already have it.  (Even if you are using another server, for the first few lessons you will need Blazix.  It includes an EJB wizard that we will use for generating EJBs.  This way, we don't need to deal with all the details initially and we can concentrate on the important concepts.  Once you understand the concepts, it should be relatively easy to transfer the concepts to other servers as well.)  Also make sure to modify your PATH to include the Blazix installation directory, and to modify your CLASSPATH to include the blazix.jar file.  (For any questions relating to the Blazix server, visit the Blazix Group at Yahoo.)

Important:  The advantages of getting an actual server and trying everything hands-on cannot be overstated.  Blazix is only a 1.5 MB download so it can easily be downloaded even over a modem in a few minutes.  It will run on any Java platform including Windows 98.  Running the tutorial examples and doing the exercises is very important, because this tutorial has been written with the hands-on student in mind.  So if you haven't yet, it is strongly recommended that you go get the server now, before you proceed with this tutorial anymore!

As briefly mentioned in the overview, entity beans require a certain framework:

  • A "remote" interface.  This is the interface that does the real work -- it provides the actual services needed by the clients of the entity bean.
  • A "home" interface.  Before using an entity bean, one must find it, or create it.  The "home" interface provides methods for creating or finding the beans.
  • Entity beans also need a "primary key" class.  Each entity bean has a "primary key".  The primary key may be a single member field contained in the entity bean, or it may consist of a few member fields.  If the primary key is composed of more than one member fields, a class must be provided that corresponds to the primary key member fields.
The Blazix EJB Wizard - Blizzard - takes care of generating the basic framework, thereby simplifying the task of creating an entity bean.   For the first few exercises, we will be taking advantage of the wizard so we won't need to know all the details of the framework.

For this example, we will create an entity bean that is a permanent, shareable version of a Property list.  It will allow any of its clients to add a string at a given "key", and to retrieve the string stored at a given key.  This is a very simple usage of an entity bean, but is still useful and displays the advantages of entity beans.

We must decide upon a database representation first.  For this entity bean, a table with one column called "key" and one column called "value" is sufficient.

Step 1:  Create a database table called "PropsTable" with two columns, one called "key" and one called "value".  They should be "varchar" (or the corresponding type in your database) with some reasonable space limit, such as 255.   IMPORTANT:  Do not use the "char" datatype, otherwise all your calls will need padding the string to the correct length with spaces.

If you do not have access to a database, and if you are on a Windows machine, download the Props.mdb file which is an MS-Access database and should work on all Windows machines.

Step 2:  Configure the database table created in step 1 into the EJB configuration file.  A convenient way to do this is to create an ODBC data source. Suppose you created an ODBC data source called "PropsOdbc".  Then add the following lines to the EJB configuration file ejb.ini: 

dataSource.name: propsDataSource
dataSource.propsDatasource.odbc: PropsOdbc
Step 3:  Run the Blazix EJB wizard Blizzard, and select "Create an Entity bean".  Give the wizard the datasource you created in step 2, and the name of the table you created in step 1 above.  The wizard will go through the table columns.  For column "key", select "primary key".  For both columns, select the datatype "String".  For column "value", select "generate Setters".  The following link show the various pages the wizard displays.
Entity Bean Wizard Steps
Note:  In the next steps of the tutorial, it is assumed that in the last page of the wizard, the bean name has been changed to "Props".

Now examine the files created by the wizard.  We will be covering the ejb-jar.xml file later, but for now, look in the remote interface, the home interface and the bean class.  Notice that the remote interface consists of methods to access the bean fields, the home interface consists of methods to create or find the beans, and the bean class provides a simple implementation of the remote interface.

Step 4:  Build the bean.  The wizard creates a .cmd file containing the list of commands you must type to build the bean.  This involves compiling the source files, running "jar" to create a Jar file containing all the classes and the ejb-jar.xml file (we will be examining this file in more detail in a later step) created by the wizard, and then running blxejbc, the Blazix EJB compiler.  The EJB compiler will generate another Jar file, which is ready to deploy.  Note that you will need Blazix installation directory to be in your path in order to be able to use the blxejbc command.

Exercise:  Build another entity bean called "Employees".  The primary key for this will be social security numbers (use strings) of the employees.  Create a database table with fields for the social security number, first name, last name, salary, position, employment year, and date of birth.  Create and build an entity bean from this database table.

Troubleshooting Tips
Next tutorial: Deploying the Entity Bean