CHAPTER 11 The CMP Engine

FIGURE 11-1. The main CMP2 example classes

To build the example code, execute ant with the following arguments:

[nr@toki examples]$ ant -Dchap=cmp2 config

Buildfile: build.xml

...

init:

[echo] Using jboss.dist=/tmp/jboss-3.2.3

compile:

[mkdir] Created dir: /Users/orb/Desktop/jboss/docs323/examples/output/classes

[javac] Compiling 123 source files to /Users/orb/Desktop/jboss/docs323/examples/output/classes

config:

prepare:

[mkdir] Created dir: /Users/orb/Desktop/jboss/docs323/examples/output/cmp2

build-ejb.jar:

[jar] Building jar: /Users/orb/Desktop/jboss/docs323/examples/output/cmp2/cmp2-ex1.jar

config:

[copy] Copying 1 file to /tmp/jboss-3.2.3/server/default/deploy

[echo] Waiting for 5 seconds for deploy...

[junit] .

[junit] Time: 4.535

[junit] OK (1 test)

This command builds and deploys the application to the JBoss server. When you start your JBoss server, or if it is already running, you should see the following deployment messages:

13:50:18,316 INFO [MainDeployer] Starting deployment of package: file:/private/tmp/jboss-3.2.3/server/default/deploy/cmp2-ex1.jar

13:50:20,811 INFO [EjbModule] Deploying OrganizationEJB

13:50:20,851 INFO [EjbModule] Deploying GangsterEJB

13:50:20,882 INFO [EjbModule] Deploying JobEJB

13:50:20,918 INFO [EjbModule] Deploying LocationEJB

13:50:20,942 INFO [EjbModule] Deploying EJBTestRunnerEJB

13:50:20,965 INFO [EjbModule] Deploying ReadAheadEJB

13:50:21,590 INFO [EntityInstancePool] Started jboss.j2ee:jndiName=crimeportal/Organization,plugin=pool,service=EJB

13:50:21,594 INFO [EntityContainer] Started jboss.j2ee:jndiName=crimeportal/Organization,service=EJB

13:50:21,647 INFO [EntityInstancePool] Started jboss.j2ee:jndiName=crimeportal/Gangster,plugin=pool,service=EJB

13:50:21,653 INFO [EntityContainer] Started jboss.j2ee:jndiName=crimeportal/Gangster,service=EJB

13:50:21,721 INFO [EntityInstancePool] Started jboss.j2ee:jndiName=crimeportal/Job,plugin=pool,service=EJB

13:50:21,725 INFO [EntityContainer] Started jboss.j2ee:jndiName=crimeportal/Job,service=EJB

13:50:21,843 INFO [OrganizationEJB] Created table 'ORGANIZATION' successfully.

13:50:21,972 INFO [GangsterEJB] Created table 'GANGSTER' successfully.

13:50:21,992 INFO [GangsterEJB] Created table 'GANGSTER_ENEMIES' successfully.

13:50:22,169 INFO [JobEJB] Created table 'JOB' successfully.

13:50:22,196 INFO [JobEJB] Created table 'GANGSTER_JOB' successfully.

13:50:22,271 INFO [LocationEJB] Created table 'LOCATION' successfully.

13:50:22,275 INFO [EntityInstancePool] Started jboss.j2ee:jndiName=crimeportal/Location,plugin=pool,service=EJB

13:50:22,279 INFO [EntityContainer] Started jboss.j2ee:jndiName=crimeportal/Location,service=EJB

13:50:22,417 INFO [StatelessSessionInstancePool] Started jboss.j2ee:jndiName=ejb/EJBTestRunner,plugin=pool,service=EJB

13:50:22,431 INFO [StatelessSessionContainer] Started jboss.j2ee:jndiName=ejb/EJBTestRunner,service=EJB

13:50:22,460 INFO [StatelessSessionInstancePool] Started jboss.j2ee:jndiName=crimeportal/ReadAhead,plugin=pool,service=EJB

13:50:22,463 INFO [StatelessSessionContainer] Started jboss.j2ee:jndiName=crimeportal/ReadAhead,service=EJB

13:50:22,466 INFO [EjbModule] Started jboss.j2ee:module=cmp2-ex1.jar,service=EjbModule

13:50:22,469 INFO [EJBDeployer] Deployed: file:/private/tmp/jboss-3.2.3/server/default/deploy/cmp2-ex1.jar

13:50:22,591 INFO [MainDeployer] Deployed package: file:/private/tmp/jboss-3.2.3/server/default/deploy/cmp2-ex1.jar

13:50:38,358 INFO [OrganizationBean$Proxy] Creating organization Yakuza, Japanese Gangsters

13:50:38,506 INFO [OrganizationBean$Proxy] Creating organization Mafia, Italian Bad Guys

13:50:38,514 INFO [OrganizationBean$Proxy] Creating organization Triads, Kung Fu Movie Extras

13:50:38,572 INFO [GangsterBean$Proxy] Creating Gangster 0 'Bodyguard' Yojimbo

13:50:38,651 INFO [GangsterBean$Proxy] Creating Gangster 1 'Master' Takeshi

13:50:38,665 INFO [GangsterBean$Proxy] Creating Gangster 2 'Four finger' Yuriko

13:50:38,697 INFO [GangsterBean$Proxy] Creating Gangster 3 'Killer' Chow

13:50:38,711 INFO [GangsterBean$Proxy] Creating Gangster 4 'Lightning' Shogi

13:50:38,728 INFO [GangsterBean$Proxy] Creating Gangster 5 'Pizza-Face' Valentino

13:50:38,744 INFO [GangsterBean$Proxy] Creating Gangster 6 'Toohless' Toni

13:50:38,785 INFO [GangsterBean$Proxy] Creating Gangster 7 'Godfather' Corleone

13:50:38,809 INFO [JobBean$Proxy] Creating Job 10th Street Jeweler Heist

13:50:38,821 INFO [JobBean$Proxy] Creating Job The Greate Train Robbery

13:50:38,831 INFO [JobBean$Proxy] Creating Job Cheap Liquor Snatch and Grab

Before the chapter tests can be run, the log level of JBossCMP must be increased. To enable DEBUG logging for the CMP subsystem, add the following category to your log4j.xml file:

<category name="org.jboss.ejb.plugins.cmp">

<priority value="DEBUG"/>

</category>

In addition to this, it is necessary to decrease the threshold on the CONSOLE appender to allow DEBUG level messages to be logged to the console. The following changes also need to be applied to the log4j.xml file.

<!-- ============================== -->

<!-- Append messages to the console -->

<!-- ============================== -->

<appender name="CONSOLE" class="org.apache.log4j.ConsoleAppender">

<param name="Threshold" value="DEBUG"/>

<param name="Target" value="System.out"/>

<layout class="org.apache.log4j.PatternLayout">

<!-- The default pattern: Date Priority [Category] Message\n -->

<param name="ConversionPattern" value="%d{ABSOLUTE} %-5p [%c{1}] %m%n"/>

</layout>

</appender>

To see the full workings of the CMP engine you would need to enable the custom TRACE level priority on the org.jboss.ejb.plugins.cmp category as show here:

<category name="org.jboss.ejb.plugins.cmp">

<priority value="TRACE" class="org.jboss.logging.XLevel"/>

</category>

One final note before moving on to look at how to run the chapter examples. Since the beans in the examples are configured to remove their tables on undeployment, anytime you restart the JBoss server you need to rerun the config target to reload the example data. Also, if you make changes to the examples and want to redeploy the example EJB jar, this also should be done using the config target so that the example data is reloaded.

Tests

The first test target illustrates a number of the customization features that will be discussed throughout this chapter. To run these tests execute the following ant target:

[nr@toki examples]$ ant -Dchap=cmp2 -Dex=test run-example

14:03:27,920 DEBUG [OrganizationEJB#findByPrimaryKey] Executing SQL: SELECT name FROM ORGANIZATION WHERE name=?

14:03:28,011 DEBUG [OrganizationEJB] Executing SQL: SELECT desc, the_boss FROM ORGANIZATION WHERE (name=?)

14:03:28,020 DEBUG [OrganizationEJB] Executing SQL: SELECT id FROM GANGSTER WHERE (organization=?)

14:03:28,044 DEBUG [GangsterEJB#findByPrimaryKey] Executing SQL: SELECT id FROM GANGSTER WHERE id=?

14:03:28,052 DEBUG [GangsterEJB#findByPrimaryKey] Executing SQL: SELECT id FROM GANGSTER WHERE id=?

14:03:28,070 DEBUG [GangsterEJB#findByPrimaryKey] Executing SQL: SELECT id FROM GANGSTER WHERE id=?

14:03:28,229 DEBUG [GangsterEJB#findBadDudes_ejbql] Executing SQL: SELECT t0_g.id FROM GANGSTER t0_g WHERE (t0_g.badness > ?)

14:03:28,256 DEBUG [GangsterEJB#findByPrimaryKey] Executing SQL: SELECT id FROM GANGSTER WHERE id=?

14:03:28,264 DEBUG [GangsterEJB#findByPrimaryKey] Executing SQL: SELECT id FROM GANGSTER WHERE id=?

14:03:28,270 DEBUG [GangsterEJB#findByPrimaryKey] Executing SQL: SELECT id FROM GANGSTER WHERE id=?

14:03:28,276 DEBUG [GangsterEJB#findByPrimaryKey] Executing SQL: SELECT id FROM GANGSTER WHERE id=?

14:03:28,281 DEBUG [GangsterEJB#findByPrimaryKey] Executing SQL: SELECT id FROM GANGSTER WHERE id=?

14:03:28,395 DEBUG [GangsterEJB#findBadDudes_jbossql] Executing SQL: SELECT t0_g.id, t0_g.badness FROM GANGSTER t0_g WHERE (t0_g.badness > ?) ORDER BY t0_g.badness DESC

14:03:28,417 DEBUG [GangsterEJB#findByPrimaryKey] Executing SQL: SELECT id FROM GANGSTER WHERE id=?

14:03:28,423 DEBUG [GangsterEJB#findByPrimaryKey] Executing SQL: SELECT id FROM GANGSTER WHERE id=?

14:03:28,429 DEBUG [GangsterEJB#findByPrimaryKey] Executing SQL: SELECT id FROM GANGSTER WHERE id=?

14:03:28,439 DEBUG [GangsterEJB#findByPrimaryKey] Executing SQL: SELECT id FROM GANGSTER WHERE id=?

14:03:28,446 DEBUG [GangsterEJB#findByPrimaryKey] Executing SQL: SELECT id FROM GANGSTER WHERE id=?

14:03:28,605 DEBUG [GangsterEJB#findBadDudes_declaredsql] Executing SQL: SELECT id FROM GANGSTER WHERE badness > ? ORDER BY badness DESC

14:03:28,613 DEBUG [GangsterEJB#findByPrimaryKey] Executing SQL: SELECT id FROM GANGSTER WHERE id=?

14:03:28,631 DEBUG [GangsterEJB#findByPrimaryKey] Executing SQL: SELECT id FROM GANGSTER WHERE id=?

14:03:28,641 DEBUG [GangsterEJB#findByPrimaryKey] Executing SQL: SELECT id FROM GANGSTER WHERE id=?

14:03:28,647 DEBUG [GangsterEJB#findByPrimaryKey] Executing SQL: SELECT id FROM GANGSTER WHERE id=?

14:03:28,655 DEBUG [GangsterEJB#findByPrimaryKey] Executing SQL: SELECT id FROM GANGSTER WHERE id=?

14:03:28,783 DEBUG [GangsterEJB#ejbSelectBoss_ejbql] Executing SQL: SELECT DISTINCT t0_underling_organization_theBos.id FROM GANGSTER t1_underling, ORGANIZATION t4_underling_organization, GANGSTER t0_underling_organization_theBos WHERE ((t1_underling.name = ?) OR (t1_underling.nick_name = ?)) AND t1_underling.organization=t4_underling_organization.name AND t4_underling_organization.the_boss=t0_underling_organization_theBos.id

14:03:28,815 DEBUG [GangsterEJB#findByPrimaryKey] Executing SQL: SELECT id FROM GANGSTER WHERE id=?

14:03:28,822 DEBUG [GangsterEJB#ejbSelectBoss_ejbql] Executing SQL: SELECT DISTINCT t0_underling_organization_theBos.id FROM GANGSTER t1_underling, ORGANIZATION t4_underling_organization, GANGSTER t0_underling_organization_theBos WHERE ((t1_underling.name = ?) OR (t1_underling.nick_name = ?)) AND t1_underling.organization=t4_underling_organization.name AND t4_underling_organization.the_boss=t0_underling_organization_theBos.id

14:03:28,829 DEBUG [GangsterEJB#findByPrimaryKey] Executing SQL: SELECT id FROM GANGSTER WHERE id=?

14:03:28,835 DEBUG [GangsterEJB#ejbSelectBoss_ejbql] Executing SQL: SELECT DISTINCT t0_underling_organization_theBos.id FROM GANGSTER t1_underling, ORGANIZATION t4_underling_organization, GANGSTER t0_underling_organization_theBos WHERE ((t1_underling.name = ?) OR (t1_underling.nick_name = ?)) AND t1_underling.organization=t4_underling_organization.name AND t4_underling_organization.the_boss=t0_underling_organization_theBos.id

14:03:29,011 DEBUG [GangsterEJB#ejbSelectBoss_declaredsql] Executing SQL: SELECT DISTINCT boss.id FROM GANGSTER boss , gangster g, organization o WHERE (LCASE(g.name) = ? OR LCASE(g.nick_name) = ?) AND

g.organization = o.name AND o.the_boss = boss.id

14:03:29,163 DEBUG [GangsterEJB#findByPrimaryKey] Executing SQL: SELECT id FROM GANGSTER WHERE id=?

14:03:29,172 DEBUG [GangsterEJB#ejbSelectBoss_declaredsql] Executing SQL: SELECT DISTINCT boss.id FROM GANGSTER boss , gangster g, organization o WHERE (LCASE(g.name) = ? OR LCASE(g.nick_name) = ?) AND

g.organization = o.name AND o.the_boss = boss.id

14:03:29,201 DEBUG [GangsterEJB#findByPrimaryKey] Executing SQL: SELECT id FROM GANGSTER WHERE id=?

14:03:29,208 DEBUG [GangsterEJB#ejbSelectBoss_declaredsql] Executing SQL: SELECT DISTINCT boss.id FROM GANGSTER boss , gangster g, organization o WHERE (LCASE(g.name) = ? OR LCASE(g.nick_name) = ?) AND

g.organization = o.name AND o.the_boss = boss.id

14:03:29,378 DEBUG [GangsterEJB#ejbSelectGeneric] DYNAMIC-QL: SELECT OBJECT(g) FROM gangster g WHERE g.hangout.state IN (?1, ?2, ?3, ?4) ORDER BY g.name

14:03:29,390 DEBUG [GangsterEJB#ejbSelectGeneric] SQL: SELECT DISTINCT t0_g.id, t0_g.name FROM GANGSTER t0_g, LOCATION t1_g_hangout WHERE (t1_g_hangout.st IN (?, ?, ?, ?) AND t0_g.hangout=t1_g_hangout.id) ORDER BY t0_g.name ASC

14:03:29,394 DEBUG [GangsterEJB#ejbSelectGeneric] Executing SQL: SELECT DISTINCT t0_g.id, t0_g.name FROM GANGSTER t0_g, LOCATION t1_g_hangout WHERE (t1_g_hangout.st IN (?, ?, ?, ?) AND t0_g.hangout=t1_g_hangout.id) ORDER BY t0_g.name ASC

14:03:29,422 DEBUG [GangsterEJB#findByPrimaryKey] Executing SQL: SELECT id FROM GANGSTER WHERE id=?

14:03:29,428 DEBUG [GangsterEJB#findByPrimaryKey] Executing SQL: SELECT id FROM GANGSTER WHERE id=?

14:03:29,433 DEBUG [GangsterEJB#findByPrimaryKey] Executing SQL: SELECT id FROM GANGSTER WHERE id=?

14:03:29,440 DEBUG [GangsterEJB#findByPrimaryKey] Executing SQL: SELECT id FROM GANGSTER WHERE id=?

14:03:29,449 DEBUG [GangsterEJB#findByPrimaryKey] Executing SQL: SELECT id FROM GANGSTER WHERE id=?

14:03:29,465 DEBUG [GangsterEJB#findByPrimaryKey] Executing SQL: SELECT id FROM GANGSTER WHERE id=?

14:03:29,671 DEBUG [OrganizationEJB#ejbSelectOperatingZipCodes_declaredsql] Executing SQL: SELECT DISTINCT hangout.zip FROM LOCATION hangout , organization o, gangster g WHERE LCASE(o.name) = ? AND o.name = g.organization AND

g.hangout = hangout.id ORDER BY hangout.zip

14:03:29,822 DEBUG [GangsterEJB#ejbSelectGeneric] DYNAMIC-QL: SELECT OBJECT(g) FROM gangster g WHERE g.hangout.state IN (?1, ?2, ?3, ?4) ORDER BY g.name

14:03:29,828 DEBUG [GangsterEJB#ejbSelectGeneric] SQL: SELECT DISTINCT t0_g.id, t0_g.name FROM GANGSTER t0_g, LOCATION t1_g_hangout WHERE (t1_g_hangout.st IN (?, ?, ?, ?) AND t0_g.hangout=t1_g_hangout.id) ORDER BY t0_g.name ASC

14:03:29,832 DEBUG [GangsterEJB#ejbSelectGeneric] Executing SQL: SELECT DISTINCT t0_g.id, t0_g.name FROM GANGSTER t0_g, LOCATION t1_g_hangout WHERE (t1_g_hangout.st IN (?, ?, ?, ?) AND t0_g.hangout=t1_g_hangout.id) ORDER BY t0_g.name ASC

14:03:29,865 DEBUG [GangsterEJB#findByPrimaryKey] Executing SQL: SELECT id FROM GANGSTER WHERE id=?

14:03:29,962 DEBUG [GangsterEJB#findByPrimaryKey] Executing SQL: SELECT id FROM GANGSTER WHERE id=?

14:03:29,970 DEBUG [GangsterEJB] Executing SQL: SELECT name, nick_name, badness, hangout, organization FROM GANGSTER WHERE (id=?)

14:03:29,980 DEBUG [GangsterEJB] Executing SQL: SELECT cell_area, cell_exch, cell_ext, page_area, page_exch, page_ext, email FROM GANGSTER WHERE (id=?)

14:03:29,987 DEBUG [GangsterEJB] Executing SQL: UPDATE GANGSTER SET cell_area=?, cell_exch=?, cell_ext=?, page_area=?, page_exch=?, page_ext=?, email=? WHERE id=?

14:03:29,995 DEBUG [GangsterEJB] Rows affected = 1

These tests exercise various finders, selectors and object to table mapping issues. We will refer to the tests throughout the chapter.

Read-ahead

The other main target runs a set of tests to demonstrate the optimized loading configurations presented in Optimized Loading. Now that the logging is setup correctly, the read-ahead tests will display useful information about the queries performed. Note that you do not have to restart the JBoss server for it to recognize the changes to the log4j.xml file, but it may take a minute or so. The following shows the actual execution of the readahead client:

[starksm@banshee examples]$ ant -Dchap=cmp2 -Dex=readahead run-example

Buildfile: build.xml

...

run-example:

run-examplereadahead:

[junit] .

[junit] Time: 0.561

[junit] OK (1 test)

When the readahead client is executed, all of the SQL queries executed during the test are displayed in the JBoss server console. The important items of note when analyzing the output are the number of queries executed, the columns selected, and the number of rows loaded. The following shows the read-ahead none portion of the JBoss server console output from readahead:

########################################################

### read-ahead none

###

08:31:15,892 DEBUG [findAll_none] Executing SQL: SELECT t0_g.id, t0_g.id FROM GANGSTER t0_g ORDER BY t0_g.id ASC

08:31:15,902 DEBUG [GangsterEJB] Executing SQL: SELECT name, nick_name, badness, hangout, organization FROM GANGSTER WHERE (id=?)

08:31:15,912 DEBUG [GangsterEJB] Executing SQL: SELECT name, nick_name, badness, hangout, organization FROM GANGSTER WHERE (id=?)

08:31:15,912 DEBUG [GangsterEJB] Executing SQL: SELECT name, nick_name, badness, hangout, organization FROM GANGSTER WHERE (id=?)

08:31:15,912 DEBUG [GangsterEJB] Executing SQL: SELECT name, nick_name, badness, hangout, organization FROM GANGSTER WHERE (id=?)

08:31:15,922 DEBUG [GangsterEJB] Executing SQL: SELECT name, nick_name, badness, hangout, organization FROM GANGSTER WHERE (id=?)

08:31:15,922 DEBUG [GangsterEJB] Executing SQL: SELECT name, nick_name, badness, hangout, organization FROM GANGSTER WHERE (id=?)

08:31:15,932 DEBUG [GangsterEJB] Executing SQL: SELECT name, nick_name, badness, hangout, organization FROM GANGSTER WHERE (id=?)

08:31:15,932 DEBUG [GangsterEJB] Executing SQL: SELECT name, nick_name, badness, hangout, organization FROM GANGSTER WHERE (id=?)

08:31:15,942 INFO [ReadAheadTest]

###

########################################################

We will revisit this example and explore the output when we discuss the settings for optimized loading.

A sample jbosscmp-jdbc.xml Entity Mapping

<?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>

...

<enterprise-beans>

<entity>

<ejb-name>GangsterEJB</ejb-name>

<table-name>gangster</table-name>

<!-- CMP Fields (see CMP-Fields) -->

<!-- Load Groups (see Load Groups)-->

<!-- Queries (see Queries) -->

</entity>

</enterprise-beans>

</jbosscmp-jdbc>

In this case the DOCTYPE declaration is optional, but will reduce configuration errors. In addition, all of the elements are optional except for ejb-name, which is used to match the configuration to an entity declared in the ejb-jar.xml file. Unless noted otherwise, the default values come from the defaults section of either the jbosscmp-jdbc.xml file, or the conf/standardjbosscmp-jdbc.xml file for the current server configuration file set. The defaults section is discussed in Defaults.

FIGURE 11-3. The entity element content model

A detailed description of each entity element follows:

• 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, as it vastly constrains the domain over which finders and ejbSelects can query. The default is java:/DefaultDS unless 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 in Type Mapping. The default is "Hypersonic SQL" unless overridden in the defaults section.
• create-table: This optional element when true, specifies that JBossCMP should attempt to create a table for the entity. When the application is deployed, JBossCMP checks if 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 overridden in the defaults section.
• remove-table: This optional element when true, JBossCMP will attempt to drop the table for each entity and each relation table mapped relationship. When the application is undeployed, JBossCMP will attempt 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 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 only executed if create-table is true and the table did not previously exist.
• read-only: This optional element when true specifies that the bean provider will not be allowed to change the value 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, and is discussed in Read-only Fields. The default is false unless 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 overridden in the defaults section.
• row-locking: This optional element if true specifies that JBossCMP will lock 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 overridden in the defaults section.
• pk-constraint: This optional element if true specifies that JBossCMP will add a primary key constraint when creating tables. The default is true unless 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 in Read-ahead.
• 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 overridden in the defaults section.
• 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 overridden in the defaults section.
• 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 one to define how the ejb-jar.xml cmp-field is mapped onto the persistence store. This is discussed in CMP-Fields.
• load-groups: This optional element specifies one or more groupings of cmp-fields to declare load groupings of fields. This is discussed in Load Groups.
• eager-load-groups: This optional element defines one or more load grouping as eager load groups. This is discussed in Eager-loading Process.
• lazy-load-groups: This optional element defines one or more load grouping as lazy load groups. This is discussed in Lazy-loading Process.
• query: This optional element specifies the definition of finders and selectors. This is discussed in Queries.
• unknown-pk: This optional element allows one to define how an unknown primary key type of java.lang.Object maps to the persistent store.
• entity-command: This optional element allows one to define the entity creation command instance. Typically this is used to define a custom command instance to allow for primary key generation. This is described in detail in Entity Commands and Primary Key Generation.
• optimistic-locking: This optional element defines the strategy to use for optimistic locking. This is described in detail in Optimistic Locking.
• audit: This optional element defines the cmp fields that will be audited. This is described in detail in Auditng Entity Access.

Sample cmp-field abstract accessor declaration

public abstract class GangsterBean implements EntityBean {

public abstract Integer getGangsterId();

public abstract void setGangsterId(Integer gangsterId);

public abstract String getName();

public abstract void setName(String param);

public abstract String getNickName();

public abstract void setNickName(String param);

public abstract int getBadness();

public abstract void setBadness(int param);

}

Each cmp-field is required to have both a getter and a setter method, and each accessor method must be declared public abstract.

The ejb-jar.xml cmp-field Declaration

<ejb-jar>

<enterprise-beans>

<entity>

<ejb-name>GangsterEJB</ejb-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>

</entity>

</enterprise-beans>

</ejb-jar>

FIGURE 11-4. The jbosscmp-jdbc.xml cmp-field element content model.

An example usage of cmp-field mapping is shown in See The jbosscmp-jdbc.xml cmp-field Mapping.:

The jbosscmp-jdbc.xml cmp-field Mapping

<jbosscmp-jdbc>

<enterprise-beans>

<entity>

<ejb-name>GangsterEJB</ejb-name>

<table-name>gangster</table-name>

<cmp-field>

<field-name>gangsterId</field-name>

<column-name>id</column-name>

</cmp-field>

<cmp-field>

<field-name>name</field-name>

<column-name>name</column-name>

<not-null/>

</cmp-field>

<cmp-field>

<field-name>nickName</field-name>

<column-name>nick_name</column-name>

<jdbc-type>VARCHAR</jdbc-type>

<sql-type>VARCHAR(64)</sql-type>

</cmp-field>

<cmp-field>

<field-name>badness</field-name>

<column-name>badness</column-name>

</cmp-field>

</entity>

</enterprise-beans>

</jbosscmp-jdbc>

In the cmp-field element, you can control the name and datatype of the column. A detailed description of each element follows:

• field-name This required element is the name of the cmp-field that is being configured. It must match the field-name element of a cmp-field declared for this entity in the ejb-jar.xml file.
• column-name This optional element is the name of the column to which the cmp-field is mapped. The default is to use the field-name value.
• not-null This optional element indicates that JBossCMP should add a NOT NULL to the end of the column declaration when automatically creating the table for this entity. The default for primary key fields and primitives not null.
• jdbc-type This is the JDBC type that is used when setting parameters in a JDBC PreparedStatement or loading data from a JDBC ResultSet. The valid types are defined in java.sql.Types. Only required if sql-type is specified, default is based on datasourcemapping
• sql-type This is the SQL type that is used in create table statements for this field. Valid sql-types are only limited by your database vendor. Only required if jdbc-type is specified, default is based on datasourcemapping
• property This optional element allows one to define how the properties of a dependent value class cmp-field should be mapped to the persistent store. This is discussed further in Dependent Value Classes (DVCs).
• auto-increment The presence of this optional field indicates that it is auto-incremented by the database layer. This is used to map a field to a generated column as well as an externally manipulated column.
• dbindex: The presence of this optional field indicates that the server should create an index on the corresponding column in the database, and the index name will be fieldname_index.

A sample jbosscmp-jdbc.xml cmp-field read-only declaration

<jbosscmp-jdbc>

<enterprise-beans>

<entity>

<ejb-name>GangsterEJB</ejb-name>

<cmp-field>

<field-name>lastUpdated</field-name>

<read-only>true</read-only>

<read-time-out>1000</read-time-out>

</cmp-field>

</entity>

</enterprise-beans>

</jbosscmp-jdbc>

FIGURE 11-5. The jbosscmp-jdbc.xml audit element content model

• created-by This optional element indicates that the caller who created the entity should be saved to either the indicated column-name or cmp field-name.
• created-time This optional element indicates that the time of entity creation should be saved to either the indicated column-name or cmp field-name.
• updated-by This optional element indicates that the caller who last modified the entity should be saved to either the indicated column-name or cmp field-name.
• updated-time This optional element indicates that the last time of entity modification should be saved to either the indicated column-name or cmp field-name.
• */field-name This element indicates that the corresponding audit information should be stored in the indicated cmp-field of the accessed entity bean. Note that there does not have to be an actual cmp field match in the entity. In case there are matching field names, you will be able to access audit fields in the application using the corresponding cmp field abstract getters and setters. Otherwise, audit fields will be created and added to entity internally, and you will be able to access audit information in EJB-QL queries using the audit field names, but not directly through the entity accessors.
• */column-name This element indicates that the corresponding audit information should be stored in the indicated column of the entity table. If JBossCMP is creating the table the jdbc-type and sql-type element can be used to define the storage type.

A sample audit element declaration

<jbosscmp-jdbc>

<enterprise-beans>

<entity>

<ejb-name>AuditChangedNamesEJB</ejb-name>

<table-name>cmp2_audit_changednames</table-name>

<audit>

<created-by>

<column-name>createdby</column-name>

</created-by>

<created-time>

<column-name>createdtime</column-name>

</created-time>

<updated-by>

<column-name>updatedby</column-name></updated-by>

<updated-time>

<column-name>updatedtime</column-name>

</updated-time>

</audit>

</entity>

</enterprise-beans>

</jbosscmp-jdbc>

FIGURE 11-6. The jbosscmp-jdbc dependent-value-classes element model.

An example declaration of a phone number DVC and contact information DVC, and the corresponding classes is shown in See The jbosscmp-jdbc.xml Dependent Value Class Declaration.:

The jbosscmp-jdbc.xml Dependent Value Class Declaration

<jbosscmp-jdbc>

<dependent-value-classes>

<dependent-value-class>

<description>A phone number</description>

<class>org.jboss.cmp2.crimeportal.PhoneNumber</class>

<property>

<property-name>areaCode</property-name>

<column-name>area_code</column-name>

</property>

<property>

<property-name>exchange</property-name>

<column-name>exchange</column-name>

</property>

<property>

<property-name>extension</property-name>

<column-name>extension</column-name>

</property>

</dependent-value-class>

<dependent-value-class>

<description>General contact info</description>

<class>org.jboss.cmp2.crimeportal.ContactInfo</class>

<property>

<property-name>cell</property-name>

<column-name>cell</column-name>

</property>

<property>

<property-name>pager</property-name>

<column-name>pager</column-name>

</property>

<property>

<property-name>email</property-name>

<column-name>email</column-name>

<jdbc-type>VARCHAR</jdbc-type>

<sql-type>VARCHAR(128)</sql-type>

</property>

</dependent-value-class>

</dependent-value-classes>

</jbosscmp-jdbc>

public class PhoneNumber implements Serializable {

/** The first three digits of the phone number. */

private short areaCode;

/** The middle three digits of the phone number. */

private short exchange;

/** The last four digits of the phone number. */

private short extension;

...

}

public class ContactInfo implements Serializable {

/** The cell phone number. */

private PhoneNumber cell;

/** The pager number. */

private PhoneNumber pager;

/** The email address */

private String email;

...

}

Each DVC is declared with a dependent-value-class element. A DVC is identified by the Java class type declared in the class element. Each property to be persisted is declared with a property element. This specification is based on the cmp-field element, so it should be self-explanatory. This restriction will also be removed in a future release. The current proposal involves storing the primary key fields in the case of a local entity and the entity handle in the case of a remote entity.

The dependent-value-classes section defines the internal structure and default mapping of the classes. When JBossCMP encounters a field that has an unknown type, it searches the list of registered DVCs, and if a DVC is found, it persists this field into a set of columns, otherwise the field is stored in serialized form in a single column. JBossCMP does not support inheritance of DVCs; therefore, this search is only based on the declared type of the field. A DVC can be constructed from other DVCs, so when JBossCMP runs into a DVC, it flattens the DVC tree structure into a set of columns. If JBossCMP finds a DVC circuit during startup, it will throw an EJBException. The default column name of a property is the column name of the base cmp-field followed by an underscore and then the property column name. If the property is a DVC, the process is repeated. For example, a cmp-field of type ContactInfo (seeSee The jbosscmp-jdbc.xml Dependent Value Class Declaration.) and named info will have the following columns:

Generated Column Names for ContactInfo Dependent Value Class

info_cell_area_code

info_cell_exchange

info_cell_extension

info_pager_area_code

info_pager_exchange

info_pager_extension

info_email

The automatically generated column names can quickly become excessively long and awkward. The default mappings of columns can be overridden in the entity element as follows:

The jbosscmp-jdbc.xml cmp-field Dependent Value Class Property Override

<jbosscmp-jdbc>

<enterprise-beans>

<entity>

<ejb-name>GangsterEJB</ejb-name>

<cmp-field>

<field-name>contactInfo</field-name>

<property>

<property-name>cell.areaCode</property-name>

<column-name>cell_area</column-name>

</property>

<property>

<property-name>cell.exchange</property-name>

<column-name>cell_exch</column-name>

</property>

<property>

<property-name>cell.extension</property-name>

<column-name>cell_ext</column-name>

</property>

<property>

<property-name>pager.areaCode</property-name>

<column-name>page_area</column-name>

</property>

<property>

<property-name>pager.exchange</property-name>

<column-name>page_exch</column-name>

</property>

<property>

<property-name>pager.extension</property-name>

<column-name>page_ext</column-name>

</property>

<property>

<property-name>email</property-name>

<column-name>email</column-name>

<jdbc-type>VARCHAR</jdbc-type>

<sql-type>VARCHAR(128)</sql-type>

</property>

</cmp-field>

</entity>

</enterprise-beans>

</jbosscmp-jdbc>

As shown in See The jbosscmp-jdbc.xml cmp-field Dependent Value Class Property Override. , when overriding property info for the entity, you need to refer to the property from a flat perspective as in cell.areaCode.

Collection Valued cmr-field Abstract Accessor Declaration

public abstract class OrganizationBean implements EntityBean {

public abstract Set getMemberGangsters();

public abstract void setMemberGangsters(Set gangsters);

}

Second, add the following to the GangsterBean class:

Single Valued cmr-field Abstract Accessor Declaration

public abstract class GangsterBean implements EntityBean {

public abstract Organization getOrganization();

public abstract void setOrganization(Organization org);

}

Although in See Collection Valued cmr-field Abstract Accessor Declaration. and See Single Valued cmr-field Abstract Accessor Declaration. each bean declared a cmr-field, only one of the two beans in a relationship must have a set of accessors. As with cmp-fields, a cmr-field is required to have both a getter and a setter method.

The ejb-jar.xml Relationship Declaration

<ejb-jar>

<relationships>

<ejb-relation>

<ejb-relation-name>Organization-Gangster</ejb-relation-name>

<ejb-relationship-role>

<ejb-relationship-role-name>org-has-gangsters

</ejb-relationship-role-name>

<multiplicity>One</multiplicity>

<relationship-role-source>

<ejb-name>OrganizationEJB</ejb-name>

</relationship-role-source>

<cmr-field>

<cmr-field-name>memberGangsters</cmr-field-name>

<cmr-field-type>java.util.Set</cmr-field-type>

</cmr-field>

</ejb-relationship-role>

<ejb-relationship-role>

<ejb-relationship-role-name>gangster-belongs-to-org

</ejb-relationship-role-name>

<multiplicity>Many</multiplicity>

<cascade-delete/>

<relationship-role-source>

<ejb-name>GangsterEJB</ejb-name>

</relationship-role-source>

<cmr-field>

<cmr-field-name>organization</cmr-field-name>

</cmr-field>

</ejb-relationship-role>

</ejb-relation>

</relationships>

</ejb-jar>

As you can see, each relationship is declared with an ejb-relation element within the top level relationships7 element, and each ejb-relation contains two ejb-relationship-role elements (one for each entity in the relationship). The ejb-relationship-role tags are as follows:

• ejb-relationshiprole-name This optional element is used to identify the role and match the database mapping the jbosscmp-jdbc.xml file. The name cannot be the same as the related role.
• multiplicity This required element must be "One" or "Many". Note, as with all XML elements, this element is case-sensitive.
• cascade-delete When this optional element is present, JBossCMP will delete the child entity when the parent entity is deleted. Cascade deletion is only allowed for a role where the other side of the relationship has a multiplicity of one. The default is to not cascade delete.
• relationship-role-source/ejb-name This required element gives the name of the entity that has the role.
• cmr-field/cmr-field-name This is the name of the cmr-field of the entity has one, if entity has a cmrfield abstract accessor.
• cmr-field/cmr-field-type This is the type of the cmr-field. Must be java.util.Collection or java.util.Set . Only required if cmr-field abstract accessor is collection valued

After adding the cmr-field abstract accessors and declaring the relationship, the relationship should be functional. For more information on relationships, see section 10.3 of the EJB 2.0 specification. The next section discusses the database mapping of the relationship.

FIGURE 11-7. The jbosscmp-jdbc.xml ejb-relation element content model

The basic template of the relationship mapping declaration for Organization-Gangster follows:

The jbosscmp-jdbc.xml Relationship Mapping Template

<jbosscmp-jdbc>

<relationships>

<ejb-relation>

<ejb-relation-name>Organization-Gangster</ejb-relation-name>

<foreign-key-mapping/>

<ejb-relationship-role>

<ejb-relationship-role-name>org-has-gangsters

</ejb-relationship-role-name>

<key-fields>

<key-field>

<field-name>name</field-name>

<column-name>organization</column-name>

</key-field>

</key-fields>

</ejb-relationship-role>

<ejb-relationship-role>

<ejb-relationship-role-name>gangster-belongs-to-org

</ejb-relationship-role-name>

<key-fields/>

</ejb-relationship-role>

</ejb-relation>

</relationships>

</jbosscmp-jdbc>

After the ejb-relation-name of the relationship being mapped is declared, the mapping style is declared using a foreign-key-mapping element or a relation-table-mapping element, both of which are discussed in the next two sections. The read-only and read-time-out elements have the same semantics they did in the entity element. The ejb-relationship-role elements are optional, but if one is declared, the other must also be declared. A detailed description of the elements contained in the ejb-relationship-role element follows:

• ejb-relation This required element gives the name of the relationship that is being configured. This element must match the name of a relationship declared in the ejb-jar.xml file.
• read-only This optional element if true indicates that the bean provider will not be allowed to change the value of this relationship. A relationship that is read-only will not be stored in, or inserted into, the database. If a set accessor is called on a read-only relationship, it throws an EJBException.
• read-time-out This optional element gives the amount of time in milliseconds that a read on a read-only relationship 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. If read-only is false, this value is ignored.

The ejb-relation element must contain either a foreign-key-mapping element or a relation-table-mapping element, which are described in the foreign key mapping and relation-table mapping sections respectively. This element may also contain a pair of ejb-relationship-role elements as described in the following section.

Relationship Role Mapping

Each of the two ejb-relationship-role elements contains mapping information specific to an entity in the relationship, and the content model of the ejb-relationship-role element is shown in See The jbosscmp-jdbc ejb-relationship-role element content model..

Sample jboss.xml fragment illustrating insert-after-ejb-post-create

<jboss>

...

<container-configurations>

<container-configuration extends="Standard CMP 2.x EntityBean">

<container-name>INSERT after ejbPostCreate Container</container-name>

<insert-after-ejb-post-create>true</insert-after-ejb-post-create>

</container-configuration>

</container-configurations>

 

</jboss>

An alternate means of working around the non-null foreign key issue is to map the foreign key elements onto non-null cmp fields. In this case you simply populate the foreign key fields in ejbCreate using the associated cmp field setters.

The content model of the key-fields element is shown in See The jbosscmp-jdbc key-fields element content model..

 

Foreign Key Mapping

Foreign key mapping is the most common mapping style for one-to-one and one-to-many relationships, but is not allowed for many-to many relationships. The foreign key mapping element is simply declared by adding an empty foreign key-mapping element to the ejb-relation element.

As noted in the previous section, with a foreign key mapping the key-fields declared in the ejb-relationship-role are added to the table of the related entity. If the key-fields element is empty, a foreign key will not be created for the entity. In a one-to-many relationship, the many side (Gangster in the example) must have an empty key-fields element, and the one side (Organization in the example) must have a key-fields mapping. In one-to-one relationships, one or both roles can have foreign keys.

The foreign key mapping is not dependent on the direction of the relationship. This means that in a one-to-one unidirectional relationship (only one side has an accessor) one or both roles can still have foreign keys. The complete foreign key mapping for the Organization-Gangster relationship is shown in See The jbosscmp-jdbc.xml Foreign Key Mapping. with the foreign key elements highlighted in bold:

Relation-table Mapping

Relation table mapping is less common for one-to-one and one-to-many relationships, but is the only mapping style allowed for many-to-many relationships. Relation table mapping is defined using the relation-table-mapping element, the content model of which is shown in See The jbosscmp-jdbc relation-table-mapping element content model..

Finder Declaration

public interface GangsterHome extends EJBLocalHome {

Collection findBadDudes_ejbql(int badness) throws FinderException;

}

The ejbSelect methods are declared in the entity implementation class, and must be public abstract just like cmp-field and cmr-field abstract accessors. Select methods must be declared to throw a FinderException, but not a RemoteException. The following code declares an ejbSelect method:

ejbSelect Declaration

public abstract class GangsterBean implements EntityBean {

public abstract Set ejbSelectBoss_ejbql(String name)

throws FinderException;

}

A sample ejb-jar.xml Query Declaration

<ejb-jar>

<enterprise-beans>

<entity>

<ejb-name>GangsterEJB</ejb-name>

...

<query>

<query-method>

<method-name>findBadDudes_ejbql</method-name>

<method-params>

<method-param>int</method-param>

</method-params>

</query-method>

<ejb-ql><![CDATA[

SELECT OBJECT(g)

FROM gangster g

WHERE g.badness > ?1

]]></ejb-ql>

</query>

<query>

<query-method>

<method-name>ejbSelectBoss_ejbql</method-name>

<method-params>

<method-param>java.lang.String</method-param>

</method-params>

</query-method>

<ejb-ql><![CDATA[

SELECT DISTINCT underling.organization.theBoss

FROM gangster underling

WHERE underling.name = ?1 OR underling.nickName = ?1

]]></ejb-ql>

</query>

</entity>

</enterprise-beans>

</ejb-jar>

EJB-QL is similar to SQL but has some surprising differences. The following are some important things to note about EJB-QL:

• EJB-QL is a typed language, meaning that it only allows comparison of like types (i.e., strings can only be compared with strings).
• In an equals comparison a variable (single valued path) must be on the left hand side. Some examples follow:11

g.hangout.state = 'CA' Legal

'CA' = g.shippingAddress.state NOT Legal

'CA' = 'CA' NOT Legal

(r.amountPaid * .01) > 300 NOT Legal

r.amountPaid > (300 / .01) Legal

• Parameters use a base 1 index like java.sql.PreparedStatement.
• Parameters are only allowed on the right hand side of a comparison. For example:

gangster.hangout.state = ?1 Legal

?1 = gangster.hangout.state NOT Legal

FIGURE 11-11. The jbosscmp-jdbc query element content model

• description An optional description for the query.
• query-method This required element specifies the query method that being configured. This must match a query-method declared for this entity in the ejb-jar.xml file.
• jboss-ql, dynamic-ql, declared-sql These elements are alternate ways to specify the query method and each is discussed in its own section.
• read-ahead This optional element allows one to optimize the loading of additional fields for use with the entities referenced by the query. This is discussed in detail in Optimized Loading.

The jbosscmp-jdbc.xml JBossQL Override

<jbosscmp-jdbc>

<enterprise-beans>

<entity>

<ejb-name>GangsterEJB</ejb-name>

<query>

<query-method>

<method-name>findBadDudes_jbossql</method-name>

<method-params>

<method-param>int</method-param>

</method-params>

</query-method>

<jboss-ql><![CDATA[

SELECT OBJECT(g)

FROM gangster g

WHERE g.badness > ?1

ORDER BY g.badness DESC

]]></jboss-ql>

</query>

</entity>

</enterprise-beans>

</ejb-jar>

JBossQL SQL Mapping

SELECT t0_g.id

FROM gangster t0_g

WHERE t0_g.badness > ?

ORDER BY t0_g.badness DESC

Another capability of JBossQL is the ability to retrieve finder results in blocks using the LIMIT and OFFSET functions. For example, to iterate through the large number of jobs performed, the following findManyJobs_jbossql finder may be defined.

A sample jboss-ql finder using LIMIT and OFFSET

<jbosscmp-jdbc>

<enterprise-beans>

<entity>

<ejb-name>GangsterEJB</ejb-name>

<query>

<query-method>

<method-name>findManyJobs_jbossql</method-name>

<method-params>

<method-param>int</method-param>

</method-params>

<method-params>

<method-param>int</method-param>

</method-params>

</query-method>

<jboss-ql><![CDATA[

SELECT OBJECT(j)

FROM jobs j

OFFSET ?1 LIMIT ?2

]]></jboss-ql>

</query>

</entity>

</enterprise-beans>

</ejb-jar>

DynamicQL

DynamicQL allows the runtime generation and execution of JBossQL queries. A DynamicQL query method is an abstract method that takes a JBossQL query and the query arguments as parameters. JBossCMP compiles the JBossQL and executes the generated SQL. The following generates a JBossQL query that selects all the gangsters that have a hangout in any state in the states set:

DeclaredSQL

DeclaredSQL is based on the legacy JAWS CMP 1.1 engine finder declaration, but has been updated for CMP 2.0. Commonly this declaration is used to limit a query with a WHERE clause that cannot be represented in EJB-QL or JBossQL. The content model for the declared-sql element is given in See The jbosscmp-jdbc declared-sql element content model...

BMP Custom Finders

JBossCMP continues the tradition of JAWS in supporting bean managed persistence custom finders. If a custom finder matches a finder declared in the home or local home interface, JBossCMP will always call the custom finder over any other implementation declared in the ejb-jar.xml or jbosscmp-jdbc.xml files. The following simple example finds the entities by a collection of primary keys:12

Loading Scenario Example Code

1. public String createGangsterHtmlTable_none() throws FinderException {
2. StringBuffer table = new StringBuffer();
3. table.append("<table>");
5. Collection gangsters = gangsterHome.findAll_none();
6. for(Iterator iter = gangsters.iterator(); iter.hasNext(); )
7. {
8. Gangster gangster = (Gangster)iter.next();
9. table.append("<tr>");
10. table.append("<td>").append(gangster.getName());
11. table.append("</td>");
12. table.append("<td>").append(gangster.getNickName());
13. table.append("</td>");
14. table.append("<td>").append(gangster.getBadness());
15. table.append("</td>");
16. table.append("</tr>");
17. }
18. return table.toString();
19. }

Assume this code is called within a single transaction and all optimized loading has been disabled. At line 5, JBossCMP will execute the following query:

Unoptimized findAll Query

SELECT t0_g.id

FROM gangster t0_g

ORDER BY t0_g.id ASC

Then at line 8, in order to load the eight Gangsters in the sample database, JBossCMP executes the following eight queries:

Unoptimized Load Queries

SELECT name, nick_name, badness, hangout, organization

FROM gangster WHERE (id=0)

SELECT name, nick_name, badness, hangout, organization

FROM gangster WHERE (id=1)

SELECT name, nick_name, badness, hangout, organization

FROM gangster WHERE (id=2)

SELECT name, nick_name, badness, hangout, organization

FROM gangster WHERE (id=3)

SELECT name, nick_name, badness, hangout, organization

FROM gangster WHERE (id=4)

SELECT name, nick_name, badness, hangout, organization

FROM gangster WHERE (id=5)

SELECT name, nick_name, badness, hangout, organization

FROM gangster WHERE (id=6)

SELECT name, nick_name, badness, hangout, organization

FROM gangster WHERE (id=7)

There are two problems with this scenario. First, an excessive number of queries are executed because JBossCMP executes one query for findAll and one query for each element found. This is known as the "n+1" problem13 and is addressed with the read-ahead strategies described in the following sections. Second, values of unused fields are loaded because JBossCMP loads the hangout and organization fields,14 which are never accessed. Configuration of eager loading is described in Eager-loading Process. The following table shows the execution of the queries:

The jbosscmp-jdbc.xml Load Group Declaration

<jbosscmp-jdbc>

<enterprise-beans>

<entity>

<ejb-name>GangsterEJB</ejb-name>

...

<load-groups>

<load-group>

<load-group-name>basic</load-group-name>

<field-name>name</field-name>

<field-name>nickName</field-name>

<field-name>badness</field-name>

</load-group>

<load-group>

<load-group-name>contact info</load-group-name>

<field-name>nickName</field-name>

<field-name>contactInfo</field-name>

<field-name>hangout</field-name>

</load-group>

</load-groups>

</entity>

</enterprise-beans>

</jbosscmp-jdbc>

In See The jbosscmp-jdbc.xml Load Group Declaration., two load groups are declared: basic and contact info. Note that the load groups do not need to be mutually exclusive. For example, both of the load groups contain the nickName field. In addition to the declared load groups, JBossCMP automatically adds a group named "*" (the star group) that contains every cmp-field and cmr-field with a foreign key in the entity.

on-find

The on-find strategy reads additional columns when the query is invoked. If the query in the scenario detailed in See Loading Scenario Example Code. is on-find optimized, JBossCMP will execute the following query at line 5:

on-load

The on-load strategy block loads additional data for several entities when an entity is loaded, starting with the requested entity and the next several entities in the order they were selected.16 This strategy is based on the theory that the results of a find or ejbSelect will be accessed in forward order. When a query is executed, JBossCMP stores the order of the entities found in the list cache. Later, when one of the entities is loaded, JBossCMP uses this list to determine the block of entities to load. The number of lists stored in the cache is specified with the list-cachemax element of the entity. This strategy is also used when faulting in data not loaded in the on-find strategy. With this strategy, the query executed at line 5 of See Loading Scenario Example Code. remains unchanged.

none

The none strategy is really an anti-strategy. This strategy causes the system to fall back to the default lazy-load code, and specifically does not read-ahead any data or remember the order of the found entities. This results in the queries and performance shown at the beginning of this chapter. The none strategy is declared with a read-ahead element. If the read-ahead element contains a page-size element or eager-load-group, it is ignored. The none strategy is declared in See The jbosscmp-jdbc.xml none Declaration.:

Commit Options

Central to the loading process are the commit options, which control when the data for an entity expires. JBoss supports four commit options A, B, C and D. The first three are described in section 10.5.9 of the Enterprise JavaBeans Specification Version 2.0 Final Release and the forth, D, is specific to JBoss. A detailed description of each commit option follows:

• A: JBossCMP assumes it is the sole user of the database; therefore, JBossCMP can cache the current value of an entity between transactions, which can result is substantial performance gains. As a result of this assumption, no data managed by JBossCMP can be changed outside of JBossCMP. For example, changing data in another program or with the use of direct JDBC (even within JBoss) will result in an inconsistent database state.
• B: JBossCMP assumes that there is more than one user of the database but keeps the context information about entities between transactions. This context information is used for optimizing loading of the entity. 20 This is the default commit option.
• C: JBossCMP discards all entity context information at the end of the transaction.
• D: This is a JBoss specific commit option. This option is similar to commit option A, except that the data only remains valid for a specified amount of time.

The commit option is declared in the jboss.xml file. For a detailed description of this file see Chapter 5. The following example changes the commit option to A for all entity beans in the application:

Eager-loading Process

One of the most important changes in CMP 2.0 is the change from using class fields for cmp-fields to abstract accessor methods. In CMP 1.x, the container could not know which fields were required in a transaction, so the container had to eager-load every field when loading the17 bean. In CMP 2.x, the container creates the implementation for the abstract accessors, so the container can know when the data for a field is required. JBossCMP can be configured to eager-load only some of the fields when loading an entity, and later lazy-load the remaining fields as needed.

When an entity is loaded, JBossCMP must determine the fields that need to be loaded. By default, JBossCMP will use the eager-load-group of the last query that selected this entity. If the entity has not been selected in a query, or the last query used the none read-ahead strategy, JBossCMP uses the default eager-load-group declared for the entity. In the See The jbosscmp-jdbc.xml Eager Load Declaration. configuration, the basic load group is set as the default eager-load-group for the GangsterEJB entity:

Lazy-loading Process

Lazy-loading is the other half of eager-loading. If a field is not eager-loaded, it must be lazy-loaded. When the bean accesses an unloaded field, JBossCMP loads the field and any field in a lazy-load-group of which the unloaded field is a member. JBossCMP performs a set join and then removes any field that is already loaded. An example configuration is shown in See The jbosscmp-jdbc.xml Lazy Load Group Declaration.:

No Transaction Loading Example Code

1. public String createGangsterHtmlTable_no_tx() throws FinderException
2. {
3. StringBuffer table = new StringBuffer();
4. table.append("<table>");
6. Collection gangsters = gangsterHome.findFour();
7. for(Iterator iter = gangsters.iterator(); iter.hasNext(); )
8. {
9. Gangster gangster = (Gangster)iter.next();
10. table.append("<tr>");
11. table.append("<td>").append(gangster.getName());
12. table.append("</td>");
13. table.append("<td>").append(gangster.getNickName());
14. table.append("</td>");
15. table.append("<td>").append(gangster.getBadness());
16. table.append("</td>");
17. table.append("</tr>");
18. }
19.  
20. table.append("</table>");
21. return table.toString();
22. }

The query executed at line 53 is shown in See No Transaction on-find Optimized findAll Query.:

No Transaction on-find Optimized findAll Query

SELECT t0_g.id, t0_g.name, t0_g.nick_name, t0_g.badness

FROM gangster t0_g

WHERE t0_g.id < 4

ORDER BY t0_g.id ASC

Normally this would be the only query executed, but since this code is not running in a transaction, all of the preloaded data is thrown away as soon as findAll returns. Then at line 56 JBossCMP executes the following four queries (one for each loop):18

No Transaction on-load Optimized Load Queries

SELECT id, name, nick_name, badness

FROM gangster

WHERE (id=0) OR (id=1) OR (id=2) OR (id=3)

SELECT id, name, nick_name, badness

FROM gangster

WHERE (id=1) OR (id=2) OR (id=3)

SELECT id, name, nick_name, badness

FROM gangster

WHERE (id=2) OR (id=3)

SELECT name, nick_name, badness

FROM gangster

WHERE (id=3)

See No Transaction on-find optimized query execution. shows the execution of the queries:

FIGURE 11-13. No Transaction on-find optimized query execution

This performance is much worse than read-ahead none because of the amount of data loaded from the database. The number of rows loaded is determined by the following equation:

This all happens because the transaction in the example is bounded by a single call on the entity. This brings up the important question "How do I run my code in a transaction?" The answer depends on where the code runs. If it runs in an EJB (session, entity, or message driven), the method must be marked with the Required or RequiresNew trans-attribute in the assembly-descriptor. If the code is not running in an EJB, a user transaction is necessary. The following code wraps a call to the method declared in See User Transaction Example Code. with a user transaction:

User Transaction Example Code

public String createGangsterHtmlTable_with_tx()

throws FinderException

{

UserTransaction tx = null;

try

{

InitialContext ctx = new InitialContext();

tx = (UserTransaction) ctx.lookup("UserTransaction");

tx.begin();

String table = createGangsterHtmlTable_no_tx();

if (tx.getStatus() == Status.STATUS_ACTIVE)

{

tx.commit();

}

return table;

}

catch (Exception e)

{

try

{

if (tx != null) tx.rollback();

}

catch (SystemException unused)

{

// eat the exception we are exceptioning out anyway

}

if (e instanceof FinderException)

{

throw (FinderException) e;

}

if (e instanceof RuntimeException)

{

throw (RuntimeException) e;

}

throw new EJBException(e);

}

}

A sample autogenerated key config for a known pk cmp-field

<jbosscmp-jdbc>

<enterprise-beans>

<entity>

<ejb-name>LocationEJB</ejb-name>

<pk-constraint>false</pk-constraint>

<table-name>location</table-name>

<cmp-field>

<field-name>locationID</field-name>

<column-name>id</column-name>

<auto-increment/>

</cmp-field>

...

<entity-command name="hsqldb-fetch-key"/>

</entity>

</enterprise-beans>

</jbosscmp-jdbc>

An alternate example using an unknown primary key without an explicit cmp-field is shown in See A sample autogenerated key config for an uknown-pk..

A sample autogenerated key config for an uknown-pk

<jbosscmp-jdbc>

<enterprise-beans>

<entity>

<ejb-name>LocationEJB</ejb-name>

<pk-constraint>false</pk-constraint>

<table-name>location</table-name>

<unknown-pk>

<unknown-pk-class>java.lang.Integer</unknown-pk-class>

<field-name>locationID</field-name>

<column-name>id</column-name>

<jdbc-type>INTEGER</jdbc-type>

<sql-type>INTEGER</sql-type>

<auto-increment/>

</unknown-pk>

...

<entity-command name="hsqldb-fetch-key"/>

</entity>

</enterprise-beans>

</jbosscmp-jdbc>

FIGURE 11-18. The jbosscmp-jdbc function-mapping element content model

• function-name: This required element gives the EJB-QL function name, e.g., concat, substring.
• function-sql: This required element gives the SQL for the function as appropriate for the underlying database. Examples for a concat function include: "(?1 || ?2)", "concat(?1, ?2)", "(?1 + ?2)".

FIGURE 11-19. The jbosscmp-jdbc mapping element content model.

If JBossCMP cannot find a mapping for a type, it will serialize the object and use the java.lang.Object mapping. The following describes the three child elements of the mapping element:

• java-type: This required element gives the fully qualified name of the Java class to be mapped. If the class is a primitive wrapper class such as java.lang.Short , the mapping also applies to the primitive type.
• jdbc-type: This required element gives the JDBC type that is used when setting parameters in a JDBC PreparedStatement or loading data from a JDBC ResultSet . The valid types are defined in java.sql.Types .
• sql-type: This required element gives the SQL type that is used in create table statements. Valid sql-types are only limited by your database vendor.

An example mapping element for a short in Oracle9i is shown in See A sample short mapping for Oracle9i.

A sample short mapping for Oracle9i

<jbosscmp-jdbc>

<type-mappings>

<type-mapping>

<name>Oracle9i</name>

...

<mapping>

<java-type>java.lang.Short</java-type>

<jdbc-type>NUMERIC</jdbc-type>

<sql-type>NUMBER(5)</sql-type>

</mapping>

</type-mapping>

</type-mappings>

</jbosscmp-jdbc>

The org.jboss.ejb.plugins.cmp.jdbc.Mapper interface

public interface Mapper

{

/** This method is called when CMP field is stored.

* @param fieldValue - CMP field value

* @return column value.

*/

Object toColumnValue(Object fieldValue);

/** This method is called when CMP field is loaded.

* @param columnValue - loaded column value.

* @return CMP field value.

*/

Object toFieldValue(Object columnValue);

}

A prototypical use case is the mapping of an integer type to its type-safe Java enum instance. The content model of the user-type-mappings element consists of one or more user-type-mapping elements, the content model of which is shown in See The user-type-mapping content model..

FIGURE 11-20. The user-type-mapping content model

• java-type: the fully qualified name of the cmp field type in the mapping.
• mapped-type: the fully qualified name of the database type in the mapping.
• mapper: the fully qualified name of the Mapper interface implementation that handles the conversion between the java-type and mapped-type.