25 Caching Data

This chapter describes how to enable data caching in MAF applications.

This chapter includes the following section:

Section 25.1, "Introduction to Data Caching"

25.1 Introduction to Data Caching

Data caching is a key part of providing a positive user experience to the users of mobile applications. Users expect mobile apps to be available and to work, at all times. Unfortunately, mobile application connectivity is notoriously unreliable, as network connectivity may not be available, or it may come and go as connections are established and subsequently dropped. In order to provide the best possible user experience for your mobile apps, MAF provides APIs that enable you to develop applications that will continue to work, even when offline, ensuring the best possible user experience for your mobile apps. When network connectivity is unavailable, your mobile app can access locally stored cached data to ensure a seamless user experience.

Central to offline data storage are a set of policies that improve the user experience by describing how your mobile application will refresh the REST resources stored in the local cache. These policies, which tell the Sync Client SDK how to process requests, enable you to improve application performance because it's quicker for applications to use an offline read to fetch data stored on a device than it is to retrieve data from a server. These policies also enable the application caching to maintain an optimal user experience by enabling offline reads when an internet connection becomes unavailable.

25.1.1 Implementing Data Caching with the sync-config.xml File

The sync client included with MAF resides on the device, within the MAF application. The sync client employs specific policies when caching data, giving you the ability to cache different resources by observing specific policies defined for each resource, identified by URL. The sync client caches data locally, using the policies set in the sync-config.xml file. For information about configuring data storage and caching policy settings, see Section 25.1.3, "About Caching Policies." For information about how to enable data caching, see Section 25.1.2, "How to Enable Data Caching."

The sync-config.xml file enables the mobile application to not only cache the data retrieved from server-side resources accessed through REST with JSON payloads, but also enables the application to update this data within the cache and to the server-side resource.

Rather than implement caching capabilities in the application code, you can configure them by editing the properties in the sync-config.xml file. When you create an application, it contains a default version of the sync-config.xml file, as shown in Figure 25-1. You can access the sync-config.xml file from the ADF-META-INF node of the Application Resources pane, and you can modify the file using the Source editor in JDeveloper. The MAF runtime reads this file after it is deployed.

Note:

Although this is an application-wide resource, you can include the sync-config.xml file in a feature archive (FAR) file. When the FAR is added to a MAF application, its sync-config.xml file is merged with the application's sync-config.xml. For more information, see Section 25.1.4, "What You May Need to Know About Using a FAR to Update the sync-config.xml File."

Figure 25-1 Data Storage Policy Settings in the sync-config.xml File's Overview Editor

Surrounding text describes Figure 25-1 .

The following example shows the default sync-config.xml file.

<?xml version="1.0" encoding="UTF-8"?>
<Settings xmlns="http://xmlns.oracle.com/sync/config">
  <BaseUri>http://127.0.0.1</BaseUri>
  <AppId/>
  <LazyPersistence/>
  <RefreshPolicy/>
  <DbStorageFolderPath/>
  <FileStorageFolderPath/>
  <Policies>
    <DefaultPolicy>
      <FetchPolicy>FETCH_FROM_SERVICE</FetchPolicy>
      <UpdatePolicy>UPDATE_IF_ONLINE</UpdatePolicy>
      <ExpirationPolicy>NEVER_EXPIRE</ExpirationPolicy>
      <EvictionPolicy>MANUAL_EVICTION</EvictionPolicy>
    </DefaultPolicy>
  </Policies>
</Settings>

The following example shows how you can define caching attributes in the sync-config.xml file. Requests are matched using the baseUri attribute and the Path element when determining which policy to use.

<?xml version="1.0" encoding="UTF-8"?>
<Settings xmlns="http://xmlns.company.com/sync/config">
  <BaseUri>http://name.loc.company.com:9100</BaseUri>
  <AppId>1</AppId>
  <LazyPersistence>false</LazyPersistence>
  <MaxCachedFileSize>1024000</MaxCachedFileSize>
  <EnableEncryption>false</EnableEncryption>
    <Policies>
      <ServerGroup id="fusion" baseUri="http://name.loc.company.com:7100/"
        <Policy id="fs01">
          <Path>/stable/rest/latest/Employees</Path>
          <FetchPolicy>FETCH_FROM_SERVICE_ON_CACHE_MISS_OR_EXPIRY</FetchPolicy>
          <UpdatePolicy>QUEUE_IF_OFFLINE</UpdatePolicy>
          <ExpirationPolicy>NEVER_EXPIRE</ExpirationPolicy>
          <EvictionPolicy>EVICT_ON_EXPIRY_AT_STARTUP</EvictionPolicy>
        </Policy>
      </ServerGroup>
        <DefaultPolicy>
          <FetchPolicy>FETCH_FROM_SERVICE_ON_CACHE_MISS_OR_EXPIRY</FetchPolicy>
          <UpdatePolicy>QUEUE_IF_OFFLINE</UpdatePolicy>
          <ExpirationPolicy>EXPIRE_AFTER</ExpirationPolicy>
          <ExpireAfter>700</ExpireAfter>
          <EvictionPolicy>EVICT_ON_EXPIRY_AT_STARTUP</EvictionPolicy>
        </DefaultPolicy>
    </Policies>
</Settings>

These are some of the use cases for which caching policies can be configured using the properties in the sync-config.xml file:

Static lists that seldom change (FETCH_FROM_SERVICE_ON_CACHE_MISS_OR_EXPIRY)
Highly dynamic data, where the results are highly contextual and should therefore be refreshed rather than cached (FETCH_FROM_CACHE_SCHEDULE_REFRESH or FETCH_FROM_SERVICE_IF_ONLINE)
Data that is likely to change with every request, such as search results (FETCH_FROM_SERVICE)

25.1.2 How to Enable Data Caching

The sync client employs specific policies when caching data, giving you the ability to cache different resources by observing specific policies defined for each resource, identified by URL. When you enable data caching, the policies in the default sync-config.xml file are used unless you overwrite them.

To enable data caching, uncomment the following line in the maf.properties file:

#java.commandline.argument=-DsyncEnabled=true

Note:

When you enable data caching, any data that is passed over the network will be cached. Once your application is deployed with caching enabled, there is no way to turn it off at runtime.

For information about configuring data storage policy settings, see Section 25.1.1, "Implementing Data Caching with the sync-config.xml File."

25.1.3 About Caching Policies

You define caching policies for a mobile app in the sync-config.xml file. Combine policies to provide appropriate content for any mobile app.

For information about configuring data storage policy settings, see Section 25.1.1, "Implementing Data Caching with the sync-config.xml File."

The policies that enable you to configure your application's caching behavior fall under the following groups:

Fetch Policies—Tells the Sync Client SDK to fetch resources (from server, from local cache, a combination of the two, and so on). See Table 25-1 for a list of these policies.
Expiration Policies—Sets the time period (in seconds) after which Sync Client SDK notes the resources stored in the local cache as out-dated or stale and therefore requiring either updating per the update policies (described in Table 25-4) or deletion from the local cache per the eviction policies (see Table 25-3). For more information on the expiration policies, see Table 25-2.
Eviction Policies—Designates when the Sync Client SDK deletes resources stored in the local cache. The eviction policies apply only to the data in the local cache, not to server-side resources. See Table 25-3 for a list of policies.
Update Policies—Defines when expired resources stored in the local cache will be updated. See Table 25-4 for a list of policies.

Table 25-1 Fetch Policies

Policy	Description
Fetch from Cache	Instructs the Sync Client SDK to fetch the data from cache only, not from the server. If the Sync Client SDK can't find the data in the cache, it returns an error or a null object. Because the Sync Client SDK retrieves data directly from the cache when it applies this policy, it can carry out this policy when the client application is online or offline.
Fetch from Service	Instructs the Sync Client SDK to fetch the data directly from the server only, not from the cache. The Sync Client SDK can only apply this policy when the client application is online. Otherwise, it returns an error or a null object to the client application.
Fetch from Service, if Online	Instructs the Sync Client SDK to fetch the data from the server when the client application is online, or to fetch data from the cache when the application is offline.
Fetch from Service on Cache-Miss	Instructs the Sync Client SDK to fetch data from the cache. If it can't find the requested data, the Sync Client SDK fetches it from the server.
Fetch from Service on Cache-Miss or Expiry	Instructs the Sync Client SDK to fetch data in the cache if it exists in the cache and is not stale (expired). Otherwise, the Sync Client SDK fetches the request data from the server.
Fetch from Cache, Schedule Refresh	Instructs the Sync Client SDK to fetch data from the cache and schedule a background refresh to update cache from the server's latest copy. If there's a cache-miss (meaning that the cache doesn't have the requested data), the Sync Client SDK returns a null object to the client application.
Fetch with Refresh	Instructs the Sync Client SDK to: Fetch data from the cache if the requested data exists and has not expired. Schedule a background refresh to update the cache from the server's latest copy. If there's a cache-miss (meaning that the cache doesn't have the requested data) or if the data has expired, the Sync Client SDK fetches the data directly from the server as it does for the Fetch from Service policy.

Table 25-2 Expiration Policies

Policy	Description
Expire on Restart	Instructs the Sync Client SDK to note the data for any URI as expired when the client application restarts, or to update the local data with the server copy the next time it's called by the client application.
Expire After	Instructs the Sync Client SDK to expire the data after a specified time (in seconds) that is set in the Expire After Duration policy. Use this policy for data that refreshed on a regular basis.
Expire After Duration	The number of seconds after which the Sync Client SDK notes that the data in the cache has expired.
Never Expire	Instructs the Client Sync SDK that it can't designate the local data as expired.

Table 25-3 Eviction Policies

Policy	Description
Evict on Expiry at Startup	Instructs the Sync Client SDK to delete the expired data from cache when the client application restarts, or to update the local data with the server copy the next time it's called by the client application.
Manual Eviction	The Sync Client SDK can't remove data from the local cache automatically. To evict data manually, use an API.

Table 25-4 Update Policies

Policy	Description
Update if Online	Instructs the Sync Client SDK to update the local cache with server-side data only when the client application is online. Otherwise, the Sync Client SDK returns an error.
Queue if Offline	Instructs the Sync Client SDK to update the local cache with server-side data when the client application is online. If the client application is offline, the Sync Client SDK queues the operation so that it can update the local cache when the client application is once again online. NOTE: This policy is not currently supported.

Policy

Description

Update if Online

Instructs the Sync Client SDK to update the local cache with server-side data only when the client application is online. Otherwise, the Sync Client SDK returns an error.

Queue if Offline

Instructs the Sync Client SDK to update the local cache with server-side data when the client application is online. If the client application is offline, the Sync Client SDK queues the operation so that it can update the local cache when the client application is once again online.

NOTE: This policy is not currently supported.

25.1.4 What You May Need to Know About Using a FAR to Update the sync-config.xml File

The sync-config.xml file is included in the Feature Archive file when the view controller project is deployed as a FAR. Like the connections.xml file, MAF merges the contents of the sync-config.xml file in the FAR (jar-sync-config.xml) with those of the consuming application's sync-config.xml file after you add the FAR to the application. Because the sync-config.xml file describes the web service endpoints used by the mobile application, you can update the endpoints for all of the web services used by the application features that comprise a mobile application by adding a FAR as described in Section 8.4, "What Happens When You Add a FAR as a View Controller Project."

After you add the FAR to the application, MAF logs messages that prompt you to verify and, if needed, modify the application's sync-config.xml and connections.xml files. As illustrated in Figure 25-2, these messages reflect the state of the sync-config.xml file in the consuming application.

Figure 25-2 The Messages Log

The surrounding text describes this image.

If the consuming application lacks the sync-config.xml file, then MAF adds the file to the application and writes a message similar to the following:

oracle.adfmf.framework.dt.deploy.features.deployers.SyncConfigMerger _logNoSyncConfigInAppUsingFar
WARNING: The application does not contain a synchronization file, "sync-config.xml". Creating one 
containing the synchronization configuration in the Feaure Archive.

MAF writes a log message similar to the following that requests that you verify (or create) a connection if the sync-config.xml file's <ServerGroup> elements do not have corresponding <Reference> elements defined in the consuming application's connections.xml file:

oracle.adfmf.framework.dt.deploy.features.deployers.SyncConfigMerger _logAddedServerGroups
WARNING: The following server groups were added sync-config.xml by the Add to Application 
operation:
{
  ServerGroup1 - there is no existing application connection defined for this server group.
Please create the connection.

  ServerGroup2 - verify its configuration.
}

If the <ServerGroup> definitions in the consuming application's sync-config.xml file duplicate those of the counterpart sync-config.xml file included in the FAR, then MAF writes the following SEVERE-level message to the log:

oracle.adfmf.framework.dt.deploy.features.deployers.SyncConfigMerger _logDuplicateServerGroups
SEVERE: Cannot merge the server groups from the Feature Archive because the following definitions 
already exist:
ServerGroup1
ServerGroup2