VaultMobileSDK  18R3
iOS framework for Vault API
Instance Methods | Class Methods | Properties | List of all members
VEVVaultJSONCache Class Reference

Instances of this class are used to store JSON responses from Vault for later use—for example when the user is offline. Caches support complex queries, are persistent, and retain their contents across application restarts. More...

Inheritance diagram for VEVVaultJSONCache:
VEVVaultCache

Instance Methods

(void) - cache:vault:handler:
 Caches a collection of JSON responses originating from a Vault API endpoint, e.g., documents. Each response is required to have a key at the top level labeled "id" which uniquely identifies it within the cache. If another response is subsequently cached with an id matching that of an existing response, then the original response will be replaced with the updated response. More...
 
(void) - query:handler:
 Queries the local cache and asynchronously returns the matching responses as an array of VEVVaultJSONCacheEntry objects. More...
 
(void) - removeEntries:handler:
 Removes the specified entries from the cache. More...
 
(void) - removeAllEntries:
 Removes all entries from the cache. More...
 
(void) - reindexWithFields:handler:
 Reindexes the cache entries. Calling this method is required when new fields that have been added to the JSON response schema need to be searchable. More...
 

Class Methods

(instancetype) + openCacheWithName:vault:fields:
 Opens or creates a VEVVaultJSONCache with the specified name, vault, and search fields. The first time a cache with a given name and vault is opened it is created. On subsequent calls with the same name and vault the existing cache is opened and returned. More...
 

Properties

NSArray< VEVVaultJSONField * > * fields
 The fields that this cache has enabled for querying.
 
- Properties inherited from VEVVaultCache
NSString * name
 The name associated with the cache.
 
VEVVaultvault
 The Vault associated with the cache.
 

Detailed Description

Instances of this class are used to store JSON responses from Vault for later use—for example when the user is offline. Caches support complex queries, are persistent, and retain their contents across application restarts.

Opening a Cache

You create or open an existing VEVVaultJSONCache by calling openCacheWithName:vault:fields: (VEVVaultJSONCache), passing in a name for the cache, a VEVVault, and a collection of VEVVaultJSONField objects. The name and the VEVVault together define a scope for the responses being stored (see Caching Responses). The VEVVaultJSONField objects define which keys from the response are searchable when retrieving stored responses (see Querying Responses).

While the name you give to a cache can be anything you like, best practice is to choose a name that corresponds to a Vault type such as 'DocumentCache'. Responses stored in the cache should then all correspond to this type.

Example:

if let vault = VEVVaultAuth.sharedInstance().currentUser?.vaults?.first {
       let nameField = VEVVaultJSONField("name__v", type: .text)
       let idField = VEVVaultJSONField("id", type: .integer)
       let cache = VEVVaultJSONCache.open(withName: "Documents", vault: vault, fields: [nameField, idField])
   }

Caching Responses

You cache responses by calling the cache:vault:handler: (VEVVaultJSONCache) method. Each response in the given collection must have a key at the top level labeled "id". Caching a response will update any previously cached response that has a matching id, as long as the cache being used to update has the same scope as the original cache—that is, as long as it has the same name and Vault. Otherwise, it will be added as a new response. Cache scopes are enforced even when different cache instances are used, for example when recreating caches after restarting the application.

Example:

let sampleResponse : [Dictionary< String, Any >] = [[
               "id" : 1,
               "version_id":1_0_1,
               "name__v" : "clinical document"
               ],[
               "id" : 2,
               "version_id":2_0_1,
               "name__v" : "site document"
               ]]

       cache.cache(sampleResponse, vault: vault) { (entries, error) in
           print("Newly added cache entries \(entries)")
        }

Querying Responses

You query a cache for responses by constructing a VEVVaultLocalQuery object from one or more VEVVaultQueryCriteria, and passing it to query:handler: (VEVVaultJSONCache). The process overall is meant to correspond closely with writing directly in a query language, as the following example demonstrates:

let query = VEVVaultLocalQuery.create(withExpression: [
    VEVVaultQueryCriteria(field: "name__v", like: "Pleasanton"),
    VEVVaultLogicalOperatorAnd,
    VEVVaultQueryCriteria(field: "pages__v", equalTo: @2)])

documentsJsonCache.query(localQuery, handler: { (entries, error) in
    print("JsonCacheEntries \(entries)")
})

The fields given to the query object are limited to those that were specified when opening the cache.

Method Documentation

◆ openCacheWithName:vault:fields:()

+ (instancetype) openCacheWithName: (NSString *)  name
vault: (VEVVault *)  vault
fields: (NSArray< VEVVaultJSONField * > *)  fields 

Opens or creates a VEVVaultJSONCache with the specified name, vault, and search fields. The first time a cache with a given name and vault is opened it is created. On subsequent calls with the same name and vault the existing cache is opened and returned.

The fields parameter specifies which keys in the cached JSON responses are searchable.

Parameters
nameThe name of the cache to open.
vaultThe Vault server from which all JSON responses in the cache originated from.
fieldsThe collection of searchable fields.

◆ cache:vault:handler:()

- (void) cache: (NSArray< NSDictionary * > *)  jsonResponse
vault: (VEVVault *)  vault
handler: (VEVVaultJSONCacheCacheResponseResultHandler _Nullable)  handler 

Caches a collection of JSON responses originating from a Vault API endpoint, e.g., documents. Each response is required to have a key at the top level labeled "id" which uniquely identifies it within the cache. If another response is subsequently cached with an id matching that of an existing response, then the original response will be replaced with the updated response.

Parameters
jsonResponseAn array of NSDictionaries containing JSON representations of Vault entities, e.g., Documents.
vaultThe Vault from which jsonResponse originated.
handlerThe callback invoked upon completion.
Remarks
The vault that is passed in is meant to serve as a check that ensures all cached responses correspond to the same originating Vault. If vault does not match the cache's vault property and error is returned.

◆ query:handler:()

- (void) query: (VEVVaultLocalQuery *)  query
handler: (VEVVaultJSONCacheQueryResultHandler _Nullable)  handler 

Queries the local cache and asynchronously returns the matching responses as an array of VEVVaultJSONCacheEntry objects.

Parameters
queryThe VEVVaultLocalQuery to execute. Only field names that correspond to the fields property can be queried.
handlerThe callback invoked upon completion.
See also
+ openCacheWithName:vault:fields:
VEVVaultLocalQuery
VEVVaultJSONCacheEntry

◆ removeEntries:handler:()

- (void) removeEntries: (NSArray< VEVVaultCacheEntry * > *)  entries
handler: (VEVVaultCacheRemoveEntriesResultHandler _Nullable)  handler 

Removes the specified entries from the cache.

Parameters
entriesAn array of VEVVaultCacheEntry to be removed.
handlerThe callback invoked upon completion.

Implements VEVVaultCache.

◆ removeAllEntries:()

- (void) removeAllEntries: (VEVVaultCacheRemoveAllEntriesResultHandler _Nullable)  handler

Removes all entries from the cache.

Parameters
handlerThe callback invoked upon completion.

Implements VEVVaultCache.

◆ reindexWithFields:handler:()

- (void) reindexWithFields: (NSArray< VEVVaultJSONField * > *)  newFields
handler: (VEVVaultJSONCacheReindexResultHandler _Nullable)  handler 

Reindexes the cache entries. Calling this method is required when new fields that have been added to the JSON response schema need to be searchable.

Parameters
newFieldsThe updated list of searchable fields. The original list of fields is replaced completely by this updated list so it is important to include any original fields that should remain searchable.
handlerThe callback invoked upon completion.

The documentation for this class was generated from the following file: