The Phone Book Bean Example

This is an example of a JSP-page calling an Enity Bean that uses container managed persistence (CMP). The result looks like this:

If you have read my former mini example about the time bean, then you already know that can't spell. I hope you can understand it anyway.

Some of the things in this example have already been explained in the time bean example, so in this example I will not discuss thouse things again.

In this example, I have not used any of the things making EJB development easier, like Eclipse, Ant or Xdoclet. I have tried to strip of everything just to make this example as easy as possible to understand. This is an example using geronimo 1.1, java 1.4 and EJB 2.1 along with the in geronimo built in database called derby. In the end I'll show how to switch database to MySQL.

Entity beans seams to be on their way out. In the spec for EJB 3.0 they do not exist any more. In java EE (1.5) there is a new API called Java Persistence API. I guess that it is more like object relational mapping stuff sutch as Hibernate. But I have not looked in to it yeat so I don't know.

Anyhow, I have a table in my derby database that I called phonebook. I started by using the DBManager in the geronimo console ( http://localhost:8080/console/portal/internalDB/internalDB_DBManager ) And created a new database that I called PhonebookDB.

Then I created the table and put some values in the table using these SQL statements.

This EJB application searches for numbers when the user enters names.

An enity java bean, as you know, represents a row in the database table. An entity java bean only have getter and setter methods for the fields in the table. It does not have properties (variables) and it does not have any other methods than the getter/setter and methods in the EntityBean interface (note that by putting it this way I did not have to write that enity beans can't have business methods as I refuse to refere to so called business methods with the word business methods. Let's not have advertising people controling our way of talking and by that also our way of thinking, shall we. And also I must admit, that entity EJB can, but should not, have methods that I refuse to refere to as business methods). The entity bean is also always abstract.

This is my entity bean that I have put in a package named myphonebookpak:

The fist methods are part of the EntityBean interface. They are never used for any good as far as I know and are only there to mess upp your code. ejbCreate is a constructor, and when you craete a bean it is stored in the database. There are many pages out there that explains the diffrence between ejbCreate and ejbPostCreate. This text below is cited from http://www.jguru.com/faq/view.jsp?EID=1036904
---8<----------------------------------------
ejbCreate() is called before the state of the bean is written to the persistence storage (database). After this method is completed, a new record (based on the persistence fields) is created and written. If the Entity EJB is BMP, then this method must contain the code for writing the new record to the persistence storage. If you are developing an EJB following 2.0 specs, you can have overloading methods in the form of ejbCreateXXX(). This will improve the development so you can have different behaviour for creating a bean, if the parameters differs. The only requirement is that for each ejbCreateXXX() you need to have corrisponding createXXX() methods in the home or local interface.

ejbPostCreate() is called after the bean has been written to the database and the bean data has been assigned to an EJB object, so when the bean is available. In an CMP Entity EJB, this method is normally used to manage the beans' container-managed relationship fields.
---------------------------------------->8--

Note the talk about ejbCreateXXX if you don't have all the parameters needed for inserating a new row with all fileds in a table, if I understand it right.

Enity beans have home and remote interfaces. In this example I only call the bean from a JSP-page in the same application server so I use the localhome and local interfaces instead that don't make use of the network.

This is the code for the local home interface called MyPhonebookLocalHome :

The findByPrimaryKey is like a SQL select statement (Select * from phonebook where name = ?).
This is the local interface called MyPhonebookLocal:

The set-methods are like update statements and the get-methods are like rs.getString("name") if you know what I mean.
Now, lets have a look at the deployment descriptors. You need 2 of them, ejb-jar.xml and openejb-jar.xml. This is what they look like:

ejb-jar.xml:

You recognize the tags ejb-name, local-home etc from the time bean example. But then we have some new tags, they are stright forward describing the the non existing properties (variables) that we have getter/setter mtehods for. Also the primary key is pointed out.
Here comes the openejb-jar.xml file:

Note that this does not have ejb-ref, ref-name or ejb-link tags. Instead there are the tags ejb-name and local-jndi-name. Then there is mappings between the bean and the underlaying table in the database.

That's it. Now over to the JSP page:

Just to make this JSP page interactive so you can search for diffrent names I have made it just a little bit more complicated, but this way is more fun. The inportant part is:

First there is the lookup MyPhonebookBean in "java:comp/env/ejb/MyPhonebookBean" that coresponds to the local-jndi-name in the openejb-jar.xml file. findByPrimaryKey is like a select statement and myPhonebookLocal.getNumber() simply gets the number from the EJB that we just found.
Deployment descriptors:

geronimo-web.xml:

Only inportant here (as far as I understand) is the context-root that becomes the URI.

web.xml

This is similar to what we saw in the former time bean example.
Finally there is the deployment descriptors for the EAR-file, that in this case also includes a database pool xml-file. The best thing to do is to start with the database pool. In Geronimo console there a link in the left navigation called "Database Pools". From there, click the link "Using the Geronimo database pool wizard". You will end upp here:

http://localhost:8080/console/portal/services/services_jdbc/
_rp_services_jdbc_row1_col1_p1_adapterDisplayName/
1_TranQL0x8Generic0x8JDBC0x8Resource0x8Adapter/_rp_services_jdbc_row1_col1_p1_mode/1_rdbms/
_pm_services_jdbc_row1_col1_p1/view/_st_services_jdbc_row1_col1_p1/normal/_pid/
services_jdbc_row1_col1_p1/_md_services_jdbc_row1_col1_p1/view

Follow the wizard using the derby database click on the test button to see that it works, and then you click the button "Skip test and show plan". Then geronimo, this is very handy, show a compleat database pool xml file, and also instructions of how to use it under the section "Add to EAR"!

This is what my pool file derby_PhonebookPool.xml looks like. Note that I in the bottom of the file added a comment with the text from the wizard telling me how to use the pool file.

It seams as "app" is a good user name to use with the build in derby database. No password. But this can perhaps be configurated somewere. Following the instructions from the wizard I made a copy of tranql-connector-1.2.rar and saved it in the applications home directory (see file layout later on) along with the pool file.
There is two more deployment descriptors left. The application.xml and the geronimo-application.xml

application.xml:

There are three modules. The ejb and web modules we recognize from the time bean example, but the connector part is new. This simply states that we have a connector. I am not sure exactly what tranql-connector really is, but I handles the contact with the database in some way that we perhaps do not need to understand.
geronimo-application.xml As you can see here we also have a module conector tag. Here the pool file is referenced. Not that in derby_PhonebookPool.xml there is a name-tag called PhonebookPool that is referenced in the resource-link in openejb-jar.xml file. This is how the applications gets to know about the database.

This is the file layout (If you want to do this kind of layouts and are on a windows system like me, try the DOS command tree /F):

In order to compile this application we start with the EJB. Then, when it is compiled, we copy MyPhonebookLocal.class and MyPhonebookLocalHome.class to the web\WEB-INF\classes\myphonebookpak, they are needed there or elese the JSP-page will not work.
When compilations is done, it is time to pack the application, that is done in three steps, first pack the EJB, then the WAR (that is the JSP-page) and finally pack it all together in an EAR-file. This is the steps for compiling and packing the application, assuming you are in the applications home directory (in my case under c:\java\j2ee\phone so I start with cd c:\java\j2ee\phone). I have put this commands in a bat file (sh file for lunux users) so I don't have to do it by hand evry time. But really, one should use Ant for this kind of work instead.

This is very similar to the time bean example, but here we also add the two files derby_PhonebookPool.xml and tranql-connector-1.2.rar to the ear-file.
To deploy this I use (but you can of course also use the geronimo console) the deploy tool in the geronimo servers bin directory. Like this on my windows system where I have geonimo installed under c:\geronimo\geronimo-1.1 :

c:\geronimo\geronimo-1.1\bin\deploy.bat --user system --password manager deploy myphonebook-ear.ear

Now you can look at the application at: http://localhost:8080/myphonebook
If you change things, compile and pack evrything again and change the above deployment command to redeploy myphonebook-ear.ear in the end of the line.

All soure code can be downloaded in the zip-file: myphonebook.zip

Using MySQL as a database instead of derby

I have a MySQL 5.0.24-community-nt database installed on my computer. Let's see what we need to do to get the phnoebook example work with MySQL istead!
First set up the database! Logg in as root and create a new database called PhonebookDB (same as for derby earlier in this example). Then create the table and put som values. Be sure to put in a new person in this table so we later on can prove to ourselfs that we are really using the new mysql database instead of the old derby. This is my commands:

Now, let's use the pool wizard again as described earlier, but this time, make a mysql pool by selecting "Database Type": MySQL. I can't rembember if the JDBC driver comes default or if you would have to download it by simply clicking the button "Download driver". Fill in "phone" as user name and "book" as password.

You should end up with a database pool file like this. I save it with the name mysql_PhonebookPool.xml in the same directory as the former derby_PhonebookPool.xml :

All we have to do now is to change the pool file reference in the geronimo-application.xml file so that the module part looks like this instead.

Now repack the ear file like this with the derby pool file switched for the corresponding mysql:
jar -cf myphonebook-ear.ear myphonebook-ejb.jar myphonebook-web.war mysql_PhonebookPool.xml tranql-connector-1.2.rar META-INF

Redeploy the application by the command :
c:\geronimo\geronimo-1.1\bin\deploy.bat --user system --password manager redeploy myphonebook-ear.ear

Now we should be able to find Cindy's phone number to prove that we are really using the mysql database. This picture shouws this: