AgileApps Support Wiki Pre Release

Category:Transaction Management

From AgileApps Support Wiki

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

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");

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");

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
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);


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
void Functions.showMessage(String message);
void Functions.showMessage(String key, String[] args);

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)

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

Functions.showMessage("Include <br> for <br> newline");
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

Pages in category "Transaction Management"

The following 6 pages are in this category, out of 6 total.