5 Managing Synchronization

The Mobile Server administrator uses the Data Synchronization Manager to manage synchronization tasks. This chapter includes:

5.1 How Does the Synchronization Process Work?

The Mobile Server uses synchronization to replicate data between the Mobile clients with their client Oracle Lite databases (including those for OC4J, Web-to-Go, Win32, Windows CE, Symbian and Linux platforms) and the application tables, which are stored on a back-end Oracle database.

When most people think of synchronizing data, they think of their Palm Pilot. When you hit the synchronization button for the Palm Pilot, any changes are added to the database of information on the Windows machine immediately. This is not the case for Oracle Database Lite, which is used for multiple clients. In order to accomodate multiple users, the application tables on the back-end database cannot be locked by a single user. Thus, the synchronization process involves using queues to manage the information between the Mobile clients and the application tables in the database (demonstrated by Figure 5-1), as follows:

Figure 5-1 Data Synchronization Architecture

synchronization architecture.
Description of "Figure 5-1 Data Synchronization Architecture"

  1. Synchronization is initiated on the Mobile client either by the user or from automatic synchronization. Note that the Mobile client may be a Windows platform client or a PDA.

  2. Mobile client software gathers all of the client changes into a transaction and the Sync Client uploads the transaction to the Sync Server on the Mobile Server.

  3. Sync Server places the transaction into the In-Queue.

    Note:

    When packaging your application, you can specify if the transaction is to be applied at the same time as the synchronization. If you set this option, then the transaction is immediately applied to the application tables. However, note that this may not be scaleable and you should only do this if the application of the transaction immediately is important and you have enough resources to handle the load.

  4. Sync Server gathers all transactions destined for the Mobile client from the Out-Queue.

  5. Sync client downloads all changes for client Oracle Lite database.

  6. Mobile client applies all changes for client Oracle Lite database. If this is the first synchronization, the Oracle Lite database is created.

    Note:

    For information on what Oracle Lite database (ODB) files are installed on the client, see Section 2.2, "Synchronize or Execute Applications on the Mobile Client".

  7. All transactions uploaded by all Mobile clients are gathered by the MGP out of the In-Queue.

  8. The MGP executes the apply phase by applying all transactions for the Mobile clients to their respective application tables to the back-end Oracle database. The MGP commits after processing each publication.

    Note:

    The behavior of the apply/compose phase can be modified. See Section 5.1.1, "Defining Behavior of Apply/Compose Phase for Synchronization" for more information.

  9. MGP executes the compose phase by gathering the client data into outgoing transactions for Mobile clients.

  10. MGP places the composed data for Mobile clients into the Out-Queue, waiting for the next client synchronization for the Sync Server to gather the updates to the client.

Overall, synchronization involves two parties: the Mobile client using the Sync Client/Server to upload and download changes and the MGP process interacting with the queues and the application tables to apply and compose transactions. These are displayed separately in the Data Synchronization section of the Mobile Manager.

On the Mobile Server home page, you can navigate to the Data Synchronization home page by clicking Data Synchronization, which is located under the Components section.

5.1.1 Defining Behavior of Apply/Compose Phase for Synchronization

By default, before the MGP processes the Compose, it checks to see if user data has been uploaded into the In Queue. The MGP checks to see if the user uploaded data before it performs the compose for that user, because if the compose completes with unresolved data from the user, then the user data may be compromised. So, the Compose is not performed to ensure that user data is not overwritten. Instead, the Compose phase is terminated and then waits until the next time that the MGP runs the Apply/Compose phase.

However, you can modify this behavior. The compose phase may take a while, depending on the number of users, so you may not want to wait until the next MGP compose phase. In this case, use the DO_APPLY_BFR_COMPOSE parameter. Or, maybe you know that the uploaded client data will not be compromised by the compose; in this case, use the SKIP_INQ_CHK_BFR_COMPOSE parameter.

Table 5-1

Webtogo.ora Parameter Description

DO_APPLY_BFR_COMPOSE

Setting DO_APPLY_BFR_COMPOSE to true modifies this behavior. If data is in the in queue, MGP will execute a second Apply to commit all user data and then will execute the Compose.

SKIP_INQ_CHK_BFR_COMPOSE

Setting SKIP_INQ_CHK_BFR_COMPOSE to true modifies this behavior. Even if data is in the in queue, MGP executes the Compose. The data that was uploaded to the In Queue must be data that will not be compromised by downloading data from the server to the client.

Note:

Setting these parameters can also avoid the MGP Compose postponed error. For more information, see Section 2.1.6 "MGP Compose Postponed Due to Transaction in the In-Queue" in the Oracle Database Lite Troubleshooting and Tuning Guide.

5.2 User Scenarios for Synchronization

The following scenarios demonstrate how a client user may want to synchronize the data:

  • You can enable Automatic Synchronization between the client and the server, which is specified on the publication item level. With automatic synchronization, you can specify under which conditions synchronization is automatically started to save any changes on the client back to the server. This way, the client data is synchronized on a regular basis in the background, automatically, without user intervention.

    For more information on automatic synchronization, see Section 5.4, "Using Automatic Synchronization".

  • You can specify that the client or the client application manually synchronizes. The user can synchronize through a GUI; an application can initiate synchronization programmatically through the APIs. This manually initiates synchronization for uploading/downloading the modifications made on the client and server. This is the default mechanism for synchronization.

  • You can enable a type of synchronization where only the data on the client is uploaded to the server; data is never downloaded from the server. This is an option for read-only clients, where multiple clients are using the same data. If you have a situation where you have a large number of clients that use the same read-only data, use the cached user, which can be replicated on multiple clients. See Section 5.6, "Improving Performance for Multiple Clients that Use the Same Read-Only Data With a Cached User" for more details.

5.3 Managing the Sync Server from the Data Synchronization Home Page

The Sync Server is an HTTP servlet that listens to client synchronization requests. As demonstrated by Figure 5-1, during every synchronization session, the Sync Server uploads client transactions from the client Oracle Lite database and places them within the In-Queues. The Sync Server then downloads any server-side transactions from the Out-Queues to the client Oracle Lite database.

From the Data Synchronization home page, you can manage Sync Server tasks—such as the following:

5.3.1 Starting/Stopping the Sync Server

To start the Sync Server, navigate to the Data Synchronization home page. The Sync Server default status is Up, as displayed in Figure 5-2.

  1. Figure 5-2 Data Synchronization Home Page

    The Data Synchronization home page.
    Description of "Figure 5-2 Data Synchronization Home Page"

To gracefully shut down the Sync Server, click Stop. The Sync Server stops after all current sessions have completed synchronization. To immediately stop the Sync Server, click Stop Immediately, which kills current sync sessions immediately. Use for emergency situations.

5.3.2 Checking Synchronization Alerts

On the right-hand side of the Data Synchronization Home page, you can see all of the alerts. Both the Sync Server and MGP register alerts if a problem occurs within any part of the synchronization phases. There are two types of alerts, as follows:

  • Critical alerts—For the Sync Server, clients cannot synchronize if the Sync Server encounters an exception (also known as a critical alert); thus, the errors must be resolved by the administrator. Once resolved, the administrator re-starts the Sync Server.

  • Warning alerts—These alerts are registered when an individual synchronization session fails. The administrator checks the Sync session details in the Sync Session History and determines the reasons for the failure. If necessary, the administrator may need to involve a DBA, if the reason is database-related.

Each alert provides the alert name, degree of severity, time when the alert was triggered, and time when the alert was last checked by a DBA.

Table 5-2 lists sample alerts. Note that the type designates whether the alert originates from the Sync Server or the MGP.

Table 5-2 Alert Types

Name Type Severity

Sync Server Exception

Sync Server

CRITICAL

User Sync Failure(s)

Sync Server

WARNING

MGP Job Exception

MGP

CRITICAL

MGP User Apply/Compose Failure(s)

MGP

WARNING

5.3.3 Managing Sync Sessions

For all users, the sessions that are currently in the process of synchronization are displayed in the Active Sessions table at the bottom of the Data Synchronization Home Page. Synchronization involves uploading or downloading updates between the the Sync Client and Sync Server.

You can terminate any active session on the Data Synchronization Home page by performing the following steps:

  1. Select the active session that you wish to terminate and click Kill.

  2. Click Yes.

  3. Click OK for the confirmation message.

The Active Sessions table on the Data Synchronization home page also displays session details. Select the active session that you wish to view and click Details to see the publication items that have been uploaded or downloaded, waiting publication items, records and timing information, and the session trace file.

If you want to view all details about completed synchronization sessions, navigate to the Synchronization History Sessions screen. To navigate to this screen, either click the number hyperlink next to History Sessions on the home page or navigate through the Performance tab. The total number of registered sessions is designated by the number next to History Sessions.

Note:

The session history for each user between the Sync Client and Sync Server is saved only if you set the SYNC_HISTORY parameter to YES, which is the default. You can set the SYNC_HISTORY instance parameter to YES or NO by navigating to Data Synchronization->Administration->Instance Parameters.

Figure 5-3 shows the Synchronization History Sessions page.

Figure 5-3 Synchronization History Sessions Page

The Synchronization History Sessions page.
Description of "Figure 5-3 Synchronization History Sessions Page"

All session history is not displayed until you search for the appropriate records. If you want all records within a specified date, then the only thing that you need to provide is the From and To date range and click Search. Be careful to only click Search and Delete if you want these records removed. You can further narrow the search by specifying one or more of the following:

  • The name of the user from which all synchronizations originated

  • The device platform type to see all synchronizations from just these platforms.

  • Only those synchronizations that were successful or failures from the server-side.

  • Only those synchronizations that were successful or failures from the device-side.

The Session History page displays matched sessions in the Results section. Once displayed, you can sort by most of the headers to either sort top to bottom or bottom to top. For example, to sort sync sessions by user, click the User header title.

To delete a session, select the session that you want to delete and click Delete. To view the details of a session, select the session and click Details. The Sync History Session page displays session details, such as publication items that are uploaded or downloaded, records and timing information, and the session trace file. The View and Download links are automatically enabled for viewing or downloading trace files that are available for the chosen session.

5.3.4 Displaying Operating System (OS) and Java Virtual Machine (JVM) Information

You can see the operating system and JVM versions that are installed on the host where the Mobile Server resides by clicking the Host hyperlink that is located below the Start/Stop buttons on the Data Synchronization home page. As displayed in Figure 5-4, the Host page displays host information, such as host name, IP address, OS type, and OS user name. The JVM section displays the Java CLASSPATH, Java version, and heap memory size.

Figure 5-4 Host Page

The Host page.
Description of "Figure 5-4 Host Page"

5.4 Using Automatic Synchronization

In the past, a client had to manually request synchronization either through an application program executing an API or by a user manually pushing the Sync button. Now, you are provided the option to configure under what circumstances synchronization should occur and then Oracle Database Lite performs the synchronization for you automatically. This way, synchronization can happen seamlessly without the user's knowledge.

For example, you may have a user who changes data on their handheld device, but does not sync as often as you would prefer. You may have multiple users who all synchronize at the same time and overload your system. These are just a few examples of how automatic synchronization can make managing your data easier, be more timely, and occur at the moment you need it to be uploaded.

Automatic synchronization is specified on the publication item. The rules for when and how synchronization is automatically started may be specified in the publication, publication item, and/or platform level. With automatic synchronization, the client data is backed up on a regular basis in the background, automatically, without user intervention.

The rules for Automatic Synchronization are defined in three places:

The following provides more information about your automatic synchronization:

5.4.1 Specifying Platform Rules for Automatic Synchronization

You can specify rules that apply to publications that are enabled for automatic synchronization for a given platform. There are two types of rules: events and conditions. If an event is true, it starts synchronization; however, the synchronization cannot occur unless all conditions are true, as well. This evaluates as follows:

when EVENT and if (CONDITIONS) then sync;

Specify these rules in the Mobile Manager Platform Settings page under Data Synchronization.

Note:

These rules only apply to automatic synchronization. If the user manually starts synchronization, it will execute.

To specify platform-based rules for all publications, perform the following:

  1. On the Data Synchronization page, select Platform Settings. Figure 5-5 shows the settings for automatic synchronization on each platform.

    Figure 5-5 Platform Settings for Automatic Synchronization

    Platform settings for automatic synchronization
    Description of "Figure 5-5 Platform Settings for Automatic Synchronization"

  2. Select the platform name to modify the automatic synchronization platform settings. Figure 5-6 shows the screen for the platform-based rules. There are three tabs: System Events, Conditions, and Networks.

    Figure 5-6 Platform-Based System Events for Automatic Synchronization

    Description of Figure 5-6 follows
    Description of "Figure 5-6 Platform-Based System Events for Automatic Synchronization"

  3. Configure the System Events. Figure 5-6 shows the System Events page. Select the checkbox for each event that you want to enable. If the event requires a value, enter the value you desire to be followed. If one event is true, then the automatic synchronization is initiated the first time the event occurs. For example, if the battery runs below the percentage you specified, the automatic synchronization occurs. As the battery continues to deplete, you will not trigger another synchronization.

    The following three system events will trigger an automatic synchronization if true.

    • Synchronize when the network bandwidth is greater than <number> Kb/second. Where <number> is an integer that indicates the bandwidth in KB/seconds. When the bandwidth becomes available, the synchronization occurs.

    • Synchronize when the battery level drops to <number>%, where <number> is a percentage. Often you may wish to synchronize before you lose battery power. Set this to the percentage of battery left, when you want the synchronization to automatically occur.

    • Synchronize when the AC power is detected. Select this checkbox if you want the synchronization to occur when the device is plugged in.

    • Synchronize at a specific time or time interval. You can configure an automatic synchronization to occur at a specific time each day or as an interval.

      • Select Specify Time if you want to automatically synchronize at a specific hour, such as 8:00 AM, everyday.

      • Select Specify Time Interval if you want to synchronize at a specific interval. For example, if you want to synchronize every hour, then specify how long to wait in-between synchronization attempts.

  4. Configure the Platform Conditions. Select the Conditions tab. Figure 5-7 displays the Conditions screen.

    If an Automatic Synchronization is about to start, Oracle Database Lite evaluates the conditions to determine if the synchronization can continue. If the condition is not true, the synchronization cannot proceed. For example, if you enabled that synchronization can only occur if the battery level is greater than 30%, then if an automatic synchronization is about to start, but the battery level is at 20%, this synchronization is canceled.

    Figure 5-7 Platform-Based Conditions for Automatic Synchronization

    Description of Figure 5-7 follows
    Description of "Figure 5-7 Platform-Based Conditions for Automatic Synchronization"

    The following conditions that must be true for this platform in order for any automatic synchronization to occur:

    • Synchronize only if the battery level is greater than <number>%, where <number> is the percentage of battery level left. Sometimes you may not want synchronization to occur and use up what battery you may have left. Thus, you can specify a minimum at which point you do not want this feature to occur. This condition must be true in order for an automatic synchronization to occur.

      Click Apply to save changes; click Revert to cancel changes.

    • Data/Network Conditions: You could have defined records in your snapshot with a data priority of HIGH (value of 0) or LOW (value of 1).

      Note:

      Data priority is a column that is added to the table to indicate priority of the row. You can modify the values in this column to either 0 or 1.

      Use this condition to specify under what conditions the different priority records are synchronized. By default, the value is LOW, which is synchronized last. If you have a very low network bandwidth and a high ping delay, you may only want to synchronize your HIGH priority data.

      • Select an existing condition and click Edit to modify an existing condition.

      • Select an existing condition and click Delete to remove an existing condition.

      If you selected a condition and clicked Edit, Figure 5-8 displays the fields that you can specify for this condition.

      Figure 5-8 Editing the Data Priority Condition

      Editing the data priority condition
      Description of "Figure 5-8 Editing the Data Priority Condition"

    The values you can specify for the data priority condition are as follows:

    • Minimum Network Bandwidth (bits/sec): Configure the minimum bandwidth (bits/second) in which the automatic synchronization can occur for records with this data priority.

    • Maximum Ping Delay (ms): Configure the maximum ping delay (milliseconds) in which the automatic synchronization can occur for records with this data priority.

    • Include Dial-up Networks?: The always-on network is used if available. However, if this network is not available, select YES if you want to use any of the dial-up networks for this data priority.

  5. Configure the Network settings for the platform rules.

    Figure 5-9 Add Network Information for Automatic Synchronization

    Add Network Information for automatic synchronization
    Description of "Figure 5-9 Add Network Information for Automatic Synchronization"

    The Network settings screen provides any proxy server configuration—if your network provider requires that you specify a proxy server to access the internet. You could have two types of networks, as follows:

    • Always-on: If this network uses a proxy server, then define the proxy and port number. Click Apply when finished.

    • Dial-up:

      • Click Add Dial-up Network to add a a new entry for dial-up configuration.

      • To edit an existing configuration, select the name of the existing configuration.

      • To delete an existing configuration, select the checkbox next to the desired configuration and click Delete.

    Figure 5-10 Add Dial-Up Network Information

    Add dial-up network information
    Description of "Figure 5-10 Add Dial-Up Network Information"

    If you are required to provide proxy configuration for any dial-up network, then configure the following so that Oracle Database Lite can connect to the Mobile Server for the automatic synchronization process. If you do not need to define a proxy for a dial-up network, but you want to include it in the order of execution, you can add an entry with only the network name. You do not need to specify the proxy server and port.

    • Network Name—Specify the network name, which is the same as the network name defined on the device.

    • Proxy Server—If you have to go through a proxy server, then provide the name of the proxy server for the dial-up network.

    • Port—Provide the port number of the proxy server.

5.4.2 Start, Stop, or Get Status for Automatic Synchronization

You can start, stop or retrieve status of automatic synchronization through the Sync Agent UI, which is started either through the Start menu or by running the syncagent.exe executable in a command prompt. Figure 5-11 shows the Sync Agent UI.

Note:

You can also start and stop automatic synchronization using programmatic APIs. For full details, see Section 3.2.2, "Enable/Disable Automatic Synchronization" in the Oracle Database Lite Developer's Guide.

Figure 5-11 Managing Automatic Synchronization Agent

automatic synchronization agent
Description of "Figure 5-11 Managing Automatic Synchronization Agent"

The Synchronization Agent controls the automatic synchronization for the client device. If you want to stop synchronization in order to execute a manual synchronization, click the Stop button. This allows any currently executing synchronization to complete fully. If you want to terminate the existing synchronization, click End. To restart the automatic synchronization, click Start.

Note:

If you notice that the automatic synchronization does not start, check the Status to see if the synchronization agent is "Disabled". Enable the synchronization agent with either the SYNC_AGENT parameter in polite.ini or click Enable in the Sync Agent UI.

The start, stop, and end buttons only control the automatic synchronization temporarily. To fully disable automatic synchronization, so that it is not restarted when a device is powered on, click Disable. To re-enable automatic synchronization, click Enable. This can also be accomplished through configuring the polite.ini; see Section F.3.2.13, "SYNC_AGENT" for details.

To see the status of any existing or the last automatic synchronization, click Refresh.

5.4.3 How the Automatic Synchronization Transaction is Retried

If the automatic synchronization fails because of a network error, the client-side Sync Agent probes the network to retry the transaction, as follows:

  • The network is always checked before synchronization is attempted. If the network is not available, the network is checked as follows:

    1. every 15 seconds three times

    2. every 30 seconds three times

    3. every 60 seconds three times

    4. every 20 minutes until the network is available

  • If the network is available, then the transaction is retried, as follows:

    1. every 15 seconds three times

    2. every 30 seconds three times

    3. every 60 seconds three times

If the network is still not available, the Sync Agent continues to check the network every 20 minutes. If it detects an available network, the automatic synchronization is started.

5.5 Configuring Data Synchronization For Farm or Single Mobile Server

There are two types of configuration parameters for Data Synchronization:

  • Shared—Shared parameters affect all Mobile Server instances in the farm. The administrator can have multiple Mobile Server instances in a single farm that uses the same Mobile repository. To modify these parameters, navigate to the Administration screen and click Shared Parameters.

  • Instance—Instance parameters only affect a single Mobile Server instance; that is, the Mobile Server that you are currently viewing. These parameters are stored in the WEBTOGO.ORA file; thus, once modified, you may need to restart the Mobile Server. Check the Need Restart column to verify if a restart is necessary. To modify these parameters, navigate to the Administration screen and click Instance Parameters. See Appendix A, "Configuration Parameters for the WEBTOGO.ORA File" for a description of each of these parameters.

    It is never recommended to modify the webtogo.ora file directly; instead, use the Mobile Manager to modify any of the webtogo.ora file parameters. In the Mobile Manager, migrate Administration tab and select Edit Config file. This is the webtogo.ora file.

To view the parameter description and additional information, click Show. You can modify any of the values in the New Value field and click Apply. Some of the Instance parameter values do not take effect until the Mobile Server is restarted.

5.6 Improving Performance for Multiple Clients that Use the Same Read-Only Data With a Cached User

If you have the default method for synchronization, each Mobile client must have a unique synchronization user ID, which is used to coordinate the modifications between the client and the server. However, if you have multiple Mobile clients that use the same data—where the clients only are allowed to read this data—then there is no need to track modifications on the client. Thus, in this scenario, you can choose a more performant solution by configuring a single user for all read-only clients with access to the same publication data.

All Mobile clients share the same user ID, which is subscribed to a publication, where all publication items are read-only. Thus, when they synchronize, they are only downloading data from the Mobile Server. The only difference, then, between the clients is when they synchronize to download the data. Since the Mobile clients could synchronize at different times, each are provided a unique state, where the cached user and state combination informs the server how much data to download to each particular Mobile client.

To use this feature, perform the following:

  1. Ensure that the publication items are read-only. When adding publication items to the publication, pass the value of IUD for the argument DISABLED_DML. In this state, client-side DML modifications cannot be uploaded to the Mobile Server.

  2. Create a single user and subscribe it to the read-only publication. For each group of clients that subscribe to the same subset of data, create one user. In the simplest case, where all clients share the same data, create a single user and subscribe it to the read-only publications.

  3. Configure the users that are sharing the data, as follows:

    1. On Mobile Manager, navigate as follows: Data Synchronization->Administration->Instance Parameters.

    2. Configure each user that is to share the data from the read-only publications in the CACHED_USERS field. If you have more than one cached user, separate each user by a comma.

Note:

In this scenario, you may consider using Offline Instantiation for installing the Mobile client and the initial data download on each client. See Chapter 9, "Offline Instantiation" for more information.

A restriction for this feature is that the synchronization user can only subscribe to read-only publication items. A workaround is to create a shared user for all of the clients and a unique user for each client. The shared user subscribes to the shared read-only publication items and the unique user subscribes to the updateable publication items. The Mobile client needs to synchronize both users.

5.7 How Do You Encrypt All Databases for the Initial Sync?

In the default server configuration, Mobile clients do not automatically encrypt the snapshot ODB files after you complete the initial sync. However, you can modify your configuration to automatically encrypt all snapshot ODB files with the synchronization user password after the initial sync completes. The following sections demonstrate how to configure for this option either on the client or on the server:

5.7.1 Configuring on the Local Client for Automatic Encryption of Local Snapshots

On the local client, you can configure for automatic encryption of the snapshot ODB files after initial synchronization by modifying the POLITE.INI/POLITE.TXT file by setting the ENCRYPT_DB parameter in the SYNC section.

For details on what value to use for the ENCRYPT_DB parameter in the POLITE.INI/POLITE.TXT file, see Section F.3.2.12, "ENCRYPT_DB".

5.7.2 Configuring on the Server for Automatic Encryption of Local Snapshots

On the server, you can configure for automatic encryption of the snapshot ODB files after initial synchronization by performing the following:

  1. Logon to the Mobile Server as an Administrator and launch the Mobile Manager tool.

  2. Click on Mobile Devices, followed by Administration.

  3. Click on Command Management.

  4. Click Create Command.

  5. Create the following new Command:

    Name: EncryptDB
Command: updt_conf.otl
Description: Encrypt Database

  6. Edit the newly created command EncryptDB, as follows:

    Command: updt_conf?app=sync&key=ENCRYPT_DB&val=1

  7. Apply the changes.

  8. Edit the DeviceInfo Command. Insert the new Command EncryptDB and click OK.

For more information on sending commands to the Mobile device, see Section 7.7, "Sending Commands to Your Mobile Devices".

5.8 Managing Trace Settings and Trace Files

You can configure the type of tracing that occurs for Data Synchronization components. For more information, see See Section 3.1.2, "Data Synchronization Tracing" in the Oracle Database Lite Troubleshooting and Tuning Guide.

5.9 Browsing the Repository for Synchronization Details

The Repository screen describes how to look up user information, publications, publication items, and the In-Queue, Out-Queue, and Error queues that facilitate synchronization. This section contains the following topics:

5.9.1 Viewing User Information

All users that have been added by the administrator (see Section 4.1, "Managing Users and Groups") are contained within the Mobile repository. With this Users screen, you can view everything that is attached to this user, such as application subscriptions, publication items, parameters, SQL scripts, Java resources, sequences, and performance analysis.

  1. To view information about existing users in the repository, click the Repository tab on the Data Synchronization home page.

    As displayed in Figure 5-12, the Repository tab appears.

    Figure 5-12 Repository Tab

    The Repository page
    Description of "Figure 5-12 Repository Tab"

  2. Click Users, which brings up a list of all users currently in the repository. The number next to Users details the number of users currently in the repository.

  3. Choose the user in which you are interested and click Subscriptions. The Subscriptions page displays the existing publications for the user. A subscription is the combination of the publication, its publications items, and the user to which it is attached.

    On the subscriptions screen, choose any publication and then click any of the buttons above it to see all of the publication items, parameters, SQL scripts, Java resources, and sequences. In addition, if you click the Consperf performance analysis button, you can generate performance analysis for the publication items. See Section 5.10.3, "Analyzing Performance of Publications With the Consperf Utility" for more information on Consperf performance analysis.

You can add subscriptions to the user by granting the user access to the application that contains the publication. See Section 4.2.1, "Grant or Revoke Application Access to Users" on how to grant access to applications. To add a publication to an application, use the Mobile Database Workbench.

5.9.2 Viewing Publications

To view all publications that have been published against the Mobile Server, click Publications under the Users and Publications section. The number next to Publications are the number of publications currently in the repository, which were uploaded to the repository when the application was published. You can view these publications individually using this link. Clicking Publications brings up a screen that contains a list of all of the publications. If there are too many to fit on a page, you can search for a specific publication. Similar to the Users screen, you can select a publication and then view the publication items, parameters, SQL scripts, Java resources, sequences, and users that are attached to this publication.

When you add publication items to each publication, you specify certain properties for each publication item within the publication, such as the order weight of when this item is executed in relation to the other publication items in the subscription, who wins when a conflict occurs, and options for disabling DML. You can view some of these properties when you select the publication and click Publication Items. For more information on these properties, see Section 3.3.1.6 "Adding Publication Items to a Publication" in the Oracle Database Lite Developer's Guide.

You can also view the users subscribed to each publication by selecting the publication and then clicking Users. When you do so, you see the following information about each user subscribed:

  • User: the user name

  • Parameter Set: If a data subsetting parameter is required for the publication, then this indicates if the parameter was set for this user.

  • Instantiated: This indicates if the user is ready for synchronization. If there is a data subsetting parameter for the publication, but the value has not been set for this user, then this value is NO. The value is YES if either there is no data subsetting parameter or that the required parameters are set.

  • Complete Refresh Requested: Indicates if this user requests a complete refresh.

You can only view publications in this screen. To modify your publication, use the Mobile Database Workbench. For more information, see Chapter 5 "Using Mobile Database Workbench to Create Publications" in the Oracle Database Lite Developer's Guide.

5.9.3 Viewing Publication Items

To view publication items, click Publication Items under the Users and Publications section. The number next to Publication Items details the number of publication items stored in the repository. These items were uploaded to the repository when the application was published.

Click Show to view the publication item properties.

You can only view publication items in this screen. To modify you publication and its publication item, use the Mobile Database Workbench. For more information, see Chapter 5 "Using Mobile Database Workbench to Create Publications" in the Oracle Database Lite Developer's Guide.

5.9.4 Viewing Synchronization Queues

You can view what is currently in the synchronization queues. To view transactions that are listed in queues, click the required hyperlink under the Queues section. For example, to view transactions that are listed in the Out-Queue, click Out Queue. The number next to each queue shows the number of transactions contained within that queue.

The In-Queue and Error Queue are organized by transactions.

5.9.4.1 Viewing Transactions in the In-Queue

You can view the current transactions that exist in the In-Queue. If you are wondering if your changes have been applied to the application tables, you can verify if they are still in the In-Queue or have already been processed by the MGP. If you see your transactions held in the In-Queue longer than you wish, then modify the timing on how often the MGP executes in the Job Scheduler. See Section 6.3, "Manage Scheduled Jobs Using the Mobile Manager" for more information on the Job Scheduler.

5.9.4.2 Viewing Subscriptions in the Out-Queue

The Out-Queue contains the transactions that are destined for the Mobile client. The transactions are organized by subscriptions, which is a combination of the user and each publication for the user. Also, you can see if a complete refresh is requested. Figure 5-13 displays the Out-Queue Publications page.

Figure 5-13 Out-Queue Publications Page

The Outqueue publications page.
Description of "Figure 5-13 Out-Queue Publications Page"

You can view the details of each subscription by performing the following:

  1. Select the subscription to view with the Select button next to the user name/publication in which you are interested.

  2. Click Publication Items, which brings up Figure 5-13.

    The Publications Items screen describes how many records is in the publication and whether it uses a fast or complete refresh mode.

    Figure 5-14 Publication Items in the Out-Queue Subscription

    Publication items in Out-Queue subscription
    Description of "Figure 5-14 Publication Items in the Out-Queue Subscription"

  3. View the records of the publication item by clicking the Select button and then click View Records.

  4. Click Show on each record to see the record data.

5.9.4.3 Viewing Transactions in the Error Queue

The purpose of the error queue is to store transactions that fail due to errors or conflicts that can arise when a client synchronization does not perform as planned. Synchronization errors cause a rollback of the application of the client data to the server database and the error is posted to the error queue. In order to have the transaction apply to the base tables in the server database, you must resolve the error condition and re-apply the transaction.

Synchronization conflicts are resolved by the MGP using the relevant conflict rules. All modifications are applied to the server tables and the transaction is committed. If the conflict rule is "Server Wins", then an error queue record with the message CONFLICT DETECTED is also generated to let you know that a conflict occurred and this rule was applied. A conflict that is resolved by the conflict rules is not rolled back. You can choose to override the conflict resolution performed by modifying the error queue record for a conflict and re-executing the transaction.

A Mobile Server synchronization conflict occurs if:

  • The client and the server update the same row. This error is resolved by the Mobile Server by the conflict rules, but is logged in the error queue for you to see the result. You can choose to modify the result.

  • The client and server create rows with the same primary key values. This error is resolved by the Mobile Server, but is logged in the error queue for you to see the result. You can choose to modify the result.

  • The client deletes the same row that the server updates. This error is resolved by the Mobile Server, but is logged in the error queue for you to see the result. You can choose to modify the result.

A Mobile Server synchronization error occurs if:

  • The server deletes the same row that the client updates. This error is unresolved by the Mobile Server. The administrator must decide how this is resolved.

  • Client is out of sync. This error is unresolved by the Mobile Server. The administrator must decide how this is resolved.

  • Client records violate server database constraints. This error is unresolved by the Mobile Server. The administrator must decide how this is resolved by either modifying the database constraints and re-executing the transaction, or by modifying the error queue record to conform to the constraints.

  • An error occurs when reapplying a backup. See Section 4.3, "Oracle Database Lite Backup Coordination Between Client and Server" in the Oracle Database Lite Troubleshooting and Tuning Guide for instructions on recovering from a backup.

  • An unexpected error occurs with the back-end database, such as a constraint violation or storage issue.

Note:

Normally, only the first error is reported if an error occurs in the apply phase of the transaction. If you want to view all errors that occur for the transaction, set the REPORT_ALL_ERRORS parameter to YES in the Consolidator parameters, which is set in the Instance Parameters section of the Mobile Manager GUI.

If the administrator resolves the error condition that caused the problem, then the administrator may attempt to re-apply the transaction or purge the error queues. If you decide to reapply the records in the transaction to the application tables, perform the following:

  1. To view the transaction details, select a particular transaction and click Publication Items. This shows the Error Queue transaction with the associated publication items with a number designating Sync Errors or Conflicts. If a publication item shows an error count of zero, no errors have been reported.

    Figure 5-15 Publication Items in the Error Queue

    error queue transactions
    Description of "Figure 5-15 Publication Items in the Error Queue"

  2. Select the publication item to analyze and correct, and click View Records, which brings you to the Edit Error Queue Records page, as shown in Figure 5-16. All of the details of the client and server data are displayed. If the Message field for any row is not blank, it means that this record produced a Sync Error or a Conflict. A message of CONFLICT DETECTED signifies a Sync Conflict; any other Message indicates a Sync Error. A blank Message field implies that the record executed correctly.

    Figure 5-16 Error Queue Records for a Single Publication Item

    error queue records for a single publication item
    Description of "Figure 5-16 Error Queue Records for a Single Publication Item"

    The Error Queue record displays the data that arrived from the client and the data on the server for the corresponding row, if any. If you click Show under Details, then you can edit the Error Queue record, as shown in Figure 5-17.

    Figure 5-17 Show Details of Error Queue Record

    Modify the record values by clicking on the Show button.
    Description of "Figure 5-17 Show Details of Error Queue Record"

  3. Correct the reason why the error occurred in the first place by either modifying the record details or by taking the server-side values.

    • Edit fields—Modify any fields in the Error Queue Record section under Record Details and click Save.

    • Update DML—You can only re-execute the transaction if the DML operation is changed to an Insert, Update, or Delete DML operation. If the DML operation is in the Error state, then modify the DML operation from Error to Update. Select a value from the Update DML drop-down list under Record Details and click Save.

    • Take Server Values—Click Take Server Values under Record Details. If a server record is present, the server-side values will appear in Error Queue Record. That is, the Error Queue Record will have the same values as Server Record.

      Note:

      If the conflict resolution is set to "server wins," then you may lose the client modifications. Thus, if you set the conflict resolution to "client wins," then you force these changes to overwrite the server.

  4. After completing one or more of the above operations, click Apply to commit the changes. Clicking on Revert causes the changes to be cancelled. Avoid navigating to some other page without first clicking Apply or Revert.

  • Alternatively, you can update several transactions at once on a group of selected records; that is, the operations are simultaneously executed for all records for which the Select checkbox is checked. After selecting the desired rows, choose the buttons at the top of the page ot perform one or more of the following:

  • Update DML—Select a set of rows using the checkboxes. Choose a value from the Update DML drop-down list at the top of the page and click Go.

  • Update Field—Select a set of rows using the checkboxes. Choose the name of the field from the Update Field drop-down list which contains all the editable fields in the table. Then enter the value you want to enter for that field and click Go.

  • Take Server Values—Select a set of rows using the checkboxes and click on Take Server Values at the top of the page.

  • Create New Transaction—Select a set of rows using the checkboxes and click on Create New Transaction. The selected records will be removed from the current Error Queue transaction and a fresh transaction is created that consists of only these records. This operation may be used when you want to re-apply on a certain set of the original records. The new transaction could either be purged to applied separately.

After completing one or more of the above operations, click Apply to commit the changes. Clicking Revert causes the changes to be cancelled. Avoid navigating to some other page without clicking Apply or Revert. You do not need to click Apply or Revert for the Create New Transaction operation.

5.10 Monitoring and Analyzing Performance

The following sections describe how to monitor and analyze Data Synchronization performance.

5.10.1 Viewing Sync Server Statistics

The Performance tab displays the Sync Server statistics of the current session and statistics of history sessions that have occurred in the last 24 hours.

To view Sync Statistics, click the Performance tab. As displayed in Figure 5-18, you can see the active Sync Server statistics from the currently active sessions and compare it to overall statistics gathered from all sessions in the past 24 hours. This includes an overall section, the upload phase, and the download phase.

Figure 5-18 Performance Page

This image displays the performance page.
Description of "Figure 5-18 Performance Page"

To view statistics from other dates, click the Synchronization Statistics link in the General section of this page. The Synchronization Statistics page contains search criteria such as user name, device type, and duration. Specify your criteria in the Search section and click Go. The Sync Statistics page displays results such as summary, upload phase, and download phase details.

5.10.2 Viewing MGP Cycles and Statistics

By navigating to the MGP tab off of the Data Synchronization screen, the Mobile Server administrator can view the current status of the MGP cycle (see Figure 5-19). The columns are separated so that you can see how, in the last 24 hours, the MGP has performed overall, as well as for each individual phase: apply, compose and process.

Figure 5-19 MGP Page

The MGP page.
Description of "Figure 5-19 MGP Page"

When you click on MGP Current Cycle, you can see what the MGP process is currently doing. For instance, you can check if the apply or compose cycle is running when the MGP cycle is in progress. If you have set the MGP_HISTORY instance parameter, (see Section 5.5, "Configuring Data Synchronization For Farm or Single Mobile Server"), then upon completion of the apply or compose cycle, the cycle details are stored in Cycle History.

Since the front page only shows the last 24 hours, you can view farther back by clicking on the MGP Apply/Compose Cycle Statistics. You can set a date range to search and can even specify whether to search based upon the following:

  • Apply Only or Apply/Compose

  • Success, Failure, or Conflict results

When you click MGP Apply/Compose cycles, you can search for a range of historical records of these cycles and then view the details of each cycle.

5.10.3 Analyzing Performance of Publications With the Consperf Utility

The Consperf utility profiles your subscriptions and may modify how the publication item is executed if the utility determines that there is a more performant option. The Consperf tool evaluates how the SQL within the publication item interacts with our Data Synchronization query templates. The first synchronization is always a complete refresh, which is a direct invocation of the query. On subsequent synchronizations, the query templates determine incremental refreshes. This improves your performance from not having to perform a complete refresh each time you synchronize. However, the interaction of our query templates and your SQL may not be optimal, which is discovered by the Consperf tool. We either modify the query template or type of logical delete or insert for you or you can adjust your SQL to be more performant in regards to our templates.

In addition, application developers and administrators use this utility to analyze the performance of subscriptions and identify potential bottlenecks during synchronization.

This tool generates the following two primary analysis reports:

  1. Timing statistics for publication items

  2. Explain plans for publications

The Consperf tool automatically tunes subscription properties, if the default templates do not supply the highest performing option. You can select a client and choose the desired subscription for performance analysis. Users can change parameter values before analyzing performance. The analysis results, which are timing and execution plan reports, are stored on the server and can be accessed by viewing the same user and subscription.

For a full description of how to use the Consperf utility, see Section 1.2.1 "Analyzing Performance of Publications With the Consperf Utility" or for the Explain Plan, see Section 1.4, ""Determining Performance of Client SQL Queries With the EXPLAIN PLAN" in the Oracle Database Lite Troubleshooting and Tuning Guide.

5.10.4 Monitoring Synchronization Using SQL Scripts

If, instead of viewing MGP statistics within the Mobile Manager, you can execute SQL scripts to monitor Mobile application status during synchronization. For a full description of how to monitor synchronization, see Section 1.2.2. "Monitoring Synchronization Using SQL Scripts" in the Oracle Database Lite Troubleshooting and Tuning Guide.