Access Intent

Entity beans are used in J2EE application architectures as abstractions representing business objects. Entity beans provide an effective way to map the "things" of a business model, often defined by analysts and non-programmers, from something that exists in the "real world" to a construct in source code. Entity bean implementations, and the associated application server runtime support, manage the entity data by interacting with a persistent store such as a relational database. However, the implementation of those entities, done in part by bean providers and in part by the container and the runtime, must decide upon and provide answers to a number of more detailed questions. The answers to these questions may or may not be present in the abstraction being implemented. The answers might lie in the usage of the entity or in the application architecture itself.

A complete entity-relationship diagram of a business model would reveal a number of things about the usage patterns of the data. For example, expectations relating to locking and isolation level might be present, as well as information about result sets and navigation. As the container does much of the work involved in managing an entity bean, you cannot put these hints about usage patterns into the source code.

As it turns out, these facts about the intended usage of the data are often necessary to ensure that a business model can be effectively executed using entity beans. The EJB specification has some accommodation for capturing these facts about the entities and the intended usages involving those entities. For example, settings that can be configured in the deployment descriptor include security roles and method permissions or something as detailed as cascade-delete requirements for relationship management. However, more precise and detailed access intent information is often necessary. This has become even more necessary as we have moved from the EJB 1.1 to the EJB 2.0 model.

EJB 2.0 provides more flexibility and more capability to the bean provider, but also suggests the need for a more precise specification of the various intents. The application server can use this information to govern and regulate the interaction with the resource managers that contain the persistent state data. The persistence mechanisms that manage essential state need additional intent information so they can make proper decisions about concurrency control and resource management.

Access Intent support in WAS 5.0 is centered on capturing this intent information and ensuring that it can be utilized in the runtime. In conjunction with the Application Profile service, the WebSphere runtime is able to use the right intents at the right times in the execution sequence to ensure effective and accurate backend interactions.

Access intent is a set of declarative annotations used at run time by WAS to ensure that the optimal calls to the resource managers are made. These policies are named and defined at the module level. An EJB module may have one or many such policies. The Application Profile service enables us to apply multiple policies to a single bean and to determine at execution time which policy to apply based on the run-time context. This lets entity beans be reused in different ways by different applications with necessarily different access intent requirements. The most common example is the need to access an entity bean either optimistically or pessimistically, where optimistic and pessimistic refer to the locking of the underlying rows in the database.

Before diving into the Application Profile service, however, let us first describe the access intent policies that are allowed.

Access Intent Hints

Access intent in WebSphere provides support for the following hints:

• Access-type
  This indicates whether a component interaction is read or write oriented, and whether or not the component interaction is to be done pessimistically or optimistically. When dealing with EJBs, pessimistic refers to an action on a backend database where a lock is held for the affected data from the time it is first read until the transaction involving the data is complete. Optimistic generally means that the data involved in the transaction is read, but a lock is not held. If the data in the underlying datastore has changed when the transaction is to be finished, a rollback will occur. The pessimistic update hint is further qualified by the following attributes:

• Exclusive
  This specifies that the application requires exclusive access to the database rows. The backend should use the most stringent locking scheme available. Specifically this means that it will map down to what is normally called "serializable" on the underlying resource manager.

• No collision
  This specifies that the application is designed such that no concurrent transactions will access the same database rows. Therefore, a less stringent locking scheme or in fact no locking at all may be used. Specifically this means that this maps to read-committed on the underlying resource manager.

• Weakest lock at load
  This indicates whether a lock upgrade should be attempted. This applies to those resource managers that support read locks; an initial read lock is acquired and later in the transaction the lock is escalated or promoted if an update is performed.

• Collection scope
  This indicates how long a collection is to be used. This can be set to transaction or ActivitySession. ActivitySession is described in more detail later in this chapter.

• Collection increment
  This indicates the increment size that should be used for a lazy collection. A lazy collection is a collection that does not hold the complete contents asked for by the caller, but rather maintains the ability to acquire the contents on demand from a cache or database.

• Read ahead hint
  This is a hint that indicates to the server how deeply the object graph for EJB 2.0 CMR relationships should be read.

• Resource manager prefetch increment
  This is used by the persistence manager to provide a hints to the database about retrieving data for collections.

These are called hints because, in some cases, the application server runtime will be unable to exactly match the behavior in the hint. This is usually either due to the backend system and restrictions that may exist in the interaction styles allowed or because of conflicts with other hints which may be in effect. More examples will be given as the details are described.

With this brief introduction, let's explore these a bit more before going on to describing how these can be used by applications.

Default Intents

WAS comes with a set of access intent policies that will be enough for you to get started configuring and using CMP 2.0 Entity Beans.

Note

Note that Resource manager prefetch is set to zero for all of these sets of access intents, which lets the database make the best default decision. When we get to the Application Profile service, changing this value is discussed further.

wsPessimisticUpdate

This set of access intents will provide an update lock at ejbLoad() time on the row in the table of the underlying database. This will be useful on a findByPrimaryKey() and on single-table finders. This will keep you out of deadlocks more than the other pessimistic options. Specifically, this results in a SELECT FOR UPDATE with whatever isolation level is one level weaker than serializable for a particular database. For Oracle, this is read- committed. For DB2, this is repeatable-read. This setting will connection-share with wsPessimisticRead:

Access-type                         = pessimistic update  Exclusive                           = false  No collision                        = false Weakest lock at load                = false  Collection scope                    = transaction  Collection increment                = 1  Resource manager prefetch increment = 0  Read ahead hint                     = null

wsPessimisticUpdate-NoCollision

This set of access intents is the same as the previous one, except that it will not generate a SELECT FOR UPDATE on the findByPrimaryKey() and other finder methods:

Access-type                         = pessimistic update Exclusive                           = false No collision                        = true Weakest lock at load                = false Collection scope                    = transaction Collection increment                = 25 Resource manager prefetch increment = 0 Read ahead hint                     = null 

wsPessimisticUpdate-Exclusive

This set of access intents provides the strongest level of locking. It maps to a serializable isolation level on DB2. This set of access intents should prevent others from inserting rows:

Access-type                         = pessimistic update Exclusive                           = true No collision                        = false Weakest lock at load                = false Collection scope                    = transaction Collection increment                = 1 Resource manager prefetch increment = 0 Read ahead hint                     = null

wsPessimisticUpdate-WeakestLockAtLoad

This set of access intents will potentially upgrade read locks to write locks if the underlying resource manager supports that locking style:

Access-type                         = pessimistic update Exclusive                           = false No collision                        = false Weakest lock at load                = true Collection scope                    = transaction Collection increment                = 25 Resource manager prefetch increment = 0 Read ahead hint                     = null

wsPessimisticRead

This set of access intents will provide a 'repeatable read' semantic. There are no update locks. The runtime will throw an exception if an update is attempted while these policies are in effect:

Access-type                         = pessimistic read  Collection scope                    = transaction  Collection increment                = 25  Resource manager prefetch increment = 0  Read ahead hint                     = null

wsOptimisticUpdate

This set of access intents does not hold a lock. It uses a "read commited" semantic as it applies to the underlying database. Updates are allowed and rollbacks will occur at transaction commit time:

Access-type                         = optimistic update Collection scope                    = transaction Collection increment                = 25 Resource manager prefetch increment = 0 Read ahead hint                     = null

wsOptimisticRead

This final set of access intents holds no locks. The runtime, however, will not permit updates:

Access-type                         = optimistic read Collection scope                    = transaction Collection increment                = 25 Resource manager prefetch increment = 0  Read ahead hint                     = null

A CMP 2.0 entity bean will run using wsPessimisticUpdate-WeakestLockAtLoad access intent policy unless it is changed in the Application Assembly Tool, which we will demonstrate how to do in the next section.

Note

Notice also that the Read ahead hint is always null. This is because these hints are specific to particular CMR relationships and are customized using patterns similar to those described in the next section.

Applying Access Intent

If no customization of access intent is done, applications with entity beans will default to the wsPessimisticUpdate-WeakestLockAtLoad policy. While this will usually let you start testing an application, it is often not sufficient for use in a production environment. The easiest way to change the access policy used is to use another one of the policies provided in the system. The following example shows setting a specific policy for the Customer entity bean from our Plants-By-WebSphere application.

First, when you right-click on the Access Intent item in the AAT, you are given a choice to create a new access intent. This brings you to a window like this:

Provide a name for this usage of an access policy. Also, use the pull-down menu to decide which access intent to apply. In our case, we will use the wsOptimisticRead policy:

The final task is to describe which methods will use this policy. Access intent policies configured without the benefit of the application profile service (to be described later in this chapter) are applied to the methods of a bean and its home. When the invocation of a method causes the container to read the bean's data from the underlying data store, the access intent policy configured on that method will be used to manage the access and concurrency for that bean instance for the duration of the unit-of-work.

Clicking the Add button under the Methods heading will provide a selection dialogue like this:

For this first example, we will just pick Customer(*), which indicates that all methods will use the wsOptimisticRead policy. More granular selection is obviously possible. The final display before pressing Apply will the look like this:

If you want to use a set of access intents for a bean or a set of methods on that bean that had a slight variation form the default, you can override or customize it as shown below. The collection increment is set to 100, but the rest of the default profile will be used as it is:

Sometimes it might be necessary to build a completely new access intent policy. This is easy to do in the application assembly tool. Under the Access Intent Policies on the main application assembly tool view, just right-click and you will see the New choice where you should fill in the view as shown:

This set of capabilities lets you customize which access intent applies to an entity bean. All of this is done at assembly time and once you have deployed the EJB, the access intent policy that is used to interact with the backend is known, fixed, and used by the runtime. It is part of the extended deployment descriptor information and is found in the ibm-ejb-jar-ext.xmi file. The only problem is the "fixed" part. Fortunately, the Application Profile service is going to let us reach another level of flexibility.