This chapter includes the following sections:
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 26-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 26-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.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.
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 26-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 enable 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 26-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 host name changes), you only need to make a change in the connections.xml
file. The sync-config.xml
file requires no changes.
Example 26-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>
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 26-1 for a list of these policies.
Expiration Policies—Sets the time period (in seconds) after which the cache layer notes the resources stored in the local cache as out-dated or stale and therefore requiring either updating in accordance with the update policies (described in Table 26-4) or deletion from the local cache in accordance with the eviction policies (see Table 26-3). For more information on the expiration policies, see Table 26-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 26-3for a list of policies.
Update Policies—Defines when expired resources stored in the local cache will be updated. See Table 26-4 for a list of policies.
Table 26-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 cannot 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 cannot 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 the cache from the server's latest copy. If there is a cache-miss (meaning that the cache does not 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 is a cache-miss (meaning that the cache does not 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 26-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 is 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 refreshes 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 cannot designate the local data as expired. |
Table 26-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 cannot remove data from the local cache automatically. To evict data manually, use an API. |
Table 26-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. |
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.
MAF provides you with the ability to encrypt data that the MAF application caches.
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>
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 26-2, these messages reflect the state of the sync-config.xml
file in the consuming application.
Figure 26-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 requesting 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