Java API:Transaction Management

The Transaction Management Java APIs provide the ability to Rollback transactions to a SavePoint.

Transactions are operations on a record (such as Add, Update or Delete), and include modifying the contents of field data in a record
Rollbacks perform an undo operation, reversing transactions to a previous SavePoint
SavePoints are intermediate placemarks, which identify points at which the data fields contain intact, legitimate values

When are SavePoints and Rollbacks used?

A SavePoint might be set to identify the initial values of fields in a record, prior to applying a Transaction. Multiple SavePoints are typically used, whenever it might be important to track the values of fields in a record. SavePoints can be used to "undo" any transaction, or perform multiple "undos" to a specific "saved" condition.

A Rollback might be performed when a series of actions cause an error condition, so it is necessary to return to previous SavePoint(s)

addSavePoint

Functions.addSavePoint(String name)

Adds a SavePoint with the string name.

Syntax

Functions.addSavePoint(String name)

Return: None

Example: This example creates a SavePoint with the name Foo

Functions.addSavePoint("Foo");

For additional examples, see Rollback

rollbackToSavePoint

Functions.rollbackToSavePoint(String name)

Rollback the transaction to the SavePoint with the string name.

Syntax

void Functions.rollbackToSavePoint(String name)

Return: None

doesSavePointExist

Functions.doesSavePointExist(String name)

Checks whether SavePoint exists with the string name.

Syntax

boolean Functions.doesSavePointExist(String name)

Return: TRUE if the SavePoint with the string name exists, else returns FALSE

rollback

Functions.rollback(String name)

Performs a rollback of the entire transaction

Syntax

void Functions.rollback()

Return: None

Examples

Single SavePoint Rollback
Multiple SavePoints Rollback
Rollback Entire Transaction

Single SavePoint Rollback

Rollback a record to the values contained in the last SavePoint

Functions.addSavePoint("save_point");
                               
Parameters params = Functions.getParametersInstance();
params.add("first_name","Jack");
params.add("last_name","Nicholson");
Result result = Functions.addRecord("CONTACT",params);
Functions.rollbackToSavePoint("save_point");

</syntaxhighlight>

Multiple SavePoints Rollback

Restores multiple SavePoints to the initial state, and rolls back all of the addRecord actions.

Functions.addSavePoint("save_point");

Parameters params = Functions.getParametersInstance(); params.add("first_name","Jack"); params.add("last_name","Nicholson");

Result result = Functions.addRecord("CONTACT",params);

Functions.addSavePoint("second_save_point");

Logger.info("Second Save Point :"

         + Functions.doesSavePointExist("second_save_point"), "Rollback");

Parameters secondParams = Functions.getParametersInstance(); secondParams.add("first_name","Anthony"); secondParams.add("last_name","Hopkins");

Result secondResult = Functions.addRecord("CONTACT",secondParams);

Functions.addSavePoint("third_save_point");

Parameters thirdParams = Functions.getParametersInstance(); thirdParams.add("first_name","Clint"); thirdParams.add("last_name","Eastwood");

Result thirdResult = Functions.addRecord("CONTACT",thirdParams);

Functions.rollbackToSavePoint("save_point"); </syntaxhighlight>

Rollback Entire Transaction

Roll back a series of transactions, to the original SavePoint.

From the web browser these results are seen:

If a record was added before this transaction, then the record will not exist
If a record was edited before this transaction, then no updates will be recorded for the record

<syntaxhighlight lang="java" enclose="div"> Functions.addSavePoint("save_point");

Parameters params = Functions.getParametersInstance(); params.add("first_name","Jack"); params.add("last_name","Nicholson");

Result result = Functions.addRecord("CONTACT",params);

Functions.addSavePoint("second_save_point");

Logger.info("Second Save Point: "

+ doesSavePointExists("second_save_point"), "Rollback");

Parameters secondParams = Functions.getParametersInstance(); secondParams.add("first_name","Anthony"); secondParams.add("last_name","Hopkins");

Result secondResult = Functions.addRecord("CONTACT",secondParams);

Functions.rollback(); // rollbacks all batabase operations like insert, update and delete before this. Functions.addSavePoint("third_save_point");

Parameters thirdParams = Functions.getParametersInstance(); thirdParams.add("first_name","Client"); thirdParams.add("last_name","Eastwood");

Result thirdResult = Functions.addRecord("CONTACT",thirdParams); </syntaxhighlight>

removeSavePoint

Functions.removeSavePoint(String name)

Removes the specified SavePoint from a list of SavePoints.

Syntax

void Functions.removeSavePoint(String name)

Return: None

showMessage

Description

This function displays a message to the user, either at the top of page or in a dialog, depending on the context.

The basic version of the function displays a message string.
With additional options, a localized version of a message can displayed.

Considerations

The function displays the message in the UI, irrespective of any database insertions or updates (in other words, without interrupting the program flow).
If the function is called multiple times, the messages are concatenated, and displayed together when the code returns to the platform. (Only one dialog is ever displayed.)
The text is displayed in HTML format, so linebreaks (<br>) and text formatting (<b>, <i>) can be included.
In a JSP page, this function does nothing. Use a JavaScript alert(), instead.

Syntax: <syntaxhighlight lang="java" enclose="div">

void Functions.showMessage(String message); void Functions.showMessage(String key, String[] args); </syntaxhighlight>

To display a localized message:

Element	Type	Description
key	String	A category name, followed by '.' and a message or label identifier (a "token"). Example: `#categoryname.tokenname`
args	Array of String	Optional. Causes the first parameter to be treated as a key. If no additional arguments are passed, the original key (the message string) is displayed. If arguments are passed, the key is used to retrieve a Custom Label in the current language, with the supplied arguments injected into it.

To provide a key for a label that has no arguments (for example, for a label in the #custom category), use:

Functions.showMessage("#custom.label", null) </syntaxhighlight>

To include linebreaks in the message, specify <br>:

Functions.showMessage("Include
for
newline"); </syntaxhighlight>

Return

Returns the localized message configured on the key in the Translation Workbench.
If no key is configured in the translation workbench, then the passed key is returned.

getAllSavePoints

getAllSavePoints()

Returns Set of all Save Points.

Syntax

set getAllSavePoints()

Return: Set of all SavePoints

Search

where to start

Feedback

customize and design

resources

Tools

Personal tools