Getting Started with Entity Beans

What are CMP Entity Beans?

An entity bean represents a business object in a persistent storage mechanism. In other words, entity beans are used to model real-world objects with properties that need to be stored and remembered over time. Examples of business objects are customers, products, orders, credit cards, and addresses. Typically, each entity bean has an underlying table in a relational database, and each bean instance corresponds to a row in that table. An entity bean has one or more primary keys, or unique indices, to uniquely identify an object, that is, a particular record in the database.

Container-managed persistence (CMP) entity beans are entity beans for which the EJB container takes care of mapping property and relationship fields to the underlying database and knows how to insert, update, and delete data for an entity bean.

Developing Entity Beans with Workshop

In Workshop, you develop an entity bean by creating a class that extends weblogic.ejb.GenericEntityDrivenBean and implements javax.ejb.EntityBean. You annotate this class with @Entity, @JndiName, and @FileGeneration annotations (and others, as needed) that specify EJB characteristics. You also add annotations to designate virtual fields, select and find methods, and relations that the entity has with other entities.

You can get started easily in the IDE by using the WebLogic Entity Bean template. When you use the template, the IDE generates code such as the following:

/**
 * GenericEntityBean subclass automatically generated by Workshop.
 * 
 * Please review and update the existing content to ensure it matches your
 * intended use (esp. the Entity and JndiName annotations and the primary key
 * field, ejbCreate() and ejbPostCreate() methods).
 */
@Entity(ejbName = "MyEntityBean", 
        dataSourceName = "samplesDataSource", 
        tableName = "MyEntityBean", 
        primKeyClass = "java.lang.Integer")
@JndiName(local = "ejb.MyEntityBeanLocalHome")
@FileGeneration(localClass = Constants.Bool.TRUE, 
        localHome = Constants.Bool.TRUE, 
        remoteClass = Constants.Bool.FALSE, 
        remoteHome = Constants.Bool.FALSE, 
        valueClass = Constants.Bool.TRUE)
abstract public class MyEntityBean 
    extends GenericEntityBean 
    implements EntityBean {

    /**
     * IMPORTANT: Automatically generated ejbCreate() method.
     * Please change as appropriate.
     */
    public java.lang.Integer ejbCreate(java.lang.Integer key)
            throws CreateException {
        setKey(key);
        return null;
    }

    /**
     * IMPORTANT: Automatically generated ejbPostCreate() method.
     * Please change as appropriate.
     */
    public void ejbPostCreate(java.lang.Integer key) {
    }

    /**
     * IMPORTANT: Automatically generated primary key field getter method.
     * Please change name and class as appropriate.
     */
    @CmpField(column = "key", primkeyField = Constants.Bool.TRUE)
    @LocalMethod()
    public abstract java.lang.Integer getKey();

    /**
     * IMPORTANT: Automatically generated primary key field setter method.
     * Please change name and class as appropriate.
     */
    @LocalMethod()
    public abstract void setKey(java.lang.Integer key);
}

Note: To use the WebLogic Entity Bean template, in the Project Explorer right-click the package that will contain the bean, select New > Other, expand EJB, then click WebLogic Entity Bean.

The code includes typical values for the commonly used class-level annotation attributes. In addition, the template-generated code includes the container-managed persistence (CMP) fields for a primary key. The idea is to provide a starting place for your own code -- for you to rewrite it with your code for the create methods, for virtual field declarations, methods for business logic, and so on.

Workshop uses these annotations to generate the interfaces and descriptor files that are required for EJB entity beans. The following sections describe these entity bean pieces and characteristics.

Home and Business Interfaces

An entity bean can have four different interfaces, called the local home interface, the local business interface (or simply, the local interface), the remote home interface, and the remote business interface (or simply, the remote interface). The local interfaces define the bean's methods that can be used by other EJBs, EJB controls, web services, and page flows defined within the same application. That is, if you define an entity bean and only plan to use it within that application, you can use local interfaces. In contrast, the remote interfaces define the bean's methods that be invoked by EJBs, EJB controls, web services, and page flows defined in other applications.

In Workshop, you can use the Properties view to set or view the interface names for a given entity bean. To do this, open the bean's source code and place your cursor in the bean class code (in other words, not a method or other member or annotation). In the Properties view, scroll to where the FileGeneration annotation's attributes are listed. There, you'll see attributes such as localHomeName and localClassName (the business interface), as well as remoteHomeName and remoteClassName (the remote interface). These correspond to attributes for the @FileGeneration Annotation in your source code.

Client applications and other session or entity beans can obtain an instance of an entity bean with which to communicate by using methods in the (remote or local) home interface. Methods in the home interface include create methods, the findByPrimaryKey method, and other finder methods that return a single reference or a set of references to entity bean instances. In addition, Home methods are defined in the local interface. The (remote or local) business interface contains the methods that manipulate an entity bean instance. These methods include field accessor (getter and setter) methods and component methods.

CMP Fields

Container-managed persistence (CMP) fields contain the business object's properties. For example, a Customer bean might contain first name, last price, gender, and age fields. Because the EJB container takes care of the mapping of these properties to a database, CMP fields are virtual fields in an entity bean; that is, these fields are not defined in the entity bean itself but correspond to columns in the database table. The entity bean only defines the accessor (getter and setter) methods. A CMP field can serve as a primary key field, meaning that this field uniquely identifies the entity bean instance or, if multiple primary keys are defined, in combination with the other primary keys uniquely identifies the entity bean instance.

In entity bean code, you designate CMP fields with the @CmpField annotation.

Create Methods

An ejbCreate method is used to create a new instance of an entity bean, that is, insert a new record in the underlying database. At least one ejbCreate method must be defined, but multiple ejbCreate methods are not uncommon. Each ejbCreate method defined for an entity bean has the signature public PrimaryKeyClass ejbCreate(parameters). The PrimaryKeyClass can be a primitive type, such as Integer, when a single primary key is defined, or it can be a separate primary keytes a primary key class with the name provided as an attribute in the @FileGeneration Annotation. To find out which primary key class is used for an entity bean, ensure you are in Design View and go to the General section in the Property Editor. In Source View, this attribute is part of the @Entity Annotation.

Multiple ejbCreate methods can only be distinguished by their parameter composition. In the home interface, ejbCreate methods are exposed as create methods and can correspondingly be distinguished only by the unique set of parameters each one requires.

Component Methods

Component methods are the business methods that are invoked on an entity bean instance. A simple example of a business method is updateCustomer(firstName, lastName, age). This method will in turn invoke the bean's setFirstName, setLastName and setAge methods to update the CMP fields holding this information.

Home Methods

A home method is a business method that relates to the entity bean but is not specific to a single bean instance. For instance, a Customer bean might have a home method returning the total number of customers between 25 and 35 years of age. A home method is defined as an ejbHomeMethodName method in the bean, and is exposed as a MethodName method on the bean's home interface. For example the method ejbHomeGetNCustomers defined in the bean class is exposed as getNCustomers in its home interface.

Finder and Select Methods

Finder and select methods are methods that execute queries on the database, using the EJB QL or WebLogic QL query languages. A finder method is defined in the bean's home interface and returns a reference to a single bean instance or to a set of references to bean instances. In contrast, a select method is not defined in any interface and can only be invoked internally, for instance by a bean's component method. A select method can return a reference to a single bean instance, a set of bean instances, or one or more individual CMP fields.

In addition to the finder and select methods defined for the bean, the method findByPrimaryKey(PrimaryKeyClass) is automatically defined by WebLogic in the home interface(s) defined for the bean class. This method returns a reference to the bean instance that is uniquely defined by the method's parameter. As before, the PrimaryKeyClass can be a primitive type, such as Integer, when a single primary key is defined, or it can be a separate primary key class.

In Workshop, you can use the Properties view to find out which primary key class is used for an entity bean. To do this, open the bean's source code and place your cursor in the class name. In the Properties view, scroll to where the Entity annotation's attributes are listed, then look for the primKeyClass attribute. This attribute might also be given in the bean's @Entity annotation in source code.

In entity code, you specify finder and select methods with the @Finder and @Select annotations. For more information on these and the EJB QL (query language), see Query Methods and EJB QL.

Relations

Entity relationships are used to model dependencies between business objects. For example, a customer can have one or more credit cards, and a product has a manufacturer. Relations between two entity beans can be defined such that for a customer, you can easily access its credit cards by using the accessor method getCreditCards. The entity relation accessor methods, also known as the CMR field accessor methods are defined in the bean's business interface.

In entity code, you designate relations with the @Relation annotation. For more information, see Entity Relationships.

Other Methods

An entity bean has several predefined methods, as well as a number of callback methods, invoked by the EJB container during certain operations, that an entity bean must implement. In WebLogic these callback methods are by default automatically implemented. In many cases you will find it unnecessary to use these methods, with the possible exception of the remove methods used to remove an entity bean instance. To learn more about predefined methods and remove methods in particular, see Defining an Entity Bean. To learn more about callback methods, see the Callback Methods section of that same topic and Life Cycle of an Entity Bean.