Skip Headers

Oracle9iAS Containers for J2EE Enterprise JavaBeans Developer's Guide
Release 2 (9.0.3)

Part Number A97677-01
Go To Core Documentation
Core
Go To Platform Documentation
Platform
Go To Table Of Contents
Contents
Go To Index
Index

Go to previous page Go to next page

3
CMP Entity Beans

This chapter demonstrates simple Container Managed Persistence (CMP) EJB development with a basic configuration and deployment. Download the CMP entity bean example (cmpapp.jar) from the OC4J sample code page on the OTN Web site.

This chapter demonstrates the following:

See Chapter 6, "BMP Entity Beans", for an example of how to create a simple bean-managed persistent entity bean. For a description of persisting object relationships between EJBs, see Chapter 4, "Entity Relationship Mapping".

Entity Bean Overview

With EJB 2.0 and the local interface support, most developers agree that entity beans should be paired with a session bean, servlet, or JSP that acts as the client interface. The entity bean is a coarse-grain bean that encapsulates functionality and represents data and dependent objects. Thus, you decouple the client from the data so that if the data changes, the client is not affected. For efficiency, the session bean, servlet, or JSP can be collocated with entity beans and can coordinate between multiple entity beans through their local interfaces. This is known as a session facade design. See the http://java.sun.com Web site for more information on session facade design.

An entity bean can aggregate objects together and effectively persist data and related objects under the umbrella of transactional, security, and concurrency support through the container. This and the following chapters focus on how to use the persistence functionality of the entity bean.

An entity bean manages persistent data in one of two ways: container-managed persistence (CMP) and bean-managed persistence (BMP). The primary difference between the two is as follows:

Creating Entity Beans

To create an entity bean, perform the following steps:

  1. Create the component interfaces for the bean. The component interfaces declare the methods that a client can invoke.

    1. The local component interface extends javax.ejb.EJBLocalObject.

    2. The remote component interface extends javax.ejb.EJBObject.

  2. Create the home interfaces for the bean. The home interface defines the create and finder methods, including findByPrimaryKey, for your bean.

    1. The local home interface extends javax.ejb.EJBLocalHome.

    2. The remote home interface extends javax.ejb.EJBHome.

  3. Define the primary key for the bean. The primary key identifies each entity bean instance and is a serializable class. You can use a simple data type class, such as java.lang.String, or define a complex class, such as one with two or more objects as components of the primary key.

  4. Implement the bean. This includes the following:

    1. The implementation for the methods that are declared in your component interfaces.

    2. The methods that are defined in the javax.ejb.EntityBean interface.

    3. The methods that match the methods that are declared in your home interfaces, which include the following:

      • The ejbCreate and ejbPostCreate methods with parameters matching the associated create method defined in the home interface.

      • Finder methods, other than ejbFindByPrimaryKey and ejbFindAll, that are defined in the home interface. The container generates the ejbFindByPrimaryKey and ejbFindAll method implementations--although you must still provide an empty method for each of these.

  5. Create the bean deployment descriptor. The deployment descriptor specifies properties for the bean through XML elements. This step is where you identify the data within the bean that is to be managed by the container. These relationships could also entail other objects, which Chapter 4, "Entity Relationship Mapping" discusses.

  6. If the persistent data is saved to or restored from a database and you are not using the defaults provided by the container, then you must ensure that the correct tables exist for the bean. In the default scenario, the container creates the table and columns for your data based on deployment descriptor and datasource information.

  7. Create an EJB JAR file containing the bean, component interface, home interface, and the deployment descriptors. Once created, configure the application.xml file, create an EAR file, and deploy the EJB to OC4J.

The following sections demonstrate a simple CMP entity bean. This example continues the use of the employee example, as in other chapters--without adding complexity.

Home Interface

The home interface is primarily used for retrieving the bean reference, on which the client can request business methods.

The home interface must contain a create method, which the client invokes to create the bean instance. Each create method can have a different signature. For an entity bean, you must develop a findByPrimaryKey method. Optionally, you can develop other finder methods, which are named find<name>, for the bean.

In addition to creation and retrieval methods, you can provide home interface business methods within the home interface. The functionality within these methods cannot access data of a particular entity object. Instead, the purpose of these methods is to provide a way to retrieve information that is not related to a single entity bean instance. When the client invokes any home interface business method, an entity bean is removed from the pool to service the request. Thus, this method can be used to perform operations on general information related to the bean.

Our employee example provides the local home interface with a create, findByPrimaryKey, findAll, and calcSalary methods. The calcSalary method is a home interface business method that calculates the sum of all employee salaries. It does not access the information of a particular employee, but performs a SQL inquiry against the database for all employees.

Example 3-1 Entity Bean Employee Home Interface

The employee home interface provides a method to create the component interface. It also provides two finder methods: one to find a specific employee by an employee number and one that finds all employees. Last, it supplies a home interface business method, calcSalary, to calculate how much all employees cost the business.

The home interface is required to extend javax.ejb.EJBHome and define the create and findByPrimaryKey methods.

package employee;

import javax.ejb.*;
import java.rmi.*;

public interface EmployeeLocalHome extends EJBLocalHome
{

  public EmployeeLocal create(Integer empNo) throws CreateException;

  // Find an existing employee
  public EmployeeLocal findByPrimaryKey (Integer empNo) throws FinderException;

  //Find all employees
  public Collection findAll() throws FinderException;

  //Calculate the Salaries of all employees
  public float calcSalary() throws Exception;
}

Component Interfaces

The entity bean component interfaces are the interfaces that the customer sees and invokes methods upon. The component interface defines the business logic methods for the entity bean instance.

The employee entity bean example exposes the local component interface, which contains methods for retrieving and updating employee information.

package employee;

import javax.ejb.*;

public interface EmployeeLocal extends EJBLocalObject
{
  public Integer getEmpNo();
  public void setEmpNo(Integer empNo);

  public String getEmpName();
  public void setEmpName(String empName);

  public Float getSalary();
  public void setSalary(Float salary);
}

Entity Bean Class

The entity bean class implements the following methods:

However, with container-managed persistence, the container manages most of the target methods and the data objects, thereby leaving little for you to implement.

package employee;

import javax.ejb.*;
import java.rmi.*;

public abstract class EmployeeBean implements EntityBean
{

  private EntityContext ctx;

  // Each CMP field has a get and set method as accessors
  public abstract Integer getEmpNo();
  public abstract void setEmpNo(Integer empNo);

  public abstract String getEmpName();
  public abstract void setEmpName(String empName);

  public abstract Float getSalary();
  public abstract void setSalary(Float salary);

  public void EmployeeBean()
  {
    // Constructor. Do not initialize anything in this method.
    // All initialization should be performed in the ejbCreate method.
    // The passivate() method may destroy these attributes when pooling
  }

  public float ejbHomeCalcSalary() throws Exception
  {
    Collection c = null;
    try {
       c = ((EmployeeLocalHome)this.ctx.getEJBLocalHome()).findAll();

       Iterator i = c.iterator();
       float totalSalary = 0;
       while (i.hasNext())
       {
         EmployeeLocal e = (EmployeeLocal)i.next();
         totalSalary = totalSalary + e.getSalary().floatValue();
       }
       return totalSalary;
    }
    catch (FinderException e) {
      System.out.println("Got finder Exception "+e.getMessage());
      throw new Exception(e.getMessage());
    }
  }

  public EmployeePK ejbCreate(Integer empNo, String empName, Float salary)
    throws CreateException
  {
    setEmpNo(empNo);
    setEmpName(empName);
    setSalary(salary);
    return new EmployeePK(empNo);
  }

  public void ejbPostCreate(Integer empNo, String empName, Float salary)
    throws CreateException
  {
    // Called just after bean created; container takes care of implementation
  }

  public void ejbStore()
  {
    // Called when bean persisted; container takes care of implementation
  }

  public void ejbLoad()
  {
     // Called when bean loaded; container takes care of implementation
  }

  public void ejbRemove() throws RemoveException
  {
     // Called when bean removed; container takes care of implementation
  }

  public void ejbActivate()
  {
    // Called when bean activated; container takes care of implementation.
    // If you need resources, retrieve them here.
  }

  public void ejbPassivate()
  {
    // Called when bean deactivated; container takes care of implementation.
    // if you set resources in ejbActivate, remove them here.
  }

  public void setEntityContext(EntityContext ctx)
  {
    this.ctx = ctx;
  }

  public void unsetEntityContext()
  {
    this.ctx = null;
  }
}

Primary Key

Each entity bean instance has a primary key that uniquely identifies it from other instances. You must declare the primary key (or the fields contained within a complex primary key) as a container-managed persistent field in the deployment descriptor. All fields within the primary key are restricted to either primitive, serializable, or types that can be mapped to SQL types. You can define your primary key in one of two ways:

For a simple CMP, you can define your primary key to be a well-known type by defining the data type of the primary key within the deployment descriptor.

The employee example defines its primary key as a java.lang.Integer and uses the employee number (empNo) as its primary key.

<enterprise-beans>
      <entity> 
         <display-name>Employee</display-name>
         <ejb-name>EmployeeBean</ejb-name>
         <local-home>employee.EmployeeLocalHome</local-home>
         <local>employee.EmployeeLocal</local>
         <ejb-class>employee.EmployeeBean</ejb-class>
         <persistence-type>Container</persistence-type>
         <prim-key-class>java.lang.Integer</prim-key-class>
         <reentrant>False</reentrant>
         <cmp-version>2.x</cmp-version>
         <abstract-schema-name>Employee</abstract-schema-name>
         <cmp-field><field-name>empNo</field-name></cmp-field>
         <cmp-field><field-name>empName</field-name></cmp-field>
         <cmp-field><field-name>salary</field-name></cmp-field>
         <primkey-field>empNo</primkey-field>
      </entity>
...
</enterprise-beans>

Once defined, the container creates a column in the entity bean table for the primary key and maps the primary key defined in the deployment descriptor to this column.

Defining the Primary Key in a Class

If your primary key is more complex than a simple data type, your primary key must be a class that is serializable of the name <name>PK. You define the primary key class within the <prim-key-class> element in the deployment descriptor.

The primary key variables must adhere to the following:

Within the primary key class, you implement a constructor for creating a primary key instance. Once the primary key class is defined in this manner, the container manages the class.

The following example places the employee number within a primary key class.

package employee;

public class EmployeePK implements java.io.Serializable
{
  public Integer empNo;

  public EmployeePK()
  {
    this.empNo = null;
  }

  public EmployeePK(Integer empNo)
  {
    this.empNo = empNo;
  }
}

The primary key class is declared within the <prim-key-class> element, and each of its variables are declared within a <cmp-field><field-name> element in the XML deployment descriptor, as follows:

<enterprise-beans>
      <entity>
         <description>no description</description>
         <display-name>EmployeeBean</display-name>
         <ejb-name>EmployeeBean</ejb-name>
         <local-home>employee.LocalEmployeeHome</home>
         <local>employee.LocalEmployee</remote>
         <ejb-class>employee.EmployeeBean</ejb-class>
         <persistence-type>Container</persistence-type>
         <prim-key-class>employee.EmployeePK</prim-key-class>
         <reentrant>False</reentrant>
         <cmp-version>2.x</cmp-version>
         <abstract-schema-name>Employee</abstract-schema-name>
         <cmp-field><field-name>empNo</field-name></cmp-field>
         <cmp-field><field-name>empName</field-name></cmp-field>
         <cmp-field><field-name>salary</field-name></cmp-field>
      </entity>
</enterprise-beans>

Once defined, the container creates a column in the entity bean table for the primary key and maps the primary key class defined in the deployment descriptor to this column.

Defining an Auto-Generated Primary Key

If you specify a java.lang.Object as the primary key class type in <prim-key-class>, but do not specify the primary key name in <primkey-field>, then the primary key is auto-generated by the container.

The employee example defines its primary key as a java.lang.Object. Thus, the container auto-generates the primary key.

<enterprise-beans>
      <entity> 
         <display-name>Employee</display-name>
         <ejb-name>EmployeeBean</ejb-name>
         <local-home>employee.EmployeeLocalHome</local-home>
         <local>employee.EmployeeLocal</local>
         <ejb-class>employee.EmployeeBean</ejb-class>
         <persistence-type>Container</persistence-type>
         <prim-key-class>java.lang.Object</prim-key-class>
         <reentrant>False</reentrant>
         <cmp-version>2.x</cmp-version>
         <abstract-schema-name>Employee</abstract-schema-name>
         <cmp-field><field-name>empNo</field-name></cmp-field>
         <cmp-field><field-name>empName</field-name></cmp-field>
         <cmp-field><field-name>salary</field-name></cmp-field>
      </entity>
...
</enterprise-beans>

Once defined, the container creates a column called autoid in the entity bean table for the primary key of type LONG. The container uses random numbers for the primary key values.

Persistence Fields

The persistent data in your CMP bean can be one of the following:

Each type results in its own complex rules of how to configure. This section discusses persistence fields. For information on relationship fields, see Chapter 4, "Entity Relationship Mapping".

In CMP entity beans, you define the persistent data both in the bean instance and in the deployment descriptor.

For these fields to be mapped to a database, you can do one of the following:

Default Mapping of Persistent Fields to the Database

If you simply define the persistent fields in the ejb-jar.xml file, then OC4J provides the following mappings of these fields to the database:

Explicit Mapping of Persistent Fields to the Database

As "Default Mapping of Persistent Fields to the Database" discusses, your persistent data can be automatically mapped to a database table by the container. However, if the data represented by your bean is more complex or you do not want to accept the defaults that OC4J provides for you, then you can map the persistent data to an existing database table and its columns within the orion-ejb-jar.xml file. Once the fields are mapped, the container provides the persistence storage of the persistent data to the indicated table and rows.

For explicit mapping, Oracle recommends that you do the following:

  1. Deploy your application with only the ejb-jar.xml elements configured.

    OC4J creates an orion-ejb-jar.xml file for you with the default mappings in them. It is easier to modify these fields than to create them from scratch. This provides you a method for choosing all or part of the modifications that are discussed in this section.

  2. Modify the <entity-deployment> element in the orion-ejb-jar.xml file to use the database table and columns you specify.

Once you define persistent fields, each within its own <cmp-field> element, you can map each to a specific database table and column. Thus, you can map CMP fields to existing database tables. The mapping occurs with the OC4J-specific deployment descriptor: orion-ejb-jar.xml.

The explicit mapping of CMP fields is completed within an <entity-deployment> element. This element contains all mapping for an entity bean. However, the attributes and elements that are specific to CMP field mapping is as follows:

<entity-deployment name="..." location="..."
table="..." data-source="...">
<primkey-mapping> <cmp-field-mapping name="..." persistence-name="..." /> </primkey-mapping> <cmp-field-mapping name="..." persistence-name="..." /> ... </entity-deployment>

Element or Attribute Name Description

name

Bean name, which is defined in the ejb-jar.xml file in the <ejb-name> element.

location

JNDI location

table

Database table name

data-source

Data source for the database where the table resides

primkey-mapping

Definition of how the primary key is mapped to the table.

cmp-field-mapping

The name attribute specifies the <cmp-field> in the deployment descriptor, which is mapped to a table column in the persistence-name attribute.

You can configure the following within the orion-ejb-jar.xml file:

  1. Configure the <entity-deployment> element for every entity bean that contains CMP fields that will be mapped within it.

  2. Configure a <cmp-field-mapping> element for every field within the bean that is mapped. Each <cmp-field-mapping> element must contain the name of the field to be persisted.

    1. Configure the primary key in the <primkey-mapping> element contained within its own <cmp-field-mapping> element.

    2. Configure simple data types (such as a primitive, simple object, or serializable object) that are mapped to a single field within a single <cmp-field-mapping> element. The name and database field are fully defined within the element attributes.

Example 3-2 Mapping Persistent Fields to a Specific Database Table

The following example demonstrates how to map persistent data fields in your bean instance to database tables and columns by mapping the employee persistence data fields to the Oracle database table EMP.

After deployment, OC4J maps the element values to the following:

Bean Database

emp/EmpBean

EMP table, located at jdbc/OracleDS in the data-sources.xml file

empNo

EMPNO column as primary key

empName

ENAME column

salary

SAL column

CMP Types

In defining the container-managed persistent fields in the <cmp-field> and the primary key types, you can define simple data types and Java user classes that are serializable.

Simple Data Types

The following table provides a list of simple data types and the mapping of these types to SQL types and to Oracle database types.

Table 3-1 Simple Data Types

Known Type (native) SQL type Oracle type

java.lang.String

VARCHAR(255)

VARCHAR(255)

java.lang.Integer(int)

INTEGER

NUMBER(20,0)

java.lang.Long(long)

INTEGER

NUMBER(20,0)

java.lang.Short(short)

INTEGER

NUMBER(10,0)

java.lang.Double(double)

DOUBLE PRECISION

NUMBER(30,0)

java.lang.Float(float)

FLOAT

NUMBER(20,5)

java.lang.Byte(byte)

SMALLINT

NUMBER(10,0)

java.lang.Character(char)

CHAR

CHAR(1)

java.lang.Boolean(boolean)

BIT

NUMBER(1,0)

java.util.Date

DATETIME

DATE

java.util.Locale

VARCHAR(5)

VARCHAR(5)

java.sql.Date

DATE

DATE

java.sql.Clob

CLOB

CLOB

java.sql.Blob

BLOB

BLOB

java.sql.Timestamp

TIMESTAMP

TIMESTAMP

javax.mail.internet.InterenetAddress

VARCHAR(127)

VARCHAR(127)

java.math.BigInteger

VARCHAR(100)

VARCHAR(100)

java.io.Serializable

LONGVARBINARY

BLOB

You can modify the mapping of these data types in the config/database-schema/<db>.xml XML configuration files.

Serializable Classes

In addition to simple data types, you can define user classes that implement Serializable. These classes are stored in a BLOB in the database.

Other Entity Beans or Collections

You should not define other entity beans or Collections as a CMP type. Instead, these are relationships and should be defined within a CMR field.


Go to previous page Go to next page
Oracle
Copyright © 2002 Oracle Corporation.

All Rights Reserved.
Go To Core Documentation
Core
Go To Platform Documentation
Platform
Go To Table Of Contents
Contents
Go To Index
Index