distributed-metadata module

Use the distributed-metadata module to manage distributed variables in the distributed store. The distributed store is the gateway-peering instance for distributed variables.

Distributed variables provide you with a mechanism to read from or write to DataPower® facilities across transactions or domains. Access the distributed-metadata module with a require(distributed-metadata') statement. To use distributed variables, you must define the settings for distributed variables that include a dedicated gateway-peering instance. For more information, see Distributed variables.

Important: Distributed variables are an alternative to system variables. You can manage system variables with the APIs in the system-metadata module.
Each API in the distributed-metadata module supports a name form and an options form.
  • The name form takes a variable name and a callback function.
  • The options object form takes a JSON object and a callback function. The JSON object includes the name property and the following properties.
    useDomain
    Specifies whether to limit the variable scope to the application domain.
    useOrg
    Specifies whether to limit the variable scope to the organization defined for the API gateway. This property is ignored if defined for a traditional DataPower service.
    useCatalog
    Specifies whether to limit the variable scope to the catalog defined for the API gateway. This property is ignored if defined for a traditional DataPower service.

    When useOrg is false, useCatalog must be false. When useOrg is false and useCatalog is true, the call returns an error.

    setExclusive
    Specifies whether subsequent writes to variables of the same name overwrite the existing value. The default value is false, which supports the overwriting of the value. To support only the initial write, specify true.
    expire
    Specifies the duration in seconds to persist the variable in the distributed store. By default, variables do not expire. Alternatively, you can specify 0 to indicate that the variable does not expire.

    When useDomain, useOrg, and useCatalog are true, the variable is specific to the domain. For an API gateway, the variable is specific to the same organization in a catalog.

The following code illustrates an example to manage a variable from any domain, organization, and catalog. The variable is set on initial write and cannot be overwritten afterward. The variable expires after 15 seconds.

let optGlobal = {
  name: 'var://dist/myContext/myGlobalVar',
  useDomain: false,
  useOrg: false,
  useCatalog: false,
  setExclusive: true,
  expire 15
};
The following APIs are available in the distributed-metadata module.

dm.delVariable()

Deletes the distributed variable from distributed storage.

Syntax
name form
dm.delVariable(name,callback)
options form
dm.delVariable(options,callback)
Parameters
dm
The name of the previously defined variable for the distributed-metadata object.
name
The name of the distributed variable to delete in the form of var://dist/context/variable. Where context is the name of the context and variable is the name of the variable.
options
The JSON object that defines the distributed variable to delete in the appropriate scope.
callback
The callback function in the function(error,response){} form.
Guidelines
The dm.delVariable() API deletes the distributed variable from distributed storage or returns undefined if the variable does not exist. For a successful call, the result is the number of deleted entries.
Examples
Delete the myVariable distributed variable in the myContext context.
var dm = require('distributed-metadata');
dm.delVariable('var://dist/myContext/myVariable',function(error,result) {
  if( !error) {
    console.log('delVariable result = ' + result);
  } else {
    console.error('delVariable error = ' + error);
  }
});

dm.getVariable()

Gets the value of a distributed variable.

Syntax
name form
dm.getVariable(name,callback)
options form
dm.getVariable(options,callback)
Parameters
dm
The name of the previously defined variable for the distributed-metadata object.
name
The name of the distributed variable to access in the form of var://dist/context/variable. Where context is the name of the context and variable is the name of the variable.
options
The JSON object that defines the distributed variable to access in the appropriate scope.
callback
The callback function in the function(error,response){} form.
Guidelines
The dm.getVariable() API returns the value of the variable or returns undefined if the variable does not exist. For a successful call, the result is the retrieved value for the entry.
Examples
Gets the value of the myVariable distributed variable in the myContext context.
var dm = require('distributed-metadata');
dm.getVariable('var://dist/myContext/myVariable',function(error,result) {
  if( !error) {
    console.log('getVariable result = ' + result);
  } else {
    console.error('getVariable  error = ' + error);
  }
});

dm.setVariable()

Sets the value of a distributed variable.

Syntax
name form
dm.setVariable(name,value,callback)
options form
dm.setVariable(options,callback)
Parameters
dm
The name of the previously defined variable for the distributed-metadata object.
name
The name of the distributed variable to create in the form of var://dist/context/variable. Where context is the name of the context and variable is the name of the variable.
options
The JSON object that defines the distributed variable to set in the appropriate scope.
value
The value to set for the distributed variable. The value must be one of the following data types. Attempting to set a value of any other type results in an error.
  • array
  • boolean
  • document
  • nodelist
  • null
  • number
  • object
  • string
  • undefined
callback
The callback function in the function(error,response){} form.
Guidelines
The dm.setVariable() API creates a distributed variable if the specified distributed variable does not exist. For a successful call, the result is OK.
Examples
Create the myVariable distributed variable in the myContext context with a value of myValue.
var dm = require('distributed-metadata');
dm.setVariable('var://dist/myContext/myVariable', "myValue",function(error,result) {
  if( !error) {
    console.log('setVariable result = ' + result);
  } else {
    console.error('setVariable error = ' + error);
  }
});
Use the options object to create the same distributed variable but limits the scope for its use.
var dm = require('distributed-metadata'); 

options = { 
    useDomain: true,
    useOrg: true,
    useCatalog: false
}

options.name = 'var://dist/myContext/myVariable';
options.value = 'myValue';

dm.setVariable(options, function(error,result) {
  if( !error) {
    console.log('setVariable result = ' + result);
  } else {
    console.error('setVariable error = ' + error);
  }
});