Entity Bean CMP (Container-Managed Persistence)

Entity Container-Managed Persistence

Objectives

The objective is to learn how to develop an Entity Bean Container-Managed Persistence (CMP).

Entity Bean Life-cycle

Code

Here is the code source.
We will focus on the CMP part.
We will use XDoclet

Customer Entity Bean CMP

We will develop an Entity Bean CMP that maps to a table in embedded database in jBoss hsqldb. This table has the following columns: "email", "firstName", "lastName", ...

Top-down or bottom-up design?

What do you think?

Top-down

We will use the top-down approach. We will let jBoss create the tables in the database for us based on the Entity Bean code and XML deployment descriptors that we will deploy.
For each Entity Bean CMP, a table will be created. For each Container-Managed Persistent Fields, a column will be created.

If you want to use another database such as MySQL, you will find at the end of this document a description of the configuration for jBoss.

CustomerBean.java

An Entity Bean is a simple abstract Java class that implements the javax.ejb.EntityBean interface.
Cette interface defines 7 methods:

void setEntityContext(javax.ejbEntityContext ec)
void unsetEntityContext()
void ejbActivate()
void ejbPassivate()
void ejbLoad()
void ejbStore()
void ejbRemove()

Any idea about the utility of those methods?

Let's now imagine that our Entity defines the following CMP fields:

Nom du champ	Type du champ
email	String - Cle primaire
firstName	String
lastName	String
dateOfBirth	Date

Those fields must be coded using setters and getters. We also need to use Xdoclet to specify that they are CMP fields.
For the CustomerBean class, we must define:

The JNDI name for the lookup (@ejb.bean / jndi-name)
the EJB name (@ejb.bean / name)
The primary key or compound key of the table using the MP fields (@ejb.bean / primkey-field)
The persistence type: BMP or CMP (@ejb.bean / type)
The Visibility: remote or local (@ejb.bean / view-type)
The Transaction type: (required, never, mandatory, ...) (@ejb.transaction)
The table name in the database (@ejb.persistence / table-name)
Some optional finders (@ejb.finder)
Some propriatary tags (@jboss:create-table / create)


/**
 * CustomerBean
 *  
 * @ejb.bean
 *   cmp-version="2.x"
 *   jndi-name="org.jyperion.sample.j2ee.eb.CustomerBean"
 *   name="Customer"
 *   primkey-field="email"
 *   type="CMP"
 *   view-type="remote"
 * 
 * @ejb:transaction type="Required"
 * 
 * @ejb.persistence
 *   table-name="Customer"
 * 
 * @ejb:finder signature="java.util.Collection findAll()"
 * 
 * @jboss:table-name 
 *   table-name="Customer"
 *
 * @jboss:create-table 
 *   create="true"
 *
 * @jboss:remove-table 
 *   remove="true"
 *  
 * @author janaudy
 * @version 1.0
 */
public abstract class CustomerBean implements EntityBean { ...

The, we write the fields that are persisted to the database (CMP fields).
We only write the setters and the getters using the XDoclet tag @ejb.persistent-field, with a specific visibility (@ejb.interface-method / view-type), to which column this field must map (@ejb.persistence / column-name), and finally, if this field is or is part of the primary key (@ejb.pk-field)
:


/**
 * @ejb.persistent-field 
 * 
 * @ejb.persistence
 *   column-name="email"
 * 
 * @ejb.interface-method
 *   view-type="remote"
 * 
 * @ejb.pk-field 
 * 
 * @return email
 */
 public abstract String getEmail();
 

 /**
  * @param email
  */
 public abstract void setEmail(String email);

Then, we have to write the "create" methods: ejbCreate and ejbPostCreate that have the same number and type of arguments.


/**
 * @ejb.create-method
 * 
 * @param email
 * @param firstName
 * @param lastName
 * @throws CreateException
 */
public String ejbCreate(String email, String firstName, String lastName)
  throws CreateException {
  this.setEmail(email);
  return null;
}

Develop and deploy your Entity Bean CMP: ClientBean

What are you waiting for? Code!!! (Do not forget the client, and use an EAR file).

EJB-QL: Enterprise JavaBean Query Language

On the previous bean, write the following finders:

findAll: a finder that returns all the lines of the table
findClientByLastName: a finder that returns the clients by last name

Here you go! The next lab is more exciting: CMP with CMR (how to deal with relationships).

Configuration jBoss for MySQL

Please note that you first need to install mysql (_tools/mysql2install).

Creation of the mysql-ds.xml file in the $JBOSS_HOME/server/default/deploy folder


<?xml version="1.0" encoding="UTF-8"?>

<datasources>
  <local-tx-datasource>
    <jndi-name>Jyperion/MySqlDS</jndi-name>
    <connection-url>jdbc:mysql://localhost/jyperiondb</connection-url>
    <driver-class>com.mysql.jdbc.Driver</driver-class>
    <user-name>root</user-name>
    <password>mysql</password>
  </local-tx-datasource>
</datasources>

Edition of the standardjboss-cmp.xml file in $JBOSS_HOME/server/default/conf

Add:


  <datasource>java:/Jyperion/MySqlDS</datasource>
  <datasource-mapping>mySQL</datasource-mapping>

in the jbosscmp-jdbc/defaults section.

UML View

Exercise

Create a new Java project in Eclipse and develop the following:

A Stateless Session Bean (TradeSessionBean) with one method: transfer(id1, id2, double)
An Entity Bean CMP (AccountEntityBean) with id (the pk) and a column 'money'
an Entity Bean CMP (TxEntityBean) that represents the business transactions 'idtx', 'date', 'id1', 'id2', 'amount'

In TradeSessionBean, for each 'transfer' call, money is transfered from one account to the other using AccountEntityBean, then transaction is logged using TxEntityBean.

Use ANT, XDoclet.