Entity Beans

Let's start our look at entity beans in JBoss by examining one of the CMP entity beans in the crime portal. Let's look at the gangster bean, which is implemented as a local CMP entity bean. Although JBoss can provide remote entity beans with pass-by-reference semantics for calls in the same VM to get the performance benefit as from local entity beans, the use of local entity beans is strongly encouraged.

Let's start with the required home interface. Because you're only concerned with the CMP fields at this point, the following code shows only the methods that deal with the CMP fields:

 // Gangster Local Home Interface public interface GangsterHome     extends EJBLocalHome {     Gangster create(Integer id, String name, String nickName)         throws CreateException;     Gangster findByPrimaryKey(Integer id)         throws FinderException; } 

The local interface is what clients use to talk. Again, it contains only the CMP field accessors:

 // Gangster Local Interface public interface Gangster     extends EJBLocalObject {     Integer getGangsterId();          String getName();     String getNickName();     void setNickName(String nickName);     int getBadness();     void setBadness(int badness); } 

Finally, the following is the actual gangster bean:

 // Gangster Implementation Class public abstract class GangsterBean     implements EntityBean {      private EntityContext ctx;     private Category log = Category.getInstance(getClass());     public Integer ejbCreate(Integer id, String name, String nickName)         throws CreateException     {         log.info("Creating Gangster " + id + " '" + nickName + "' "+ name);         setGangsterId(id);         setName(name);         setNickName(nickName);         return null;     }     public void ejbPostCreate(Integer id, String name, String nickName) {     }     // CMP field accessors ---------------------------------------------     public abstract Integer getGangsterId();     public abstract void setGangsterId(Integer gangsterId);     public abstract String getName();     public abstract void setName(String name);     public abstract String getNickName();     public abstract void setNickName(String nickName);     public abstract int getBadness();     public abstract void setBadness(int badness);     public abstract ContactInfo getContactInfo();     public abstract void setContactInfo(ContactInfo contactInfo);     //...     // EJB callbacks ---------------------------------------------------     public void setEntityContext(EntityContext context) { ctx = context; }     public void unsetEntityContext() { ctx = null; }     public void ejbActivate() { }     public void ejbPassivate() { }     public void ejbRemove() { log.info("Removing " + getName()); }     public void ejbStore() { }     public void ejbLoad() { } } 

Despite the size if this bean, very little code is actually required. The bulk of the class is the create method.

The only thing missing now is the ejb-jar.xml deployment descriptor. Although the actual bean class is named GangsterBean, the entity is called GangsterEJB:

[View full width]
 <?xml version="1.0" encoding="UTF-8"?> <ejb-jar xmlns="http://java.sun.com/xml/ns/j2ee" version="2.1"    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee /ejb-jar_\2_1.xsd">    <display-name>Crime Portal</display-name>         <enterprise-beans>         <entity>             <display-name>Gangster Entity Bean</display-name>             <ejb-name>GangsterEJB</ejb-name>             <local-home>org.jboss.cmp2.crimeportal.GangsterHome</local-home>             <local>org.jboss.cmp2.crimeportal.Gangster</local>                          <ejb-class>org.jboss.cmp2.crimeportal.GangsterBean</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>gangster</abstract-schema-name>               <cmp-field>                 <field-name>gangsterId</field-name>             </cmp-field>             <cmp-field>                 <field-name>name</field-name>             </cmp-field>             <cmp-field>                 <field-name>nickName</field-name>             </cmp-field>             <cmp-field>                 <field-name>badness</field-name>             </cmp-field>             <cmp-field>                 <field-name>contactInfo</field-name>             </cmp-field>             <primkey-field>gangsterId</primkey-field>                          <!-- ... -->         </entity>     </enterprise-beans> </ejb-jar> 

Note that the CMP version of 2.x indicates that this is the EJB 2.x CMP entity bean. The abstract schema name is set to gangster. This will be important when you look at EJB-QL queries in the "Declaring Queries" section, later in this chapter.

Entity Mapping

The JBoss configuration for the entity is declared with an entity element in the jbosscmp-jdbc.xml file. This file is located in the META-INF directory of the EJB JAR and contains all the optional configuration information for configuring the CMP mapping. The entity elements for each entity bean are grouped together in the enterprise-beans element, under the top-level jbosscmp-jdbc element. A stubbed-out entity configuration is shown here:

 <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE jbosscmp-jdbc PUBLIC      "-//JBoss//DTD JBOSSCMP-JDBC 3.2//EN"      "http://www.jboss.org/j2ee/dtd/jbosscmp-jdbc_3_2.dtd"> <jbosscmp-jdbc>     <defaults>         <!-- application-wide CMP defaults -->     </defaults>     <enterprise-beans>         <entity>             <ejb-name>GangsterEJB</ejb-name>             <!-- overrides to defaults section -->             <table-name>gangster</table-name>             <!-- CMP Fields (see CMP-Fields) -->             <!-- Load Groups (see Load Groups)-->             <!-- Queries (see Queries) -->         </entity>     </enterprise-beans> </jbosscmp-jdbc> 

The ejb-name element is required to match the entity specification here with the one in the ejb-jar.xml file. The remainder of the elements specify either overrides of the global or application-wide CMP defaults or CMP mapping details specific to the bean. The application defaults come from the defaults section of the jbosscmp-jdbc.xml file, and the global defaults come from the defaults section of the standardjbosscmp-jdbc.xml file in the conf directory for the current server configuration file set. The defaults section is discussed later in this chapter, in the "JBoss Global Defaults" section. Figure 11.3 shows the full entity content model.

Figure 11.3. The entity element content model.

Detailed descriptions of the elements follow:

• ejb-name This required element is the name of the EJB to which this configuration applies. This element must match an ejb-name of an entity in the ejb-jar.xml file.

• datasource This optional element is the jndi-name used to look up the datasource. All database connections used by an entity or relation-table are obtained from the datasource. Having different datasources for entities is not recommended because it vastly constrains the domain over which finders and ejbSelects can query. The default is java:/DefaultDS, unless that is overridden in the defaults section.

• datasource-mapping This optional element specifies the name of the type-mapping, which determines how Java types are mapped to SQL types and how EJB-QL functions are mapped to database-specific functions. (Type mappings are discussed later in this chapter.) The default is Hypersonic SQL, unless that is overridden in the defaults section.

• create-table When this optional element is TRue, JBoss attempts to create a table for the entity. When the application is deployed, JBoss checks whether a table already exists before creating the table. If a table is found, it is logged, and the table is not created. This option is very useful during the early stages of development, when the table structure changes often. The default is false unless that is overridden in the defaults section.

• alter-table If create-table is used to automatically create the schema, alter-table can be used to keep the schema current with changes to the entity bean. alter-table performs the following specific tasks:

  It creates new fields.

  It removes fields that are no longer used.

  It increases the length of string fields that are shorter than the declared length to the declared length. (This is not supported by all databases.)

• remove-table When this optional element is true, JBoss attempts to drop the table for each entity and each relation-table mapped relationship. When the application is undeployed, JBoss attempts to drop the table. This option is very useful during the early stages of development, when the table structure changes often. The default is false, unless that is overridden in the defaults section.

• post-table-create This optional element specifies an arbitrary SQL statement that should be executed immediately after the database table is created. This command is executed only if create-table is true and the table did not previously exist.

• read-only When this optional element is TRue, the bean provider is not allowed to change the values of any fields. A field that is read-only will not be stored in, or inserted into, the database. If a primary key field is read-only, the create method will throw a CreateException. If a set accessor is called on a read-only field, it throws an EJBException. Read-only fields are useful for fields that are filled in by database triggers, such as last update. The read-only option can be overridden on a per-cmp-field basis, as discussed later in this chapter. The default is false, unless that is overridden in the defaults section.

• read-time-out This optional element is the amount of time, in milliseconds, that a read on a read-only field is valid. A value of 0 means that the value is always reloaded at the start of a transaction, and a value of -1 means that the value never times out. This option can also be overridden on a per-cmp-field basis. If read-only is false, this value is ignored. The default is -1, unless that is overridden in the defaults section.

• row-locking If this optional element is true, JBoss locks all rows loaded in a transaction. Most databases implement this by using the SELECT FOR UPDATE syntax when loading the entity, but the actual syntax is determined by the row-locking-template in the datasource-mapping used by this entity. The default is false, unless that is overridden in the defaults section.

• pk-constraint This optional element, if true, specifies that JBoss will add a primary key constraint when creating tables. The default is TRue, unless that is overridden in the defaults section.

• read-ahead This optional element controls caching of query results and cmr-fields for the entity. This option is discussed later in this chapter.

• fetch-size This optional element specifies the number of entities to read in one round-trip to the underlying datastore. The default is 0, unless that is overridden in the defaults section.

• list-cache-max This optional element specifies the number of read-lists that can be tracked by this entity. This option is discussed in on-load. The default is 1000, unless that is overridden in the defaults section.

• clean-read-ahead-on-load When an entity is loaded from the read-ahead cache, JBoss can remove the data used from the read-ahead cache. The default is false.

• table-name This optional element is the name of the table that will hold data for this entity. Each entity instance will be stored in one row of this table. The default is the ejb-name.

• cmp-field The optional element allows you to define how the ejb-jar.xml cmp-field is mapped onto the persistence store. This is discussed later in this chapter.

• load-groups This optional element specifies one or more groupings of CMP fields to declare load groupings of fields.

• eager-load-groups This optional element defines one or more load groupings as eager load groups.

• lazy-load-groups This optional element defines one or more load groupings as lazy load groups.

• query This optional element specifies the definition of finders and selectors. This is discussed later in this chapter.

• unknown-pk This optional element allows you to define how an unknown primary key type of java.lang.Object maps to the persistent store.

• entity-command This optional element allows you to define the entity creation command instance. Typically, this is used to define a custom command instance to allow for primary key generation.

• optimistic-locking This optional element defines the strategy to use for optimistic locking.

• audit This optional element defines the CMP fields that will be audited.