Package com.sap.cloud.mobile.foundation.cache

Class SecureStoreCache

  • All Implemented Interfaces:
    com.sap.cloud.mobile.foundation.cache.Cache 
    
public final class SecureStoreCache<V extends Serializable>
extends CacheBase<K, V>

    A SecureStoreCache is a fixed size LRU (Least Recently Used) cache that contains key-value pairs persisted in an encrypted database.

    • Key Type-- String
    • Value Types-- supports Boolean, Byte, Double, Float, Integer, Long, Short, String, byte[], and any object that implements Serializable interface.
    To instantiate a SecureStoreCache, you need to specify the Android application context, the size of the cache, database file name, an optional database table name, and the database encryption key.

    After a SecureStoreCache is constructed, open the cache with an encryption key which is used to encrypt the underlying persistence store. It is recommended to use EncryptionUtil to obtain the encryption key. If this is the first time store is being opened and null is provided, an encryption key will be generated transparently and will be used for subsequent opens. 

    
    MyObjectClass myObject = new MyObjectClass(...); // MyObjectClass must implement Serializable.
    ....
    byte[] myEncryptionKey = EncryptionUtil.getEncryptionKey("aliasForMySecureCache", myPasscode);
    SecureStoreCache<MyObjectClass> cache = new SecureStoreCache<>(
        context,            // Android application context.
        32,                 // The size of the cache.
        "myStoreName");     // The name of the store.

    try {
        cache.open(myEncryptionKey);

        // Or pass null for the cache to generate an encryption key transparently.
        // cache.open(null);
    } catch (OpenFailureException ex) {
        // Incorrect encryption key. If the encryption key was obtained from UI, try again.
    }
    You can use methods specified by Cache interface to perform CRUD operations: 
    
    // Create operations.
    cache.put("myKey", myObject);
    ...
    // Read operations.
    MyObject retrievedObject = cache.get("myKey");    // Read an entry.

    // Iterates through existing keys.
    List<String> keyList = cache.keys();

    for (String key : keyList) {
        logger.debug("Secure Store Key: {} ", key);
    }

    int totalEntries = cache.getEntryCount();
    ...
    // Update operations.
    cache.put("myKey", myNewObject);

    // Delete (remove) operations.
    cache.remove("myKey");  // Remove entries one at a time.
    cache.removeAll();  // Or remove all entries including entries in the backing store!
    You can change the encryption of the underlying persistence store while the cache is in open state. 
    
    cache.changeEncryptionKey(newEncryptionKey);
    When you finish executing cache operations, close the SecureStoreCache so that the underlying persistence store relinquishes any resources it has acquired during its operations. 
    
    cache.close();
    You may want to remove the persistence store in some occasions. Note that after the persistence store is removed, any further operation performed on the instance will cause FileMissingException. 
    
    cache.deleteStore(context); // The cache instance will not be usable after this method!

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description

    • Constructor Summary

      Constructors 
      Constructor Description
      SecureStoreCache(Context context, int maxEntries, String storeName) Constructs a Secure Store Cache with LRU replacement policy.

    • Enum Constant Summary

      Enum Constants 
      Enum Constant Description

    • Method Summary

      Modifier and Type Method Description
      void open(@Nullable() Array<byte> encryptionKey) Opens the underlying persistence store.
      boolean isOpen() Checks if the cache is in open state, that is, open has been called and close has not been called.
      void changeEncryptionKey(@Nullable() Array<byte> newEncryptionKey) Changes the encryption key of the persistence store while the cache is in open state.
      V put(@NonNull() String key, @NonNull() V value, double cost) Not Supported.
      V put(@NonNull() String key, @NonNull() V value) Adds or updates a value associated with a key.
      V get(@NonNull() String key) Returns the value associated with a key.
      CacheEntry<String, V> getEntry(@NonNull() String key) Retrieves the value associated with a key, then returns a CacheEntry object that embeds the key and value.
      double getCostOfEntries() Not supported.
      int getEntryCount() Returns the number of entries (key-value pairs) in the cache.
      List<String> keys() Returns a list of keys of all entries in LRU order or an empty list.
      void remove(@NonNull() String key) Removes a cache entry.
      void removeAll() Removes all entries from the cache.
      void close() Closes the underlying persistence store.
      void deleteStore(@NonNull() Context context) Deletes the underlying persistence store.

      • Methods inherited from class com.sap.cloud.mobile.foundation.cache.CacheBase

        getContext, getMaxEntries, init, init

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • SecureStoreCache

        SecureStoreCache(Context context, int maxEntries, String storeName)
        Constructs a Secure Store Cache with LRU replacement policy.
        Parameters:
        context - Android application context
        maxEntries - maximum number of entries the cache can hold.
        storeName - a non-empty name of the persistence store that contains only -, _, a-z, A-Z, 0-9 and ..

    • Method Detail

      • open

         void open(@Nullable() Array<byte> encryptionKey)

        Opens the underlying persistence store.

        Parameters:
        encryptionKey - a key to encrypt/decrypt the persistence store.

      • isOpen

         boolean isOpen()

        Checks if the cache is in open state, that is, open has been called and close has not been called.

        Returns:

        True if cache is in open state, false otherwise.

      • changeEncryptionKey

         void changeEncryptionKey(@Nullable() Array<byte> newEncryptionKey)

        Changes the encryption key of the persistence store while the cache is in open state.

        Parameters:
        newEncryptionKey - new encryption key.

      • put

        @Nullable() V put(@NonNull() String key, @NonNull() V value, double cost)

        Not Supported.

      • put

        @Nullable() V put(@NonNull() String key, @NonNull() V value)

        Adds or updates a value associated with a key.

        Parameters:
        key - a non-null key of a cache entry
        value - a non-null value to add
        Returns:

        The original value of an existing cache entry, or null if this is a new entry.

      • get

        @Nullable() V get(@NonNull() String key)

        Returns the value associated with a key.

        Parameters:
        key - a non-null key of a cache entry
        Returns:

        The value associated with a key or null if the key is not found.

      • getEntry

        @Nullable() CacheEntry<String, V> getEntry(@NonNull() String key)

        Retrieves the value associated with a key, then returns a CacheEntry object that embeds the key and value.

        Parameters:
        key - a non-null key of a cache entry
        Returns:

        A CacheEntry or null if the key is not found.

      • getEntryCount

         int getEntryCount()

        Returns the number of entries (key-value pairs) in the cache.

        Returns:

        The number of entries.

      • keys

        @NonNull() List<String> keys()

        Returns a list of keys of all entries in LRU order or an empty list.

        Returns:

        A list of keys of all entries in LRU order or an empty list.

      • remove

         void remove(@NonNull() String key)

        Removes a cache entry.

        Parameters:
        key - a non-null key of the entry to remove

      • removeAll

         void removeAll()

        Removes all entries from the cache.

      • close

         void close()

        Closes the underlying persistence store.

        Note:

        1. Any CRUD operations on this instance of secure store cache after a successful return from this method will induce runtime error.

        2. Entries persisted in the underlying backing store are not cleared.

      • deleteStore

         void deleteStore(@NonNull() Context context)

        Deletes the underlying persistence store. Note that this instance will no longer be usable after the call. Any operation performed will cause FileMissingException.

        Parameters:
        context - Android application context