5 Managing Synchronization

The mobile server administrator uses the Data Synchronization Manager to manage synchronization tasks. This chapter includes the following:

5.1 How Does the Synchronization Process Work?

With Oracle Database Mobile Server, you can create an application where multiple users enter data on their client devices and the data is synchronized with a back-end Oracle database. In addition, only the data designated for each user is downloaded from the server to the client's device.

The mobile server uses synchronization to replicate data between the mobile clients with their client databases and the application tables, which are stored on a back-end Oracle database. The Oracle Database Mobile Server architecture consists of the mobile client, the mobile server as the middle tier, and the mobile server repository in the back-end Oracle database server. The mobile client contains the client database and client applications, which resides on the mobile device. The mobile server acts as the middle tier to coordinate the synchronization process and provide management tools for the administrator. The mobile server repository resides in the back-end Oracle database server and is where all data from all users is stored.

Figure 5-1 shows a simplified architecture of the Oracle Database Mobile Server synchronization tiers:

Figure 5-1 General Synchronization Architecture

Description of Figure 5-1 follows
Description of "Figure 5-1 General Synchronization Architecture"

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 Mobile Server, which is used for multiple clients. In order to accommodate 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.

In reality, our synchronization process uses asynchronous communication and queues to ensure that multiple users can be synchronizing at the same time as well as ensuring data integrity and performance. By using queues and asynchronous communication, the user can queue the updates for processing and then download any updates from the server without ever locking the database. The only downside is that the changes are not immediately updated. Instead, the updates occur when the In Queue is read and processed on the server-side.

The following graphic and steps shows the full details and the additional components that work in conjunction to enable a seamless synchronization from multiple clients. This graphic introduces the following new components:

  • Sync Client and Sync Server: The Sync Client and Sync Server work in conjunction to upload mobile client changes to the mobile server In Queue. The Sync Client resides on the mobile client; the Sync Server resides on the mobile server. The Sync Server places the client modifications into the In Queue and downloads any new data from the server for the client from the Out Queue.

  • Message Generator and Processor (MGP): A background process called the Message Generator and Processor (MGP) runs in the same tier as the mobile server, periodically collects all the uploaded changes from the multiple mobile users out of the In-Queue and applies these changes to the repository in the server database. The MGP executes independently and periodically based upon an interval specified in the Job Scheduler in the mobile server.

    The MGP prepares any modifications that are sent to each mobile user and places them into the Out Queue. The next time the mobile user synchronizes with the mobile server, these changes can be downloaded to the client and applied to the client database.

Figure 5-2 describes how each of these components interact to complete the asynchronous, queue-based synchronization for each client:

Figure 5-2 Data Synchronization Architecture

synchronization architecture.
Description of "Figure 5-2 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 PDA, a Windows platform client or a supported Linux platform client.

  2. The 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 database.

  6. The mobile client applies all changes for client database.

  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.

Synchronization involves two components: the Sync Client/Server and the MGP process, which 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, set the DO_APPLY_BFR_COMPOSE parameter to NO. 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

MOBILE.ORA Parameter Description

DO_APPLY_BFR_COMPOSE

Setting DO_APPLY_BFR_COMPOSE to no, the Compose executes. However, by default, this parameter is set to yes, so that 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.4 "MGP Compose Postponed Due to Transaction in the In-Queue" in the Oracle Database Mobile Server Troubleshooting and Tuning Guide.

5.2 Initiate Synchronization of the Mobile Client

You can initiate synchronization of the client using one of the following methods:

Note:

The mobile client device clock must be accurate for the time zone set on the device before attempting to synchronize. An inaccurate time may result in the following exception during synchronization: CNS: 9026 "Wrong user name or password. Please enter correct value and reSync."

When you initiate a synchronization from the client, either manually or by scheduling a job, the synchronization cannot occur if there is an active connection with an uncommitted transaction opened from another source. This could be from scheduling two jobs to synchronize at the same time, from mSync or the client synchronization APIs.

The mSync GUI is shown in Figure 5-3.

Figure 5-3 Using the mSync GUI to Initiate Synchronization

msync GUI for synchronization
Description of "Figure 5-3 Using the mSync GUI to Initiate Synchronization"

To bring up the mSync GUI, execute msync.exe on WinCE and Win32 or msync on Linux, which is located in the /bin subdirectory under the directory where you installed the mobile client. Modify the following supplied values, if incorrect:

  • User name and password for the user that is starting the synchronization.

    Note:

    See Section 4.3.1.2.1, "Define User Name and Password" for conventions for creating the user name or password.

  • Check if you want the password saved for future requests.

  • Mobile Server URL, which is http://<mobile_server_hostname>:<port_number>, replace 'http' with 'https' in case SSL is used. If SSL is not used, 'http://' can be skipped.

Click Sync to start the Synchronization. Click Apply to save any modifications you made to the entries. Click Exit to leave the tool.

If there are software updates that are waiting to be downloaded to the client, the update tool is automatically executed after the end of the synchronization process.

Note:

The only time that the client does not check for software updates is if you are using the Synchronization APIs. If you want to launch the update UI, then enter update on the command line.

You can also modify the tool options by selecting the Tools Selection at the bottom of the UI, as shown in Figure 5-4.

Figure 5-4 The mSync Tools Selection

mSync Tools
Description of "Figure 5-4 The mSync Tools Selection"

The following sections describe the Tools options:

5.2.1 Network Options for MSync Tool

Figure 5-5 displays the Network options screen where you can specify a proxy if your network provider requires that you use a proxy server to access the internet. . Click Use Proxy to use a proxy and then enter the proxy server and port number.

Figure 5-5 The mSync Network Options Selection

Network options
Description of "Figure 5-5 The mSync Network Options Selection"

5.2.2 Sync Options for MSync Tool

Figure 5-6 displays the Sync Options screen where you can specify the following:

  • Mobile User Password—Modify the existing password. The mobile user password is stored on both the client and the mobile server. To ensure that both are modified, only change the password when connected to the mobile server.

  • High Priority—Select this checkbox to specify synchronizing only High Priority data. This specifies 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.

    When you select this checkbox, you are enabling pre-defined high priority records to be synchronized first. This only for those publication items that have specified a restricting predicate. See Section 1.2.10, "Priority-Based Replication" in the Oracle Database Mobile Server Troubleshooting and Tuning Guide for more information.

  • Force Refresh—The force refresh option is an emergency only synchronization option. Check this option when a client is corrupt or malfunctioning, so that you decide to replace the mobile client data with a fresh copy of data from the enterprise data store with the forced refresh. When this option is selected, any data transactions that have been made on the client are lost.

    When a force refresh is initiated all data on the client is removed. The client then brings down an accurate copy of the client data from the enterprise database to start fresh with exactly what is currently stored in the enterprise data store.

Figure 5-6 The mSync Options Selection

mSync Options
Description of "Figure 5-6 The mSync Options Selection"

5.2.3 Use Mobile Client Tools on Linux

The mobile client for Linux supports the msync, dmagent and update tools. To use the UI-based tools, use the following executables: msync, dmagent, or update.

To synchronize on a Linux client with the command line tool, use the msync executable for synchronization, as follows:

./msync username/password@server[:port][@proxy:port]

For example,

./msync john/john@testserver:8000

The other msync options, such as -save, -a, -password and -force currently will not result in a successful sync. This is a limitation only for the msync executable in the MDK installation on Linux.

5.3 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.5, "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.9, "Improving Performance for Multiple Clients that Use the Same Read-Only Data With a Cached User" for more details.

  • You may save all synchronization transactions in an encrypted file. There are times when you do not have network access to the mobile server, but there is a way you can manually carry a file between the mobile server and the client. In this instance, you may want to use File-Based Sync, which saves all transactions in an encrypted file either for the upload from the client for the mobile server or the download from the mobile server for the client. See Section 5.10, "Synchronizing to a File With File-Based Sync" for more details.

  • You may decide that it would be more performant to store your application data on an Oracle database that is separate from the Oracle database that contains the mobile server repository. In this case, you can have multiple back-end databases, where the mobile server repository exists on the main database and the data for one or more applications may exist on the main database or another database of your choosing. For more information, see Section 5.8, "Register a Remote Oracle Database for Application Data".

5.4 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-2, during every synchronization session, the Sync Server uploads client transactions from the client database and places them within the In-Queues. The Sync Server then downloads any server-side transactions from the Out-Queues to the client database.

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

5.4.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-7.

  1. Figure 5-7 Data Synchronization Home Page

    The Data Synchronization home page.
    Description of "Figure 5-7 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.4.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.4.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-8 shows the Synchronization History Sessions page.

Figure 5-8 Synchronization History Sessions Page

The Synchronization History Sessions page.
Description of "Figure 5-8 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.4.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-9, 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-9 Host Page

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

5.5 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 Mobile Server 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:

Automatic synchronization is based on a different model than manual synchronization. Automatic synchronization operates on a transactional basis. Thus, when the conditions are correct, any new data transactions are uploaded to the server, in the order of the specified priority for the data. In the manual synchronization model, you can synchronize all data or use the selective sync option, where you can detail only certain portions of the data to be synchronized. The selective sync option is not supported in automatic synchronization, since we are no longer concerned with synchronization of only a subset of data.

The following provides more information about your automatic synchronization:

5.5.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 Platforms 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 Platforms. Figure 5-10 shows the settings for automatic synchronization on each platform.

    Figure 5-10 Platforms for Automatic Synchronization

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

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

    Figure 5-11 Platform-Based Events for Automatic Synchronization

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

  3. Configure the Events. Figure 5-11 shows the 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 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.

        However, you must enter the time in Coordinates Universal Time (UTC) for a specific time as it gives us a common base. Every timezone can be expressed as an offset from UTC (that is, UTC+4) and by doing this the server does not need to know about each client's respective timezones. For example, if you want something to happen at 8:00 A.M your time, you must specify that time in UTC and then enter that into the server.

      • 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-12 displays the Conditions screen.

    If an Automatic Synchronization is about to start, Oracle Database Mobile Server 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-12 Platform-Based Conditions for Automatic Synchronization

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

    The following conditions must be true for this platform 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-13 displays the fields that you can specify for this condition.

      Figure 5-13 Editing the Data Priority Condition

      Editing the data priority condition
      Description of "Figure 5-13 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-14 Add Network Information for Automatic Synchronization

    Add Network Information for automatic synchronization
    Description of "Figure 5-14 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 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-15 Add Dial-Up Network Information

    Add dial-up network information
    Description of "Figure 5-15 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 Mobile Server 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.5.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 autosync executable in a command prompt. Figure 5-16 shows the Sync Agent UI.

Note:

You can also start and stop automatic synchronization using programmatic APIs. For full details, see Section 3.2, "Managing Automatic Synchronization on the Mobile Client" in the Oracle Database Mobile Server Developer's Guide.

Figure 5-16 Managing Automatic Sync Agent

automatic synchronization agent
Description of "Figure 5-16 Managing Automatic Sync Agent"

The Sync 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 Sync Agent is "Disabled". Enable the Sync Agent by clicking 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. To see the status of any existing or the last automatic synchronization, click Refresh.

5.5.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.4 Viewing Client-Side Synchronization Conflicts

For automatic synchronization publication items only, any synchronization conflict error information is stored in the CONF$<snapshot> table in the same client database as the snapshot.

5.6 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 server 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 mobile.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 Files for the Mobile Server" for a description of each of these parameters.

    It is never recommended to modify the mobile.ora file directly; instead, use the Mobile Manager to modify any of the mobile.ora file parameters. In the Mobile Manager, migrate Administration tab and select Edit Config file. This is the mobile.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.7 Resuming an Interrupted Synchronization

With client/server networking, communication may be interrupted by unreliable network conditions, physical disconnections, limited transport bandwidth, and so on. To efficiently cope with these conditions, the transport protocol between the client and server resumes a synchronization session from the last acknowledged byte. For example, the client starts to upload 10 MB of data and the connection fails after sending 9 MB of the data. In this instance, the client does not resend the 9 MB that was acknowledged, but resumes the synchronization by uploading the last 1 MB of data. The resume feature works the same for both the upload and download phases of the transport.

The resume feature manages intermittent network failures. If resume is enabled on both the server and the client, synchronization resumes automatically within the specified resume timeout period. Also, if sync session was interrupted during a network operation, the next synchronization resume the operation, as long as resume is enabled and the resume timeout has not expired.

Configure the resume feature parameters, as follows:

5.7.1 Defining Temporary Storage Location for Client Data

By default, the client data is buffered in memory and maximum of 16 MB is allocated for the buffering. If more space is needed, new clients are blocked until space is freed. Alternatively, you can configure where the client data is temporarily stored and how much space to allocate with the RESUME_FILE and RESUME_FILE_SIZE parameters in the CONSOLIDATOR section of the mobile.ora file on the mobile server, as follows:

RESUME_FILE=d:\path\file
RESUME_FILE_SIZE =NNN (MB)

Setting the RESUME_FILE_SIZE parameter configures the amount of memory allocated for the buffering. Setting RESUME_FILE allows using a disk file instead of RAM, which is more efficient if JDK 1.4 or later is installed and memory mapping can be used.

If there are multiple disks available on the mobile server host, one spool file should be created per disk to optimize performance. You can specify several spool files with multiple RESUME_FILE and RESUME_FILE_SIZE parameters, each designated with a unique suffix, as follow: RESUME_FILE_2, RESUME_FILE_SIZE_2. The maximum number of files is determined by the operating system and hardware for the mobile server. The maximum size for each file is 2047 MB.

Normally, 64 KB blocks are used to buffer client data. Resume block size can be specified in KB, with the RESUME_BLOCKSIZE parameter. If you are using disk files to minimize fragmentation, then the block size should be specified as a larger number.

5.7.2 Controlling Server Load

If too many clients connect to a mobile server at once, it can become overloaded, run out of memory, or have poor performance when responding to the clients. The RESUME_MAXACTIVE parameter controls the maximum number of connections that the mobile server handles at a single time. If more clients try to connect, they are queued until existing connections complete. The default is 100 connections.

After RESUME_MAXACTIVE has reached, configure RESUME_MAX_WAIT for the number of minutes a new client should wait before returning with error message. This parameter is configured in minutes, instead of seconds.

The RESUME_TIMEOUT parameter indicates how long to keep client data while the client is not connected. The default is 0, which means that resume is disabled and after disconnection, the client data is discarded. A short timeout, such as 15 minutes, is suitable to resume any accidentally dropped connections. A longer timeout may be needed if users explicitly pause and resume synchronization to switch networks or use a dialup connection for another purpose.

The RESUME_MAXCHUNK parameter causes the server to drop the connection after sending the specified data size, in KB. This forces the client to reconnect and inform the server on how much data it already has. The server can the discard all data before that offset. The fault value is 1024 KB.

These parameters are all configured within the mobile.ora file on the mobile server.

5.8 Register a Remote Oracle Database for Application Data

By default, the mobile server repository metadata and the application schemas are present in the same database. However, it is possible to place the application schemas in a database other than the Main database where the mobile server repository exists. This can be an advantage from a performance or administrative viewpoint.

Thus, you can spread your application data across multiple databases.

Note:

We refer to the database where the application schema resides as remote because it is separate from the Main database that contains the mobile server repository. It does not mean that the database is geographically remote. It can be local or remote. For performance reasons, the mobile server must have connectivity to all databases involved in the synchronization—Main and remote.

Figure 5-17 Separating Application Data from Mobile Server Repository

Description of Figure 5-17 follows
Description of "Figure 5-17 Separating Application Data from Mobile Server Repository"

You can register one or more remote Oracle databases that host the application data. Once registered, you can specify application schemas on these databases during publication creation. Synchronization is executed on a per publication basis rotating through the databases.

To use an Oracle database other than the Oracle database used for the mobile server repository, you must perform the following:

  1. Register the remote Oracle database as described in Section 5.8.1, "Register or Deregister a Remote Oracle Database for Application Data".

  2. When creating the publication item, specify the URL of the Oracle database for storing the application data. All data for a single application must be contained in the same Oracle database. In MDW, when you select New-Project, you can specify the URL for the remote database for the publication. For more information, see Section 4.2, "Create a Project" in the Oracle Database Mobile Server Developer's Guide.

In order for the synchronization to complete successfully, both the application database and the mobile server repository database must be up.

Note:

For details on how to use Consolidator APIs or to modify callbacks to use a remote Oracle database, see Section 2.15, "Register a Remote Oracle Database for Application Data" in the Oracle Database Mobile Server Developer's Guide.

5.8.1 Register or Deregister a Remote Oracle Database for Application Data

If you want your application data to be on a database other than the mobile server repository, then you can register the remote database through the Mobile Manager. However, once registered, this database cannot be used by any other installation of Oracle Database Mobile Server.

Publications and publication items can be defined against application data in the remote database. The Mobile Manager manages the Main database and all registered application databases in the same way.

Note:

All registered databases must be up and running for proper operation. If a database is already used by a separate Oracle Database Mobile Server installation, either as a mobile server repository or as an application repository, then the registration fails. An application repository can be deregistered from one installation and then registered to a different installation.

To register the Oracle database, navigate to Data Synchronization->Repository. The bottom section lists the registered Oracle databases, where MAIN is the Oracle database that contains the mobile server repository.

  1. As shown in Figure 5-18, click the Register Database button to register a new database.

    Figure 5-18 Register or Deregister Oracle Database for Application Data

    register Oracle database
    Description of "Figure 5-18 Register or Deregister Oracle Database for Application Data"

  2. Enter the Oracle database information as follows:

    • Name—An identifying name for the database where the application schema resides. Once defined, this name cannot be modified. This name must be unique across all registered database names.

      Note:

      A log is generated for each remote database application in the ORACLE_HOME/Mobile/Server/<DB_NAME>/apprepository.log file, where the <DB_Name> is this identifying name.

    • Description—A user-defined description to help identify this database.

    • JDBC URL—The JDBC URL can be one of the following formats:

      * The URL for a single Oracle database has the following structure: jdbc:oracle:thin:@<host>:<port>:<SID>

      * The JDBC URL for an Oracle RAC database can have more than one address in it for multiple Oracle databases in the cluster and follows this URL structure:

      jdbc:oracle:thin:@(DESCRIPTION=
 (ADDRESS_LIST=
   (ADDRESS=(PROTOCOL=TCP)(HOST=PRIMARY_NODE_HOSTNAME)(PORT=1521))
   (ADDRESS=(PROTOCOL=TCP)(HOST=SECONDARY_NODE_HOSTNAME)(PORT=1521))
 )
 (CONNECT_DATA=(SERVICE_NAME=DATABASE_SERVICENAME)))

    • Schema Name—The application schema name.

    • Password—The administrator password is used to logon to the database. The administrator name is the same as what was defined for the main database.

      When defining, the password must conform to the following restrictions:

      • not case sensitive

      • cannot contain white space characters

      • maximum length of 28 characters

      • must begin with an alphabet

      • can contain only alphanumeric characters, and special characters of '$' (dollar sign), '#' (number sign), and '_' (underscore)

      • cannot be an Oracle database reserved word

  3. Click Apply. The Oracle database is now registered with the mobile server and can be specified in a publication item.

After you register a database, Oracle Database Mobile Server creates the application database repository in the application database. The application database repository includes the schema and related consolidator tables. This is similar to the mobile server repository creation on the MAIN database.

When registering an application database, the user must provide the correct password for the repository schema. The password used is the user password. However, if the password provided is incorrect, then the administrator user name and password are requested.

Edit Oracle Database Details

To edit, select the name of the desired registered Oracle database in the list.

You can edit the description and password for any registered database. The password is used to logon to the application database. Before you can modify the password here, you must first modify the password on the database itself. Once modified on the database, then modify it in the mobile server as well on this screen.

DeRegister Oracle Database

Before you can deregister any database, you must first drop all associated publication and publication items. To deregister, select the radio button next to the desired database and click Deregister. Click Yes.

5.9 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 8, "Offline Instantiation for Mobile Clients" 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.

For cached user, if you try to synchronize for multiple clients at the same time, the server will synchronize serially and will block all clients while a single client is updated.

If you are using the cached user feature, you cannot enable automatic synchronization. If you do enable automatic synchronization, only one client will be notified to initiate an automatic synchronization.

5.10 Synchronizing to a File With File-Based Sync

There are times when you do not have network access to the mobile server, but there is a way you can manually carry a file between the mobile server and the client. In this instance, you may want to use File-Based Sync, which saves all transactions in an encrypted file either for the upload from the client for the mobile server or the download from the mobile server for the client.

Once saved within the encrypted file, the file is manually transported and copied onto the desired recipient—whether mobile client or mobile server. This file is uploaded and the normal synchronization steps are performed. The only difference is that the interim transmission of the data is through a file copied to the correct machine—rather than transmitted over a network.

Most of the activity on the mobile client and the mobile server is the same as with a network synchronization. The only difference is that instead of the data being transmitted over the network, it is placed into a file that is transported in another manner.

The following sections describe the activity necessary on the mobile client and the mobile server for file-based synchronization:

5.10.1 Upload Synchronization Transactions to an Encrypted File on the Mobile Client

Perform the following on the mobile client to upload all synchronization transactions to an encrypted file destined for the mobile server:

  1. Enable file-based synchronization with one of the following methods:

    • When using the mSync UI tool, select the File-Based Sync option off the Tools menu. Perform the steps described in Section 3.3.3, "Sync to a File Using File-Based Sync" in the Oracle Database Mobile Server Mobile Client Guide, setting the radio button to Send.

    • On the mobile client setup page, select the File-Based Sync button. Perform the steps described in Section 3.3.3, "Sync to a File Using File-Based Sync" in the Oracle Database Mobile Server Mobile Client Guide, setting the radio button to Send.

    • Enable file-based synchronization programmatically with the set Synchronization Property APIs. For upload, set the filename and the sync direction to Send. See the appropriate programming language section in Chapter 3, "Managing Synchronization on the Mobile Client" in the Oracle Database Mobile Server Developer's Guide.

  2. For manual synchronization, initiate the synchronization. Automatic synchronization cannot use file-based synchronization.

    If the synchronization fails during writing of the synchronization file, then the file may be deleted and the synchronization can be restarted. When restarted, the synchronization engine recreates the same synchronization file. If the failure occurs again, then it is most likely a hardware issue that must be resolved, such as not enough storage, database corruption or other hardware errors.

    Note:

    When the mobile server uploads the synchronization file or receives an upload from a network synchronization, it downloads any new data for the client as well as sends an acknowledgement for the transactions it received.

    If, during a synchronization request, the client has not received or downloaded any acknowledgement from the mobile server from the last upload, then the client will send all unacknowledged, previously uploaded transactions as well as any new transactions.

  3. Once the file is created in the directory specified, transport it to the mobile server using removable media or any other appropriate manner.

5.10.2 Apply and Compose Mobile Client Transactions on the Mobile Server

To perform the apply and compose function on the mobile server for mobile client transactions that are saved in an encrypted synchronization file, perform the following on the mobile server:

Note:

Only the user is allowed to upload the synchronization file from the client with the user's id. All other users will be denied permission for the upload.

  1. On the Mobile Server Workspace page, before you log into your mobile server, select the File-Based Sync tab.

  2. Enter the user name and password of the client user. Click Logon.

  3. Using the Browse button, locate and identify the encrypted synchronization file on the mobile server machine. Click Sync. The file uploads to the mobile server and the MGP applies the transactions to the mobile server repository.

    The mobile server starts the MGP to perform the apply/compose phase for the mobile client based upon the uploaded synchronization file. If this fails after several attempts, then the file may be corrupted. You can re-create the file and try again.

  4. A screen prompts the user for the name and directory for the synchronization file for the mobile client. This file downloads all composed transactions meant for the user to the designated file from the mobile server. Enter the name and directory for the file. Use your removable media to transport this file to the mobile client.

5.10.3 Download Composed Transactions from Mobile Server to the Mobile Client

To download all transactions from the mobile server to the mobile client, perform the following on the mobile client:

  1. Enable file-based synchronization with one of the following methods:

    • When using the mSync UI tool, select the File Based Sync option off the Tools menu. Perform the steps described in Section 3.3.3, "Sync to a File Using File-Based Sync" in the Oracle Database Mobile Server Mobile Client Guide, setting the radio button to Receive. Browse for the encrypted synchronization file that was transported from the mobile server.

    • Enable file-based synchronization programmatically with the set Synchronization Property APIs. For download, browse for the file that was transferred from the mobile server and set the sync direction to Receive. See the appropriate programming language section in Chapter 3, "Managing Synchronization on the Mobile Client" in the Oracle Database Mobile Server Developer's Guide.

  2. For manual synchronization, initiate the synchronization. For automatic synchronization, the file is automatically created when the automatic synchronization occurs.

    If an error occurs while receiving the synchronization file, you may restart the processing again. The client verifies that the transaction has not been processed.

5.10.4 Troubleshooting File-Based Synchronization Scenarios

When you have a disconnected synchronization, you may run into one of the following scenarios:

5.10.4.1 Normal Network Synchronization Occurs During File Upload

What happens if a network synchronization from the client was in progress when you started uploading a synchronization file to the mobile server? In this case, the file upload is aborted and a Network Sync In Progress error is reported. Since the data included in the synchronization file is also likely to be within the network synchronization, the appropriate data is synchronized and there is no need to upload the file.

However, if you do upload a synchronization file of data that has already been applied to the mobile server, then the server recognizes that it has already applied one or all of the client transactions. In this case, the mobile server skips the transactions it already has processed, sends any acknowledgements to the client that have not been sent, and applies any client transactions that have not been applied previously.

Additionally, any data destined for the client is sent by the mobile server to the client.

5.10.4.2 Conflict Resolution for File-Based Synchronization

The disconnected nature of file-based synchronization increases the probability that the client may have modified data, which has not been uploaded to ther server. Meanwhile, the server may have modified the same data, which creates a conflict. This conflict is solved using the same conflict rules that are configured in the subscription.

5.11 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.2, "Data Synchronization Tracing" in the Oracle Database Mobile Server Troubleshooting and Tuning Guide.

5.12 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.12.1 Viewing User Information

All users that have been added by the administrator (see Section 4.3, "Managing Users and Groups") are contained within the mobile server repository. With this Users screen, you can view everything that is attached to this user, such as application subscriptions, publication items, parameters, SQL scripts, 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-19, the Repository tab appears.

    Figure 5-19 Repository Tab

    The Repository page
    Description of "Figure 5-19 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, and sequences. In addition, if you click the Consperf performance analysis button, you can generate performance analysis for the publication items. See Section 5.13.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.4.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.12.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, 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 2.4.1.7, "Adding Publication Items to Publications" in the Oracle Database Mobile Server 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 4, "Using Mobile Database Workbench to Create Publications" in the Oracle Database Mobile Server Developer's Guide.

5.12.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 4, "Using Mobile Database Workbench to Create Publications" in the Oracle Database Mobile Server Developer's Guide.

5.12.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.12.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.12.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-20 displays the Out-Queue Publications page.

Figure 5-20 Out-Queue Publications Page

The Outqueue publications page.
Description of "Figure 5-20 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-20.

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

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

    Publication items in Out-Queue subscription
    Description of "Figure 5-21 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.12.4.3 Viewing Server-Side Synchronization Conflicts and Errors in the Error Queue

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.

  • 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.

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.

If you decide to reapply the records in the transaction to the application tables, click on Error Queue off the main page for the mobile server, which displays Figure 5-22.

Note:

To modify the error queue programmatically, use the ConsolidatorManager API, as described in Section 2.10, "Resolving Conflicts with Winning Rules" in the Oracle Database Mobile Server Developer's Guide.

Figure 5-22 Main Page for Error Queue

Error queue page
Description of "Figure 5-22 Main Page for Error Queue"

As Figure 5-22 shows, you can perform the following for the error transactions for each user:

  • To view and modify the details for the transaction in the error queue, select the transaction and click Publication Items. See Section 5.12.4.3.1, "Modifying Transaction in the Error Queue" for full details.

  • If you want to re-execute all records for a user, select the transaction and click Execute. This may be useful if you have modified the records and want to execute all transactions at once after the modification.

  • To delete all transactions for a user from the error queue, select the transaction and click Purge.

  • To search for a user error queue transaction, enter the user name in the Search field and click Go. Based on your search criteria, the mobile server displays the result.

5.12.4.3.1 Modifying Transaction in the Error Queue

Before re-executing the transaction, correct the error within each record of the transaction, as follows:

  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.

  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-23. 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 did not cause any problems.

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

    error queue records for a single publication item
    Description of "Figure 5-23 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-24.

    Figure 5-24 Show Details of Error Queue Record

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

  3. Correct the reason why the error occurred in the first place. By performing one or more of the following, you are modifying the record within the error queue. The changes that you make in this record are not executed until you select the transaction and click the Execute button in the main Error Queue screen shown in Figure 5-22.

    • 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.

    • Edit Fields and Select DML Action: Modify any fields in the Error Queue Record section under Record Details. Once you have completed all necessary changes to any records, then verify the DML action to be executed for this record in the Select DML Action pulldown. You can select Update, Insert or Delete in the Update DML pull-down. Clicking Save modifies the record in the transaction in the error queue.

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. This is shown in Figure 5-23.

After selecting the desired rows, choose the buttons at the top of the page ot performs 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 one or more rows with the checkboxes and click 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-execute a subset of the original records. After you create a new transaction, you can execute it off the main Error Queue page.

5.12.5 Viewing Client-Side Synchronization Conflicts

For automatic synchronization publication items only, any synchronization conflict error information is stored in the CONF$<snapshot> table in the same client database as the snapshot.

5.13 Monitoring and Analyzing Performance

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

5.13.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-25, 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-25 Performance Page

This image displays the performance page.
Description of "Figure 5-25 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.13.2 Displaying MGP Cycles and Statistics

As shown in the Mobile Manager Home page on Figure 5-26, the status for all MGP Jobs are listed in a table under the Data Synchronization section on the top. To see the statistics for each MGP Job, select the link under the Status column for the desired MGP job. For more details, refer to Section 6.3.4, "Viewing MGP Cycle Statistics".

Figure 5-26 MGP Status

MGP status

5.13.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 enable you to 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" in the Oracle Database Mobile Server Troubleshooting and Tuning Guide. The Consperf tool uses the Oracle Database version of the Explain Plan; thus, for full details on the Oracle Database Explain Plan, refer to the Oracle Database documentation.

5.13.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 Mobile Server Troubleshooting and Tuning Guide.