Final Class: JoiningDataProvider

Oracle® JavaScript Extension Toolkit (JET)
11.1.0

F37999-01

Since:
  • 10.0.0
Module:
  • ojjoiningdataprovider

QuickNav

Description

JoiningDataProvider is a wrapping DataProvider that performs client-side joins from a base data provider to other data providers and returns the joined records.

Whenever possible, server-side joins are encouraged. If FetchByKeysCapability.implementation on joined DataProvider is not 'batchLookup', using JoiningDataProvider may encounter performance issue.

In addition to the base data provider's attributes, the fetch methods' parameter of a JoiningDataProvider can also take joined data providers' attributes in the 'attributes' option. If no attributes are provided, all fields will be returned.


Usage

Signature:

final class JoiningDataProvider<K, D extends BD, BD> implements DataProvider<K, D>

Generic Parameters
ParameterDescription
KType of key
DType of returned data
BDType of base data
Typescript Import Format
//This class is exported directly as module. To import it
import JoiningDataProvider= require("ojs/ojjoiningdataprovider");

For additional information visit:


Final classes in JET

Classes in JET are generally final and do not support subclassing. At the moment, final is not enforced. However, this will likely change in an upcoming JET release.


Constructor

new JoiningDataProvider(baseDataProvider, options)

Parameters:
Name Type Description
baseDataProvider DataProvider.<K, BD> The base data provider.

The metadata from this data provider will be the metadata for the JoiningDataProvider, and all data from this data provider will be part of the data for the JoiningDataProvider.

The resulting data for the JoiningDataProvider will be the set of attributes from the base data provider, plus the set of attributes specified by the "joins" option. Data returned by each data provider specified in the "joins" options will be merged into the JoiningDataProvider as an object.

options JoiningDataProvider.Options<D, BD> | JoiningDataProvider.DataProviderOptions.<D, BD> Options for the JoiningDataProvider.
Example
let employee = [
  { id: 1001, departmentId: 2001, managerId: 1011, firstName: "Chris", lastName: "Black", title: "Software Engineer" },
  { id: 1011, departmentId: 2002, managerId: 1021, firstName: "Jenifer", lastName: "Cooper", title: "Manager" },
  { id: 1021, departmentId: 2003, managerId: 1031, firstName: "Kurt", lastName: "Jonhson", title: "VP" },
  { id: 1022, departmentId: 2003, managerId: 1031, firstName: "Mike", lastName: "Chrison", title: "VP", manager: { firstName: "Guangping", lastName: null } }
];
let department = [
  { id: 2001, locationId: 1, VPId: 1021, name: "JET" },
  { id: 2002, locationId: 1, VPId: 1022, name: "Visual Builder" }
];
let location = [
  { id: 1, city: "Redwood City", state: "California" }
];

// initialize basic DataProvider
let dpEmployee = new ArrayDataProvider(employee, { keyAttributes: 'id' });
let dpDepartment = new ArrayDataProvider(department, { keyAttributes: 'id' });
let dpLocation = new ArrayDataProvider(location, { keyAttributes: 'id' });

// join for department
let locJoin = { foreignKeyMapping: { foreignKey: 'locationId' }, joinedDataProvider: dpLocation };
let VPJoin = { foreignKeyMapping: { foreignKey: 'VPId' }, joinedDataProvider: dpEmployee };
let dpJoinDepartment = new JoiningDataProvider(dpDepartment,
  { joins: { location: locJoin, VP: VPJoin } });

let deptJoin = { foreignKeyMapping: { foreignKey: 'departmentId' }, joinedDataProvider: dpJoinDepartment };
let mgrJoin = { foreignKeyMapping: { foreignKey: 'managerId' }, joinedDataProvider: dpEmployee };

this.dpJoinEmployee = new JoiningDataProvider(dpEmployee,
  { joins: { manager: mgrJoin, department: deptJoin } });

// Using joined dataprovider attributes for fetch methods
// The returned fields will include all fields from base data provider and department plus title from manager.
this.dpJoinEmployee.fetchByOffset({ offset: 0, attributes: ['manager.title'] });

Methods

addEventListener(eventType: string, listener: EventListener): void

Add a callback function to listen for a specific event type.
Parameters:
Name Type Description
eventType string The event type to listen for.
listener EventListener The callback function that receives the event notification.

containsKeys(parameters : FetchByKeysParameters<K>) : Promise<ContainsKeysResults<K>>

Check if there are rows containing the specified keys. The resulting key map will only contain keys which were actually found.
Parameters:
Name Type Description
parameters FetchByKeysParameters contains by key parameters
Since:
  • 4.2.0
Returns:
Returns Promise which resolves to ContainsKeysResults.
Type
Promise.<ContainsKeysResults>
Example

Check if keys 1001 and 556 are contained

let keySet = new Set();
keySet.add(1001);
keySet.add(556);

let value = await dataprovider.containsKeys({keys: keySet});
let results = value['results'];
if (results.has(1001)) {
  console.log('Has key 1001');
} else if (results.has(556){
  console.log('Has key 556');
}

createOptimizedKeyMap(initialMap?: Map<K, D>): Map<K, D>

Return an empty Map which is optimized to store key value pairs

Optionally provided by certain DataProvider implementations for storing key/value pairs from the DataProvider in a performant fashion. Sometimes components will need to temporarily store a Map of keys provided by the DataProvider, for example, in the case of maintaining a Map of selected keys. Only the DataProvider is aware of the internal structure of keys such as whether they are primitives, Strings, or objects and how to do identity comparisons. Therefore, the DataProvider can optionally provide a Map implementation which can performantly store key/value pairs surfaced by the DataProvider.

Parameters:
Name Type Argument Description
initialMap Map.<any> <optional>
Optionally specify an initial map of key/values for the Map. If not specified, then return an empty Map.
Since:
  • 6.2.0
Returns:
Returns a Map optimized for handling keys from the DataProvider.
Type
Map.<any>
Example

create empty key Map

// create optional parameter
let initMap = new Map();
initMap.set('a', 'apple');
let keyMap = dataprovider.createOptimizedKeyMap(initMap);

createOptimizedKeySet(initialSet?: Set<K>): Set<K>

Return an empty Set which is optimized to store keys

Optionally provided by certain DataProvider implementations for storing keys from the DataProvider in a performant fashion. Sometimes components will need to temporarily store a Set of keys provided by the DataProvider, for example, in the case of maintaining a Set of selected keys. Only the DataProvider is aware of the internal structure of keys such as whether they are primitives, Strings, or objects and how to do identity comparisons. Therefore, the DataProvider can optionally provide a Set implementation which can performantly store keys surfaced by the DataProvider.

Parameters:
Name Type Argument Description
initialSet Set.<any> <optional>
Optionally specify an initial set of keys for the Set. If not specified, then return an empty Set.
Since:
  • 6.2.0
Returns:
Returns a Set optimized for handling keys from the DataProvider.
Type
Set.<any>
Example

create empty key Set

// create optional initial parameter
let initSet = new Set();
initSet.add('a');
let keySet = dataprovider.createOptimizedKeySet(initSet);

dispatchEvent(evt: Event): boolean

Dispatch an event and invoke any registered listeners.
Parameters:
Name Type Description
event Event The event object to dispatch.
Returns:
Return false if a registered listener has cancelled the event. Return true otherwise.
Type
boolean

fetchByKeys(parameters : FetchByKeysParameters<K>) : Promise<FetchByKeysResults<K, D>>

Fetch rows by keys. The resulting key map will only contain keys which were actually found.
Parameters:
Name Type Description
parameters FetchByKeysParameters fetch by key parameters
Since:
  • 4.2.0
Returns:
Returns Promise which resolves to FetchByKeysResults.
Type
Promise.<FetchByKeysResults>
Example

Fetch for keys 1001 and 556

let keySet = new Set();
keySet.add(1001);
keySet.add(556);

let value = await dataprovider.fetchByKeys({keys: keySet});
// get the data for key 1001
console.log(value.results.get(1001).data);

fetchByOffset(parameters: FetchByOffsetParameters<D>): Promise<FetchByOffsetResults<K, D>>

Fetch rows by offset

A generic implementation of this method is available from FetchByOffsetMixin. It is for convenience and may not provide the most efficient implementation for your data provider. Classes that implement the DataProvider interface are encouraged to provide a more efficient implementation.

Parameters:
Name Type Description
parameters FetchByOffsetParameters fetch by offset parameters
Since:
  • 4.2.0
Returns:
Returns Promise which resolves to FetchByOffsetResults.
Type
Promise.<FetchByOffsetResults>
Example

Fetch by offset 5 rows starting at index 2

let result = await dataprovider.fetchByOffset({size: 5, offset: 2});
let results = result['results'];
let data = results.map(function(value) {
  return value['data'];
});
let keys = results.map(function(value) {
  return value['metadata']['key'];
});

fetchFirst(parameters?: FetchListParameters<D>): AsyncIterable<FetchListResult<K, D>>

Get an AsyncIterable object for iterating the data.

AsyncIterable contains a Symbol.asyncIterator method that returns an AsyncIterator. AsyncIterator contains a “next” method for fetching the next block of data.

The "next" method returns a promise that resolves to an object, which contains a "value" property for the data and a "done" property that is set to true when there is no more data to be fetched. The "done" property should be set to true only if there is no "value" in the result. Note that "done" only reflects whether the iterator is done at the time "next" is called. Future calls to "next" may or may not return more rows for a mutable data source.

Please see the DataProvider documentation for more information on custom implementations.

Parameters:
Name Type Argument Description
params FetchListParameters <optional>
fetch parameters
See:
Returns:
AsyncIterable with FetchListResult
Type
AsyncIterable.<FetchListResult>
Example

Get an asyncIterator and then fetch first block of data by executing next() on the iterator. Subsequent blocks can be fetched by executing next() again.

let asyncIterator = dataprovider.fetchFirst(options)[Symbol.asyncIterator]();
let result = await asyncIterator.next();
let value = result.value;
let data = value.data;
let keys = value.metadata.map(function(val) {
  return val.key;
});
// true or false for done
let done = result.done;

getCapability(capabilityName: string): any

Determines whether this DataProvider defines a certain feature.
Parameters:
Name Type Description
capabilityName string capability name. Defined capability names are: "fetchByKeys", "fetchByOffset", "sort", "fetchCapability" and "filter".
Since:
  • 4.2.0
Returns:
capability information or null if undefined
Type
Object
Example

Check what kind of fetchByKeys is defined.

let capabilityInfo = dataprovider.getCapability('fetchByKeys');
if (capabilityInfo.implementation == 'iteration') {
  // the DataProvider supports iteration for fetchByKeys
  ...

getTotalSize : {Promise.<number>}

Return the total number of rows in this dataprovider
Returns:
Returns a Promise which resolves to the total number of rows. -1 is unknown row count.
Type
Promise.<number>
Example

Get the total rows

let value = await dataprovider.getTotalSize();
if (value == -1) {
  // we don't know the total row count
} else {
  // the total count
  console.log(value);

isEmpty(): 'yes' | 'no' | 'unknown'

Returns a string that indicates if this data provider is empty. Valid values are:
  • "yes": this data provider is empty.
  • "no": this data provider is not empty.
  • "unknown": it is not known if this data provider is empty until a fetch is made.
Since:
  • 4.2.0
Returns:
string that indicates if this data provider is empty
Type
"yes" | "no" | "unknown"
Example

Check if empty

let isEmpty = dataprovider.isEmpty();
console.log('DataProvider is empty: ' + isEmpty);

removeEventListener(eventType: string, listener: EventListener): void

Remove a listener previously registered with addEventListener.
Parameters:
Name Type Description
eventType string The event type that the listener was registered for.
listener EventListener The callback function that was registered.

Type Definitions

DataProviderOptions<D, BD>

Deprecated:
Since Description
10.1.0 Use type Options instead of object for options
Properties:
Name Type Description
joins Record<keyof Omit<D, keyof BD>, DataProviderJoinInfo<D, any, any>>

A map of attribute name to information about DataProviders to join in.

The returned data for each row from the joined DataProvider will be merged as an object under the attribute name in the JoiningDataProvider.

Options<D, BD>

Properties:
Name Type Description
joins Record<keyof Omit<D, keyof BD>, DataProviderJoinInfo<D, any, any>>

A map of attribute name to information about DataProviders to join in.

The returned data for each row from the joined DataProvider will be merged as an object under the attribute name in the JoiningDataProvider.