Caching API

Top  Next

Backendless Caching API provides a way to temporarily store data on the server in a highly efficient in-memory cache. The cache storage accepts key-value pairs where key is a string and value can be a primitive or complex data structure (arrays, complex types, maps/dictionaries, etc). The caching mechanism is cross-platform, that means Backendless automatically takes care of adapting data between heterogeneous client types. For instance, an Android client can put into cache an instance of Java object of type Person and an iOS (or any other) client can retrieve that object as an instance of the corresponding iOS (or other client type) class.

 

Restrictions

Maximum time duration a value can stay in cache is 2 hours (7200 seconds), but it's "life" can be extended with an API request.
Before an object is placed in cache, it is serialized as a byte array. The size of the serialized object cannot exceed 10240 bytes.
Customers on the Free plan can store up to 50 objects in cache (concurrent storage), Backendless Plus - 200 objects, Cloud Enterprise - 1000 objects.

 

The Caching API supports the following functions:

 

Putting data into cache


This API request places the object into Backendless cache and maps it to the specified key. If the timeToLive argument is not set, the object will expire from cache in 2 hours from the time when it is put in cache. All methods are available via Backendless.Cache.[methodname] accessor:

// synchronous methods
public void put( String key, Object obj )
public void put( String key, Object obj, int timeToLive )

// asynchronous methods
public void put( String key, Object obj, AsyncCallback<Object> callback )
public void put( String key, Object obj, int timeToLive, AsyncCallback<Object> callback );

where:

key- key assigned to the object to identify it in cache. The key is used to retrieve the object from cache or to check if the cache still contains the object.
obj- object to place into cache.
timeToLive- numeric value (in seconds) indicating how long the object must stay in cache before it is expires. When an object expires, Backendless automatically removes it from cache. The default value is 7200 seconds.
callback- the callback used for asynchronous calls to indicate that the operation has either successfully completed or resulted in error.

 

Example:

    AsyncCallback<Object> callback = new AsyncCallback<Object>()
    {
      @Override
      public void handleResponse( Object o )
      {
         System.out.println( "[ASYNC] object has been placed into cache" );
      }

      @Override
      public void handleFault( BackendlessFault backendlessFault )
      {
        System.out.println( "Error - " + backendlessFault.getMessage() );
      }
    };

    // putting string into cache
    Backendless.Cache.put( "foo", "hello world", callback );

    // putting complex object into cache
    Order order = Backendless.Persistence.of( Order.class ).findFirst();
    Backendless.Cache.put( "firstorder", order );
    System.out.println( "[SYNC] object has been placed into cache" );

 

Retrieving data from cache


This API request retrieves an object from Backendless cache. If object is not present in cache, the method returns null for complex types or default value for primitive values. All methods are available via Backendless.Cache.[methodname] accessor:

// synchronous method
public <T> T get( String key, Class<? extends T> type );

// asynchronous method
public <T> void get( final String key, final AsyncCallback<T> callback )

where:

key- identifies the object to retrieve from cache.
callback- the callback used for asynchronous calls to deliver object from cache or error.

 

Example:

    AsyncCallback<Order> callback = new AsyncCallback<Order>()
    {
      @Override
      public void handleResponse( Order order )
      {
         System.out.println( "[ASYNC] retrieved order from cache - " + order.getName() );
      }

      @Override
      public void handleFault( BackendlessFault backendlessFault )
      {
        System.out.println( "Error - " + backendlessFault.getMessage() );
      }
    };

    // get object from cache asynchronously
    Backendless.Cache.get( "firstorder", callback );

    // get object from cache synchronously
    Order order = Backendless.Cache.get( "firstorder", Order.class );
    System.out.println( "[SYNC] retrieved order from cache - " + order.getName() );

 

Checking if key exists in cache


This API request checks if an object exists in cache. If object is present in cache, the method returns true, otherwise - false. All methods are available via Backendless.Cache.[methodname] accessor:

// synchronous method
public Boolean contains( String key )

// asynchronous method
public void contains( String key, AsyncCallback<Boolean> callback )

where:

key- identifies the object to check in cache.
callback- the callback used for asynchronous calls to deliver result or fault to the calling program

 

Example:

    AsyncCallback<Boolean> callback = new AsyncCallback<Boolean>()
    {
      @Override
          public void handleResponse( Boolean result )
          {
             System.out.println( "[ASYNC] object exists in cache - " + result );
          }

          @Override
          public void handleFault( BackendlessFault backendlessFault )
          {
            System.out.println( "Error - " + backendlessFault.getMessage() );
          }
    };

    // get object from cache asynchronously
    Backendless.Cache.contains( "firstorder", callback );

    // get object from cache synchronously
    boolean objectExists = Backendless.Cache.contains( "firstorder" );
    System.out.println( "[SYNC] object exists in cache - "  + objectExists );

 

Extending object's life in cache


There are two way to extend object's life in cache - relative timeframe and fixed timeframe. With the relative timeframe a period of time is added to the timestamp of the call to determine the new expiration time. The fixed timestamp approach sets the timestamp when the object must expire from cache. All methods are available via Backendless.Cache.[methodname] accessor:

// **************************************************************
// synchronous methods
// **************************************************************
// relative time extension
public void expireIn( String key, int secomds );

// fixed time extension
  public void expireAt( String key, Date date );
  public void expireAt( String key, long timestamp );

// **************************************************************
// asynchronous methods
// **************************************************************
// relative time extension
public void expireIn( String key, int timeToLive, AsyncCallback<Object> callback )

// fixed time extension
public void expireAt( String key, Date date, AsyncCallback<Object> callback );
public void expireAt( String key, long timestamp, AsyncCallback<Object> callback )

where:

key- identifies the object to extend the life of in cache.
seconds- number of seconds to extend the life of object in cache by. Must be a value between 1 and 7200 (2 hours).
timestamp- a timestamp in milliseconds when the object should expire and removed from cache. The difference between timestamp and the current time must be equal or less than 7200000 milliseconds (2 hours).
callback- the callback used for asynchronous calls to deliver result or fault to the calling program.

 

Example:

    AsyncCallback<Object> callback = new AsyncCallback<Object>()
    {
      @Override
          public void handleResponse( Object result )
          {
             System.out.println( "[ASYNC] object life has been extended" );
          }

          @Override
          public void handleFault( BackendlessFault backendlessFault )
          {
            System.out.println( "Error - " + backendlessFault.getMessage() );
          }
    };

    // extend object's life in cache asynchronously by 1200 seconds - 20 minutes
    Backendless.Cache.expireIn( "firstorder", 1200, callback );

    // extend object's life in cache synchronously by 1200 seconds - 20 minutes

    long timestamp = System.currentTimeMillis() + 1200000;
    Backendless.Cache.expireAt( "firstorder", timestamp );

 

Deleting object from cache


This method deleted an object from cache if it is present there. All methods are available via Backendless.Cache.[methodname] accessor:

// synchronous method
public void delete( String key )

// asynchronous methods
public void delete( String key, AsyncCallback<Object> callback )

where:

key- identifies the object to delete from cache.
callback- the callback used for asynchronous calls to deliver result or fault to the calling program.

 

Example:

    AsyncCallback<Object> callback = new AsyncCallback<Object>()
    {
      @Override
          public void handleResponse( Object result )
          {
             System.out.println( "[ASYNC] object has been deleted from cache" );
          }

          @Override
          public void handleFault( BackendlessFault backendlessFault )
          {
            System.out.println( "Error - " + backendlessFault.getMessage() );
          }
    };

    // delete object asynchronously
    Backendless.Cache.delete( "firstorder", callback );

    // delete object synchronously
    Backendless.Cache.delete( "firstorder" );
    System.out.println( "[SYNC] object has been deleted from cache" );


Please let us know how we can improve the documentation by leaving a comment. All technical questions should be posted to the Backendless Support forum. We do not respond to the technical questions on the documentation pages.: