ActivitySession Service Application Samples

Copyright license

COPYRIGHT LICENSE: This information contains sample code provided in source code form. You may copy, modify, and distribute these sample programs in any form without payment to IBM for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample code is written. Notwithstanding anything to the contrary, IBM PROVIDES THE SAMPLE SOURCE CODE ON AN "AS IS" BASIS AND IBM DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, ANY IMPLIED WARRANTIES OR CONDITIONS OF MERCHANTABILITY, SATISFACTORY QUALITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND ANY WARRANTY OR CONDITION OF NON-INFRINGEMENT. IBM SHALL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR OPERATION OF THE SAMPLE SOURCE CODE. IBM HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS OR MODIFICATIONS TO THE SAMPLE SOURCE CODE.

About this task

Enterprise beans have ActivitySession attributes that you can specify on a per-method basis as part of deployment. These attributes follow the model established by the transaction attributes defined in the Enterprise JavaBeans (EJB) specification with ActivitySessions being either bean-managed, or container-managed. The EJB container also supports activation and passivation policies scoped to the ActivitySession service and supports local transactions scoped to ActivitySession attributes, rather than restricted to method invocation boundaries.

Activity sessions can also be used in the web container and can be related to HTTP sessions. Web applications can be deployed with the following ActivitySession control values:

Application
The web application is responsible for starting and ending the ActivitySession service and for moving the ActivitySession context to and from the thread.
Container
The web application has no access to the UserActivitySession interface. Each HTTP session created by the web application has an ActivitySession service implicitly created and associated with it.
None
The web application does not use the ActivitySession service.

For more information, see the ActivitySession service topic in the WebSphere Application Server Information Center.

The sample application comprises three individual samples contained in a single EAR file:

HTTP session association (MasterMind Game)
Container-managed ActivitySessions
Bean-managed ActivitySessions

Procedure

In the following information, profile_root refers to the root directory for your profile. For example, app_server_root/profiles/profile1.

Install the samples
1. Extract the ActivitySessionSample.zip folder into the samples_dir directory.
2. Open a command prompt and change directory to the samples_dir/scripts directory.
3. In the command prompt, run the following command:
```
profile_root/bin/wsadmin -conntype none -f samplesMaster.jacl
```

Uninstall the samples

Open a command prompt, and run the following command:

profile_root/bin/wsadmin -conntype none -lang jython
-c "AdminApp.uninstall('activitysession')"

Build the samples
1. Open a command prompt, and run one of the following commands.
  On Windows operating systems, run:
```
profile_root\bin\setupCmdLine
```
  On Unix operating systems, run:
```
. profile_root/bin/setupCmdLine.sh
```
  On iSeries operating systems, run:
```
. profile_root/bin/setupCmdLine
```
2. Then run the following command:
```
./buildsamples
```

Information about how to run the individual samples is provided below.

The HTTP session association (MasterMind Game) sample
A servlet provides the user interface for a game called MasterMind. The game uses an HTTP session to control the ActivitySession life-cycle, and communicates with an enterprise bean, which holds the state and provides the logic for the game. The aim of the game is to guess the four-element code that is generated at the start. On each guess, clues are given to the identity of the target code by how many elements in the guess are present in the target and how many of these elements are correctly placed.

MasterMindGame enterprise bean

The MasterMindGame enterprise bean is a stateful session bean that stores the target code for each game and processes each guess. The bean is not persistent and moreover all its instance variables are transient and only maintain value while the bean remains active. The bean has an activation policy of ActivitySession.

MasterMind servlet

The MasterMind servlet generates the HTML presented to the user, and dispatches guesses to the MasterMindGame bean for processing. The servlet web.xml file contains an entry that sets the activity session control for the servlet to Container. When the servlet creates an HTTP session, an ActivitySession is automatically created and associated with the HTTP session. The life-cycle of the activity session is also related to that of the HTTP session. The servlet stores its reference to the bean inside the HTTP session.

Running the MindGame sample

The MasterMind game is accessible at the following URL:
```
http://host_name:port/samples/activitysessions/MasterMind
```
When a new game starts, a new HTTP session begins in the servlet. Because an activation session control of Container is specified, an activity session begins. The HTTP session lasts until the servlet invalidates it at the end of each game. Because the bean has an activation policy of ActivitySession, its transient state remains in memory for the duration of the game.

The container-managed ActivitySessions sample
This sample consists of a client, which begins and ends the ActivitySessions service, updating an entity bean. The sample demonstrates client access to the UserActivitySession interface, container-managed ActivitySessions service, and container resolution of resource-managed local transactions. These transactions start within the enterprise beans that have a Local Transaction Containment (LTC) boundary of ActivitySession. The client verifies that updates to bean instances are committed when the ActivitySession service is completed with the EndModeCheckpoint and rolled back when the EndModeReset is used.

ASContainerManaged enterprise bean

The ASContainerManaged enterprise bean is an entity bean that uses container-managed persistence, backed by a local transaction-capable data source. It has the following settings:

an ActivitySession attribute of Mandatory
an activation policy of ActivitySession
a Transaction attribute of NotSupported
a Local Transaction Containment (LTC) boundary of ActivitySession
an LTC resolution control of ContainerAtBoundary

ASContainerSampleClient J2EE application client

This Java EE client accesses the UserActivitySession interface to begin and end activity sessions. It creates and finds instances of the ASContainerManagedEJB enterprise bean and updates them inside activity sessions.

The client accesses the entity bean during an activity session. When the bean is accessed the client ActivitySession context is established in the bean because the ActivitySession attribute is Mandatory. No global transaction context exists, so a Local Transaction Containment (LTC) is started. The LTC is scoped to the activity session and the resolution control of ContainerAtBoundary causes the container to complete the LTC when the activity session ends.

The client runs two activity sessions, updating two instances of the bean in each session. The sample completes the first session with a checkpoint and the second session with a reset. It then checks that updates that were made during the first activity session are committed to the data store, and updates that were made during the second activity session are rolled back. Each instance of the bean runs within its own LTC, but the same activity session.

In addition to demonstrating how to access the UserActivitySession interface from a Java EE client, the sample shows how the LTCs used in the bean instances are completed by the container when the activity session is completed. This action is particularly noticeable where the ActivitySession reset causes both LTCs for each bean instance to roll back.

This usage scenario is common for activity sessions, whereby multiple operations against one or more beans backed by one-phase resource managers can be grouped together to be verified or discarded.

Running the container-managed ActivitySessions sample

Open a command prompt and run one of the following commands.
On Windows operating systems, run:
```
profile_root\bin\setupCmdLine
```
On Unix operating systems, run:
```
. profile_root/bin/setupCmdLine.sh
```
On iSeries operating systems, run:
```
. profile_root/bin/setupCmdLine
```
In the command prompt, change the directory to the samples_dir/installableApps directory.
To invoke the sample, run one of the following commands.
On Windows operating systems, run:
```
profile_root\bin\launchClient activitysession.ear
-CCBootstrapPort=port -CCjar=ASContainerSampleClient.jar
-CCexitVM=true
```
On Unix operating systems, run:
```
profile_root/bin/launchClient.sh activitysession.ear
-CCBootstrapPort=port -CCjar=ASContainerSampleClient.jar
-CCexitVM=true
```
On iSeries operating systems, run:
```
profile_root/bin/launchClient activitysession.ear
-CCBootstrapPort=port -CCjar=ASContainerSampleClient.jar
-CCexitVM=true
```
The element, port, is the port on which the application server is listening.

Configuration Default Port Number

Base 2809

Network Deployment 9810

Note: If you are not using either of the default port numbers listed here, see the Running a Java EE client application with launchClient topic for details on using the launchClient command.
If global security is enabled, enter the relevant user ID and password in the Client Container menu.

Configuration	Default Port Number
Base	2809
Network Deployment	9810

The client reports the progress. See the following example output:

Starting ActivitySessions Sample
 Accessing UserActivitySession
 Retrieving an ASContainerManagedEJBHome from JNDI
 Finding or Creating EJB instances
 Starting First ActivitySession
 Updating EJBs
 Ending ActivitySession with Checkpoint
 Starting Second ActivitySession
 Updating EJBs
 Ending ActivitySession with Reset
 Checking values
 Sample has completed successfully

The bean-managed ActivitySessions sample

This sample consists of a client that invokes a method on a stateless session bean. This session bean uses bean-managed activity sessions, beginning and ending the ActivitySessions with the UserActivitySession interface. During these activity sessions, a stateful session bean is accessed. This stateful session bean, which uses the container-managed ActivitySession service, an LTC boundary of ActivitySession, and an LTC resolution control of Application, is called several times to update data in a database. Sometimes the stateful session bean is instructed to complete the resource manager local transactions (RMLTs), either to commit them or roll them back. Sometimes the RMLTs are left incomplete. The stateless session bean then completes the ActivitySession service and reports back to the client whether the results are consistent with the expected behavior.

ASBeanManaged enterprise bean

The ASBeanManagedEJB enterprise bean is a stateless session bean that uses the UserActivitySession interface to begin and end activity sessions. It calls methods on an instance of the ASContainerManagedEJB2 bean inside these activity sessions and reports results back to the client. This enterprise bean has an ActivitySession attribute of BeanManaged and a transaction attribute of BeanManaged.

ASContainerManagedEJB2 enterprise bean

The ASContainerManagedEJB2 enterprise bean is a stateful session bean that uses Java DataBase Connectivity (JDBC) to access a local transaction-capable data source. It has the following settings:

method ActivitySession attributes of Mandatory
an activation policy of ActivitySession
method transaction attributes of NotSupported
a Local Transaction Containment (LTC) boundary of ActivitySession
an LTC resolution control of Application
an LTC unresolved action of rollback

ASBeanSampleClient JEE application client

This Java Enterprise Edition (JEE) client accesses an instance of the ASBeanManagedEJB enterprise bean.

This sample shows a session bean with BeanManaged ActivitySession attributes accessing the UserActivitySession interface to begin and end activity sessions. During these ActivitySessions, instances of the ASContainerManagedEJB2 bean are accessed. The LTCs in the ASContainerManagedEJB2 beans are bounded by the activity session in which the bean instances are invoked. The Resource-Manager Local Transactions (RMLTs) used to access the local transaction-capable data source remain active over multiple method invocations that occur within the same activity session.

The LTC resolution control of Application means that the container does not automatically complete the LTCs (and by implication, RMLTs) in the direction specified at ActivitySession end. Rather, it is the responsibility of the application (in this case, the ASContainerManagedEJB2 bean instances) to complete the RMLTs in the correct directions. If incompleted RMLTs exist at the end of the activity session, the container completes them in the direction specified by the LTC unresolved action. In this case, unresolved RMLTs are rolled back at the end of an activity session.

Running the bean-managed ActivitySessions sample

Open a command prompt and run one of the following commands.
On Windows operating systems, run:
```
profile_root\bin\setupCmdLine
```
On Unix operating systems, run:
```
. profile_root/bin/setupCmdLine.sh
```
On iSeries operating systems, run:
```
. profile_root/bin/setupCmdLine
```
In the command prompt, change directory to the samples_dir/installableApps directory.
To invoke the sample, run one of the following commands.
On Windows operating systems, run:
```
profile_root\bin\launchClient activitysession.ear
-CCBootstrapPort=port -CCjar=ASBeanSampleClient.jar
-CCexitVM=true
```
On Unix operating systems, run:
```
profile_root/bin/launchClient.sh activitysession.ear
-CCBootstrapPort=port -CCjar=ASBeanSampleClient.jar
-CCexitVM=true
```
On iSeries operating systems, run:
```
profile_root/bin/launchClient activitysession.ear
-CCBootstrapPort=port -CCjar=ASBeanSampleClient.jar
-CCexitVM=true
```
The element, port, is the port on which the application server is listening:

Configuration Default Port Number

Base 2809

Network Deployment 9810

Note: If you are not using either of the default port numbers listed here, see the Running a Java EE client application with launchClient topic for details on using the launchClient command.
If global security is enabled, enter the relevant user ID and password in the Client Container menu.

Configuration	Default Port Number
Base	2809
Network Deployment	9810

The client reports the progress. See the following example output:

Starting ActivitySessions Sample
Retrieving an ASBeanManagedEJBHome from JNDI
Creating EJB instance
Calling ASBeanManagedEJB to perform tasks
Starting ActivitySessions Sample
Retrieving an ASContainerManagedEJB2Home from JNDI
Creating EJB instance
Starting an ActivitySession
Calling open
Calling performUpdates
Calling endLTC to end LTC with commit
Ending an ActivitySession with EndModeCheckPoint
Checking values
Values correct
Starting an ActivitySession
Calling open
Calling performUpdates
Calling endLTC to end LTC with rollback
Ending an ActivitySession with EndModeCheckPoint
Checking values
Values correct
Starting an ActivitySession
Calling open
Calling performUpdates
endLTC not called leaving LTC dangling
Ending an ActivitySession with EndModeCheckPoint
Checking values
Values correct
Sample has completed successfully

ActivitySession service application samples

Time required to set up and configure this sample

Prerequisites for use

Copyright license

About this task

Procedure