Using container-managed persistence with jBoss

By Kevin Boone (k.boone@web-tomorrow.com)

What this article is about

his article presensts a step-by-step example of creating, deploying and testing an Entity JavaBean that uses `container-managed persistence' with the jBoss EJB server. This example is very simple, and is a variation of the old favourite `music CD' case study. I have chosen this example because the application is likely to be familiar to most people without much explanation. In short, the `CD' EJB models a music CD. Applications will want to add and delete CDs to a collection, and search the collection for specific CDs. There is also a `CDCollection' EJB that lists and searches collections of CDs.
The full source code to accompany this article can be found here (in gzipped tar format). This archive contains the Java source code, JavaDoc documentation, and a text file of test data (CDs.txt) to initialize the database.
Although I will occasionally make reference to Linux, this is only because that's what I use for EJB development; most of the material in this article will work with any Unix version, and even with Windows NT if the directory structure is adjusted accordingly.

Pre-requisites

You will need a fully-functioning jBoss installation to follow this tutorial, which must have a working database connection. I will assume that you are basically familiar with EJBs and know how to structure and compile JavaBeans as Java packages. Also I will assume you know the basic structure of a deployment descriptor, and the run-time descriptor that jBoss uses (jboss.xml). I will assume that you know how to package and deploy EJBs using jBoss. If you don't know about these things, you might want to look at my introductory article on jBoss first.

jBoss hints

jBoss is written entirely in Java, as is the `Hypersonic' database with which it is supplied. Searching a database requires lots of repetitive operations, and an interpreting Java system will be extremely slow if the database is large. If you are using the Sun JDK, you will need to ensure that it is configured to use the `Hotspot' virtual machine, to achieve anything close to acceptable performance. For the purposes of study, you could get along by ensuring that the database size is kept small, but with even a hundred objects you will find it too slow to use. Some Linux systems are reluctant to use the `Hotspot' JVM, but they can normally be coerced to.

Persistence: review

There are, in essence, two kinds of Enterprise JavaBean: session and entity. Entity EJBs contain information that is persistent across different client-Bean interactions, while session EJBs don't. For example, a class called `Customer' that represents the customers of a particular service will contain persistent information (about the customer). A class called `CustomerFinder', say, that finds Customer instances that match certain criteria is likely to be a session EJB, because it does not require information that is maintained between different client-server interactions.
       Session EJBs can be further divided into `stateless' and `stateful'. A stateful session EJB has a state that is persistent between invocations of its methods. A stateless EJB does not even have to retain its state between method invocations. The stateless session EJB is therefore the type of EJB that exhibits the least persistence.
       The entity EJBs contain information that persists even when no clients are using any of the Bean's services; the information should persist even if the server is restarted. There is a high degree of correspondence between instances of an entity EJB and rows of a database table. In practice, all EJB servers implement entity instances as table rows. This correspondence is so strong that the notion of a `primary key' is relevant to an entity EJB. Of course, a primary key is a database concept, not an object-orientation concept at all.
       The persistence of an entity EJB may be managed by the Bean itself, or by the server (technically by the `container'). The latter technique is called `Container-managed persistence', and is the subject of the rest of this article.

Begin tutorial...

After the tutorial, you might like to read the discussion