Accessing the cache in Node.js

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

You can use the apigee-access module to access the Edge distributed cache from within a Node.js application. The module includes methods for getting a cache and putting, getting, and removing data.

The Apigee Edge distributed cache lets you store strings or other data. Like most caches, it is a least-recently-used cache with a maximum size. Inside Apigee Edge, the cache is distributed among all nodes where your Node.js application executes. You can manage the cache through an Apigee Edge API. Using the API, you can manually create cache resources, or you can use the default resource. For an introduction to caching on Apigee Edge, see Persistence tools in Edge. To learn more about the distributed cache, see Example: General purpose caching.

For an introduction to the apigee-access module and its other features, see Using the apigee-access module.

Methods

(1) getCache

var cache = apigee.getCache(cacheName);

Look up a named cache and create it if necessary. The resulting cache uses a pre-defined set of configuration parameters suitable for most situations.

Parameters:

cacheName - A string, the name of the cache. (Not the name of the cache resource).

Returns:

A cache object.

Example:

var apigee = require('apigee-access');
var cache = apigee.getCache('cache');

(2) getCache

var customCache = apigee.getCache(cacheName, options );

Access a custom cache resource specified in a configuration object. For information about how to create a cache resource, see Creating and editing an environment cache.

Parameters:

cacheName - A string, the name of the custom cache. (Not the name of the cache resource)

options - A configuration object. The object can be empty, or it can contain the following optional parameters:

  • resource: The name of an Apigee "cache resource" where the cache data is stored. Cache resources are used to fine-tune memory allocation and other cache parameters. If not specified, a default resource will be used. If the cache resource does not exist, then the method throws an error.

  • scope: Specifies whether cache entries are prefixed to prevent collisions. Valid values are global, application, and exclusive.

    • global: All cache entries may be seen by all Node.js applications in the same Apigee "environment."

    • application: All cache entries may be seen by all Node.js caches that are part of the same Apigee Edge application.

    • exclusive: (Default) Cache entries are only seen by Node.js caches in the same application that have the same name. This is the default.

  • prefix: If the cache key name includes a prefix, as described in Populate Cache policy and Working with cache keys, use this parameter to specify it. Edge automatically adds a double-underscore suffix to the prefix name. So if a cache key was created with the prefix "UserToken", the prefix to specify here is "UserToken__".

  • defaultTtl: Specifies the default time to live for a cache entry, in seconds. If not specified then the default TTL in the cache resource will be used.

  • timeout: How long to wait to fetch a result from the distributed cache, in seconds. The default 30 seconds. Latency-sensitive applications may wish to reduce this in order to prevent slow response times if the cache infrastructure is overloaded.

Returns:

A custom cache object.

Example:

var apigee = require('apigee-access');
var customCache = apigee.getCache('doesNotMatter',
  { resource: 'MyCustomResource', scope: 'global', prefix: 'UserToken'} );
customCache.put("myCacheKey", "xyz");

This works with a LookupCache policy configured like this:

<LookupCache name="Lookup-Cache-1">
  <CacheKey>
    <Prefix>UserToken</prefix>    
    <KeyFragment>myCacheKey</KeyFragment>
  </CacheKey>
  <CacheResource>MyCustomResource</CacheResource>
  <Scope>Global</Scope>
  <AssignTo>contextVariable</AssignTo>
</LookupCache>

put

cache.put('key', data, ttl, function(error));

Put data into a cache.

Parameters:

  • key: (Required) A string that uniquely identifies the item in the cache. Cache keys are limited to a size of 2 KB.

  • data: (Required) A string, Buffer, or object that represents the data to cache. Any other data type will result in an error. For convenience, objects will be converted into a string using "JSON.stringify".

  • ttl: (Optional) The maximum time to persist the data in the cache, in seconds. If not specified then a default TTL will be used.

  • callback: (Optional) If specified, a function that will be called once the data is safely in the cache. It will be called with an Error object as the first parameter if there is an insertion error, and otherwise it will be called with no parameters.

Example:

var apigee = require('apigee-access');
var cache = apigee.getCache();
// Insert a string into cache using the default TTL
cache.put('key1', 'Buenos dias, Mundo!');
// Insert a string into cache using a TTL of 120 seconds
cache.put('key2', 'Hello, World!', 120);
// Insert a string with the default TTL, and get notified when the insert is complete
cache.put('key3', 'Ciao, Mondo!', function(error) {
  // "error" will be falsy unless there was an error on insert
});
// Insert a string with a TTL of 600 seconds, and get notified when the insert is complete
cache.put('key4', 'Hallo Wereld!', 600, function(error) {
  // "error" will be falsy unless there was an error on insert
});

get

cache.get('key', function(error, data));

Retrieve data from a cache.

Parameters:

  • key (required): A string that uniquely identifies the item in the cache.

    For cache entries put to the cache from an Apigee Edge policy (such as Populate Cache policy), you will need to construct the cache key by inferring from the specific way the policy creates keys for entries. To do this, you'll need to know how the policy is configured. While Working with cache keys describes how cache keys are created by policies, keep in mind that you shouldn't specify string values related to scope; in calls from Node.js, scope is already part of the context.

  • callback (required): A function that will be called when the data is available. If there is cached data, it is returned in the second parameter.

    • error - An Error object. If there is an error while retrieving from the cache, then an Error object will be set here. Otherwise this parameter will be set to "undefined".

    • data - The data retrieved, if any. It will be one of four values:

      • If a string was inserted, it will be a string.
      • If a Buffer was inserted, it will be a Buffer.
      • If an object was inserted, it will be a string containing the JSON version of the object as produced by "JSON.stringify".
      • If nothing was found, then it will be "undefined".

Example:

var apigee = require('apigee-access');
var cache = apigee.getCache();
cache.get('key', function(error, data) {
  // If there was an error, then "error" will be set.
  // If error is falsy, "data" is the item that was retrieved:
  //   - undefined, in the case of cache miss, or
  //   - a Buffer, or
  //   - a String
});

remove

cache.remove('key', function(error));

Invalidate a cached item. Once a key is invalidated, subsequent get() requests will return "undefined" unless another value is inserted.

Parameters:

  • key (Required): A string that uniquely identifies the item in the cache to invalidate.

    For cache entries put to the cache from an Apigee Edge policy (such as Populate Cache policy), you will need to construct the cache key by inferring from the specific way the policy creates keys for entries. To do this, you'll need to know how the policy is configured. While Working with cache keys describes how cache keys are created by policies, keep in mind that you shouldn't specify string values related to scope; in calls from Node.js, scope is already part of the context.

  • callback (Required): A callback function that will be called with an Error object as the first parameter if there is an error.

Example:

var apigee = require('apigee-access');
var cache = apigee.getCache();
cache.remove('key', function(error) {
});