9 Synchronizing ADF Mobile Client Data and Transactions

9.4.1.1 Providing Parameters for Data Synchronization

The SyncOptions object encapsulates the parameters required by the synchronization operation.

• Username— The sync user name.

• Password—The sync password.

• Server—The URL of the Mobile Server. For example: http://syncserver.my.domain.com

• SyncProgressListener—Enables you to specify your own UI for handling sync progress events and errors by implementing oracle.adfnmc.sync.SyncProgressListener as illustrated in Example 9-2.

• SavePassword—Whether the password should be saved for future use; default is false.

• SyncMode—One of the following constants, defined in oracle.adfnmc.sync.SyncOptions, that specifies how sync credentials are to be provided:

  • SYNC_CREDENTIALS_MODE_PROMPT—Prompt the user for all necessary parameters.

  • SYNC_CREDENTIALS_MODE_EL—Use EL expressions which have already been populated with the required parameters. See also Table 9-2.

  • SYNC_CREDENTIALS_MODE_LASTUSER—Reuse the previously saved credentials.

  • SYNC_CREDENTIALS_MODE_PARAMS—The caller is providing all required parameters directly in the SyncOptions container.

  • SYNC_CREDENTIALS_MODE_SAME_AS_STARTUP—Use the same mode that was used at application startup, specified in the sync-credentials-mode key; this value is SYNC_CREDENTIALS_MODE_LASTUSER by default.

The user will be prompted to enter any missing values if not all of the required parameters have been provided, regardless of which SyncMode is specified. Table 9-1 lists examples of various synchronization modes.

SyncOptions options = new SyncOptions("username", "password", "http://syncserver.my.domain.com");

SyncOptions options = new SyncOptions(SyncOptions.SYNC_CREDENTIALS_MODE_PROMPT);

// Bind UI controls to the following expressions:
// #{syncContext.userName}
// #{syncContext.password}
// #{syncContext.url}
SyncOptions options = new SyncOptions(SyncOptions.SYNC_CREDENTIALS_MODE_EL);
// When sync begins, the required parameters are read from the EL expressions above

SyncOptions options = new SyncOptions(SyncOptions.SYNC_CREDENTIALS_MODE_LASTUSER);

SyncOptions options = new SyncOptions(SyncOptions.SYNC_CREDENTIALS_MODE_SAME_AS_STARTUP);

public class ConsoleSyncProgressListener implements SyncProgressListener
{
  public void progress(String message, int progress, int phase)
  {
    System.out.println("Sync phase: " + phase + ", progress %" + progress + ", message = " + message);
  }
}
SyncOptions options = new SyncOptions(SyncOptions.SYNC_CREDENTIALS_MODE_PROMPT);
options.setSyncProgressListener(new ConsoleProgressListener());
myAppModule.sync(options);

9.5.1.1 How to Create a Custom Synchronization Page

To enable this page (the custom sync page), you must create an additional ADF Mobile client task flow as well as an MCX file using the ADF Mobile client page and task flow dialogs.

Before you begin:

Familiarize yourself with creating MCX pages and task flows as described in Chapter 6, "Creating the ADF Mobile Client User Interface."

To create the custom sync page:

1. Right-click the MobileClient project and choose File then New then ADF Mobile Client and then ADF Mobile Client Page.

2. Create an MCX file. For example, create a page called CustomMobileSyncPage.mcx, shown in Figure 9-3 with code similar to Example 9-3.

   Figure 9-3 The Custom Sync Page

   
   

   Example 9-3 A Custom Sync Page

   <?xml version='1.0' encoding='windows-1252'?>
   <amc:view xmlns:amc="http://xmlns.oracle.com/jdev/amc">
            <amc:form onShow="#{syncContext.MobileSyncBean.onShow.execute}">
               <amc:panelGroupLayout id="home" layout="vertical">
                      <amc:outputText id="lblTitle" value="Custom Mobile Sync" fontWeight="bold" />
                      <amc:panelFormLayout>
                        <amc:inputText id="txtUserName" label="User Name: " value="#{syncContext.userName}" />
                        <amc:inputText id="txtPassword" label="Password: " value="#{syncContext.password}" secret="true" />
                        <amc:inputText id="txtUrl" label="URL: " value="#{syncContext.url}" />
                        <amc:selectBooleanCheckbox id="cbSave" label="Save Password:" value="#{syncContext.saveCredentials}" />
                     </amc:panelFormLayout>
                     <amc:panelGroupLayout layout="horizontal">
                        <amc:commandButton id="btnGo" disabled="#{syncContext.syncInProgress}" actionListener="#{syncContext.MobileSyncBean.sync.execute}" text="#{syncContext.syncLocal != true ? 'Sync' : 'OK'}" />
                        <amc:commandButton id="btnStop" actionListener="#{syncContext.MobileSyncBean.cancel.execute}" text="Cancel" />
                     </amc:panelGroupLayout>
                     <amc:panelGroupLayout layout="horizontal">
                              <amc:outputText id="lblProgress" rendered="#{syncContext.syncInProgress}" value="Progress:" />
                     </amc:panelGroupLayout>
                     <amc:outputText id="lblStatus" value="Status: #{syncContext.statusMessage}" foregroundColor="#{syncContext.error == null ? '#000000' : '#FF0000'}"/>
               </amc:panelGroupLayout>
            </amc:form>
   </amc:view>
   

   For the page to function properly, it must include the following:

   • onShow handling to reset values on the page:

     <amc:form onShow="#{syncContext.MobileSyncBean.onShow}">
     

   • User name, password, and URL information are defined within inputText components with the following values:

     <amc:inputText id="txtUserName" label="User Name: " value="#{syncContext.userName}" />
     <amc:inputText id="txtPassword" label="Password: " value="#{syncContext.password}" secret="true" />
     <amc:inputText id="txtUrl" label="URL: " value="#{syncContext.url}" />
     

   • To save credentials, create a checkbox component with the following value:

     <amc:selectBooleanCheckbox id="cbSave" label="Save Password:" value="#{syncContext.saveCredentials}" />
     

   • To initiate the sync process, you must have the following listener tied to a control:

     <amc:commandButton id="btnGo" disabled="#{syncContext.syncInProgress}" actionListener="#{syncContext.MobileSyncBean.sync}" text="#{syncContext.syncLocal != true ? 'Sync' : 'OK'}" />
     

   • To terminate the sync process (which is optional), you must have the following listener tied to a control:

     <amc:commandButton id="btnStop" actionListener="#{syncContext.MobileSyncBean.cancel}" text="Cancel" />
     

   The remaining content in Example 9-3 is optional. Table 9-2 lists the sync-related EL expressions used in this page.

   Table 9-2 Sync EL Expression Reference

   Expression	Description
   #{syncContext.error}	Contains any exception that may have been thrown by a synchronization operation.
   #{syncContext.syncInProgress}	Inquires if a synchronization operation is currently running.
   #{syncContext.userName}	The sync user name.
   #{syncContext.password}	The sync password.
   #{syncContext.saveCredentials}	Inquires if the password should be saved.
   #{syncContext.url}	The address of the Mobile Server against which to synchronize.
   #{syncContext.statusMessage}	A brief message describing the current synchronization phase (for example, sending data, receiving data).
   #{syncContext.currentProgress}	The percent complete of the current sync phase.

   
   

3. Right-click the MobileClient project and choose File then New then ADF Mobile Client and then ADF Mobile Client Task Flow.

4. Create the bounded task flow. For example, create a task flow called custom-mobile-sync-task-flow.xml using code similar to that illustrated in Example 9-4.

   Example 9-4 The Sync Task Flow

   <?xml version="1.0" encoding="windows-1252" ?>
   <adfc-config xmlns="http://xmlns.oracle.com/adf/controller" version="1.2">
     <task-flow-definition id="custom-mobile-sync-task-flow">
       <default-activity id="__1">CustomMobileSyncPage</default-activity>
       <view id="CustomMobileSyncPage">
         <page>/CustomMobileSyncPage.mcx</page>
       </view>
       <task-flow-return id="mobileSyncSuccess">
         <outcome id="__2">
           <name>mobileSyncSuccess</name>
         </outcome>
       </task-flow-return>
       <task-flow-return id="mobileSyncFailure">
         <outcome id="__3">
           <name>mobileSyncFailure</name>
         </outcome>
       </task-flow-return>   
       <control-flow-rule id="__4">
         <from-activity-id id="__5">CustomMobileSyncPage</from-activity-id>
         <control-flow-case id="__6">
           <from-outcome id="__7">toMobileSyncSuccess</from-outcome>
           <to-activity-id id="__8">mobileSyncSuccess</to-activity-id>
         </control-flow-case>
         <control-flow-case id="__9">
           <from-outcome id="__10">toMobileSyncFailure</from-outcome>
           <to-activity-id id="__11">mobileSyncFailure</to-activity-id>
         </control-flow-case>     
       </control-flow-rule>
     </task-flow-definition>
   </adfc-config>
   

   Figure 9-4 shows the task flow created from the code illustrated in Example 9-4.

   Figure 9-4 Bounded Task Flow for Sync

   
   

5. In the application task flow, add a task flow call that points to the sync task flow, such as CustomMobileSyncTaskFlowCall in Example 9-5. For more information on task flow calls, see "Using Task Flow Call Activities" in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

   Example 9-5 The Task Flow Call to the Sync Task Flow

   <task-flow-call id="CustomMobileSyncTaskFlowCall">
           <task-flow-reference>
               <document>/custom-mobile-sync-task-flow.xml</document>
               <id>custom-mobile-sync-task-flow</id>
           </task-flow-reference>
       </task-flow-call>
   

9.5.1.2 Updating the Application Task Flow

Add a control flow rule to override the toMobileSyncTaskFlow outcome as illustrated in Example 9-6.

<control-flow-rule>
      <from-activity-id>*</from-activity-id>
      <control-flow-case>
        <from-outcome>toMobileSyncTaskFlow</from-outcome>
          <to-activity-id>CustomMobileSyncTaskFlowCall</to-activity-id>
      </control-flow-case>
    </control-flow-rule>

Figure 9-5 shows the task flow override in the diagrammer.

Figure 9-5 Task Flow Call Pointing to Custom Task Flow