Container-Managed Persistence Service: Advanced Features

 

 

Read-Only Multicast Invalidation

Read-only multicast invalidation is an efficient means of invalidating cached data.

Invalidate a read-only entity bean by calling the following invalidate() method on either the CachingHome or CachingLocalHome interface:Figure 6-1 Sample code showing CachingHome and CachingLocalHome interfaces

package weblogic.ejb;

public interface CachingHome {

 public void invalidate(Object pk) throws RemoteException;



 public void invalidate (Collection pks) throws RemoteException;



 public void invalidateAll() throws RemoteException;

public interface CachingLocalHome {

 public void invalidate(Object pk) throws RemoteException;



 public void invalidate (Collection pks) throws RemoteException;



 public void invalidateAll() throws RemoteException

}

The following example codes shows how to cast the home to CachingHome and then call the method:Figure 6-2 Sample code showing how to cast the home and call the method

import javax.naming.InitialContext ; 



import weblogic.ejb.CachingHome;

Context initial = new InitialContext(); 



Object o = initial.lookup("CustomerEJB_CustomerHome"); 



CustomerHome customerHome = (CustomerHome)o;

CachingHome customerCaching = (CachingHome)customerHome; 



customerCaching.invalidateAll();

When the invalidate() method is called, the read-only entity beans are invalidated in the local server, and a multicast message is sent to the other servers in the cluster to invalidate their cached copies. The next call to an invalidated read-only entity bean causes ejbLoad to be called. ejbLoad() reads the most current version of the persistent data from the underlying datastore

WebLogic Server calls the invalidate() method after the transaction update has completed. If the invalidation occurs during a transaction update, the previous version may be read if the isolation level does not permit reading uncommitted data.

 

 

Read-Mostly Pattern

WebLogic Server does not support a read-mostly cache strategy setting in weblogic-ejb-jar.xml. However, if you have EJB data that is only occasionally updated, you can create a "read-mostly pattern" by implementing a combination of read-only and read-write EJBs.

WebLogic Server provides an automatic invalidate() method for the Read-Mostly pattern. With this pattern, Read-Only entity bean and a Read-Write entity bean are mapped to the same data. To read the data, you use the Read-Only entity bean; to update the data, you use the Read-Write entity bean.

In a read-mostly pattern, a read-only entity EJB retrieves bean data at intervals specified by the read-timeout-seconds deployment descriptor element specified in the weblogic-ejb-jar.xml file. A separate read-write entity EJB models the same data as the read-only EJB, and updates the data at required intervals.

When creating a read-mostly pattern, use the following suggestions to reduce data consistency problems:

• For all read-only EJBs, set read-timeout-seconds to the same value for all beans that may be updated in the same transaction.
• For all read-only EJBs, set read-timeout-seconds to the smallest timeframe that yields acceptable performance levels.
• Ensure that all read-write EJBs in the system update only the smallest portion of data necessary; avoid beans that write numerous, unchanged fields to the datastore at each ejbStore().
• Ensure that all read-write EJBs update their data in a timely fashion; avoid involving read-write beans in long-running transactions that may span the read-timeout-seconds setting for their read-only counterparts.

  You can accomplish the same thing using optimistic concurrency functionality.

In a WebLogic Server cluster, clients of the read-only EJB benefit from using cached EJB data. Clients of the read-write EJB benefit from true transactional behavior, because the read-write EJB's state always matches the state of its data in the underlying datastore.

 

 

Relationship Caching with Entity Beans

Relationship caching improves the performance of entity beans by loading related beans into the cache and avoiding multiple queries by issuing a join query for the related bean. Consider this example:

Suppose your application contains entity beans with the following relationships:

customerBean	has a one-to-many relationship with	accountBean
accountBean	has a one-to-one relationship with	addressBean
customerBean	has a one-to-one relationship with	phoneBean

Consider the following EJB code for accountBean and addressBean, which have a 1-to-1 relationship:

Account acct = acctHome.findByPrimaryKey("103243"); 



Address addr = acct.getAddress(); 

Without relationship caching, a SQL query is issued by the first line of code to load the accountBean and another SQL query is issued by the second line of code to load the addressBean; this results in two queries to the database.

With relationship caching, a single query is issued to load both the AccountEJB and AddressEJB by the first line of code, which should result in better performance. So, if you know that a related bean will be accessed after executing a particular finder method, its a good idea to let the finder method know via the relationship caching feature.

 

 

Specifying Relationship Caching

To specify relationship caching :, set the relationship-caching deployment descriptor element in the bean's weblogic-cmp-rdbms-jar.xml file.

The following XML example code shows how to specify relationship-caching :

<relationship-caching>



 <caching-name>cacheMoreBeans</caching-name>



 <caching-element>


<cmr-field>accounts<</cmr-field>


<group-name>acct_group</group-name>


<caching-element>


 <cmr-field>address</cmr-field>


 <group-name>addr_group</group-name>


</caching-element>



 </caching-element>

 <caching-element>


<cmr-field>phone</cmr-field>


<group-name>phone_group</group-name>



 </caching-element>



</relationship-caching>

The accounts and phone fields are container-managed relationship (CMR) fields in the customerBean table; the address field is a cmr field in the accountBean table; and the addr_group and phone_group are groups in the addressBean and phoneBean.

Using nested caching-element deployment descriptors enables the bean to load more than one level of related beans. In the above sample XML code, addressBean is the second level related bean because it is nested in the accountBean. Currently, there is no limitation on the number of caching-elements that you can specify. However, setting too many caching-element levels could have an impact on the performance of the current transaction.

 

 

Enabling Relationship Caching

To enable relationship caching :

1. Specify a caching-name deployment descriptor element in the weblogic-query element of the weblogic-cmp-rdbms-jar.xml file.

   If a caching-name element is specified in a weblogic-query XML element, when the finder query is executed, WebLogic Server loads the related accountBean and phoneBean as well as the account's addressBeans into the cache.

2. Make sure that the finder-load-bean element, specified in the weblogic-ejb-jar.xml file, in the bean that specifies an relationship (for example, customerBean in the above sample XML code) is not set to False or relationship caching will not be enabled. The finder-load-bean element's default is True.
3. Specify a database-type deployment descriptor element in the bean's weblogic-cmp-rdbms-jar.xml file. This is because relationship caching uses outer joins for queries and outer joins don't have standard syntax for all databases.

Since relationship caching uses join queries, and a join query might duplicate results for a table in the ResultSet, the number of caching-element deployment descriptors specified in the relationship-caching element will have a direct impact on the number of duplicate results in the ResultSet. For one-to-many relationships, do not specify too many caching-element deployment descriptors in the relationship-caching element because the number of duplicate results might multiply for each caching-element deployment descriptor

The relationship-caching deployment descriptor element is specified in the weblogic-cmp-rdbms-jar.xml file

 

 

Relationship Caching Limitations

The relationship caching feature has the following limitations:

1. Relationship caching only works with one-to-one and one-to-many relationships.
2. When using weblogic-ql, this feature only works with finder methods that return references to either EJBObject or EJBLocalObject beans.
3. If you enable relationship caching for a finder or a select method, the result of the query will always be a distinct set even if the distinct keyword is not specified. This is because there is no way to identify the duplicate in the ResultSet is the result of the original data or the result of the outer join.

 

 

Combined Caching with Entity Beans

Combined caching allows multiple entity beans that are part of the same J2EE application to share a single runtime cache. Previously, you had to configure a separate cache for each entity bean that was part of an application. This caused some usability and performance problems in that it took more time to configure caches for each entity bean and more memory to run the application. This feature will help solve those problems.

To configure an application-level cache:

1. Verify that the weblogic-application.xml file is located in the META-INF directory of the EAR file.
2. Provide an entry in the weblogic-application. xml file as follows:

   
   <weblogic-application>
   
   
   
    <ejb>
   
   
   <entity-cache>
   
   
    <entity-cache-name>large_account</entity-cache-name>
   
   
    <max-cache-size>
   
   
     <megabytes>1</megabytes>
   
   
    </max-cache-size>
   
   
   </entity-cache>
   
   
   
    </ejb>
   
   
   
   </weblogic_application>
   

   Use the entity-cache element to define a named application level cache that will be used to cache entity bean instances at runtime. There are no restrictions on the number of different entity beans that may reference an individual cache.

   The sub elements of entity-cache have the same basic meaning as they do in the weblogic-ejb-jar.xml deployment descriptor file.

3. Specify an entity-descriptor element in weblogic-ejb-jar.xml file.

   Use the entity-descriptor element to configure an entity bean to use an application level cache.

The weblogic-application.xml deployment descriptor is documented in full in the Application.xml Deployment Descriptor Elements" section of Developing WebLogic Server Applications.

 

 

Caching Between Transactions

Use caching between transactions or long tern caching to enable the EJB container to cache an entity bean's persistent data between transactions. You can enable caching between transactions if the entity bean's concurrency strategy is set to either Exclusive, ReadOnly, or Optimistic.

 

 

Caching Between Transactions with Exclusive Concurrency

When you enable long term caching for an entity bean with an Exclusive concurrency strategy the EJB container must have exclusive update access to the underlying data. This means that another application outside of the EJB container must not be updating the data. If you deploy an EJB with an Exclusive concurrency strategy in a cluster, long term caching is disabled automatically because any node in the cluster may update the data. This would make long term caching impossible.

In previous versions of WebLogic Server, this feature was controlled by the db-is-shared element of weblogic-ejb-jar.xml.

Note: Exclusive concurrency is a single-server feature. Do not attempt to use it with clustered servers.

 

 

Caching Between Transactions with ReadOnly Concurrency

When you disable long term caching for an entity bean with a ReadOnly concurrency strategy it ignores the value of the caching-between-transactions setting because the EJB container always performs long term caching of read-only data.

 

 

Caching Between Transactions with Optimistic Concurrency

When you enable long term caching for an entity bean with an Optimistic concurrency strategy the EJB container reuses the cached values from previous transactions. The container ensures that the updates are transactionally consistent by checking for optimistic conflicts at the end of the transaction.

In addition, notifications for updates of optimistic data are broadcast to other cluster members to help avoid optimistic conflicts.

 

 

Enabling Caching Between Transactions

To enable caching between transactions :

1. Set the caching-between-transactions element in the weblogic-ejb-jar.xml file by choosing one of the following options:
   • Specify True to enable the EJB container performs long term caching of the data.
   • Specify False to enable the EJB container performs short caching of the data. This is the default setting.

 

 

Using cache-between-transactions to Limit Calls to ejbLoad()

WebLogic Server's default behavior of calling ejbLoad() at the start of each transaction works well for environments where multiple sources may update the datastore. Because multiple clients (including WebLogic Server) may be modifying an EJB's underlying data, an initial call to ejbLoad() notifies the bean that it needs to refresh its cached data and ensures that it works against the most current version of the data.

In the special circumstance where only a single WebLogic Server transaction ever accesses a particular EJB concurrently, such as when you use exclusive concurrency for a single server; not a cluster, calling ejbLoad() by default is unnecessary. Because no other clients or systems update the EJB's underlying data, WebLogic Server's cached version of the EJB data is always up-to-date. Calling ejbLoad() in this case simply creates extra overhead for WebLogic Server clients that access the bean.

To avoid unnecessary calls to ejbLoad() in the case of a single WebLogic Server transaction accessing a particular EJB, WebLogic Server provides the cache-between-transactions deployment parameter. By default, cache-between-transactions is set to "false" for each EJB in the bean's weblogic-ejb-jar.xml file, which ensures that ejbLoad() is called at the start of each transaction. Where only a single WebLogic Server transaction ever accesses an EJB's underlying data concurrently, you can set d to "true" in the bean's weblogic-ejb-jar.xml file. When you deploy an EJB with cache-between-transactions set to "true," the single instance of WebLogic Server calls ejbLoad() for the bean only when:

• A client first references the EJB
• The EJB's transaction is rolled back

 

 

Restrictions and Warnings for cache-between-transactions

Setting cache-between-transactions to "true" overrides WebLogic Server's default ejbLoad() container-managed-persistence (behavior, regardless of whether the EJB's underlying data is updated by one WebLogic Server instance or multiple clients. If you incorrectly set cache-between-transactions to "true" and multiple clients (database clients, other WebLogic Server instances, and so forth) update the bean data, you run the risk of losing data integrity.

Do not set cache-between-transactions to "true" if you set the entity bean's concurrency strategy to the "Database" option. Weblogic Server ignores this setting because with database concurrency specified, the EJB container continues to cache instances of entity bean classes. However, the container does not cache the state of the EJB instance between transactions. Instead, WebLogic Server calls ejbLoad() for each instance at the beginning of a transaction to obtain the latest EJB data. This means that setting cache-between-transactions to "true" which prevents WebLogic Server from calling ejbload() at the beginning of each transaction is invalid.

Also, due to the limitations of exclusive concurrency, you cannot set cache-between-transactions to "true" in a WebLogic Server cluster when using exclusive concurrency. However, you can set this element to true when using either optimistic or readonly concurrency.

 

 

ejbLoad() and ejbStore() Behavior for Entity EJBs

WebLogic Server reads and writes the persistent fields of entity EJBs using calls to ejbLoad() and ejbStore(). By default, WebLogic Server calls ejbLoad() and ejbStore() in the following manner:

1. A transaction is initiated for the entity EJB. The client may explicitly initiate a new transaction and invoke the bean, or WebLogic Server may initiate a new transaction in accordance with the bean's method transaction attributes.
2. WebLogic Server calls ejbLoad() to read the most current version of the bean's persistent data from the underlying datastore.
3. When the transaction commits, WebLogic Server calls ejbStore() to write persistent fields back to the underlying datastore.

This simple process of calling ejbLoad() and ejbStore() ensures that new transactions always use the latest version of the EJB's persistent data, and always write the data back to the datastore upon committing. In certain circumstances, however, you may want to limit calls to ejbLoad() and ejbStore() for performance reasons. Alternately, you may want to call ejbStore() more frequently to view the intermediate results of uncommitted transactions.

WebLogic Server provides several deployment descriptor elements in the weblogic-ejb-jar.xml and weblogic-cmp-rdbms-jar.xml files that enable you to configure ejbLoad() and ejbStore() behavior. The following sections discuss these elements.

 

 

Warning for is-modified-method-name

Using the is-modified-method-name element can improve performance by avoiding unnecessary calls to ejbStore(). However, it places a greater burden on the EJB developer to identify correctly when updates have occurred. If the specified is-modified-method-name returns an incorrect flag to WebLogic Server, data integrity problems can occur, and they may be difficult to track down.

If entity EJB updates appear "lost" in the system, start by ensuring that the value for all is-modified-method-name elements return "true" under every circumstance. In this way, you can revert to WebLogic Server's default ejbStore() behavior and possibly correct the problem.

 

 

Using delay-updates-until-end-of-tx to Change ejbStore() Behavior

By default, WebLogic Server updates the persistent store of all beans in a transaction only at the completion (commit) of the transaction. This generally improves performance by avoiding unnecessary updates and repeated calls to ejbStore().

If your datastore uses an isolation level of READ_UNCOMMITTED, you may want to allow other database users to view the intermediate results of in-progress transactions. In this case, the default WebLogic Server behavior of updating the datastore only at transaction completion may be unacceptable.

You can disable the default behavior by using the delay-updates-until-end-of-tx deployment descriptor element. This element is set in the weblogic-ejb-jar.xml file. When you set this element to "false," WebLogic Server calls ejbStore() after each method call, rather than at the conclusion of the transaction.

Setting delay-updates-until-end-of-tx to false does not cause database updates to be "committed" to the database after each method invoke; they are only sent to the database. Updates are committed or rolled back in the database only at the conclusion of the transaction.

 

 

Groups

In container-managed persistence, you use groups to specify certain persistent attributes of an entity bean. A field-group represents a subset of the container-managed persistence (cmp) and container-managed relation (cmr) fields of a bean. You can put related fields in a bean into groups that are faulted into memory together as a unit. You can associate a group with a query or relationship, so that when a bean is loaded as the result of executing a query or following a relationship, only the fields mentioned in the group are loaded.

A special group named "default" is used for queries and relationships that have no group specified. By default, the default group contains all of a bean's cmp fields and any cmr fields that add a foreign key to the persistent state of the bean.

A field can belong to multiple groups. In this case, the getXXX() method for the field will fault in the first group that contains the field.

 

 

Specifying Field Groups

Field groups are specified in the weblogic-rdbms-cmp-jar.xml file as follows:

<weblogic-rdbms-bean>



 <ejb-name>XXXBean</ejb-name>



 <field-group>


<group-name>medical-data</group-name>


<cmp-field>insurance</cmp-field>


<cmr-field>doctors</cmr-fields>



 </field-group>



</weblogic-rdbms-bean>

One uses field groups when you want to access a subset of fields.

 

 

Automatic Primary Key Generation

WebLogic Server supports an automatic primary key generation feature for container-managed persistence (CMP).

Generated key support is provided in two ways:

• Using DBMS primary key generation. A set of deployment descriptors are specified at compile time to generate container code that is used in conjunction with a supported database to provide key generation support.

  With this option, the container defers all key generation to the underlying database. To enable this feature, you specify the name of the supported DBMS and the generator name, if required by the database. The CMP code handles all details of implementing this feature.

• Using Bean Provider Designated Named Sequence table. A user-named and user-created database table has a schema specified by WebLogic Server. The container uses this table to generate the keys.

  With this option, you name a table that holds the current primary key value. The table consists of a single row with a single column as defined by the following statement:

  top>CREATE table_name (SEQUENCE int) INSERT into table_name VALUES (0)

Note: For instructions on creating a table in Oracle, use the Oracle database documentation.

In the weblogic-cmp-rdbms-jar.xml file, set the key_cache_size element to specify how many primary key values a database SELECT and UPDATE will fetch at one time. The default value of key_cache_size is 1. BEA recommends that you set this element to a value of >1, to minimize database accesses and to improve performance.