25 Synchronizing and Caching Data

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

This chapter includes the following sections:

25.1 Introduction to Data Caching and Synchronization

Data synchronization is a key part of 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 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 applications, MAF provides synchronization APIs that enable you to develop applications that will continue to work, even when offline, ensuring the best possible user experience for your Mobile applications. When network connectivity is unavailable, your application can access locally stored cached data to ensure a seamless user experience.

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 and synchronizing data, giving you the ability to cache different resources by observing specific policies defined for each resource. The sync client caches data locally, using the policies set in the default sync-config.xml file.

The sync-config.xml file enables the mobile application to not only cache the data retrieved from server-side resources accessed through various types of web services (SOAP, REST-XML, or REST with JSON payloads) to the embedded SQLite database, 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 illustrates the default sync-config.xml file. The properties in this file enable you to configure the caching policy for:

  • Static lists that seldom change

  • Large collections that frequently change (fetching deltas rather than refreshing the entire list)

  • Highly dynamic data, where the results are highly contextual and should therefore be refreshed rather than cached

  • Caching an individual resource and its direct children, both with one-to-one and one-to-n cardinality

<?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>

25.1.2 How to Enable Data Synchronization

The sync client employs specific policies when caching and synchronizing data, giving you the ability to cache different resources by observing specific policies defined for each resource. To enable data synchronization, uncomment the following line in the maf.properties file:

# Sync functionality is disabled by default. Uncomment the line below to enable it.
#java.commandline.argument=-DsyncEnabled=true

Note:

Once your application is deployed with synchronization 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 How to Use 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>

Note:

Be careful to replace URLs in sync-config.xml only with end points that refer to exactly the same URL specified in connections.xml. The migrator will automatically create end points in connections.xml and update sync-config.xml to use them when the application is migrated. Any subsequent changes to connection end points in sync-config.xml must be done manually.

If an end point is changed at runtime using connection overrides, the sync policies remain the same for the new URL. For more information, see Chapter 16, "Section 16, "Configuring End Points Used in MAF Applications."

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