Principle

Streamezzo framework provides straightforward facilities to cache content locally on device (instant and offline access to this content for the end-user).

Some advanced facilities are also granted for fine cache management.

On client-side, a rich media content (scene) data delivered by Streamezzo Rich Media Server can be:

• stored in cache, i.e. the currently requested and downloaded scene is rendered and stored in client cache simultaneously, so that the next access to this scene will be immediate (as long as this content has not reached a specified expiration time)
• prefetched in cache, i.e. the currently requested and downloaded scene also comes with data from other scene(s) that are stored in client cache, so the access to this/those scene(s) will be immediate (as long as this content has not reached a specified expiration time)

Connection can also be managed in order to download additional scenes data in cache as soon as the connection becomes available (optimized connection usage). This is performed in background, without interfering with the application usage, queuing the list of scene to be downloaded and store in cache when possible.

Features

Rich Media content (scene) that is dynamically processed server-side can be stored in client cache (on device) for instantaneous (and even offline) access, as long as the stored content remains valid (based on specified Time To Live (TTL)).

Cacheable scene

A 'cacheable' scene is a scene that is currently being downloaded and that can be stored in client cache.

A specific directive in server-side scenes enables to activate and configure storage in client cache: one has to set in the following attributes in the header tag:

• cacheable: boolean activating client-side caching when set to 'true'
• clientCacheTtl: specifies the client cache entry time to live (TTL), in milliseconds (default) / seconds (s) / hours (h) / days (d); can be specified as infinite with special value '0'
• permanent: boolean specifying if the client cache entry remains valid along multiple application sessions, i.e. once the application has been quitted

Prefetched scene (cacheobject)

A 'cacheobject' scene is a scene which data is downloaded at the same time as the currently accessed scene, in order to be stored in client cache.

A specific unit cacheObject in server-side scenes enables sending another scene data in the same response as the currently processed scene, specifying the following attributes.

• url: the URL of the scene, as referenced in cache
• source: the URL of the scene to prefetch; if this attribute is not specified, the scene will be accessed relying on the url attribute (i.e. specifying this attribute is only necessary if the developer wants the real URL to access the server-side scene and the reference URL in client cache to differ)
• endTime: specifies the client cache entry time to live (TTL), in milliseconds (default) / seconds (s) / hours (h) / days (d); can be specified as infinite with special value '0'
• permanent: boolean specifying if the client cache entry remains valid along multiple application sessions, i.e. once the application has been quitted
• priority: if set to value 'HIGH' (default) the scene data is sent with respect to its position among Access Units, if set to 'LOW', the scene data will only being sent once all data (all Access Unites) of the currently accessed scene has been sent

Background cache loading queue

The background cache loading queue enables specifying a list of scene URLs, those scenes data being downloaded and stored in client cache while the connection is available. This optimizes connection usage, prefetching as much data as possible, without affecting the application usage, i.e. if a connection becomes required while using the application, the scene from the queue being currently downloaded in background has its download interrupted.

Multiple operations are granted to manage the background cache loading queue in order to:

• cmd://setClientCacheQueueActivity: enable / disable background cache loading queue
  • status: if set to 'ON' (default), everytime the connection becomes available, the next scene URL in the queue will be accessed in order to be downloaded then stored in client cache; if set to 'NO' when the connection becomes available, the background cache loading queue will not handled
• cmd://setClientCacheQueueStrategy: specify the way to retrieve items from the background cache loading queue, i.e. which scene URL comes next
  • mode: the strategy to be applied
    • PRIORITY_BASED (entries with the lowest priority value are download first
    • OLDEST_QUEUED_FIRST (default)
    • LEAST_FREQUENTLY_QUEUED_FIRST
    • MOST_FREQUENTLY_QUEUED_FIRST
    • MOST_RECENTLY_QUEUED_FIRST
  • prioritize: prefer downloading first (or not) items that are supposed to be stored in client cache permanently (i.e. that remain valid along multiple application sessions, i.e. once the application has been quitted)
    • NONE (default), background cache loading queue items are extracted from the queue according to the specified strategy whether they are defined as permanent or not
    • PERMANENT, non permanent cache entries will be removed first according to the specified strategy, then (if no non-permanent cache entry remain in cache) permanent cache entries will be removed according to the specified strategy
• AddCacheQueueItem node: specify a scene URL to be added in the background cache loading queue
  • DEF: node id
  • active: node activity (once active and started the scene URL will be added to queue)
  • startTime: node startTime (once active and started the scene URL will be added to queue)
  • source: the URL of the scene to prefetch; if this attribute is not specified, the scene will be accessed relying on the url attribute (i.e. specifying this attribute is only necessary if the developer wants the real URL to access the server-side scene and the reference URL in client cache to differ)
  • endTime: specifies the client cache entry time to live (TTL), in milliseconds (default) / seconds (s) / hours (h) / days (d); can be specified as infinite with special value '0'
  • permanent: boolean specifying if the client cache entry remains valid along multiple application sessions, i.e. once the application has been quitted
  • priority: priority allocated to the scene entry related cache cleaning strategy (in case the strategy based on priority is applied: entries with the highest priority value will be removed first when the cache space if full)
  • queuePriority: priority allocated to the scene URLs in the cache loading queue (related to the cache loading queue management, in case the strategy based on priority is applied: entries with the lowest priority value will be downloaded first)
• ClearCacheQueueItem node: specify a scene URL to be removed from the background cache loading queue
  • DEF: node id
  • active: node activity (once active and started the scene URL will be removed from queue)
  • startTime: node startTime (once active and started the scene URL will be removed from queue)
  • url: URL of the cache loading queue item to be removed from background cache loading queue; this parameter is required if no urlPattern attribute is specified.
  • urlPattern: URL (starts with) pattern of the cache loading queue item(s) to be removed from background cache loading queue; this parameter is required if no url attribute is specified.
• TestClientCacheQueue node: specify a scene URL or set of scene URLs is to be tested in background cache loading queue (i.e. is it / are they currently listed in queue)
  
  • DEF: node id
  • active: node activity (once active and started the scene URL will be tested in queue)
  • startTime: node startTime (once active and started the scene URL will be tested in queue)
  • url: URL of the cache loading queue item to be tested in background cache loading queue; this parameter is required if no urlPattern attribute is specified.
  • urlPattern: URL (starts with) pattern of the cache loading queue item(s) to be tested in background cache loading queue; this parameter is required if no url attribute is specified.
  • yes: startable node id (DEF) that is started in case the test succeeds (i.e. there is at least one of scene URL matching the specified criteria)
  • no: startable node id (DEF) that is started in case the test fails (i.e. there is no scene URL matching the specified criteria)

Cache space management

It is possible to manage the content of the client cache space, thanks to following operations:

• cmd://reserveCache: enables attempting to allocated a given amount of cache space for the application
  • request: requested amount of cache space (in KBytes)
  • reservation: id (DEF) of a Text node that will contain the amount of cache space (in KBytes) that could effectively be allocated (i.e. lower or equal to request)
  • onSuccess: startable node id (DEF) that is started in case request amount of cache space could be reserved
  • onFailure: startable node id (DEF) that is started in case request amount of cache space could NOT be reserved
• cmd://setClientCacheCleaningStrategy: specify the cleaning cache space strategy in case it becomes saturated
  • mode: the strategy to be applied
    • OLDEST_STORED_FIRST (default)
    • PRIORITY_BASED (entries with the highest priority value are removed first)
    • LAST_STORED_FIRST
    • LEAST_FREQUENTLY_ACCESSED_FIRST
    • MOST_FREQUENTLY_ACCESSED_FIRST
    • LEAST_RECENTLY_ACCESSED_FIRST
    • MOST_RECENTLY_ACCESSED_FIRST
    • BIGGEST_FIRST
    • SMALLEST_FIRST
  • preserve: prefer maintaining (or not) items that are supposed to be stored in client cache permanently (i.e. that remain valid along multiple application sessions, i.e. once the application has been quitted)
    • NONE (default), entries are removed according to the specified strategy whether they are permanent or not
    • PERMANENT, non permanent cache entries will be removed first according to the specified strategy, then (if no non-permanent cache entry remain in cache) permanent cache entries will be removed according to the specified strategy

Debugging

Checking what is stored in client cache or not, when and when it becomes deprecated (TTL expiration or non permanent entries in case the application has be quitted then launched again) is necessary to ensure the available cached content is accurate at anytime and the end-user experience is fully optimized.

In order to make it possible and easy to check the client cache (and background cache loading queue) current state, Workbench Developer Emulator (Service > Emulation) offers 2 dedicated views displaying all necessary information:

• Stored cache (bottom tab): lists the current entries stored in client cache
• Cache queue (bottom tab): lists the current entries waiting to be downloaded then stored in client cache

On those 2 very similar views one will be able to check:

• which scene has been stored and when (URL + date)
• which space it occupies in cache (size)
• when it will expire (TTL + permanent)
• when it is accessed (hits)

Examples

In the simple examples provided below, all scenes are of course server-side scenes, which processing result can be stored in cache on device.

Cacheable scene

The following simple code sample illustrates how to store a currently accessed scene in client cache. Next accesses to this scene are immediate, as long as the specified TTL has not expired.

The sample code is available here.

Prefetched scene (cacheobject)

The following simple code sample illustrates how to prefetch a scene in client cache, its data being downloaded in the same response as the currently accessed scene. Accesses to this scene are immediate, as long as the specified TTL has not expired.

The sample code is available here.

Background cache loading queue

The following simple code sample illustrates how to prefetch scenes in client cache, take advantage of connection availability. Accesses to those scenes are immediate, as long as the connection has been available long enough to download then in background and their specified TTL has not expired.

The sample code is available here.