Situm SDK downloads & stores in the local cache of the smartphone the data from Situm Platform (e.g. building data). This helps avoiding future network calls when these resources are needed, saving mobile data & battery. 

This also enables the in-phone computing feature. While other solutions continuously send sensor data to a server that handles heavy geolocation computing, Situm SDK has been optimised to make all the computations on the smartphone, provided that some pre-required data (e.g. Positioning Modesl) has been previously downloaded.  Therefore, Situm SDK works even if there is no connectivity.  

How does Situm download & store information?

How Situm downloads & stores the information depens on:

1. The Cache Strategy (see below).  
2. Whether the information is versioned or not. Versioned information can be downloaded only if there is a new version available in Situm Platform: this makes sense specifically for heavy data types.

The following table describes the most important information types and how Situm downloads & stores them:  

Cache strategies

• On unversioned information (e.g. POIs), the cache is cleared and the information is downloaded again.

• On versioned information (e.g. Positioning Models), each piece of information is downloaded again only if there is a new version available in Situm Platform.  

The following example shows how to configure this cache strategy to use it when downloading the list of buildings with their basic information. In this example, SitumSDK will use the building information already stored in the cache if this information has been stored for less than 1 day. Otherwise, Situm SDK will download the information from Situm Platform.   

//Sets the TIMED_CACHE to 1 day max
SitumSdk.configuration().setCacheMaxAge(1, TimeUnit.DAYS);

//Configures a TIMED_CACHE  strategy...
NetworkOptions networkOptions = new NetworkOptionsImpl.Builder().setCacheStrategy(NetworkOptions.CacheStrategy.TIMED_CACHE).build();
CommunicationConfig communicationConfig = new CommunicationConfigImpl(networkOptions);

//... and uses it to retrieve the buildings of the account
SitumSdk.communicationManager().fetchBuildings(communicationConfig, new Handler<Collection<Building>>() {
    @Override
    public void onSuccess(Collection<Building> buildings) {
        Log.i(TAG, "Success! ");
    }

    @Override
    public void onFailure(Error error) {
        Log.i(TAG, "Error! ");
    }
});

The lifespan of the cache information is 5 seconds by default, but as shown in the previous example this can be configured using the method SitumSdk.configuration().setCacheMaxAge.

CACHE_FIRST

As opposed to the TIMED_CACHE strategy, under the CACHE_FIRST strategy the cached information does not have a lifespan. This means that, once the information is downloaded from Situm Platform, Situm SDK will always return this cached information without re-download it from Situm Platform, unless the developer invalidates the cache using the CommunicationManager.invalidateCache method.  This strategy is only recommended  in case you  require very fine control of when the information reload is acceptable.

The following snippet shows you how to configure this method and invalidate the cache:

//Configures a CACHE_FIRST strategy...
NetworkOptions networkOptions = new NetworkOptionsImpl.Builder().setCacheStrategy(NetworkOptions.CacheStrategy.CACHE_FIRST ).build();
CommunicationConfig communicationConfig = new CommunicationConfigImpl(networkOptions);

//... and uses it to retrieve the buildings of the account
SitumSdk.communicationManager().fetchBuildings(communicationConfig, new Handler<Collection<Building>>() {
    @Override
    public void onSuccess(Collection<Building> buildings) {
        Log.i(TAG, "Success! ");
    }

    @Override
    public void onFailure(Error error) {
        Log.i(TAG, "Error! ");
    }
});


//... You may invalidate the cache at any time...
SitumSdk.communicationManager().invalidateCache();

SERVER_FIRST

The SDK always tries to download the information from Situm Plaftorm. If this information is not available (e.g. network failure), Situm SDK will try to retrieve it from the cache as a second option. 

//Configures a SERVER_FIRST  strategy...
NetworkOptions networkOptions = new NetworkOptionsImpl.Builder().setCacheStrategy(NetworkOptions.CacheStrategy.SERVER_FIRST).build();
CommunicationConfig communicationConfig = new CommunicationConfigImpl(networkOptions);

//... and uses it to retrieve the buildings of the account
SitumSdk.communicationManager().fetchBuildings(communicationConfig, new Handler<Collection<Building>>() {
    @Override
    public void onSuccess(Collection<Building> buildings) {
        Log.i(TAG, "Success! ");
    }

    @Override
    public void onFailure(Error error) {
        Log.i(TAG, "Error! ");
    }
});

IGNORE_CACHE

All the information requests go straight to the network, without checking if the information is available in the cache. This is only recommended in development environments. The cache is not even used in case of network failure.

The following snippet shows you how to configure this method and invalidate the cache:

//Configures a IGNORE_CACHE strategy...
NetworkOptions networkOptions = new NetworkOptionsImpl.Builder().setCacheStrategy(NetworkOptions.CacheStrategy.IGNORE_CACHE).build();
CommunicationConfig communicationConfig = new CommunicationConfigImpl(networkOptions);

//... and uses it to retrieve the buildings of the account
SitumSdk.communicationManager().fetchBuildings(communicationConfig, new Handler<Collection<Building>>() {
    @Override
    public void onSuccess(Collection<Building> buildings) {
        Log.i(TAG, "Success! ");
    }

    @Override
    public void onFailure(Error error) {
        Log.i(TAG, "Error! ");
    }
});

In addition to the cache strategies that we have seen in the last section, there are some useful cache operations that you should know.

Erase Cache

You may delete all the cache information at any time using the CommunicationManager.invalidateCache method. 

SitumSdk.communicationManager().invalidateCache();

You may also download all the information of  any building (such the Positioning Models, floors & floorplans, POIs, etc.) at any time. This is useful, for example, if you want to make sure that when the user arrives to a building all the required information will be available without delay (e.g. to start positioning right away or to show the floorplans without waiting for their download to complete).

To do this, you may use the family of CommunicationManager.prefetchPositioningInfo methods.

//Downloads all the building information & stores it in the cache, including the 
//Positioning Models, cartography and even the
//floorplan images (thanks to the setPreloadImages setter)

NetworkOptions networkOptions = new NetworkOptionsImpl.Builder().setPreloadImages(true).build();
CommunicationConfig communicationConfig = new CommunicationConfigImpl(networkOptions);

SitumSdk.communicationManager().prefetchPositioningInfo(communicationConfig, new Handler<String>(){

   @Override
   public void onSuccess(String s) {
      Log.i(TAG, "Success! " + s);
   }

   @Override
    public void onFailure(Error error) {
        Log.e(TAG, "Error! " + error);
    }
});

Cache lifespan

This changes the lifespan of the cache for the TIMED_CACHE strategy (see above). We recommend to use a value of, at least, 24 hours.

SitumSdk.configuration().setCacheMaxAge(24, TimeUnit.HOURS);