Result Class
An instance of the Result class is returned by many of the Java APIs.
- Considerations
-
- If the return code is less than zero, it is an error code.
- The Result object contains an error message that explains the error.
- If the return code is zero, the call succeeded, but no records are present.
- This value is returned by an add, update, or delete, or when no records match specified search criteria.
- If the return code is greater than zero, the value is the number of records in the result set.
- In that case, there are two options:
- If the API expected to return a single record, as in a getRecord operation, the getParameters method (below) returns a Parameters object that contains the record fields.
- If the API expected to return multiple records, as in an execSQL query or a searchRecords operation, then the getIterator method (below) is used to cycle through the list of Parameters objects contained in the Result set (one per record). (In that case, the getParameters method returns null.)
Methods
The Result class has following methods.
getCode
Gets the error code for record handling calls such as addRecord, updateRecord, deleteRecord, and so on.
For the searchRecords and getRecord calls, the code indicates the number of records returned.
These are the rules that the record handling calls follow for setting the error code:
- All record handling calls set the error code to negative one (-1) if not successful.
- Most record handling calls set the error code to zero (0) if successful. The exceptions to this rule are:
- getRecord sets the error code to one (1) if successful
- searchRecord sets the error code to the number of records retrieved if successful
Signature of the Method
- <syntaxhighlight lang="java" enclose="div">int getCode()</syntaxhighlight>
- Example
- This example calls addRecord, assigning the returned value to an instance of Result and calling Result.getCode to assign the error code to a variable which is then conditionally checked to determine the code to execute.
<syntaxhighlight lang="java" enclose="div"> Parameters myAccount = Functions.getParametersInstance(); myAccount.add("name", "Acme Solutions"); Result result = Functions.addRecord("ACCOUNT", params); int returnCode = result.getCode(); if(returnCode < 0) {
String msg = "Account could not be added"; Logger.info(msg + ":\n" + result.getMessage(), "Accounts"); // Log details Functions.throwError(msg + "."); // Error message
} else {
// take other actions according to // your business logic.
} </syntaxhighlight>
getID
Gets the record identifier set by addRecord and generateDocument. When these calls fail, the record identifier is an empty string.
Signature of the Method <syntaxhighlight lang="java" enclose="div">String getID()</syntaxhighlight>
- Example
- This example calls addRecord, assigning the returned value to an instance of Result and calling Result.getCode to assign the error code to a variable which is then conditionally checked to determine the code to execute. If the call was successful, the code calls getID to extract the record identifier.
<syntaxhighlight lang="java" enclose="div"> Parameters myAccount = Functions.getParametersInstance(); myAccount.add("name", "Acme Solutions"); Result result = Functions.addRecord("ACCOUNT", myAccount); int returnCode = result.getCode(); if(returnCode < 0) {
String msg = "Account could not be added"; Logger.info(msg + ":\n" + result.getMessage(), "Accounts"); // Log details Functions.throwError(msg + "."); // Error message
} else {
String id = result.getID(); // use the ID when updating the record or adding a record to a related object
} </syntaxhighlight>
getMessage
Gets the message that indicates success or failure.
Signature of the Method <syntaxhighlight lang="java" enclose="div">String getMessage()</syntaxhighlight>
- Example
- This example calls addRecord, assigning the returned value to an instance of Result and calling Result.getCode to assign the error code to a variable which is then conditionally checked to determine the code to execute. If the call was not successful, the code calls getMessage to extract the message string.
<syntaxhighlight lang="java" enclose="div"> Parameters myAccount = Functions.getParametersInstance(); myAccount.add("name", "Acme Solutions"); Result result = Functions.addRecord("ACCOUNT", params); int returnCode = result.getCode(); if(returnCode < 0) {
String msg = "Error adding Acme Solutions account"; Logger.info(msg + ":\n" + result.getMessage(), "Accounts"); // Log details Functions.throwError(msg + "."); // Error message
} else {
String id = result.getID(); // use the ID to addTask, addActivity or // add any other related object.
} </syntaxhighlight>
getIterator
Gets a ParametersIterator object after a searchRecords call.
Signature of the Method <syntaxhighlight lang="java" enclose="div">ParametersIterator getIterator()</syntaxhighlight>
- Example
- This example calls searchRecords, assigning the returned value to an instance of Result and calling Result.getCode to assign the error code to a variable which is then conditionally checked to determine the code to execute. If the call was successful and records were returned, the code creates an instance of ParametersIterator. In a while loop, the code calls the ParametersIterator.next method to get an instance of Parameters from which it then extracts the record identifier.
<syntaxhighlight lang="java" enclose="div"> Result result = Functions.searchRecords("ACCOUNT", "record_id,name, number,city", "name starts with 'Acme'"); int returnCode = result.getCode(); if(returnCode < 0) {
String msg = "Error searching Account records"; Logger.info(msg + ":\n" + result.getMessage(), "Accounts"); // Log details Functions.throwError(msg + "."); // Error message
} else if(returnCode == 0) {
Functions.throwError("No records found");} else {
ParametersIterator iterator = result.getIterator(); while(iterator.hasNext()) { Parameters myAccount = iterator.next(); String id = myAccount.get("record_id"); // execute your other business logic }} </syntaxhighlight>
getParameters
Creates a Parameters object.
Signature of the Method
- <syntaxhighlight lang="java" enclose="div">
Parameters getParameters() </syntaxhighlight>
- Example
- This example calls getRecord, assigning the returned value to an instance of Result and calling Result.getCode to assign the error code to a variable which is then conditionally checked to determine the code to execute. If the call was successful and records were returned, the code creates an instance of Parameters and extracts the name.
- <syntaxhighlight lang="java" enclose="div">
String accountID = ""; // Some code to populate accountID variable Result result = Functions.getRecord("ACCOUNT", accountID); int returnCode = result.getCode(); if(returnCode < 0) {
String msg = "Error retrieving Account record"; Logger.info(msg + ":\n" + result.getMessage(), "Accounts"); // Log details Functions.throwError(msg + "."); // Error message
} else {
Parameters params = result.getParameters();
String accountName = params.get("name");
// execute your other business logic based on name
} </syntaxhighlight>