25 Caching Data in a MAF Application
This chapter includes the following sections:
25.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 25-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 25-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:
Note:
MAF applications only support the caching of data retrieved by REST services with JSON payloads.
25.2 Enable Data Caching in a MAF Application
To enable data caching, uncomment the following line in the maf.properties file (located at assembly_project/META-INF):
#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.
25.3 Specifying Cached Resources and Cache Policies in the sync-config.xml File
OEPE creates the sync-config.xml file in the /adf/META-INF directory of the ssembly project 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.
The second example below 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 second example below, 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.
<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>
25.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 25-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 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 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 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 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:
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 25-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 25-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 25-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. |
25.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 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.
25.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>
25.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 Using FAR Content in a MAF Application.
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. These messages reflect the state of the sync-config.xml file in the consuming application.
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