31.8.2. Eager-loading Process

When an entity is loaded, JBoss must determine the fields that need to be loaded. By default, JBoss 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, JBoss will use the default eager-load-group declared for the entity. In the following example configuration, the basic load group is set as the default eager-load-group for the gangster entity bean:
<jbosscmp-jdbc>
    <enterprise-beans>
        <entity>
            <ejb-name>GangsterEJB</ejb-name>
            <!-- ... -->
            <load-groups>
                <load-group>
                    <load-group-name>most</load-group-name>
                    <field-name>name</field-name>
                    <field-name>nickName</field-name>
                    <field-name>badness</field-name>
                    <field-name>hangout</field-name>
                    <field-name>organization</field-name>
                </load-group>
            </load-groups>
            <eager-load-group>most</eager-load-group>
        </entity>
    </enterprise-beans>
</jbosscmp-jdbc>
The eager loading process is initiated the first time a method is called on an entity in a transaction. A detailed description of the load process follows:
  1. If the entity context is still valid, no loading is necessary, and therefore the loading process is done. The entity context will be valid when using commit option A, or when using commit option D, and the data has not timed out.
  2. Any residual data in the entity context is flushed. This assures that old data does not bleed into the new load.
  3. The primary key value is injected back into the primary key fields. The primary key object is actually independent of the fields and needs to be reloaded after the flush in step 2.
  4. All data in the preload cache for this entity is loaded into the fields.
  5. JBoss determines the additional fields that still need to be loaded. Normally the fields to load are determined by the eager-load group of the entity, but can be overridden if the entity was located using a query or CMR field with an on-find or on-load read ahead strategy. If all of the fields have already been loaded, the load process skips to step 7.
  6. A query is executed to select the necessary column. If this entity is using the on-load strategy, a page of data is loaded as described in Section 31.7.3.2, “on-load”. The data for the current entity is stored in the context and the data for the other entities is stored in the preload cache.
  7. The ejbLoad method of the entity is called.