Transactions and Atomicity

A transaction is a logical set of updates of persistent data. For example, transferring some amount of money from one account to another is a banking transaction. It is important for transactions to be atomic: either all of the data fields are updated, or none are. The Java Card RE provides robust support for atomic transactions, so that card data is restored to its original pre-transaction state if the transaction does not complete normally. This mechanism protects against events such as power loss in the middle of a transaction, and against program errors that might cause data corruption should all steps of a transaction not complete normally.

7.1 Atomicity

Atomicity defines how the card handles the contents of persistent storage after a stop, failure, or fatal exception during an update of a single object or class field or array component. If power is lost during the update, the applet developer shall be able to rely on what the field or array component contains when power is restored.

The Java Card platform guarantees that any update to a single persistent object or class field will be atomic. In addition, the Java Card platform provides single component level atomicity for persistent arrays. That is, if the smart card loses power during the update of a data element (field in an object/class or component of an array) that shall be preserved across CAD sessions, that data element shall be restored to its previous value.

Some methods also guarantee atomicity for block updates of multiple data elements. For example, the atomicity of the Util.arrayCopy method guarantees that either all bytes are correctly copied or else the destination array is restored to its previous byte values.

An applet might not require atomicity for array updates. The Util.arrayCopyNonAtomic method is provided for this purpose. It does not use the transaction commit buffer even when called with a transaction in progress.

7.2 Transactions

An applet might need to atomically update several different fields or array components in several different objects. Either all updates take place correctly and consistently, or else all fields/components are restored to their previous values.

The Java Card platform supports a transactional model in which an applet can designate the beginning of an atomic set of updates with a call to the JCSystem.beginTransaction method. Each object update after this point is conditionally updated. The field or array component appears to be updated—reading the field/array component back yields its latest conditional value—but the update is not yet committed.

When the applet calls JCSystem.commitTransaction, all conditional updates are committed to persistent storage. If power is lost or if some other system failure occurs prior to the completion of JCSystem.commitTransaction, all conditionally updated fields or array components are restored to their previous values. If the applet encounters an internal problem or decides to cancel the transaction, it can programmatically undo conditional updates by calling JCSystem.abortTransaction.

7.3 Transaction Duration

A transaction always ends when the Java Card RE regains programmatic control upon return from the applet’s select, deselect, process, uninstall, or install methods. This is true whether a transaction ends normally, with an applet’s call to commitTransaction, or with an abortion of the transaction (either programmatically by the applet, or by default by the Java Card RE). For more details on transaction abortion, refer to Section 7.6.

Transaction duration is the life of a transaction between the call to JCSystem.beginTransaction, and either a call to commitTransaction or an abortion of the transaction.

7.4 Nested Transactions

The model currently assumes that nested transactions are not possible. There can be only one transaction in progress at a time. If JCSystem.beginTransaction is called while a transaction is already in progress, then a TransactionException is thrown.

The JCSystem.transactionDepth method is provided to allow you to determine if a transaction is in progress.

7.5 Tear or Reset Transaction Failure

If power is lost (tear) or the card is reset or some other system failure occurs while a transaction is in progress, then the Java Card RE shall restore to their previous values all fields and array components conditionally updated since the previous call to JCSystem.beginTransaction.

This action is performed automatically by the Java Card RE when it reinitializes the card after recovering from the power loss, reset, or failure. The Java Card RE determines which of those objects (if any) were conditionally updated, and restores them.

Note – The contents of an array component which is updated using the Util.arrayCopyNonAtomic method or the Util.arrayFillNonAtomic method while a transaction is in progress, is not predictable, following a tear or reset during that transaction.

Note – Object space used by instances created during the transaction that failed due to power loss or card reset can be recovered by the Java Card RE.

7.6 Aborting a Transaction

7.6.1 Programmatic Abortion

If an applet encounters an internal problem or decides to cancel the transaction, it can programmatically undo conditional updates by calling JCSystem.abortTransaction. If this method is called, all conditionally updated fields and array components since the previous call to JCSystem.beginTransaction are restored to their previous values, and the JCSystem.transactionDepth value is reset to 0.

7.6.2 Abortion by the Java Card RE

If an applet returns from the select, deselect, process, or install methods when an applet initiated transaction is in progress, the Java Card RE automatically aborts the transaction and proceeds as if an uncaught exception was thrown.

If the Java Card RE catches an uncaught exception from the select, deselect, process, or install methods when an applet initiated transaction is in progress, the Java Card RE automatically aborts the transaction.

Note – The abortion of a transaction by the Java Card RE does not directly affect the response status sent to the CAD. The response status is determined as described in Section 3.3 "The Method process.”

7.6.3 Cleanup Responsibilities of the Java Card RE

Object instances created during the transaction that is being aborted can be deleted only if references to these deleted objects can no longer be used to access these objects. The Java Card RE shall ensure that a reference to an object created during the aborted transaction is equivalent to a null reference.

Alternatively, programmatic abortion after creating objects within the transaction can be deemed to be a programming error. When this occurs, the Java Card RE may, to ensure the security of the card and to avoid heap space loss, lock up the card session to force tear/reset processing.

7.7 Transient Objects and Global Arrays

Only updates to persistent objects participate in the transaction. Updates to transient objects and global arrays are never undone, regardless of whether or not they were “inside a transaction.”

7.8 Commit Capacity

Since platform resources are limited, the number of bytes of conditionally updated data that can be accumulated during a transaction is limited. The Java Card technology provides methods to determine how much commit capacity is available on the implementation. The commit capacity represents an upper bound on the number of conditional byte updates available. The actual number of conditional byte updates available may be lower due to management overhead.

A TransactionException is thrown if the commit capacity is exceeded during a transaction.

7.9 Context Switching

Context switches shall not alter the state of a transaction in progress. If a transaction is in progress at the time of a context switch (see Section 6.1.2), updates to persistent data continue to be conditional in the new context until the transaction is committed or aborted.

Chapter 7