EJBWizard How-To

Note: This mini-guide is based on EJBWizard Version 3. There are some small differences in EJBWizard Version 2, but the principle is the same.

First, you almost certainly should know how jdbc database access works - this is required to set up the system to talk to your DBMS. Secondly, you need to know what Enterprise Java Beans are! The O'Reilly and Associates books are pretty good introductions (http://www.ora.com) as they are noted for supplying lots of sample code. You may have your own favorite technical publisher.

Out of the box, the EJBWizard is set up to work with the Objectweb JOnAS EJB system. This mostly means that in addition to the EJBWIZARD_ROOT environment, you also need a JONAS_ROOT pointing to a directory containing a "jonas.properties" file that in turn has a "jonas.datasources" line naming the various databases you want to generate beans for. None of that is essential - it's just easier if you can get the database to tell you what's what. If the database in question doesn't exist yet, you can define the fields manually. A similar system applies when generating EJBs for other EJBServers such as the BEA WebLogic Server.

You'll also want to customize the startup script in the EJBWIZARD_ROOT/bin directory so that the xerces.jar file and and jdbc drivers can be located. The -o option specifies the name of a directory (which must already exist) into which the bean source code is generated.

OK. At this point, hopefully you have launched the EJBWizard. Enterprise Java Beans come in 4 flavors (5 in EJB version 2). For pure logic, session beans are preferred. For database access, entity beans are the way to go. Most commonly used are container-managed entity beans (CMPs).

To create a CMP bean:

1. On the first tab, supply the name you want to give your bean, the package name, and the bean type. The other list items can be ignored.

Example: you want to track a fleet of dump trucks are the Jacksonville Port authority.

Bean name: DumpTruck
Package name: org.jpa.dumptruck
Bean type: Entity, Container-managed

2. Now go to the Data tab. If you have an existing dumptruck table in your database. click on the "Data source" button to log into the DBMS. Select your datasource (if more than one) from the drop list, click "Log on" to get the list of tables, select a table and click "OK" to cause the fields in the table to be placed in your data field list. You also have to designate a key field. All CMP beans REQUIRE at least one field to construct a unique primary key. This field doesn't have to be a DBMS key (though for performance it generally should), but it does have to uniquely identify a row in the database table. Sometimes a single field isn't enough, so you pick two or three fields which together make it unique. The way you define a key is to set the "key" number to a value greater than 0. The first part of the key is 1, the second (if present) is 2, etc.

You have to supply both the java names and type and their corresponding database names and types. This ties everything together. For example:

int | truckNumber | shortinteger | truck_number

Once you've described the database fields, you can define any business methods you want. Session EJBs have no database fields (although stateful beans might define fields that last for the life of the bean), but are big on business methods. Entity beans are less likely to use business methods, though they can be useful when a single value is used to set multiple fields, or you want a "helper" function related to the data (say, a method that takes a Vehicle Identification Number and returns "Ford" if it begins with "F".

3. Excepting Stateless Session beans, EJBs can have a create function or functions. These service the purpose of traditional constructors, but you DON'T construct EJBs directly (the container/manager does) so you use the create functions. One of the most common is the "create-everything" version. Just click "add" and click "All fields" on the method editor (Note - the "BODY" button doesn't do anything yet).

Important! By default, no create functions are defined (this is different than EJBWizard Version 2). The generic JSP's that get generated for entity beans need to have the "All fields" create function defined to compile properly if not customized.

4. Finally, you need at least one Finder function. for CMP beans, the function "FindPK()" is mandatory and you'll see it presupplied. Any other functions (e.g. findAllFords) you define yourself. Use the "SQL" button to bring up the dialog where you specify the search expression use to return the bean(s) that match. CMP finders are generated automatically by your appserver's ejb compiler (GenIC, in JOnAS case).

Once again, you need to add a little extra if using the generated JSPs unless you customize them. Create a findAllBean method (where "Bean" is your bean name) if you want the table-view JSP to display all beans in a single table view. The default table view displays all beans in the table, so it's not recommended for use with large tables. Customize the generated JSP as needed.

The exact text you put in the "SQL" Dialog is appserver dependent (this changes for EJB Version 2). For JOnAS, place an SQL "WHERE" clause in the dialog (including the word "WHERE"!). For WebLogic, this is a predicate in WebLogic's LISP-like query language.

Note: If you forget to add the "SQL" finder information, the default is to leave it blank. That generally results in a "find all beans" functionality!

That's it. Save your work, then select the File/Generate command to build the bean. If you get errors on the generation process, pass them on to me. Otherwise, when you see the "bean generated" dialog, you should have a ready-to-go bean in your output directory (the one pointed to by the "-o" option on the command line). At this point, if you have business methods to implement, edit the xxxBean.java file to supply their logic and add anything else you need, then run Ant to build the bean.

*** WARNNG *** When you generate a bean, it DESTROYS the old java files. Save any work you need to keep!

Further notes

Ideally, the EJBWizard would serve as a maintenance tool for the bean's entire life cycle. That's no small feat. Hopefully, the "Body" button on the method editor will eventually bring up your favorite text editor or IDE. In the mean time, the EJBWizard tries to make life easier by making backup copies of the generated files when you regenerate a bean. If you have a "diff" tool (such as the compare and merge functions of the emacs text editor, the ".BAK" files can be merged with the newly-regenerated bean files.