# Getting Started with Entity Beans

This topic provides an overview of CMP entity beans development. It contains the following sections:

- What are CMP Entity Beans?
- Home and Business Interfaces
- CMP Fields
- Create Methods
- Component Methods
- Home Methods
- Finder and Select Methods
- Relations
- Other Methods

##
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.

## 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.

To determine what interfaces are defined for an entity bean, ensure you are in Design View and go to the Naming section in the Property Editor. The Remote EJB and Local EJB sections refer to the remote and local interfaces; within each section the Home class name refers to the home interface, and the Bean class name refers to the business interface. In Source View, the attributes are part of the @ejbgen:file-generation Annotation. When you define a new entity bean, by default only the local interfaces are defined, reflecting the design assumption that in your model entity beans are not accessed directly by other client applications but indirectly, with session or message-driven beans defined in the same application as intermediaries.

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. For more information, see How Do I: Define a Container-Managed Persistence (CMP) Field?

## 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 <prim-key-class> ejbCreate(parameters). The <prim-key-class> can be a primitive type, such as Integer, when a single primary key is defined, or it can be a separate primary key class. By default, WebLogic auto-generates a primary key class, with the name provided as an attribute in the @ejbgen:file-generation 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 @ejbgen: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. For more information, see How Do I: Add a Create Method to an Entity Bean?

## 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), which is used to update the customer's first name, last name and age. This method will in turn invoke the bean's setFirstName, setLastName and setAge methods to update the CMP fields holding this information. For more information, see How Do I: Add a Component Method to an Entity or Session Bean?

## 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 a ejbHome<method-name> method in the bean, and is exposed as a <method-name> 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. For more information, see How Do I: Add a Home Method to an Entity or Session Bean? and the Home Methods Sample.

## 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(<prim-key-class>) 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 <prim-key-class> can be a primitive type, such as Integer, when a single primary key is defined, or it can be a separate primary key class. 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 @ejbgen:entity Annotation.

For more information on how to define finder or select methods, see How Do I: Add a Finder Method to an Entity Bean? and How Do I: Add a Select Method to an Entity Bean? For more information on the EJB QL and WebLogic QL query languages, see Query Methods and EJB QL, the Finder Methods Sample, and the Select Methods Sample.

## 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. For more information, see Entity Relationships, How Do I: Add a Relation to an Entity Bean?, and Tutorial: Enterprise JavaBeans.

## 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 The Life Cycle of an Entity Bean.

Related Topics

Automatic Primary Key Generation Sample

Finder Methods Sample

Home Methods Sample

Select Methods Sample

Value Object Sample

@ejbgen:file-generation Annotation

@ejbgen:entity Annotation