IronCache Documentation

Share state between your applications and processes using a key/value store built for the cloud.

1. Configure Your Client

Before you can interact with IronCache, you're going to have to configure your library of choice to use your project ID and your OAuth2 token. You can retrieve your project ID and token from the HUD. Our official client libraries all support the same configuration scheme, which you can read up on if you want a highly-customised development environment. To get started though, just save the following as "iron.json":

{
	"project_id": "INSERT YOUR PROJECT ID HERE",
	"token": "INSERT YOUR TOKEN HERE"
}

You're all configured! The client libraries will all automatically just read that file and use your credentials to authenticate requests.

2. Set the Item in the Cache

Adding an item to a cache and updating an item in a cache are the same thing; if the item exists, it will be overwritten. Otherwise, it will be created.

You can set an item using any of the client libraries or even using our REST/HTTP API directly. We're going to use the Ruby library for these examples.

@client = IronCache::Client.new
@cache = @client.cache("test_cache")
@cache.put("test_item", "Hello, World!")

The cache is technically a key/value store that enforces strings as the key and the value. It is common, however, to use JSON to store complex objects in the cache. The client libraries will all transparently translate all non-string values into their JSON equivalent before storing them in the cache.

@client = IronCache::Client.new
@cache = @client.cache("test_cache")
@cache.put("complex_item", {"greeting" => "Hello", "target" => "world"})

The server also detects numbers and stores them natively as numbers, which lets you increment and decrement them atomically. This means that if two clients try to increment the item at the same time, they won't overwrite each other; the item will be incremented twice. This is extremely useful when clients are run in a highly parallel environment like IronWorker.

@client = IronCache::Client.new
@cache = @client.cache("test_cache")
@cache.put("number_item", 42) # store a number
item = @cache.get("number_item") # retrieve the item
p item.value # output the value
@cache.increment("number_item") # increment the item
p @cache.get("number_item").value  # retrieve the item and print its value again

IronCache is designed for short-term storage. Sometimes however, it's helpful to set an expiration date on data so it will only exist for a set amount of time. To do this, just use the expires_in parameter to set the number of seconds the data should be available for.

@client = IronCache::Client.new
@cache = @client.cache("test_cache")
@cache.put("long_lived_item", 42, {:expires_in => 60 * 60 * 24 * 30}) # this item won't expire for a month

3. Retrieve the Item from the Cache

Retrieving an item from the cache is fairly straightforward:

@client = IronCache::Client.new
@cache = @client.cache("test_cache")
item = @cache.get("number_item")
p item.value

Unlike IronMQ, you do not lock an item when you retrieve it from a cache. Two or more clients may retrieve an item at the same time.

4. Delete the Item from the Cache

Should you decide you would like to remove an item from a cache before its expiration date (or to remove items with no expiration date), you can do so with a simple API call:

@client = IronCache::Client.new
@cache = @client.cache("test_cache")
@cache.delete("number_item") # remove it