AgileApps Support Wiki Pre Release

Java API:Composite Objects

From AgileApps Support Wiki

A Composite Object consists of multiple related objects, as defined by the Object Relationships. These APIs let you work with a composite object as a single entity.

Learn More: Working with Composite Objects

getRecordCount

Gets a count of records in a Composite Object that match specified filtering criteria.

Syntax
int count = Functions.getRecordCount(String objectName, String criteria);
Parameters
objectName
The object name or identifier
criteria
A filter expression that specifies records to select, where a field name of the form alias[.alias...].* or alias[.alias...].field indicates a Composite Object search.
Returns
An integer containing a count of records that match the selection criteria.

getRecord

Get a record, with specified fields.

Syntax
Result result = Functions.getRecord(String objectName, String fields, String recordID 
                  {, Parameters params} );
Parameters
objectName
An Object Identifier
fields
The fields to retrieve.
  • A comma-separated list of field names (Use the REST API:field Resource to get a complete list of fields.)
  • The asterisk ("*") wildcard specifies all fields.
  • For related-record fields in a Composite Object, specify the alias of the related object and the field name, where the alias is defined in the Object Relationships:
alias[.alias...].* or alias[.alias...].field
When fetched, an alias becomes a virtual "field" that contains an array of records from the related object, where each record contains the specified field(s).
  • alias.* specifies all fields in the aliased object.
recordID
A Record Id.
params
An optional com.platform.api.Parameters object. Use it to specify the Retrieve Record Permissions Parameter, in order to find out if the user has update or delete permissions on the record.
Return
Result object. If the return code is greater than zero, use the getParameters() method to get a Parameters object with the record's fields. (See the Java Code Samples for multiple examples of the getRecord API.)
For a Composite Object relationship, the relationship alias becomes a "field" in the Parameters object. That field contains an ArrayList of embedded Parameters objects, one for each related record.
Composite Record Example
This example assumes that a relationship has been established between Cases and a Contacts object, where Contact records have an email field and a Lookup to Cases. With that relationship, multiple contacts can be associated with a case. (In this example, the name of the alias relationship is assumed to be "contacts", matching the name of the object.)
// Get the status field and two composite fields for a specified case record.
// Composite fields are identified as <alias>.<field1>, <alias>.<field2>, etc.
// The returned structure contains an array of Parameters for the "alias", where
// each Parameters item contains the fields from a related Contact.
recordID = ...;
Result result = Functions.getRecord("cases", "status,contacts.name,contacts.email", recordID);
if (result != null && result.getCode() == 1)
{
   Parameters params = result.getParameters();
   if (params != null)      
   {
       // Get the case status
       String caseStatus = params.get("status");
       
       // The "contacts" field contains the array of Parameters for associated Contacts.
       // Each entry in the array contains the fields for one record.
       // Here we get just the first entry from the array. (Loop to get them all.)
       ArrayList caseContacts = (ArrayList)params.getObject("contacts");
       HashMap contactParams = (HashMap)caseContacts.get(0); // Get first entry
       String name = (String)contactParams.get("name");      // Get the fields
       String email = (String)contactParams.get("email");  
    }
}


searchRecords

Search and retrieve the records for an object.

Syntax

Result result;
result = Functions.searchRecords (String objectOrView, String fields, String criteria 
                                    {, Parameters params} );

result = Functions.searchRecords (String objectOrView, String fields, String criteria,
                                  String sortBy, String sortOrder, 
                                  String sortBy2, String sortOrder2, 
                                  int offset, int numberOfRows {, Parameters params} );

Notepad.png

Note: Functions.searchRecords checks for roles and application permissions of the logged in user before returning any result. There are multiple joins involved in the query formed which might duplicate the results. We recommend you to use Set interface (Java collection) to store the results.

Parameters

objectOrView
The object name, Object Type Identifier, or Database View ID.
fields
The fields to retrieve.
  • A comma-separated list of field names (Use the REST API:field Resource to get a complete list of fields.)
  • The asterisk ("*") wildcard specifies all fields.
  • For related-record fields in a Composite Object, specify the alias of the related object and the field name, where the alias is defined in the Object Relationships:
alias[.alias...].* or alias[.alias...].field
When fetched, an alias becomes a virtual "field" that contains an array of records from the related object, where each record contains the specified field(s).
  • For fields in a Database View, use the object alias for each field, in the form {alias}.{field}, where the aliases are defined in the specification of the Database View.
criteria
A filter expression that specifies records to select, where field names of the form alias[.alias...].* or alias[.alias...].field are used to specify related-object fields in a Composite Object.
sortBy
Sort the search results on the specified field. Use field names of the form alias[.alias...].* or alias[.alias...].field for related-object fields in a Composite Object.
sortOrder
Specify if the sort order is ascending ("asc") or descending ("desc"). Not case sensitive. The default is ascending.
sortBy2
Do a secondary sort on the specified field. Use field names of the form alias[.alias...].* or alias[.alias...].field for related-object fields in a Composite Object.
sortOrder2
Specify if the sort order on the second level is ascending ("asc") or descending ("desc"). Not case sensitive. The default is ascending.
offset
The maximum number of records that you can retrieve in a single call to searchRecords is 5,000. If you need to retrieve more than 5,000 records, you must set up a loop where you do paging by incrementing the offset parameter.
For example, if you need to retrieve 25,000 records, you need to set the offset parameter to zero (0) and the numberOfRows parameter to 5,000 on the first pass to get records 1-5000. Then, on the second pass, you set offset to 1 to get records 5001-10,000, and so on. In other words, you multiply offset by numberOfRows and add one to determine the number of the first record retrieved at each pass.
numberOfRows
The maximum number of records to return
params
An optional com.platform.api.Parameters object. Use it to specify the Retrieve Record Permissions Parameter, in order to find out if the user has update or delete permissions on the records.
alias.* specifies all fields in the aliased object.

Returns

Result object. If the return code is greater than zero, use the Result_Class#getIterator method to cycle through the list of Parameters objects it contains, one per record.

Learn More

Retrieved from "https://agileappscloud.info/aadev-src/index.php?title=Java_API:Composite_Objects&oldid=12739"