Java API:Composite Objects

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

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

int count = Functions.getRecordCount(String objectName, String criteria); </syntaxhighlight>

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

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

Result result = Functions.getRecord(String objectName, String fields, String recordID

                 {, Parameters params} );

</syntaxhighlight>

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

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

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

} </syntaxhighlight>

searchRecords

Search and retrieve the records for an object.

Syntax

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

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

</syntaxhighlight>

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

• Filter Expressions in JAVA APIs
• searchRecords