The transientState object provides access to transient state.

Methods

Method Description

getState(key)

Retrieves the current transient state value associated with the specified key if the following conditions are met: it is available; belongs to the current configuration locker; and has not expired. The key parameter must be a string. The transient state is always returned as a string. If the transient state does not exist or cannot be returned, then an empty string is returned.

var value = transientState.getState('myStateKey');

setState(key, state[, options])

Sets the transient state associated with the specified key to the specified value.

  • The key parameter must be a non-empty string and no more than 256 characters in length.
  • The state value must be a string. If it is null or empty, the current value is cleared.
  • The optional JavaScript object options are an optional JavaScript object that can contain an expiry time for the state value as a field called expires. The expiry time may be provided as either a JavaScript Date object, a number representing the number of milliseconds since the Unix epoch (midnight 1 Jan 1970 UTC), or an ISO 8601 date/time.
    • If an expiry time is set, then the value is automatically cleared once that time is reached and can no longer be retrieved.
    • If an expiry time is not set, then the value never expires until it is either explicitly overwritten or Rhapsody is restarted.
transientState.setState('myStateKey', 'theValue');
transientState.setState('mySecondStateKey', 'theSecondValue', {
    expires: '2016-06-30T09:00:00Z'
});

You can only modify existing transient state values that were originally created in the same configuration locker. You will encounter an error if you attempt to made to modify a transient state value in a different locker.

getAndSetState(key, state[, options])

Identical to setState() except that it returns the old transient state value after modifying it or an empty string if there is no previous value. It is conceptually the same as calling getState() followed by setState(), except that the entire getAndSetState() operation is executed atomically.

var oldValue1 = transientState.getAndSetState('myStateKey', 'theValue');
var oldValue2 = transientState.getAndSetState('mySecondStateKey', 'theSecondValue', {
    expires: '2016-06-30T09:00:00Z'
});

compareAndSetState(key, oldState, newState[, options])

Compares the existing transient state to the specified value and then modifies it only if the expected value is found. The function returns true if the value is replaced, or false if the comparison fails.

  • The key parameter must be a non-empty string and no more than 256 characters in length.
  • The oldState value is what is used to compare against the current state value, and may be set to null/empty if there is expected to be no current value.
  • The "newState" value is a string and is only used if the comparison is successful. It may be set to null/empty to clear the existing value.
  • The "options" are optional and if present are a JavaScript object that can optionally contain an expiry time for the state value as a field called expires. The expiry time may be provided as either a JavaScript Date object, a number representing the number of milliseconds since the Unix epoch (midnight 1 Jan 1970 UTC), or an ISO 8601 date/time.
    • If an expiry time is set, then the value is automatically cleared once that time is reached and can no longer be retrieved.
    • If an expiry time is not set, then the value never expires until it is either explicitly overwritten or Rhapsody is restarted.
var result1 = transientState.compareAndSetState('myStateKey', 'expectedValue', 'theValue');
var result2 = transientState.setState('mySecondStateKey', null, 'theSecondValue', {
    expires: '2016-06-30T09:00:00Z'
});

You can only modify existing transient state values that were originally created in the same configuration locker. You will encounter an error if you attempt to made to modify a transient state value in a different locker.

Examples

Set state

// Simple set state
transientState.setState('key2', 'val2');


// Setting value and an old expiry date
transientState.setState('key1', 'val1', {
expires: '2016-05-23T19:00:00z'
});

Get state

//Get values: Set property
next.setProperty('Prop' , transientState.getState('key1'));
next.setProperty('Prop' , transientState.getState('key2'));

Get and set state

//Get and set (to get old value, before setting a new one)
//Note: assume old value is empty
var old1 = transientState.getAndSetState('key3','val3');
 
next.setProperty('OldVal_Null' , old1);
next.setProperty('Val_Key3' , transientState.getState('key3'));
//Set an old value before setting new value
transientState.setState('key4', 'oldVal4');

var old2 = transientState.getAndSetState('key4','val4');

next.setProperty('Old_Val4' , old2);
next.setProperty('New_Val4' , transientState.getState('key4'));

Compare and set state

//Compare values and set new value
 
//Set value
transientState.setState('key6', 'val6');

//Compare values
var res2 = transientState.compareAndSetState('key6', 'val6', 'Newval6')

//Get value
next.setProperty('Prop8' , transientState.getState('key6'));
next.setProperty('Result2' , res2);
//Compare non-existent value with null  
var res1 = transientState.compareAndSetState('key5', null, 'val5')
 
//Get value
next.setProperty('Prop' , transientState.getState('key5'));
next.setProperty('Result1' , res1);