Chapter 12. Introduction to Entities in EJB3

Entity Beans of EJB2.x have been given a complete overhaul in EJB 3.0. Entity beans (or Entities, as they are now called) are plain Java objects that can be allocated with new and attached/detached/reattached to persistence storage. Entities are not remotable and must be accessed through the new javax.persistence.EntityManager service. JBoss's EJB 3.0 entity implementation is built on top of Hibernate.

O/R Mapping :

First let's look at the example implementation of two related Entities. org.jboss.tutorial.entity.bean.Order and org.jboss.tutorial.entity.bean.LineItem. These two entities form a one-to-many relationship.

The persistence determines the persistent properties by looking for all getter/setter method pairs. By default, all getter/setter methods will be treated as persistence properties.

Defining an Entity is easy. First, annotate the class as an @Entity. In the minimum, you must at least define a primary key field using the @Id annotation.

		
@Id @GeneratedValue
public int getId()
{
   return id;
}

Note

Annotations must be defined on the getter method or on the field. However, you cannot have a mix of annotations on the field and on the methods. The following example where we are mapping the name through the field and mapping the age through the method is not allowed:

					
@Entity
public class Employee implements java.io.Serializable
{

	@Id
	@GeneratedValue(strategy=GenerationType.AUTO)
	private long id;

	@Column (name="NAME")
	private String name;

	private int age;

	@Column (name="AGE")
	public int getAge()
	{
		return this.age
	}

	public String getName()
	{

	}
	// other getter/setters
}

The @Id annotation tells the container that id is the primary key property. The @GeneratedValue tells that it should be automatically generated by the container. The table name is specified using the @Table annotation

		
@Table(name = "PURCHASE_ORDER")

If the table name isn't specified it defaults to the simple name of the class. For instance, the LineItem entity would be mapped to the LINEITEM table.

One to Many Relationship :

The Order bean also defines a one to many relationship.

			
@OneToMany(cascade = CascadeType.ALL, fetch = FetchType.EAGER, mappedBy="order")
public Collection<LineItem> getLineItems()
{
   return lineItems;
}

Generics must be used so that the container can determine what the entity Order is related to.

CascadeType.ALL specifies that when an Order is created, any LineItems held in the lineItems collection will be created as well (CascadeType.PERSIST). If the Order is deleted from persistence storage, all related LineItems will be deleted (CascadeType.REMOVE). If an Order instance is reattached to persistence storage, any changes to the LineItems collection will be merged with persistence storage (CascadeType.MERGE).

FetchType.EAGER specifies that when the Order is loaded whether or not to pre-fetch the relationship as well. If you want the LineItems to be loaded on demand, then specify FetchType.LAZY.

The mappedBy attribute specifies that this is a bi-directional relationship that is managed by the order property on the LineItem entity.

Many to One Relationship :

			
@ManyToOne
@JoinColumn(name = "order_id")
public Order getOrder()
{
   return order;
}

The @JoinColumn specifies the foreign key column within the LineItem table.

EntityManager :

The org.jboss.tutorial.entity.bean.ShoppingCartBean allocates and stores all instances of Orders and LineItems. If you look at the example you can see that ShoppingCart interacts with Order as a plain Java object. It allocates it with new. It can pass the Order back to the client. The checkout() method actually stores it with persistence storage by using the required EntityManager service. The EntityManager service is injected using field injection and the @PersistenceContext annotation.

			
@PersistenceContext
private EntityManager manager;

The EntityManager is central to EJB 3.0 as there are no homes. The EntityManager is used to do querying, creating, find by primary key, and removal of entities in EJB3.

Building and Running

Note

To build and run the example, make sure you have installed JBoss 5.x. See the Section 1.1, “JBoss Application Server 5.x” for details.

From the command prompt, move to the "entity" folder under the Section 1.3, “Set the EJB3_TUTORIAL_HOME”

Ant Users:

Make sure your JBossAS-5.x is running

	
$ ant
$ ant run

run:
     [java] Buying 2 memory sticks
     [java] Buying a laptop
     [java] Print cart:
     [java] Total: $3000.0
     [java] 2     Memory stick     1000.0
     [java] 1     Laptop     2000.0
     [java] Checkout

Maven Users: Make sure the AS is not running.

$ mvn clean install -PRunSingleTutorial

View the tables and rows:

You can view the tables created by JBoss by going to the Hypersonic Service, scrolling down to the startDatabaseManager button and clicking it. A Hypersonic SQL window will be minimized, but you can open it up to look at the tables and do queries.