How do I configure a transaction timeout in WebSphere Liberty Batch?

• What is the role of javax.transaction.global.timeout?
• Do I need to implement the checkpointTimeout() method in CheckpointAlgorithm?
• Is there anything at the server config level? How does this interact with whatever is set at the application level?

(Edit 2016-12-02: Reworked with an explanation of the defaulting behavior when a timeout value of '0' is set for the application transaction).

Overview

Let me describe the application-level options and how that interacts with the server-level timeout.

In a chunk step in WebSphere Liberty Java Batch, you can either set an application-level timeout, or set a timeout value of '0' to default to a server-level timeout.

In addition, you can also set an upper bound for any non-zero application-level timeout value through a separate server-level setting.

Application-level timeout

The chunk transaction timeout can be set either:

In XML (static)

At the step level in JSL with special step property: javax.transaction.global.timeout (seconds)

E.g.

<step id="MyStep"> 
   <properties> 
      <!-- In seconds -->
      <property name="javax.transaction.global.timeout" value="120"/>   

If not explicitly defined in XML, it defaults to 180 (seconds).

In Java (dynamic)

If you need more dynamic/programmatic control you can implement a custom CheckpointAlgorithm and write its checkpointTimeout() to return whatever you want (a different value for each chunk even if you really wanted).

Server(JVM)-level timeouts

Setting an upper bound for application timeout values

You can prevent the application from setting too great a timeout value.

In the server config (server.xml) use propogatedOrBMTTranLifetimeTimeout :

<transaction propogatedOrBMTTranLifetimeTimeout="90s"/>

This will act as an upper bound on any non-zero application timeout value, either via javax.transaction.global.timeout or your checkpointTimeout() method,

Default timeout when application timeout is not set

In the case that the javax.transaction.global.timeout is set to '0' or the case that your checkpointTimeout() method returns '0', you will get a default timeout from the server.

This timeout value defaults to 120 seconds.

To change in the server config (server.xml) use totalTranLifetimeTimeout, e.g.:

<transaction totalTranLifetimeTimeout="60s"/>

Note:

As mentioned above, though, if javax.transaction.global.timeout isn't set at all the application timeout defaults to 180, and so the totalTranLifetimeTimeout does NOT come into play.

Other notes / references

Note: the WDT tool's Design View makes working with and remembering these server config attribute values much easier.

Mapping to WebSphere Application Server traditional config

The propogatedOrBMTTranLifetimeTimeout attribute here basically maps to the Maximum transaction timeout in traditional, while the totalTranLifetimeTimeout maps more obviously the Total transaction lifetime timeout in traditional.

Some nice examples are described within this documentation which are still largely relevant in Liberty.