24 Caching Data in a MAF Application

This chapter describes how to cache data in MAF applications.

This chapter includes the following sections:

• Introduction to Data Caching in MAF Applications

• Enable Data Caching in a MAF Application

• Specifying Cached Resources and Cache Policies in the sync-config.xml File

• Caching Policies Provided by MAF

• Using Configuration Service End Points in the sync-config.xml File

• Encrypting Cached Data in a MAF Application

• Packaging the sync-config.xml File in a FAR

24.1 Introduction to Data Caching in MAF Applications

Data caching plays a key part providing a positive user experience to the users of mobile applications. Users expect mobile applications to be available and to work, at all times. Unfortunately, mobile application connectivity can be unreliable, as network connectivity may not be available, or it may come and go as connections are established and subsequently dropped. MAF provides a number of capabilities to enable you to develop MAF applications that continue to work even when the end user’s device is offline. When network connectivity is unavailable, your MAF application can access locally stored cached data to ensure a seamless user experience.

Figure 24-1 shows how caching works in MAF. The cache layer intercepts REST calls that originate from the Business Logic layer. The cache layer reads the sync-config.xml file, and based on the file’s entries, stores responses from the REST service in the cached data store. The sync-config.xml file is where you specify URI (end point) resources to cache and the cache policies for the URI. The cache layer uses the URI that you specify as the key to identify a specific resource in the cache.

Figure 24-1 Caching Data in a MAF Application

MAF provides a set of policies that you can apply and configure to determine the refresh and expiration frequency of the data in the cache. These policies tell the cache layer how to process requests and, as a result, enable you to improve application performance because it is 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.

Implementing the functionality described in your MAF application requires you to:

• Enable Data Caching in a MAF Application

• Specifying Cached Resources and Cache Policies in the sync-config.xml File

• Encrypting Cached Data in a MAF Application

Note:

MAF applications only support the caching of data retrieved by REST services with JSON payloads.

24.2 Enable Data Caching in a MAF Application

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 passes 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 the resources to cache and the cache policies to use, see Specifying Cached Resources and Cache Policies in the sync-config.xml File.

24.3 Specifying Cached Resources and Cache Policies in the sync-config.xml File

JDeveloper creates the sync-config.xml file in the /.adf/META-INF directory of the MAF application by default when you create a MAF application. Use this file to specify caching policies to apply when your MAF application makes calls to end points (URIs) that you specify. By default, the sync-config.xml file includes a default policy that applies when you enable caching. This default caching policy applies to all end points other than those that you specify in the sync-config.xml file.

Example 24-1 demonstrates how you define two separate policies (policy1 and policy2) for two separate end points (URIs) that originate from the same server. The example also shows a default policy that applies when the MAF application makes REST calls to all other URIs other than those specified for policy1 and policy2. Finally, the example shows how you enables encryption.

You can view another example of a caching policy in use in the WorkBetter sample application's sync-config.xml file. For more information about the sample applications, see MAF Sample Applications.

In Example 24-1, TaskConn in the BaseURI element of the sync-config.xml is a reference to a connection that is defined in the MAF application's connections.xml file, as follows:

<Reference name="TaskConn" className="oracle.adf.model.connection.url.HttpURLConnection" xmlns="">
    <Factory className="oracle.adf.model.connection.url.URLConnectionFactory"/>
    <RefAddresses>
      <XmlRefAddr addrType="TaskConn">
        <Contents>
          <urlconnection name="TaskConn" url="http://localhost:7101/TaskService/rest/v1"/>
        </Contents>
      </XmlRefAddr>
    </RefAddresses>
  </Reference>

The benefit of this configuration is that, if connection details change (for example, a change in host name), you only need to make a change in the connections.xml file. No change will be required to the sync-config.xml file.

Example 24-1 Sample sync-config.xml File Defining Two Policies

<Settings xmlns="http://xmlns.oracle.com/sync/config">
   <!-- The connection.xml file defines the URL that the value of the BaseURI element references. -->
   <BaseUri>TaskConn</BaseUri>

   ...
   <EnableEncryption>true</EnableEncryption>
   <Policies>
        <ServerGroup id="tasklist" baseUri="TaskConn">
           <Policy id="policy1">
                <Path>/taskservice1/rest/v1/TaskList/*</Path>
                
         <!-- This caching policy applies to a REST service accessed by a call to an end point constructed from 
              a concatenation of the baseURI value for TaskConn and the <Path> element's value. That is,
              http://localhost:7101/TaskService/rest/v1/taskservice1/rest/v1/TaskList/* 

              When the end point above is used by the business logic layer in the MAF application, the cache layer checks sync-config.xml
        to see if there is a cache policy defined for the end point. If it finds the policy, it applies the policy. -->

                <FetchPolicy>FETCH_FROM_SERVICE_ON_CACHE_MISS_OR_EXPIRY</FetchPolicy>
                <UpdatePolicy>QUEUE_IF_OFFLINE</UpdatePolicy>
                <ExpirationPolicy>EXPIRE_AFTER</ExpirationPolicy>
                <ExpireAfter>30</ExpireAfter>
                <EvictionPolicy>EVICT_ON_EXPIRY_AT_STARTUP</EvictionPolicy>
   </Policy>
        </ServerGroup>

        <ServerGroup id="taskdetail" baseUri="TaskConn">
           <Policy id="policy2">
                <Path>/taskservice1/rest/v1/TaskDetail/*</Path>
                
         <!-- This caching policy applies to a different REST service accessed by a call to an end point constructed from 
              a concatenation of the baseURI value for TaskConn and the <Path> element's value. That is,
              http://localhost:7101/TaskService/rest/v1/taskservice1/rest/v1/TaskDetail/*

              When the end point above is used by the business logic layer in the MAF app, the cache layer checks sync-config.xml 
              to see if there is a cache policy defined for the end point. If it finds the policy, it applies the policy. -->
                
                   <FetchPolicy>FETCH_FROM_SERVICE_IF_ONLINE</FetchPolicy> 
                   <UpdatePolicy>UPDATE_IF_ONLINE</UpdatePolicy>
                   <ExpirationPolicy>EXPIRE_AFTER</ExpirationPolicy>
                   <ExpireAfter>30</ExpireAfter>
                   <EvictionPolicy>EVICT_ON_EXPIRY_AT_STARTUP</EvictionPolicy>
           </Policy>
        </ServerGroup>

  <DefaultPolicy>
                <FetchPolicy>FETCH_FROM_SERVICE_IF_ONLINE</FetchPolicy>
                <UpdatePolicy>UPDATE_IF_ONLINE</UpdatePolicy>
                <ExpirationPolicy>NEVER_EXPIRE</ExpirationPolicy>
                <EvictionPolicy>MANUAL_EVICTION</EvictionPolicy>
           </DefaultPolicy>
   </Policies>
</Settings>

24.4 Caching Policies Provided by MAF

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

For information about configuring data storage policy settings, see Specifying Cached Resources and Cache Policies in 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 cache layer to fetch resources (from server, from local cache, a combination of the two, and so on). See Table 24-1 for a list of these policies.

• Expiration Policies—Sets the time period (in seconds) after which cache layer 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 24-4) or deletion from the local cache per the eviction policies (see Table 24-3). For more information on the expiration policies, see Table 24-2.

• Eviction Policies—Designates when the cache layer 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 24-3for a list of policies.

• Update Policies—Defines when expired resources stored in the local cache will be updated. See Table 24-4 for a list of policies.

Table 24-1 Fetch Policies

Policy	Description
Fetch from Cache	Instructs the cache layer to fetch the data from cache only, not from the server. If the cache layer can't find the data in the cache, it returns an error or a null object. Because the cache layer 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 cache layer to fetch the data directly from the server only, not from the cache. The cache layer 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 cache layer 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 cache layer to fetch data from the cache. If it can't find the requested data, the cache layer fetches it from the server.
Fetch from Service on Cache-Miss or Expiry	Instructs the cache layer to fetch data in the cache if it exists in the cache and is not stale (expired). Otherwise, the cache layer fetches the request data from the server.
Fetch from Cache, Schedule Refresh	Instructs the cache layer 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 cache layer returns a null object to the client application.
Fetch with Refresh	Instructs the cache layer 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 cache layer fetches the data directly from the server as it does for the Fetch from Service policy.

Table 24-2 Expiration Policies

Policy	Description
Expire on Restart	Instructs the cache layer 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 cache layer 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 cache layer notes that the data in the cache has expired.
Never Expire	Instructs the cache layer that it can't designate the local data as expired.

Table 24-3 Eviction Policies

Policy	Description
Evict on Expiry at Startup	Instructs the cache layer 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 cache layer can't remove data from the local cache automatically. To evict data manually, use an API.

Table 24-4 Update Policies

Policy	Description
Update if Online	Instructs the cache layer to update the local cache with server-side data only when the client application is online. Otherwise, the cache layer returns an error.

24.5 Using Configuration Service End Points in the sync-config.xml File

The BaseUri element and baseUri attribute on the ServerGroup element in sync-config.xml can refer to end points defined in connections.xml. To take advantage of this functionality, replace the values to point to a valid connection reference rather than a URL as follows:

baseUri="<connection_reference_name_in_connections_xml>"

If an end point is changed at runtime using connection overrides, the cache policies remain the same for the new URL. For more information, see Chapter 16, "Configuring End Points Used in MAF Applications . The WorkBetter sample application demonstrates an implementation of this configuration. For information about how to access this and other sample applications, see MAF Sample Applications.

24.6 Encrypting Cached Data in a MAF Application

MAF provides you with the ability to encrypt data that the MAF application caches.

Once enabled, all data cached by the MAF application is encrypted. By default, it is disabled. You configure the sync-config.xml file to enable encryption, as shown in the following example.

<?xml version="1.0" encoding="UTF-8"?>
<Settings xmlns="http://xmlns.oracle.com/sync/config">
  <BaseUri>TaskConn</BaseUri>
  ...
  <EnableEncryption>true</EnableEncryption>
  <Policies>
  ...
</Settings>

24.7 Packaging the sync-config.xml File in a FAR

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 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 24-2, these messages reflect the state of the sync-config.xml file in the consuming application.

Figure 24-2 The Messages Log

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