Foundations Apex API Developer Reference

fferpcore.VirtualDataObject

global with sharing class VirtualDataObject

The Virtual Data Object represents a business object, for example the Virtual Master Order Object. This business object can be backed by any form of underlying object through a Provider. This allows the system administrator to choose how objects such as Orders are formed. The shape of a virtual object is defined in terms of the keys that are used to access its data. For example a Master Order may have a Document Date, Lines, an AccountId, Products. The Provider translates these names into the names used by its underlying data source.

The Virtual Data Object interface follows a similar pattern to FinancialForce Foundations' Data Source and Data Target interfaces. Data access occurs in two phases:

Consumers of the Virtual Object use the Prepare Phase to indicate which data fields and relationships they require. The Virtual Object may be used by multiple consumers. Each will use PreparableSource's require() methods.

The controller will create a Work Scope and call the Provider's getRecords() method to query the database. The resulting RecordList is used by the consumers to work with the data. The controller will then commit the Work Scope in order to write any changes to the underlying database in a single operation. The Work Scope is used within a try-finally-dispose block according to the fferpcore.Disposable Pattern.

Errors are fed back through an ErrorListener interface. This presents the errors in the language of the Virtual Document. For example the error may be "The Document Date cannot be in the future", rather than the language of the underlying data store "Document__c.DocumentDate__c cannot be in the future". Any error on a root Record or any Record navigated from it will prevent all changes to that Record and those descended from it to be rolled back.

This version of the Virtual Document interface does not define behaviour or directly support modifications through lookups.

The system does not guarantee Identity Map behaviour for lookups. This means that if the same lookup is referenced by multiple records, for example multiple Documents referring to the same AccountId, that changes made to the Account from one Document will not be guaranteed to be reflected when read back from another Document. The rollback behaviour of changes to objects navigated through lookups is also not defined in this version. FinancialForce implementations will return false for the Accessible interface's supportsWrite() method in this case and will reject attempts to make changes.

The system does not isolate consumers from each other. They see eachother's changes.

Virtual Data Objects are self describing using the describe methods on the PreparableSource interface.

fferpcore.VirtualDataObject.Consumer

global interface Consumer

Capable of preparing a Provider before getting Records, and processing the resulting Records.

Methods

prepare

void prepare(fferpcore.VirtualDataObject.Provider provider)

Prepare the given Provider for future processing.

Input Parameters

Name Type Description
provider fferpcore.VirtualDataObject.Provider The Provider to be prepared.

consume

void consume(fferpcore.VirtualDataObject.RecordList recordList)

Process the given RecordList.

Input Parameters

Name Type Description
recordList fferpcore.VirtualDataObject.RecordList The RecordList to be processed.

fferpcore.VirtualDataObject.WorkScope

global interface WorkScope extends Disposable

Collection of work that can be committed.

This class extends fferpcore.Disposable

Methods

commitPendingWork

Map<String, VirtualDataObject.CommitResult> commitPendingWork(Atomicity atomicity)

Commit any pending work. Atomicity has to be REQUIRE_ALL in Foundations version 4.2.

Input Parameters

Name Type Description
atomicity Atomicity Does this commit operation allow partial success, or do all Records need to be successfully committed?

Return Value

Map of CommitResults keyed by the corresponding Record ID.

fferpcore.VirtualDataObject.CommitResult

global interface CommitResult

The result of committing a Record. Returned when comitting a WorkScope, keyed by the Record ID.

Methods

getRecordId

String getRecordId()

Return Value

The ID of the Record that was committed.

isSuccess

Boolean isSuccess()

Return Value

True if the Record was successfully committed.

fferpcore.VirtualDataObject.ProviderKey

global class ProviderKey implements ObjectIO.ActivatableObject2

The Provider Key identifies a Virtual Data Object Provider. The key consists of the Virtual Data Object Name and name of the provider that backs the data. For example a "Master Order Object" may be backed by "Salesforce Order via FinancialForce Foundations".
Any two Providers with the same Provider Key are compatible. This means that it is possible to combine these into a single provider with the union of the two provider's key sets.

Methods

ProviderKey

global ProviderKey(String virtualDataObjectName, String providerName)

Construct a ProviderKey with the given virtual object and provider.

Input Parameters

Name Type Description
virtualDataObjectName String Name of the virtual object.
providerName String Name of the provider.

getVirtualDataObjectName

global String getVirtualDataObjectName()

Return Value

The name of the virtual object.

getProviderName

global String getProviderName()

Return Value

The name of the provider.

fferpcore.VirtualDataObject.ProviderFactory

global interface ProviderFactory

Capable of creating a Provider and validating record IDs.

Methods

init

void init(fferpcore.VirtualDataObject.ProviderKey key, String initData)

Initialise the factory with the given ProviderKey and data.

Input Parameters

Name Type Description
key fferpcore.VirtualDataObject.ProviderKey The specified ProviderKey.
initData String The data to create the provider with.

ownsRecord

Boolean ownsRecord(String recordId)

Determine if the given record ID is valid for the provider.

Input Parameters

Name Type Description
recordId String The record ID to validate.

Return Value

True if the provider supports the given record ID.

createProvider

VirtualDataObject.Provider createProvider(Set<String> recordIds, SharingModel sharingModel)

Create a provider using the given record IDs, and sharing model.

Input Parameters

Name Type Description
recordIds Set<String> The IDs of the records that the provider will obtain.
sharingModel SharingModel The policy in regard to sharing rules, used by the provider.

Return Value

The created Provider instance.

fferpcore.VirtualDataObject.Provider

global interface Provider extends PreparableSource

Capable of providing Records and a WorkScope to commit any changes to them. Extends PreparableSource so can also require data.

This class extends fferpcore.VirtualDataObject.PreparableSource

Methods

createWorkScope

VirtualDataObject.WorkScope createWorkScope()

Return Value

A WorkScope capable of committing changes to the Records.

getRecords

VirtualDataObject.RecordList getRecords()

Return Value

A list of Records which will be populated with all required fields.

addSourceErrorListener

void addSourceErrorListener(fferpcore.VirtualDataObject.ErrorListener listener)

Add a listener to be notified when an error is added to a source Record.

Input Parameters

Name Type Description
listener fferpcore.VirtualDataObject.ErrorListener ErrorListener to be invoked on each error.

addErrorListener

void addErrorListener(fferpcore.VirtualDataObject.ErrorListener listener)

Add a listener to be notified when an error is added to a Record.

Input Parameters

Name Type Description
listener fferpcore.VirtualDataObject.ErrorListener ErrorListener to be invoked on each error.

addError

void addError(String errorMessage)

Add an error to the Provider.

Input Parameters

Name Type Description
errorMessage String A description of the error.

fferpcore.VirtualDataObject.ErrorListener

global interface ErrorListener

Capable of handling errors added to Records.

Methods

onError

void onError(fferpcore.VirtualDataObject.ErrorEvent e)

Handle the specified error message added to the record.

Input Parameters

Name Type Description
e fferpcore.VirtualDataObject.ErrorEvent Error event information

hashCode

Integer hashCode()

Listeners must support Set operations to allow prevention of repeat additions.

equals

Boolean equals(Object other)

Listeners must support Set operations to allow prevention of repeat additions.

fferpcore.VirtualDataObject.ErrorEvent

global interface ErrorEvent

Information about an error.

Methods

getMessage

String getMessage()

Return Value

The error message. Example 'Product cannot be null.'

getErrorRecord

Record getErrorRecord()

Return Value

The record on which the error was raised. Example: Line 10

getErrorKey

String getErrorKey()

Return Value

The key of the field, lookup or child relationship on the record. Example: 'Product'

getRootRecord

Record getRootRecord()

Return Value

The record that the listener is registered with. if the listener is registered with a Provider or RecordList return the record within that list.

getErrorPathTargetType

Path2.TargetType getErrorPathTargetType()

Return Value

The type of thing that the error applies to.

getPath

Path2.Element getPath()

Return Value

The start of the path from the object that the listener was registered on to the error. If the error is on a field on the observed object then the path will point to the field. If the error applies to the observed object itself then the path will be null.

fferpcore.VirtualDataObject.PreparableSource

global interface PreparableSource

Capable of being prepared by requiring keys. Can also be described to determine associated fields.

Methods

describe

VirtualDataObject.ObjectDescribe describe()

Return Value

The description of the PreparableSource. This includes associated fields, lookups, and child relationships.

requireField

void requireField(String key, Intent intent)

Require any data associated with the specified key.

Input Parameters

Name Type Description
key String The key corresponding to the data to require.
intent Intent The purpose of requiring the data, for example to read or write.

requireLookup

VirtualDataObject.PreparableSource requireLookup(String key, Intent intent)

Require any lookup data associated with the specified key.

Input Parameters

Name Type Description
key String The key corresponding to the lookup data to require.
intent Intent The purpose of requiring the data, for example to read or write.

Return Value

A PreparableSource representing the lookup object.

requireChildren

VirtualDataObject.PreparableSource requireChildren(String key, Intent intent)

Require any child data associated with the specified key.

Input Parameters

Name Type Description
key String The key corresponding to the child data to require.
intent Intent The purpose of requiring the data, for example to read or write.

Return Value

A PreparableSource representing the child object.

fferpcore.VirtualDataObject.RecordList

global interface RecordList extends Iterable<Record>

An iterable collection of Records.

Methods

size

Integer size()

Return Value

Number of Records in the list.

get

VirtualDataObject.Record get(Integer index)

Input Parameters

Name Type Description
index Integer Position of the Record to get.

Return Value

Record at the given position in the list.

create

VirtualDataObject.Record create()

Create a new Record and add it to the list.

Return Value

The created Record.

destroyAll

void destroyAll()

Remove all Records from the list. All remove records will be deleted from the database on commit.

addErrorListener

void addErrorListener(fferpcore.VirtualDataObject.ErrorListener errorListener)

Add a listener to be notified when an error is added to the RecordList.

Input Parameters

Name Type Description
errorListener fferpcore.VirtualDataObject.ErrorListener The ErrorListener to be invoked with each error.

addError

void addError(String errorMessage)

Add an error to the RecordList.

Input Parameters

Name Type Description
errorMessage String A description of the error.

fferpcore.VirtualDataObject.Record

global interface Record

A collection of mutable data containing an ID, and multiple fields, each with a single value.

Methods

getId

String getId()

Return Value

A string that uniquely identifies the Record.

get

Object get(String key)

Input Parameters

Name Type Description
key String The key of the desired data.

Return Value

The data with the specified key.

getOptional

OptionalValue getOptional(String key)

Input Parameters

Name Type Description
key String The key of the desired data.

Return Value

Null if the key was not found, otherwise an OptionValue containing the corresponding data.

getLookupRecord

VirtualDataObject.Record getLookupRecord(String key)

Input Parameters

Name Type Description
key String The key of the desired lookup data.

Return Value

The lookup data with the specified key.

getLookupRecordOptional

OptionalValue getLookupRecordOptional(String key)

Input Parameters

Name Type Description
key String The key of the desired lookup data.

Return Value

Null if the lookup data was not found, otherwise an OptionalValue containing the lookup data.

getChildRecords

VirtualDataObject.RecordList getChildRecords(String key)

Input Parameters

Name Type Description
key String The key of the desired children data.

Return Value

The children data with the specified key.

put

void put(String key, Object value)

Set the data associated with the specified key.

Input Parameters

Name Type Description
key String The key of the data to set.
value Object The data to be set.

addErrorListener

void addErrorListener(fferpcore.VirtualDataObject.ErrorListener errorListener)

Add a listener to be notified when an error is added to the Record.

Input Parameters

Name Type Description
errorListener fferpcore.VirtualDataObject.ErrorListener The ErrorListener to be invoked with each error.

addError

void addError(String key, String errorMessage)

Add an error to the record.

Input Parameters

Name Type Description
key String The key of the field that caused the error.
errorMessage String A description of the error.

hasError

Boolean hasError()

Return Value

True if any errors have been added to the Record.

fferpcore.VirtualDataObject.SObjectRecord

global interface SObjectRecord extends Record

A record backed by an SObject.

This class extends fferpcore.VirtualDataObject.Record

Methods

getSObject

SObject getSObject()

Return Value

The SObject instance that backs this record.

fferpcore.VirtualDataObject.ObjectDescribe

global interface ObjectDescribe extends Accessible

Description of an object including available fields, lookups and child relationships. This extends Accessible so also includes the associated permissions.

This class extends fferpcore.VirtualDataObject.Accessible

Methods

getObjectName

String getObjectName()

Return Value

The name of the object being described.

getFields

Map<String, VirtualDataObject.FieldDescribe> getFields()

Return Value

A map of available field descriptions by key. Where a field is a lookup the description here refers to the foreign key itself, not the result of traversing it.

getLookups

Map<String, VirtualDataObject.LookupDescribe> getLookups()

Return Value

A map of available lookup descriptions by key.

getChildRelationships

Map<String, VirtualDataObject.ChildRelationshipDescribe> getChildRelationships()

Return Value

A map of available child relationship descriptions by key.

fferpcore.VirtualDataObject.FieldDescribe

global interface FieldDescribe extends DescribeBase

Description of a field including the associated permissions.

Methods

getDataType

DataType getDataType()

Return Value

The data type of the field.

fferpcore.VirtualDataObject.LookupDescribe

global interface LookupDescribe extends DescribeBase

Description of a lookup including the associated permissions. The Accessibility of the lookup itself refers to the foreign key field on the source object.

Methods

getTarget

VirtualDataObject.ObjectDescribe getTarget()

Return Value

Description of the object this lookup points to.

fferpcore.VirtualDataObject.ChildRelationshipDescribe

global interface ChildRelationshipDescribe extends DescribeBase

Description of a child relationship including the associated permissions.

Methods

getTarget

VirtualDataObject.ObjectDescribe getTarget()

Return Value

Description of the child object.

fferpcore.VirtualDataObject.Accessible

global interface Accessible

Capable of reporting what access is available based on current permissions.

Methods

supportsWrite

Boolean supportsWrite()

Return Value

True if it possible to write to this object regardless of permissions. Derived values, autonumbers, and some keys, are never writable.

hasReadAccess

Boolean hasReadAccess()

Return Value

True if this object can be read.

hasEditAccess

Boolean hasEditAccess()

Return Value

True if this object can be edited.

hasCreateAccess

Boolean hasCreateAccess()

Return Value

True if this object can be created.

hasDeleteAccess

Boolean hasDeleteAccess()

Return Value

True if this object can be deleted.

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