Skip Headers
Oracle® Fusion Middleware Administrator's Guide for Oracle Application Development Framework
11g Release 1 (11.1.1.5.0)

Part Number E15470-05
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

6 Deploying and Configuring ADF Mobile Transaction Replay Service

This chapter describes how to deploy and configure ADF Mobile transaction replay service during production. For information about using the transaction replay service during development, see Oracle Fusion Middleware Mobile Client Developer's Guide for Oracle Application Development Framework.

This chapter includes the following sections:

6.1 Introduction to ADF Mobile Transaction Replay Service

ADF Mobile transaction replay service (the transaction replay service) enables mobile client applications running on clients to access and execute business logic components on the server or on the base ADF application. For more information, see "Transaction Synchronization" section in Oracle Fusion Middleware Mobile Client Developer's Guide for Oracle Application Development Framework.

The transaction replay service functionality is enabled by the interaction of the following elements:

Note:

To use the transaction replay service, it must be enabled and configured at development time. For more information, see "Configuring ADF Mobile Transaction Replay Service in JDeveloper" section in Oracle Fusion Middleware Installation Guide for ADF Mobile Trans action Replay Service.

6.1.1 ADF Mobile Transaction Replay Service Schema

The transaction replay service schema is composed of the following database tables:

  • REPLAY_TYPE

  • REPLAY_ITEM

  • REPLAY_STATUS

  • REPLAY_USERS

  • REPLAY_JOBS

A database trigger is also set as part of the REPLAY_ITEM table, which notifies the transaction replay service infrastructure that a new transaction from a disconnected client requires processing. The REPLAY_USERS and REPLAY_JOBS tables are internal tables used by components of the transaction replay service architecture during processing of transactions, storing content on disconnected clients, and storing transactions to be replayed, respectively.

The REPLAY_ITEM and REPLAY_TYPE tables contain content visible to administrators and represent disconnected transactions from identified clients (replay items) and the transactions mapped business service (replay types).

The database trigger is set on the replay items table and is triggered by the insertion of a new record; that is, a new transaction entry from a disconnected client. The database trigger sets a flag in the REPLAY_USERS table for the client posting the new transaction from a client.

For more information about schema tables, see Appendix C, "ADF Mobile Transaction Replay Service Tables."

6.1.2 Replay Items

A replay item represents an action created by a disconnected client that is to be replayed on the enterprise server. Each replay item is a single record stored in the REPLAY_ITEM table of the transaction replay service schema. The attributes for the replay item record contain information that describes the disconnected transaction, including any parameters, and also references an entry in the REPLAY_TYPE table that maps the transaction to respective business service information.

The replay items record also contains identification information on the record itself, the disconnected client creating the transaction, status of the transaction replay, and authentication data.

A replay item is a logical entity that describes the client events and activities that modify the domain state of the client. The form of a replay item differs depending on the location, context, and the state of the data. A replay item contains sufficient information to ensure that server applications maintain domain write consistency. During a synchronization session, a row that has been updated by a source other than the current synchronization node since it was downloaded, cannot be updated or deleted.

The sync node repository stores the previous synchronization time. The user application maintains the time stamps for the last updates on each record.

6.1.2.1 Replay Item Dependency

The REPLAY_ITEM table has a column called DEPENDENCY. For each replay item, this column stores the ID of another replay item (parent) on which it has a dependency. The ID value stored in the DEPENDENCY column is null when a replay item does not have a parent replay item. To ensure data integrity, the transaction replay service does not process a replay item if its parent replay item's status is not successfully applied.

6.1.3 Parameter Name-Value Pair Format

The parameter-name value pair of the mobile client application can be logged using various methods, such as store the parameter information on the client in XML format, or create a parent-child relationship and store the pair information in parent-child tables.

6.1.3.1 Storing the Name-Value Pair on the Client in XML Format

Storing the parameter list as an XML node provides the advantages of XML. However, it can also result in slower parsing and larger data.

The XML schema (see Example 6-1) reconstructs the method signature and therefore enables support for method overloading.

Example 6-1 XML Schema

<?xml version=”1.0” encoding=”utf-8”?>
<xs:schema targetNamespace=”http://tempuri.org/XMLSchema.xsd” 
           elementFormDefault=”qualified” 
           xmlns=”http://tempuri.org/XMLSchema.xsd” 
           xmlns:mstns=”http://tempuri.org/XMLSchema.xsd” 
           xmlns:xs=”http://www.w3.org/2001/XMLSchema”>
   <xs:element name=”Parameter”>
      <xs:complexType>
         <xs:sequence />
         <xs:attribute name=”name” type=”xs:string” />
         <xs:attribute name=”type” type=”xs:string” use=”required” />
         <xs:attribute name=”value” type=”xs:string” use=”required” />
         <xs:attribute name=”order” type=”xs:positiveInteger” use=”required” />
      </xs:complexType>
   </xs:element>
</xs:schema>

The self-defining parameter list in the XML document (see Example 6-2) supports method overloading. The parameter description field contains the parameter name, its data type (such as String or Date) and associated value, the parameter's order and the actual data to be passed to the target method.

Example 6-2 The Self-Defining Parameter List

<?xml version=”1.0”?>
<note xmlns=”http://tempuri.org/XMLSchema.xsd”
      xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
      xsi:schemaLocation=”http://tempuri.org/XMLSchema.xsd xmfile1.xsd”>
   <Parameter Name=”SR_ID” Type=”string” Value=”102032” Order=”1” />
   <Parameter Name=”OWNER_ID” Type=”string” Value=”100” Order=”2” />
   <Parameter Name=”TIME_CR” Type=”date” Value=”03/22/2006 10:23:33” Order=”3” />
</note>

Note:

You can add the Old Value attribute to the parameter description field as oldValue.

6.1.4 ADF Mobile Transaction Replay Service Components

The transaction replay service incudes the following components:

6.1.4.1 TRS Dispatcher Component

The TRS Dispatcher component is a Java EE servlet implemented as a polling thread in the Web server. The TRS Dispatcher batches new transactions submitted by a disconnected client and forwards these transactions to the TRS TxnReplayer Component for replaying on the enterprise server. In the overall transaction replay service architecture, the TRS Dispatcher functions as a singleton component.

In further detail, the TRS Dispatcher component monitors the TRS Users table (REPLAY_USERS) for a flag (MORE_FLAG) set by the database trigger indicating that a new transaction is ready for processing. The TRS Dispatcher component creates a new row in the TRS Jobs table (REPLAY_JOBS), and submits the job to the TRS TxnReplayer component using HTTP GET commands. Submitting jobs as HTTP GET commands allows the use of the transaction replay service with any third-party Web server load balancing options. The TRS Dispatcher component then sets the status of the job to new.

6.1.4.2 TRS TxnReplayer Component

The TRS TxnReplayer component is a Java EE servlet that starts an asynchronous thread to process replay items. The TRS TxnReplayer receives a request to process replay items through a job submitted from the TRS Dispatcher Component. A job processes one or more replay items for the associated user. In the overall transaction replay service architecture, there can be several instances of the TRS TxnReplayer component to assist with load balancing.

In further detail, the TRS TxnReplayer component receives a request for transaction replay from a job submitted by the TRS Dispatcher component. The TRS TxnReplayer component queries the TRS Replay Items table (REPLAY_ITEMS) using information recorded in the submitted job for that client, and parses the replay items for any necessary parameters required by the method calls associated with the particular transaction type. The method calls are made one by one and in the order that they are received; that is, replay items from the same client are processed in order. Replay items for different clients are processed concurrently.

The TRS TxnReplayer component updates the status of replay items during processing. The replay item status is also synchronized back to the disconnected client from where it originated to complete the cycle of the transaction replay.

6.1.4.3 TRS Secure Web Service Component

The TRS Secure Web Service is a JAX-WS Web service, which can be implemented as one solution to post disconnected client transactions to the enterprise server for replaying through the transaction replay service architecture. For other transaction posting solutions and further information on the disconnected client's integration with the transaction replay service architecture, see Section 6.1.5, "Disconnected Client Interaction With ADF Mobile Transaction Replay Service Architecture".

The TRS Secure Web Service is deployed to the main enterprise server and receives calls from disconnected clients that require access to the transaction replay service architecture. The disconnected client provides user credentials, and the Web service authenticates and authorizes users for each method accessed by the disconnected client. For further details on security with the TRS Secure Web Service, see Oracle Fusion Middleware Security and Administrator's Guide for Web Services.

TRS Secure Web Service issues @SecurityPolicy annotation to attach security policies. The security policy is an XML file that contains security rules. For example, in the case of a user name token policy, the user name and password requirement is a security rule. The authentication policy and the authorization policy are attached to the TRS Web service.

To access the Web service, the mobile client application provides user name and password. After the user credentials are verified, the user is verified against the authorization policy to confirm the permissions granted for the requested operation.

The TRS Secure Web Service has three public methods for use by disconnected clients:

  • getPublicKey: Retrieves TRS public key in clear text for encryption.

  • insertReplayItem: Inserts a replay item into the REPLAY_ITEM table on the enterprise application server. This method uses TRSConnectionMgr to insert the replay item into the database.

  • hasOutstandingReplayItems: Checks if a given user's replay items have completed processing.

  • validateCredential: Validates the user name and password for a given replay type.

Using these methods, the TRS Secure Web Service can post disconnected client transactions to the transaction replay service for replaying at the enterprise server. The service can also query these replay items for their status. If replay items do not complete, error messages are logged on the enterprise server side for review.

6.1.4.4 ADF Mobile Transaction Replay Service Failover and Scalability

The transaction replay service architecture is scalable and designed for high-availability and failover. The transaction replay service can be deployed using various configurations to make sure the transaction replay service architecture is highly available for use by disconnected clients. For example, using third-party clustering services, the TRS Dispatcher Component, which can only have one instance active per node, can reside on both a primary and secondary node, and if the primary dispatcher fails, the secondary or passive node TRS Dispatcher component can be brought online to maintain availability of the architecture.

Another example of high-availability design is the deployment of the TRS TxnReplayer Component, which can have several instances running simultaneously. It maintains high-availability by use of a third-party HTTP load balancer, which balances the job requests between available components. These scenarios are examples of high-availability solutions; your individual deployment may differ.

6.1.5 Disconnected Client Interaction With ADF Mobile Transaction Replay Service Architecture

The transaction replay service architecture is independent of the type of disconnected client accessing the replay service on the enterprise server side of the application.

Any disconnected client configuration with the transaction replay service must be able to populate the REPLAY_ITEM table in the transaction replay service schema, as well as receive status or logging updates produced by the transaction replay service architecture.

6.1.6 Transaction Process Flow

The high-level interaction between various components of the transaction replay service architecture during a transaction replay is illustrated Figure 6-1.

Figure 6-1 ADF Mobile Transaction Replay Service Transaction Process

TRS Transaction Process
  1. The synchronization service runs, adding a record to the REPLAY_ITEM table. This record represents a transaction from a disconnected client requiring replay on the enterprise application server.

  2. The new REPLAY_ITEM record triggers a flag to be set on the REPLAY_USER table.

  3. The TRS Dispatcher Component, which periodically reviews the REPLAY_USER table, detects the flag.

  4. After detecting the flag, the TRS Dispatcher component creates a row in the REPLAY_JOBS table

  5. The TRS Dispatcher submits the job to the TRS TxnReplayer Component, usually through a third-party load balancer.

  6. The TRS TxnReplayer processes the items in the REPLAY_ITEM table with information from the REPLAY_TYPE table (not shown). At this stage of the process, the transaction is replayed on the server containing the application business logic.

  7. The TRS TxnReplayer component monitors the progress of the transaction replay.

  8. TRS TxnReplayer component updates the status of each replay item during processing.

  9. After the completion of the transaction on the enterprise server, the status of the replay item is updated and synchronized back to the disconnected client.

6.2 Configuring ADF Mobile Transaction Replay Service Security

The transaction replay service takes business service method calls from a disconnected mobile device and replays the calls on the server side. The mobile client application authenticates users without any direct connection to the server, and then synchronizes a batch of business service calls to the REPLAY_ITEM table on the server. The transaction replay service reads data from the REPLAY_ITEM table to get the user identity. The replay service replays the business service calls asynchronously without any user interface. If user authentication is required, the transaction replay service obtains a security token for that given user and propagates it to the business service.

The security in the transaction replay service is configured in two parts:

6.2.1 How to Configure Inbound Security

Inbound security is responsible for the integrity of data being entered into the REPLAY_ITEM table on the server. The server-side REPLAY_ITEM table is protected by server database access control. Only the administrator has privilege to access the REPLAY_ITEM table. Additionally, transaction replay service requires that the synchronization tools selected by end users must implement proper access control to allow only authorized users to synchronize data to the REPLAY_ITEM table.

Transaction replay service also requires that client applications implement authentication and authorization to allow only trustworthy data being entered into the device database.

Under these requirements, the transaction replay service assumes that the data in the REPLAY_ITEM table is always trustworthy.

6.2.2 How to Configure Outbound Security

Outbound security is responsible for establishing the user's credential for authentication during replaying a business service call. The transaction replay service supports credentials consisting of a user name and a password, and secures the password using credential store framework or public key cryptography.

6.2.2.1 Securing Password Using Credential Store Framework

The Credential Store Framework (CSF) provides a mechanism for secure storage and management of credentials for Java-based applications. The CSF API supports two types of storage:

  • File-based credentials, which are stored in the Oracle wallet.

  • Repository-based credentials, which are stored in the LDAP directory.

Using CSF, transaction replay service obtains a user's user name and password from the server storage without having the mobile client application sending the password, and hence avoiding the encryption-decryption during transmission.

For more information, see "Developing with the Credential Store Framework" section in Oracle Fusion Middleware Application Security Guide.

One limitation of using a credential store is that it relies on a server-side password storage and it may require extra effort to integrate with existing user administration.

6.2.2.2 Securing Password Using Public Key Cryptography

Public key cryptography, also known as asymmetric cryptography, is a form of cryptography in which a user has a pair of cryptographic keys–a public key and a private key. The private key is kept secret, while the public key may be widely distributed. The keys are related mathematically, but the private key cannot be practically derived from the public key. A message encrypted with the public key can be decrypted only with the corresponding private key.

To use public key cryptography to secure user passwords, the transaction replay service generates a pair of a public and a private key. It then publishes or distributes the public key. The client application uses the public key to encrypt its password and stores the encrypted password in the replay item. The password can then be transmitted safely. Only the transaction replay service can decrypt it using its private key.To implement public key cryptography, the following steps are involved:

  1. Creating a keystore:

    According to Java Cryptography Architecture (JCA), a keystore is a database of keys. Private keys in a keystore have a certificate chain associated with them, which authenticates the corresponding public key. A keystore also contains certificates from trusted entities.

    The transaction replay service supports two types of keystores, the Java Key Store and the Oracle Wallet. For more information about creating and using key stores for message protection, see the section about managing keystores, wallets, and certificates in the Oracle Fusion Middleware Administrator's Guide.

  2. Creating a certificate and a key pair:

    In cryptography, a public key certificate (or identity certificate) is an electronic document which incorporates a digital signature to bind a public key with an identity—information such as the name of a person or an organization, their address, and so forth. The certificate can be used to verify that a public key belongs to an individual.

    To use the public key cryptography in the transaction replay service, you create a certificate in a keystore. The certificate does not necessary belongs to an individual. In Java Key Store, the keytool command creates a certificate with an alias. In Oracle wallet, the alias is the Distinguished Name (DN) in a directory service of the certificate. The transaction replay service can retrieve a certificate's public key and private key from the keystore by its alias.

    The transaction replay service requires the following parameters:

    • Keystore URL: the file location of the keystore.

    • KeystoreType: JKS for Sun's Java Key Store, PKCS12 for Oracle's ewallet.p12 file, or SSO for Oracle's cwallet.sso.

    • KeystorePassword: The password to open the keystore.

    • CertificateAlias

    • keyPass (optional): The key created by Sun's keytool can have a password to protect each individual key. Therefore, the transaction replay service allows for configuration of a keyPass password to open the private key.

    • Provider (optional): To open Oracle wallet, a security provider of value OraclePKI is needed in the keyStore.getInstance method.

    The following code shows how to open a key store to retrieve a certificate and its key pair.

    KeyStore ks = KeyStore.getInstance(KeystoreType, Provider);
    char[] kspwd = KeystorePassword.toCharArray(); 
    char[] keypwd = keyPass.toCharArray();
    URL url = new URL(KeyStoreFile);
    ks.load(url.openStream(), kspwd);
    Certificate cert = ks.getCertificate(CertificateAlias);
    PublicKey pubKey = cert.getPublicKey();
    PrivateKey privKey = ks.getKey(CertificateAlias,keypwd);
    

    Due to the secrecy of the KeystorePassword and keyPass, these parameters are not stored and configured directly. Instead, you must provision two password credentials in CSF for these two passwords. The following four parameters are needed for the transaction replay service to locate them in CSF:

    • Keystore Password CSF Map

    • Keystore Password CSF Key

    • Key Password CSF Map

    • Key Password CSF Key

  3. Decrypting the password:

    The transaction replay service uses private key to decrypt the password.

  4. Applying PKE to the USER_PASSWORD column in REPLAY_ITEM:

    The user passwords are transmitted from client to server in the USER_PASSWORD column in the REPLAY_ITEM table. The USER_PASSWORD's type is VCHAR2(256). The maximum length of user password is 117 characters. The encrypted text is 128 bytes of binary data. To ease the transmission, transaction replay service requires the encrypted text to be stored using base64 encoding in the USER_PASSWORD column. The encoded string has a length of 172 bytes.

6.2.3 How to Enable Authentication and Authorization

When the user starts a mobile application for the first time after installation, they are prompted by the login page to enter the login credentials (user name and password) to establish a connection to the TRS Secure Web Service. The server performs a synchronous authentication at this time: if the credentials are correct, the TRS Secure Web Service returns its public key to the client.

The transaction replay service requires a user name and password be provided for each replay item (see Section 6.1.2, "Replay Items"). To avoid sending password in the REPLAY_ITEM table in clear text, the transaction replay service implements public key encryption to securely exchange passwords from the mobile client to the server. The mobile client obtains the transaction replay service public key in the authentication process. The client then encrypts the user password using the public key.

The getPublicKey method is implemented by the TRS Secure Web Service. It provides two web service calls for clients to use. At the time of client login, the following happens:

  1. First, the mobile client issues the getPublicKey to get the publicKey as a String

  2. The mobile client encrypts password using publicKey and makes the second call validateCredential to the same web service. The values of replay type name, user name, and public key encrypted password are passed as parameters. The method returns 1 for the valid user and the encrypted password, or 0 for the invalid user.

For more information about setting public key encryption in the transaction replay service, see "Configure Public Key Encryption for ADF Mobile Transaction Replay Service" section in Oracle Fusion Middleware Installation Guide for ADF Mobile Trans action Replay Service.

When the transaction replay service replays transactions, the replayer component honors access control and permissions associated with the user credential of the transaction. For example, if the user that generated a transaction has read-only access to Entity Object A, and the transaction requires update of Entity Object A, then the replay will fail and an error will be returned to the user.

The transaction replay service supports ADF authorization and access control. For more information, see the following:

When the end user fails to authenticate, an error message is displayed. You can configure the error message using EL expressions. For more information, see "Authentication" section in Oracle Fusion Middleware Mobile Client Developer's Guide for Oracle Application Development Framework.

6.3 Managing ADF Mobile Transaction Replay Service Using MBeans

You configure and manage the Dispatcher and the transaction replay service using standard MBeans that contain interfaces for both the MBean implementation (inputs and outputs) and behavior. All of the transaction replay service-related MBeans are in the OracleTRS domain. Figure 6-2 illustrates the OracleTRS domain within the navigation tree in JConsole, a JMX-compliant console that you can use to manage transaction replay service. You can also manage the transaction replay service using MBean operations exposed through the Oracle Enterprise Manager Fusion Middleware Control console.

Figure 6-2 The OracleTRS Domain in JConsole

The OracleTRS Domain in JConsole

6.3.1 How to Manage the Dispatcher

Table 6-5 lists attributes of the DispatcherSettings MBean that allow you to configure the Dispatcher. You can also monitor the dispatcher using the CurrentJobs, JobStatus, and JobInfo operations of the DispatcherSettings MBean.

Table 6-1 Attributes of the DispatcherSettings MBean

Attribute Description

URL

The URL used to submit a transaction replay job. Changes to this attribute take effect after the service restarts.

DataSourceName

The name of the data source that contains the transaction replay tables. Changes to this attribute take effect after the service restarts.

BackupDataSourceName

The name of the backup data source that contain the transaction replay table. Changes to this attribute take effect after the service restarts.

NumberOfDatabaseRetries

The maximum number of times that the transaction replay service attempts to establish a database connection if a database connection fails. Changes to this attribute take effect after the service restarts.

DatabaseConnectionRetryInterval

The retry interval (in milliseconds) to obtain a database connection. Changes to this attribute take effect after the service restarts.

NumberOfDispatcherDBRetries

The number of database operation retries attempted by the Dispatcher. Changes to this attribute take effect after the service restarts.

DispatcherDBRetryInterval

The retry interval (in milliseconds) for the Dispatcher database operations. Changes to this attribute take effect after the service restarts.

LoopDelay

The time (in milliseconds) to pause before reading and processing transaction replay jobs. Changes to this attribute take effect after the service restarts.

NumberOfJobRetries

The number of consecutive retries for the Dispatcher to resubmit a job for a job with an error status.

JobSubmittedTimeout

The timeout interval (in minutes) before a job is timed-out (stuck at Status 1 or 2).

JobProcessingTimeout

The timeout interval (in minutes) before a job is timed out, when stuck at Status 3.

ItemProcessingTimeout

The timeout interval (in minutes) before a txnreplayer is timed out.

URLConnectionTimeout

The time-out value (in seconds). This time-out applies to the worker servlet URL through which the Dispatcher submits jobs to the worker servlet. The default value is 60 seconds.

URLReadTimeout

The time-out value (in seconds). This time-out applies to the worker servlet URL through which the Dispatcher submits jobs to the worker servlet. The default value is 60 seconds.


6.3.2 How to Configure the Dispatcher Runtime

The DispatcherRuntimeInfo MBean lets you view and affect the run-time information from the transaction replay service system.The DispatcherRuntimeInfo MBean extends the Timer MBean class to send regular timer notifications for automatic archival of replay items and replay jobs. It also has the inner DispatcherArchiveListener class to receive the timer notifications and perform the actual archiving process.

Table 6-2 lists attributes of the DispatcherRuntimeInfo MBean.

Table 6-2 DispatcherRuntimeInfo MBean Attributes

Attributes Description

ArchiveTime

Indicates the start date and time for the auto-archiving process. The format for the start time is DD-MON-YY HH:mm. For example, 14-Feb-08 13:00. The time is in military time format and should be the local time of the host on which the Dispatcher runs. The start time of the auto-archival process is after the current date and time.

ArchiveInterval

Indicates the time interval (in minutes) between each auto archival notification. For example, setting the value to 1440 minutes would set the auto archiving process to once a day. A minimum interval could be 1 minute.

ArchiveAge

Indicates how old (in days) records must be to be removed. For example, if you set this value to 30, then all records older than 30 calendar days at the time of auto-archival are removed.

Note that for all time calculations, UTC time is used.

ArchivePath

An optional attribute that indicates the archival directory where archive files with deleted records from the REPLAY_ITEM and REPLAY_JOBS tables are stored. For example, C:\logs.

For more information, see Section 6.3.2.1, "Using the ArchivePath Attribute."


6.3.2.1 Using the ArchivePath Attribute

Consider the following when using the ArchivePath attribute of the DispatcherRuntimeInfo MBean:

  • If the archive directory path is provided (that is, it is not represented by an empty string), then prior to removing the targeted records, each record that meets the target criteria is saved to an archive file in the directory defined by the ArchivePath attribute. The archive log file name starts with a date encoding of the removal date, which facilitates sorting of all files in the directory and allows to identify the archived table:

    yyyymmddHHmm_TRS_Replay_Items.log (for replay items)

    yyyymmddHHmm_TRS_Replay_Jobs.log (for replay jobs)

    where:

    • yyyy represents the year

    • mm represents the month

    • dd represents the date

    • HH represents hours (in military time)

    • mm represents minutes

    For example, log files named 200802142035_TRS_Replay_Items.log and 200802142035_TRS_Replay_Jobs.log would contain all replay items and replay jobs older than 8:35 pm of February 14, 2008.

    The archive files contain all column data (including the column names) for each replay item and replay job record. The data are delimited by the vertical bar ( '|' ) and can be examined using Microsoft Excel.

  • If writing of the archive files fails for any reason (for example, the disk is full), then the auto-archiving process stops and records are not removed from the REPLAY_ITEM and REPLAY_JOBS tables. If the issue is resolved, these records are archived when the next notification is received.

  • If the archive files were successfully created, records that meet the target criteria are removed from the REPLAY_ITEM and REPLAY_JOBS tables.

  • If the archive directory path was not provided and the archive files were not created, records that meet the target criteria are still removed from the REPLAY_ITEM and REPLAY_JOBS tables.

6.3.2.2 What You May Need to Know About the Replay Items Removal Criteria

All replay items whose processed date is earlier than the remove date and whose status matches one of the statuses shown in Table 6-3 are removed from the REPLAY_ITEM table during the auto-archive operation.

Table 6-3 Replay Items Removal Status

Status ID Status

3

Successfully Applied

4

Error Encountered

5

Parent Error

6

Invalid Parent

7

Credential Error

8

Parameter Parsing Error

9

Replay Type Error

11

Error – Reviewed, No Action


Replay items whose status matches one of the statuses shown in Table 6-4 cannot be auto-archived.

Table 6-4 Replay Items Status That Prevent Removal

Status ID Status

1

Pending

2

Processing

10

To be reviewed by administrator


6.3.2.3 What You May Need to Know About the Replay Jobs Removal Criteria

Replay jobs that match all of the following three criteria are removed from the REPLAY_JOBS table during the auto-archive operation:

  1. Status matches one of the statuses shown in the following table:

    Status ID Status
    4 Done
    5 Error

  2. An updated date is earlier than the remove date.

  3. Not referenced by a record in the REPLAY_USERS table.

6.3.2.4 What You May Need to Know About the Attribute Persistence

Using the Preferences API defined in the java.util.prefs package, the transaction replay service persists the auto archive attributes to the oracle/txnreplay/autoarchive node. This ensures that the process of auto archiving resumes automatically if the server is restarted.

The transaction replay service accesses the same node when it needs to remove attributes.

6.3.3 How to Monitor the Dispatcher

The DispatcherRuntimeInfo MBean exposes methods listed in Table 6-5.

Table 6-5 DispatcherRuntimeInfo MBean Methods

Method Description

ReplayItemList

Returns a list of replay items currently in the system.

ReplayJobList

Returns a list of jobs currently in the system.

ReplayTypeList

Returns a list of replay types currently defined in the system.

ReplayUserList

Returns a list of replay users currently in the system.

AddReplayType

Adds a replay type to the transaction replay service system.

RemoveReplayType

Removes a reply type from the system.

UpdateReplayType

Updates a replay type.

RemoveReplayItems

Removes a reply type.

RemoveReplayJobs

Removes reply items from the REPLAY_ITEMS table.

RemoveReplayUsers

Removes users from the REPLAY_USERS table based on updated dates.

RemoveReplayUser

Removes a specific user from the REPLAY_USERS table.

GetReplayItemDependency

Returns a replay item, which is a dependency for the supplied item ID.

AutoArchive

Sends a timer notification to start a regular automatic archival process of replay items and replay jobs from the REPLAY_ITEM and REPLAY_JOBS tables, respectively.

For more information, Section 6.3.3.1, "What You May Need to Know About AutoArchive and StopAutoArchive Operations."

StopAutoArchive

By removing the auto archival notification from the timer, stops the automatic archival process for replay items and replay jobs from the REPLAY_ITEM and REPLAY_JOBS tables, respectively.

For more information, Section 6.3.3.1, "What You May Need to Know About AutoArchive and StopAutoArchive Operations."


6.3.3.1 What You May Need to Know About AutoArchive and StopAutoArchive Operations

If the auto archive notification is successfully created during the AutoArchive operation, the auto archive attributes are saved to the oracle/txnreplay/autoarchive node that contains persisted preferences settings. If the server is restarted, these attributes are retrieved and the auto archive process is automatically restarted.

If the auto archive notification is successfully removed during the StopAutoArchive operation, the auto archive attributes are removed from the oracle/txnreplay/autoarchive node.

6.3.4 How to Configure and Administer ADF Mobile Transaction Replay Service

The TransactionReplaySettings MBean lets you configure and manage the transaction replay service. This MBean has the following two interfaces:

  • TxnReplayerSettingsMBean

  • TxnReplayerSettings

The attributes of TxnReplayerSettingsMBean that Table 6-6 lists allow you to configure the behavior of the transaction replay service.

Table 6-6 Attributes of the TxnReplayerSettinsMBean Interface

Attribute Description

NumThreads

The number of Transaction Replayer threads on the server. This change takes effect when the service restarts.

DataSourceName

The name of the data source that contains the transaction replay tables. Changes to this attribute take effect when the service restarts.

BackupDataSourceName

The name of the backup data source that contains the transaction replay tables. Changes to this attribute take effect when the service restarts.

DBRetries

The maximum number of times that the transaction replay service attempts to get a database connection if the database connection fails. Changes to this attribute take effect when the services restarts.

DatabaseConnectionRetryInterval

The retry interval (in milliseconds) to get the database connection. Changes to this attribute take effect after the service restarts.

NumberofTxnReplayerDBRetries

The number of database operation retries for TxnReplayer. Changes to this attribute take effect after the service restarts.

TxnReplayerDBRetryInterval

The retry level (in milliseconds) for TxnReplayer database operations. Changes to this attribute take effect after the service restarts.

XSDURL

The location of the XML schema that is used to validate the XML parameters for each replay item. Changes to this attribute take effect after the service restarts.


6.3.4.1 Configuring Replay Types

For information on how to create and configure the transaction replay service replay types, see "Creating Transaction Replay Type" section in Oracle Fusion Middleware Installation Guide for ADF Mobile Transaction Replay Service.

6.3.4.2 Troubleshooting Transactions

Table 6-7 shows values from the REPLAY_STATUS table that you can use to monitor status of the transaction replay service transactions.

Table 6-7 Replay Status Values

Status_Id Status

1

Pending

2

Processing

3

Successfully Applied

4

Error Encountered

5

Parent Error

6

Invalid Parent

7

Credential Error

8

Parameter Parsing Error

9

Replay Type Error

10

To be reviewed by administrator

11

Error – Reviewed, No Action


In addition, you can review the transaction replay service's server log files for error messages.

6.3.5 How to Publish Business Events

The transaction replay service enables publishing of a business event to invoke a SOA component, such as a BPEL process. You can use this functionality as follows:

  1. Create a replay type that contains the following in the REPLAY_TYPE table:

    • CLASSNAME_EVENTNAMESPACE: specify the event namespace.

    • METHODNAME_EVENTNAME: specify the event name.

    • INV_TYPE: Business Event

  2. Create replay items to use the created replay type. Event payload is supplied as PARAMS in the REPLAY_ITEM table. Ensure that the event payload is defined in a valid XML format and conforms to the event schema.

You can identify thetransaction replay service replay types to use a style called Business Event.

Business events are asynchronous in nature and do not retain information after having been fired. As an event publisher, the transaction replay service can only guarantee that the event is published to the Oracle Event Delivery Network (EDN): if a replay item is to invoke a business event, the replay item's Successfully Applied status (3) indicates that the event is delivered to EDN; it does not mean that the to-be-invoked actions have completed successfully.

6.4 Configuring Security for ADF Mobile Transaction Replay Service Authentication and Data Synchronization

The transaction replay service takes business service method calls from a disconnected mobile device and replays the calls on the server side. The mobile client authenticates users without any direct connection to the server. The mobile client then synchronizes a batch of business service calls to the REPLAY_ITEM table on the server. The transaction replay service reads from the REPLAY_ITEM table to get the user identity. The replay service replays the business service calls asynchronously without any user interface. If the business service requires authentication, the transaction replay service must obtain a security token for that given user and propagate it to the business service.

6.4.1 What You May Need to Know About User Credentials

A user credential comes from the base ADF application, but it is stored and accessed by the mobile client.

The ADF Mobile client application accesses this credential when the transaction replay service's transactions are logged; the credential is sent along with the transaction. This user credential is accessed by a login screen that checks the credential typed in against the stored credential.

6.4.2 How to Set Up Users and Subscriptions

To add and manage users and user access to applications, you use the Mobile Manager.

For more information, see the following:

6.4.3 How to Configure Application Deployment Packages

Mobile Database Workbench (MDW) lets you create deployment packages, which would allow synchronization rules (publications and publication items) created in the development environment to be migrated to the production environment. For more information, see "Using the Packaging Wizard" section in Oracle Database Lite Developer's Guide.

6.4.4 How to Modify Synchronization Rules Using Mobile Database Workbench

Mobile Database Workbench (MDW) lets you make changes to refine synchronization rules for your mobile client application:

  • Define data filters (for example, filtering on a specific OrderDate).

  • Configure database sequence windows that separate ranges of sequence numbers assigned to each client.

  • Create subscription packages and assigning users. The subscription defines which data (that is, which publications) a user can access.

For more information, see Oracle Database Lite Developer's Guide.

6.4.5 How to Add Security and Grant Privileges

Oracle ADF Security framework provides authentication and authorization services to Oracle Fusion web applications.

The transaction replay service ADF entity event replay types support the security policy defined for ADF entity objects and attributes.

For information on how to grant privileges and add security, see "Enabling ADF Security in a Fusion Web Application" section in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

6.5 Monitoring Business Events and Entity Replay Items

Entity replay items record mobile client changes at the entity object level. At development time, business events can declaratively defined at the entity level and conditions under which those events should be raised can be specified. Business events that meet the specified criteria are raised upon successful commit of the changed data. A business event can be triggered on a successful create, update, or delete of an entity object. A business event is implemented during development by creating an event definition, mapping it to an event point, and then publishing that definition.

Event definition describes an event, which is published and raised within an event system. It is owned by an entity object and stored as part of the entity object's metadata. Event definitions consist of an event name and a payload, which is a list of attributes to be sent to the subscriber.

Event point is a place from which an event may be raised. There are three event points for an entity: create, update, and delete. At design time, event definitions are mapped to event points. Events are raised for each entity in the transaction after successful commit only.

6.5.1 How to Use Events To Specify Entity Replay Items

Mobile clients use three basic event names: TRS_Create, TRS_Update, and TRS_Delete.

  • TRS_Create: This event is raised when a new entity record is created. Its event payload includes entity name and all attributes from the entity object.

  • TRS_Update: This event is raised when an existing entity record is updated. Its event payload includes entity name, primary key and changed attributes, and the new and the old values.

  • TRS_Delete: This event is raised when an existing record is deleted. Its event payload includes entity name, and the primary key.

The root element of each event payload is the name of the event point concatenated with Info, and the namespace value encodes the corresponding entity name with package information. The entity name can be derided by removing events or schema from the namespace attribute.

The child elements are attribute names and values. The payload.xml file can include a list of these three types of event information with elements TRS_CreateInfo, TRS_UpdateInfo or TRS_DeleteInfo.

6.5.2 What You May Need to Know About Authentication in Replay Items

The transaction replay service requires user name and password be provided for each replay item. To avoid sending the password in the REPLAY_ITEM table in clear text, the transaction replay service implements the public key encryption to securely exchange passwords from the mobile client to the server.

The mobile client gets the transaction replay service public key during authentication, which it uses to encrypt the password. For more information about security and authentication, see Section 6.2, "Configuring ADF Mobile Transaction Replay Service Security."

6.5.3 What You May Need to Know About Error Reporting

When an entity event fails to commit, the replay servlet receives exceptions. This is critical for error reporting back to the device. The transaction replay service stores the remote exception's error message in the ERROR column of the REPLAY_ITEM table and synchronizes back to the device.

6.6 Introduction to ADF Mobile Transaction Replay Service Error Handling

The transaction replay service errors are categorized into two groups:

Note:

The transaction replay service does not resolve the conflicts, but reports the error conditions and the required information to resolve the conflict.

6.6.1 Data Errors

Data-related errors can occur when replaying the replay items. These errors are categorized into two types:

  1. Data conflict: can be either an update conflict or delete conflict.

    A data conflict could occur for various reasons, such as the following:

    • Attempt for updating the data results in a conflict error, as the data had been updated by another user after the last synchronization.

    • Attempt for updating the data results in a conflict error, as the data had been updated by another replay item in the same replay list.

    • Attempt for updating the data results in a conflict error, as the data had been updated by another DML induced within the same replay item.

    • Attempt for updating the data results in a conflict error, as the data had been deleted by another user after the last synchronization.

    • Attempt for deleting the data results in a conflict error, as the data that had been updated by another user after the last synchronization.

    • Attempt for deleting the data results in a conflict error, as the data that had been deleted by another user after the last synchronization.

  2. Constraint violation: can occur in any database manipulation operations.

    A constraint violation could occur for various reasons, such as the following:

    • Attempt for updating the data that causes a constraint violation, as the related data had been modified by another user after the last synchronization.

    • Attempt for inserting the data that causes a constraint violation.

    • Attempt for deleting the data that causes a constraint violation.

6.6.2 Process Error

All errors that do not occur due to data conflicts or constraint violations are process errors.

6.6.3 Error Information

The transaction replay service provides various information as part of the conflict resolution framework.

6.6.3.1 Error Information on the Client

The transaction replay service provides the following information on the client to identify and resolve conflicts:

  • Replay item identifier

  • Replay item error code

  • Replay item error details

  • Replay item created date

  • Replay item parameters with name-value pairs

  • Replay item old values

6.6.3.2 Error Information on the Server

The transaction replay service provides the following information on the server to identify and resolve conflict:

  • Replay item identifier

  • Replay item error code

  • Replay item error details

  • Replay item created date

  • Replay item parameters with name-value pairs

  • Job ID for the replay list

  • Server ID where the replay list was processed

  • Thread ID of the server

  • Timestamp when the replay list was processed

  • Job status

  • Job details, if available

6.7 Configuring and Monitoring ADF Mobile Transaction Replay Service Logging

The transaction replay service uses the standard java.util.logging mechanism. The following loggers are available:

You can adjust the log level using the standard Java Server log management tools, such as JConsole or Oracle Enterprise Manager. For more information, see Oracle Fusion Middleware Administrator's Guide.

6.7.1 How to Enable Logging for Entity Replay Items

To enable logging for entity replay items, configure the logging levels as described in "Configuring ADF Mobile Transaction Replay Service" section of Oracle Fusion Middleware Installation Guide for ADF Mobile Transaction Replay Service. The following settings in the adf-config.xml file of the mobile client enable entity replay item logging:

<amc:setting name="app-name" value="BB1" xmlns=""/>
<amc:setting name="replay-type-id" value="39"/>
<amc:setting name="replay-type-name" value="HR-Entity-Event-Test"/>
<amc:setting name="use-trs" value="true"/>

The replay-type-id and replay-type-name settings refer to the REPLAY_TYPE table that corresponds to the correct replay type on the server base application.