Foundations Apex API Developer Reference

fferpcore.DataSource

global with sharing abstract class DataSource

The fferpcore.DataSource class is used to collate all of the fields required for a message and generate a query to obtain the values. It represents a list of input records for use with message generation. fferpcore.DataSource instances are used with the fferpcore.MessageDescriptionService to provide data from which to build messages. The service will use the fferpcore.MessageDescription to prepare the fferpcore.DataSource by asking it to require fields, lookups and one to many relationships. It will then query the fferpcore.DataSource and use the fferpcore.MessageDescription to generate the messages.

Methods

requireField

global virtual void requireField(SObjectField field)

Requires that this data source queries the field provided. This method is called by the Declarative Publish framework or by custom message Nodes during the preparation phase of declarative message building.

Input Parameters

Name Type Description
field SObjectField A field to be included in the query.

Sample Code

//Note: This sample code is for demonstration purposes only. It is not intended for
//use in a production environment, is not guaranteed against defects or errors, and
//is in no way optimized or streamlined.

// Given a datasource for Department__c, find the department name.
departmentDataSource.requireField(Department__c.Name);

requireField

global virtual void requireField(String fieldName)

This method is called by the Declarative Publish framework or by custom message Nodes during the preparation phase of declarative message building.

Input Parameters

Name Type Description
fieldName String A field to be included in the query.

Sample Code

//Note: This sample code is for demonstration purposes only. It is not intended for
//use in a production environment, is not guaranteed against defects or errors, and
//is in no way optimized or streamlined.

// Given a datasource for Department__c, find the department name.
departmentDataSource.requireField(Department__c.Name);

requireField

global virtual void requireField(String fieldName, Intent intent)

Ensure the given field is included in the data.

Input Parameters

Name Type Description
fieldName String Name of the field to be included.
intent Intent Why is the field being included? Read, write, or both.

require

global virtual void require(fferpcore.Path path)

Requires that this data source queries the path provided. This method is called by the Declarative Publish framework or by custom message Nodes during the preparation phase of declarative message building.

Input Parameters

Name Type Description
path fferpcore.Path A Path to be included in the query.

requireLookupField

global abstract fferpcore.DataSource requireLookupField(SObjectField field)

Requires that this data source queries the lookup provided. This method is called by the Declarative Publish framework or by custom message Nodes during the preparation phase of declarative message building.

Input Parameters

Name Type Description
field SObjectField The field representing the lookup

Return Value

A DataSource representing the target of the lookup.

Sample Code

//Note: This sample code is for demonstration purposes only. It is not intended for
//use in a production environment, is not guaranteed against defects or errors, and
//is in no way optimized or streamlined.

// Given a Worker__c that has a Department__c, find the department name.
fferpcore.DataSource departmentDataSource = workerDataSource.requireLookupField(Worker__c.Department__c);
departmentDataSource.requireField(Department__c.Name);

requireLookupField

global virtual fferpcore.DataSource requireLookupField(String name)

Requires that this data source queries the lookup provided by its name. This method is called by the Declarative Publish framework or by custom message Nodes during the preparation phase of declarative message building.
This method was added in Foundations version 4.0. The default implementation returns null.

Input Parameters

Name Type Description
name String The field representing the lookup

Return Value

A DataSource representing the target of the lookup or null if one cannot be found.

Sample Code

//Note: This sample code is for demonstration purposes only. It is not intended for
//use in a production environment, is not guaranteed against defects or errors, and
//is in no way optimized or streamlined.

// Given a Worker__c that has a Department__c, find the department name.
fferpcore.DataSource departmentDataSource = workerDataSource.requireLookupField(Worker__c.Department__c);
departmentDataSource.requireField(Department__c.Name);

requireLookupField

global virtual fferpcore.DataSource requireLookupField(String name, Intent intent)

Ensure the given lookup is included in the data.

Input Parameters

Name Type Description
name String Name of the lookup to be included.
intent Intent Why is the lookup being included? Read, write, or both.

Return Value

The DataSource of the related data.

requireOneToManyField

global virtual fferpcore.DataSource requireOneToManyField(fferpcore.DataSource.BackReference backReference)

Ask that this data source to query the given Master/Detail relationship. This method is called by the Declarative Publish framework or by custom message Nodes during the preparation phase of declarative message building.

Input Parameters

Name Type Description
backReference fferpcore.DataSource.BackReference A description of the relationship as viewed from the defining "Many" Detail end.

Return Value

A DataSource representing the target of the lookup.

Sample Code

//Note: This sample code is for demonstration purposes only. It is not intended for
//use in a production environment, is not guaranteed against defects or errors, and
//is in no way optimized or streamlined.

// Given a Deparment__c find the Employee payroll numbers.
fferpcore.DataSource employeeDataSource = departmentDataSource.requireOneToManyField(
    new fferpcore.DataSource.BackReference(Worker__c.SObjectType, Worker__c.Department__c)
);
employeeDataSource.requireField(Worker__c.PayrollNumber__c);

requireOneToManyField

global virtual fferpcore.DataSource requireOneToManyField(String name)

Ensure the given child data is included in the data.

Input Parameters

Name Type Description
name String Name of the child data to be included.

Return Value

The DataSource of the child data.

requireOneToManyField

global virtual fferpcore.DataSource requireOneToManyField(String name, Intent intent)

Ensure the given child data is included in the data.

Input Parameters

Name Type Description
name String Name of the child data to be included.
intent Intent Why is the child data being included? Read, write, or both.

Return Value

The DataSource of the child data.

runQuery

global abstract Iterator<fferpcore.DataSource.Row> runQuery()

Load the data. This must only be performed on the top level DataSource, not any of the DataSources returned by the requireLookupField or requireOneToManyField methods. This method will be called by the Declarative Publish framework.

Return Value

An iterator of fferpcore.DataSource.Row objects containing the required data.

Sample Code

//Note: This sample code is for demonstration purposes only. It is not intended for
//use in a production environment, is not guaranteed against defects or errors, and
//is in no way optimized or streamlined.

public class ExampleDataSource extends fferpcore.DataSource
{
    private Set<SObjectField> m_fields;

    public ExampleDataSource()
    {
    }

    public override void requireField(SObjectField field)
    {
        m_fields.add(field);
    }

    public override Iterator<fferpcore.DataSource.Row> runQuery()
    {
        // Run SOQL to retrieve the data in m_fields
    }

}

ExampleDataSource source = new ExampleDataSource();
source.requireField(Account.Name);
source.requireField(Account.AccountNumber);
Iterator<fferpcore.DataSource.Row> rows = source.runQuery();
//use rows to construct a message

fferpcore.DataSource.Row

global abstract class Row implements Navigable

A Row in the result set of the Data Source.

This class implements the following interfaces:

Methods

getFieldValue

global abstract Object getFieldValue(SObjectField field)

Input Parameters

Name Type Description
field SObjectField The field to read. The field should have been previously requested using DataSource's requireField method.

Return Value

The value of the given field. If the field has not previously been requested, the behavior of this method is not guaranteed.

Sample Code

//Note: This sample code is for demonstration purposes only. It is not intended for
//use in a production environment, is not guaranteed against defects or errors, and
//is in no way optimized or streamlined.

trigger ExampleTrigger on Order (before insert) 
{
    fferpcore.TriggerDataSource source = new fferpcore.TriggerDataSource(Records);
    fferpcore.DataSource userDataSource = source.requireField(Order.CreatedBy); 
    userDataSource.requireField(User.Email);

    Iterator<fferpcore.DataSource.Row> dataSourceRowIterator = source.runQuery(); // runQuery should call runQuery on related data sources. E.g. on userDataSource

    while(dataSourceRowIterator.hasNext())
    {
        fferpcore.DataSource.Row orderSourceRow = dataSourceRowIterator.next();
        fferpcore.DataSource.Row userSourceRow = orderSourceRow.getRelation(Order.CreatedBy);
        String createdByEmail = userSourceRow.getField(User.Email);

        //Create and send a message with the email in it.
    }
}

getFieldValue

global virtual Object getFieldValue(String field)

Gets the value of a field using the field name string provided. This method was added in FinancialForce Foundations version 3.1. The base class implementation returns null.

Input Parameters

Name Type Description
field String The field to read. The field should have been previously requested using DataSource's requireField method.

Return Value

The value of the given field. If the field has not previously been requested, the behavior of this method is not guaranteed.

Sample Code

//Note: This sample code is for demonstration purposes only. It is not intended for
//use in a production environment, is not guaranteed against defects or errors, and
//is in no way optimized or streamlined.

trigger ExampleTrigger on Order (before insert) 
{
    fferpcore.TriggerDataSource source = new fferpcore.TriggerDataSource(Records);
    fferpcore.DataSource userDataSource = source.requireField(Order.CreatedBy); 
    userDataSource.requireField(User.Email);

    Iterator<fferpcore.DataSource.Row> dataSourceRowIterator = source.runQuery(); // runQuery should call runQuery on related data sources. E.g. on userDataSource

    while(dataSourceRowIterator.hasNext())
    {
        fferpcore.DataSource.Row orderSourceRow = dataSourceRowIterator.next();
        fferpcore.DataSource.Row userSourceRow = orderSourceRow.getRelation(Order.CreatedBy);
        String createdByEmail = userSourceRow.getField(User.Email);

        //Create and send a message with the email in it.
    }
}

getRelation

global abstract fferpcore.DataSource.Row getRelation(SObjectField field)

Input Parameters

Name Type Description
field SObjectField The lookup field of the relation. This field should have previously been requested using DataSource's requireLookupField() method.

Return Value

A Row representing the requested object, or null if the lookup is null. If the field has not previously been requested, the behavior of this method is not guaranteed.

Sample Code

//Note: This sample code is for demonstration purposes only. It is not intended for
//use in a production environment, is not guaranteed against defects or errors, and
//is in no way optimized or streamlined.

trigger ExampleTrigger on Order (before insert) 
{
    fferpcore.TriggerDataSource source = new fferpcore.TriggerDataSource(Records);
    fferpcore.DataSource userDataSource = source.requireField(Order.CreatedBy); 
    userDataSource.requireField(User.Email);

    Iterator<fferpcore.DataSource.Row> dataSourceRowIterator = source.runQuery(); // runQuery should call runQuery on related data sources. E.g. on userDataSource

    while(dataSourceRowIterator.hasNext())
    {
        fferpcore.DataSource.Row orderSourceRow = dataSourceRowIterator.next();
        fferpcore.DataSource.Row userSourceRow = orderSourceRow.getRelation(Order.CreatedBy);
        String createdByEmail = userSourceRow.getField(User.Email);

        //Create and send a message with the email in it.
    }
}

getRelation

global virtual fferpcore.DataSource.Row getRelation(String fieldName)

Input Parameters

Name Type Description
fieldName String The name of the lookup field of the relation. This field should have previously been requested using DataSource's requireLookupField() method.

Return Value

A Row representing the requested object, or null if the lookup is null. If the field has not previously been requested, the behavior of this method is not guaranteed.

Sample Code

//Note: This sample code is for demonstration purposes only. It is not intended for
//use in a production environment, is not guaranteed against defects or errors, and
//is in no way optimized or streamlined.

trigger ExampleTrigger on Order (before insert) 
{
    fferpcore.TriggerDataSource source = new fferpcore.TriggerDataSource(Records);
    fferpcore.DataSource userDataSource = source.requireField(Order.CreatedBy); 
    userDataSource.requireField(User.Email);

    Iterator<fferpcore.DataSource.Row> dataSourceRowIterator = source.runQuery(); // runQuery should call runQuery on related data sources. E.g. on userDataSource

    while(dataSourceRowIterator.hasNext())
    {
        fferpcore.DataSource.Row orderSourceRow = dataSourceRowIterator.next();
        fferpcore.DataSource.Row userSourceRow = orderSourceRow.getRelation(Order.CreatedBy);
        String createdByEmail = userSourceRow.getField(User.Email);

        //Create and send a message with the email in it.
    }
}

getOneToMany

global virtual Iterator<fferpcore.DataSource.Row> getOneToMany(fferpcore.DataSource.BackReference backReference)

Input Parameters

Name Type Description
backReference fferpcore.DataSource.BackReference A representation of the lookup from the Detail back to the Master. This should have previously been requested using DataSource's requireOneToManyField() method.

Return Value

An iterator of Rows representing the detail records for this master record. An empty iterator is returned if there are no detail rows. If the field has not previously been requested, the behavior of this method is not guaranteed.

Sample Code

//Note: This sample code is for demonstration purposes only. It is not intended for
//use in a production environment, is not guaranteed against defects or errors, and
//is in no way optimized or streamlined.

// Given a Deparment__c find the Employee payroll numbers.
new fferpcore.DataSource.BackReference workerDepartmentBackRef = new new fferpcore.DataSource.BackReference(Worker__c.SObjectType, Worker__c.Department__c);
fferpcore.DataSource employeeDataSource = departmentDataSource.requireOneToManyField(workerDepartmentBackRef);
employeeDataSource.requireField(Worker__c.PayrollNumber__c);

Iterator<fferpcore.DataSource.Row> departmentRows = departmentDataSource.runQuery();
while(departmentRows.hasNext())
{
    fferpcore.DataSource.Row departmentRow = departmentRows.next();
    Iterator<fferpcore.DataSource.Row> workerRows = departmentRow.getOneToMany(workerDepartmentBackRef);
    //Do something with all the workers in this department.
}

getOneToMany

global virtual Iterator<fferpcore.DataSource.Row> getOneToMany(String fieldName)

Obtain the child data with the given name.

Input Parameters

Name Type Description
fieldName String Name of the child data field.

Return Value

An iterator of each child DataSource.Row.

getValue

global virtual Object getValue(fferpcore.Path path)

Locates a specific value in the row at the given path.

Input Parameters

Name Type Description
path fferpcore.Path The location of the value in the row.

Return Value

The specific value at the given path.

put

global virtual void put(String fieldName, Object data)

Set the data of the given field.

Input Parameters

Name Type Description
fieldName String Name of the field.
data Object Data to be set.

addError

global virtual void addError(String fieldName, String errorMessage)

Add an error to the given field.

Input Parameters

Name Type Description
fieldName String Name of the field.
errorMessage String Description of the error.

fferpcore.DataSource.BackReference

global virtual class BackReference

Specifies the way in which a detail object relates to its master. Contains the detail ObjectType and lookup field. Designed for use as a key in maps. This class is immutable.

Methods

BackReference

global BackReference(SObjectType detailObjectType, SObjectField detailToMasterLookupField)

Input Parameters

Name Type Description
detailObjectType SObjectType The object type on the detail end of the link.
detailToMasterLookupField SObjectField The field on detailObjectType that references the master.

Sample Code

//Note: This sample code is for demonstration purposes only. It is not intended for
//use in a production environment, is not guaranteed against defects or errors, and
//is in no way optimized or streamlined.

// Given the Account and Contact objects...
DataSource.BackReference backReference = new DataSource.BackReference(Contact, Contact.AccountId);

// The detail object type and detail to master lookup field are as provided.
System.assertEquals(Contact,  backReference.getDetailObjectType());
System.assertEquals(Contact.AccountId,  backReferene.getDetailToMasterLookupField());

// The master object is Account. The primary key field is Account.Id
System.assertEquals(Account.Id, backReference.getPrimaryKeyField());

getDetailObjectType

global SObjectType getDetailObjectType()

Return Value

The object type at the detail end of the link. See constructor for example use.

getDetailToMasterLookupField

global SObjectField getDetailToMasterLookupField()

Return Value

The field that the detail uses to reference its master. See constructor for example use.

getParentObjectType

global virtual SObjectType getParentObjectType()

Return Value

The parent SObjectType, if provided.

getPrimaryKeyField

global virtual SObjectField getPrimaryKeyField()

Return Value

The primary key field on the Master side of the relationship. The field that the back reference points to. This will be the ID field on the master. See constructor for example use.

equals

global virtual Boolean equals(Object other)

Implementation of the Equals method. Returns true if 'other' is an identical BackReference.

hashCode

global virtual Integer hashCode()

Implementation of the hashCode() method allowing use as Map keys and Set values. Hash codes returned are only expected to be stable within one execution context and cannot be shared across execution contexts. This may impact any attempt to serialise a Map or Set containing BackReferences.

© Copyright 2009–2022 FinancialForce.com, inc. All rights reserved. Various trademarks held by their respective owners.