Docs Developer Site
Developer Docs Code Stable Libraries Lib Grid

Grid library

Contents

This API provides functions that enable sharing data across all applications and cluster nodes.

Due to distributed nature of SharedMap not all value types can be used. Strings, numbers, booleans, and pure JSON objects are supported. There is no runtime check for type compatibility due to performance reasons. Developers are themselves responsible for NOT modifying shared objects (keys and values) in place.

Usage

Add the following dependency to your build.gradle file:

dependencies {
  include xplibs.grid
}

Add the import statement to your code:

import gridLib from '/lib/xp/grid';

You are now ready to use the API.

Functions

getMap

This function returns an instance of SharedMap for the specified map identifier.

Parameters

Name Kind Description

mapId

string

Map identifier.

Returns

SharedMap : An instance of SharedMap bound to the given identifier.

import {getMap} from '/lib/xp/grid';

const sharedMap = getMap('mapId');

SharedMap API

set

Puts an entry into a SharedMap with a given time to live (TTL). If value is null, the existing entry for that key is removed.

Parameters

Name Kind Description

key

string

Key of the entry.

value

string|number|boolean|JSON|null

Value of the entry. Passing null removes the existing entry.

ttlSeconds

number

Optional. Maximum time (in seconds) for this entry to remain in the map. 0 means infinite; a negative value means the default TTL of the map provider (for instance, Hazelcast) or infinite if the provider has no own TTL setting.

 
import gridLib from '/lib/xp/grid';

const sharedMap = gridLib.getMap<{ greeting: string }>('mapId');

sharedMap.set({
  key: 'greeting',
  value: 'hello',
  ttlSeconds: 2 * 60
});

get

Returns the value to which the specified key is mapped, or null if the map contains no mapping for the key.

Parameters

Name Kind Description

key

string

The key whose associated value is to be returned.

Returns

string\|number\|boolean\|JSON\|null : The value mapped to the given key, or null if no mapping exists.

import gridLib from '/lib/xp/grid';

const sharedMap = gridLib.getMap('mapId');

const value = sharedMap.get('key');

delete

Removes the entry for the specified key if it is present in the map.

Parameters

Name Kind Description

key

string

The key whose associated value is to be removed.

 
import gridLib from '/lib/xp/grid';

const sharedMap = gridLib.getMap('mapId');

sharedMap.delete('key');

modify

Attempts to compute a mapping for the specified key and its current mapped value.

Parameters

Name Kind Description

key

string

Key of the entry.

func

function

Mapping function that accepts the existing mapped value (or null, if there is no associated mapping). The value it returns replaces the existing mapped value for the specified key. If the returned value is null, the entry is removed from the map.

ttlSeconds

number

Optional. Maximum time (in seconds) for this entry to remain in the map. 0 means infinite; a negative value means the default TTL of the map provider (for instance, Hazelcast) or infinite if the provider has no own TTL setting.

Returns

string\|number\|boolean\|JSON\|null : The new value mapped to the key, or null if the entry was removed (because func returned null).

import gridLib from '/lib/xp/grid';

const sharedMap = gridLib.getMap<{ counter: number }>('mapId');

const newValue = sharedMap.modify({
  key: 'counter',
  func: (oldValue) => (oldValue ?? 0) + 1,
  ttlSeconds: 2 * 60
});

Contents

Contents