This article presents 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.

Download and install the full source code as explain in the section called “Downloading the Documentation Example Source”

The files (sources, build scripts and configuration files) needed for this chapter are under "documentation-example/org/jboss/docs/cmp/cd". Take the time to review them, as well as how the classpath is set prior to compiling/running the sources.

Be comfortable with the section called “Installing Ant” as you will have to run ant to build the ejb jar, and run the test clients.

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 the chapter titled “First Steps” first.

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 database notion of a "primary key" is relevant to an entity EJB.

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.

Unlike what many folks believe, the choice of going BMP or CMP is not really one of "trade-off". If you have already schemas deployed you may find that the complexity of the schemas requires you to go with BMP or use a BMP generating tool such as "cocobase". These techniques are what we call "fake CMP" where the work of accessing the database is left to the generated classes.

The breed of CMP that has most value is the "real CMP" or a CMP where you let the container manage the persistent representation of your beans entirely. This might not work right now for you if your object are complex but should work in most simple cases. EJB2.0 also goes the extra length to make the persistent engines powerful and fast with management of dependencies and relationships. We believe that one day you will rely on the engines to manage the schemas, just like you rely on a compiler to optimize assembly code.