TaskNameManager interface

The TaskNameManager is the programmatic interface to the application profiling function. Application profiling enables you to identify particular units of work to the WAS run time environment. The run time can tailor its support to the exact requirements of that unit of work. Access intent is currently the only run time component that makes use of the application profiling functionality. For example, one can configure one transaction to load an entity bean with strong update locks and configure another transaction to load the same entity bean without locks.

Application profiling introduces two concepts in order to achieve this function: tasks and profiles.

A task is a configurable name for a unit of work. Unit of work in this case means either a transaction or an ActivitySession.

A profile is simply a mapping of a task to a set of access intent policies that are configured on entity beans. When an invocation on a bean (whether by a finder method, a container managed relationship (CMR) getter, or a dynamic query) requires data to be retrieved from the back end system, the task of the active unit of work associated with the request is used to determine the exact requirement of the transaction. The same bean loads and behaves differently in the context of the task-to-profile mapping. Each profile provides the developer an opportunity to reconfigure the application's access intent.

Programmers can declaratively configure container managed tasks for Java 2 platform, Enterprise Edition (J2EE) web components, application clients, and EJB. On rare occasions, it may be necessary to programmatically set the current task name. Application profiling supports this requirement with the TaskNameManager interface that enables both overriding of the current task associated with the thread of execution, and resetting of the current task with the original task.

Except for J2EE 1.3 applications that are executing on a server where the 5.x Compatibility Mode attribute is selected, this interface cannot be used within Enterprise JavaBeans that are configured for container-managed transactions or container-managed ActivitySessions because units of work can only be associated with a task at the exact time that the unit of work is initiated. The call to set the task name must therefore be started before the unit of work is begun. Units of work cannot be named after they are begun. Calls on this interface during the execution of a container-managed unit of work are simply ignored.

The TaskNameManager interface is available to all J2EE components using the following Java Naming and Directory Interface (JNDI) lookup

java:comp/websphere/AppProfile/TaskNameManager

package com.ibm.websphere.appprofile; 

/** 
* The TaskNameManager is the programmatic interface 
* to the application profiling function. Using this interface, 
* programmers can set the current task name on the 
* thread of execution. The task name must have been 
* configured in the deployment descriptors as a task 
* reference associated with a task. The set task 
* name's scope is the duration of the method 
* invocation in the EJB and Web components and for 
* the duration of the client process, or until the 
* resetTaskName() method is invoked. 
*/ 
public interface TaskNameManager { 

/** 
* Set the thread's current task name to the specified 
* parameter. The task name must have been configured as 
* a task reference with a corresponding task or the 
* IllegalTaskName exception is thrown. 
*/ 
public void setTaskName(String taskName) throws IllegalTaskNameException; 

/** 
* Sets the thread's task name to the value that was set
* at, or imported into, the beginning of the method 
* invocation (for EJB and Web components) or process
* (for J2EE clients). 
*/ 
public void resetTaskName(); 

}