Oracle® Fusion Middleware

Installation Guide for ADF Mobile Transaction Replay Service

11g Release 1 (11.1.1.5.0)

E15492-02

April 2011

The ADF Mobile transaction replay service replays transactions that occur on the mobile device while it is disconnected. The ADF Mobile transaction replay service component is a critical component of ADF Mobile client and requires a separate installation.

The following sections provide information on installation, configuration, and uninstallation of ADF Mobile transaction replay service component:

Installing ADF Mobile Transaction Replay Service
Configuring ADF Mobile Transaction Replay Service in Enterprise Manager
Configuring ADF Mobile Transaction Replay Service in JDeveloper
Uninstalling ADF Mobile Transaction Replay Service

1 Installing ADF Mobile Transaction Replay Service

This release of ADF Mobile transaction replay service is tested and supported on specific versions of Windows and Linux.

1.1 System Requirements

Before you run the installer program, ensure that the prerequisites listed in Table 1 are met.

Table 1 System Requirements

Component	Requirement
Operating System	Windows XP or above Linux
JDK	Version 1.6 or above. Ensure that `PATH` is set to `bin` directory. Windows example: `PATH = C:\JDK\bin` Linux example: `PATH = ...:/usr/java/jdk/bin`
Database	Oracle Database 10.0.2.2 or above, installed with privilege to create new schema.
JDeveloper	Oracle JDeveloper 11.1.1.x.x or above.
Application Server	WebLogic Server 10.0.3 or above, installed with a JRF extension domain.
Enterprise Manager	Enterprise Manager Fusion Middleware Control. Create a domain with Enterprise Manager and install JRF extension. For more information about Fusion Middleware Control, see the Oracle Application Server Administrator's Guide.

1.2 Downloading the ADF Mobile Client Extension

The ADF Mobile transaction replay service is a part of the ADF Mobile Client JDeveloper Extension.

To download the ADF Mobile Client Extension:

Open JDeveloper.
From the Help menu, choose Check for Updates.
In the Welcome page of the Check for Updates wizard, click Next to continue.
In the Source page of the wizard, JDeveloper populates the list area with update centers available.

Click Next to continue.
In the Updates page of the wizard, JDeveloper populates the list area with available updates. After the list is populated, select the ADF Mobile Client checkbox, as shown in Figure 1. Note that the version number of ADF Mobile Native Client might not be same as shown in Figure 1.

Figure 1 JDeveloper Check for Updates Wizard

Click Next to continue.
In the Download page of the wizard, JDeveloper downloads the selected extension.

When the download is complete, click Next to continue.
The Summary page of the wizard, summarizes the downloaded extension.

Click Finish to close the wizard.
Restart JDeveloper.

After JDeveloper restarts, the following ADF Mobile transaction replay service files are added to <MW_HOME>/jdeveloper/trs, where MW_HOME is the Middleware Home directory.

trs_template.jar
\lib\trs_ejb.jar
\security\README.txt
\security\test.jks
\security\test_cwallet.sso
\db_scripts\*
other files and directories

1.3 Launching the Installer

To install the ADF Mobile transaction replay service component, you must use the WebLogic Configuration Wizard to extend your application's WebLogic domain. To extend the domain, use the ADF Mobile transaction replay service component's template file trs_template.jar available in the <MW_HOME>/jdeveloper/trs directory. If you are using Enterprise Manager to manage ADF Mobile transaction replay service, the template must be installed on a base domain that is created from Enterprise Manager Fusion Middleware Control.

Before you proceed, ensure that you have administrative access to the database server used by the ADF Fusion web application. The installer creates and populates the database server with ADF Mobile transaction replay service schema.

To install the ADF Mobile Transaction Replay Service Component:

Open the Fusion Middleware Configuration Wizard. From the Windows Start Menu, choose All Programs > Oracle Fusion Middleware 11.1.1.x.x > WebLogic Server 11gR1 > Tools > Configuration Wizard.
In the Welcome page, choose Extend an existing WebLogic domain.

Click Next to continue.
In the Select a WebLogic Domain Directory page, browse and select the domain directory of your Fusion web application.

Click Next to continue.
In the Select Extension Source page, select Extend my domain using extension template. In Template Location, click Browse and select the trs_template.jar file <MW_HOME>/jdeveloper/trs directory.

Click Next to continue.
In the Configure JDBC Data Sources page, verify that TrsAdminDS is the data source, as shown in Figure 2. Select the checkbox corresponding to TrsAdminDS row, and change the Host Name, Username, and Password to the location you want to deploy the TRS schema to. The data source could be, but is not required to be, the same database that the base Fusion web application is configured with.

Figure 2 Configure JDBC Sources page of Fusion Middleware Configuration Wizard

Click Next to continue.
In the Test JDBC Data Sources page, click Test Connection to verify the JDBC options you specified in the Configure JDBC Data Sources screen. After the connection is successful, a Test Successful! message appears in the Connection Result Log area.

Click Next to continue.
In the Run Database Scripts page, click Run Scripts to populate the schema with tables and records. After the scripts run successfully, a Database Load Successful! message appears in the Results area. If you want to create a log file, select the Log File checkbox and specify the log file's location.

Click Next to continue.
In the Select Optional Configuration page, if required, select desired options.

Click Next to continue.
In the Configuration Summary screen, verify your settings that you have configured in the previous pages.

Click Extend to extend the domain.
In the Creating Domain page, click Done to close the wizard.
Start Oracle WebLogic Server.

2 Configuring ADF Mobile Transaction Replay Service in Enterprise Manager

You can configure the ADF Mobile transaction replay service component from Enterprise Manager Fusion Middleware Control. Note that Enterprise Manager is not required for configuring ADF Mobile transaction replay service, but it provides a user interface for administrative tasks such as adjusting log levels, change MBean variables and configure credential stores. For more information about Fusion Middleware Control, see the "Getting Started Using Oracle Enterprise Manager Fusion Middleware Control" section in the Oracle Fusion Middleware Administrator's Guide.

To configure the Dispatcher of ADF Mobile Transaction Replay Service Component:

Open Enterprise Manager.

Navigate to the following URL and log in using the administrator username and password:

http://<server_name:port>/em
In the left panel of Enterprise Manager console, choose Farm_your_domain > WebLogic Domain > your_domain.
On the right panel, click WebLogic Domain, and choose System MBean Browser from the dropdown list, as shown in Figure 3.

Figure 3 Enterprise Manager Fusion Middleware Control
In the left pane of the System MBean Browser page, select Application Defined MBeans.
Expand Application Defined MBeans and choose oracle.txnreplay > Server:Admin Server >DispatcherSettings.
In the Attributes page of Dispatcher, update the URL field to match the server's address and port number.

For example, http://localhost:7001/trs_txnreplayer/workerservlet, as shown in Figure 4.

Figure 4 Dispatcher Attributes page
If required, configure the logging levels.
1. Navigate to the AdminServer page. In the left panel, choose Farm_your_domain > WebLogic Domain > your_domain > AdminServer.
2. In the right pane, open the WebLogic Server dropdown list. From the Logs submenu, choose Log Configuration.
3. In the Log Levels tab of Log Configuration page, adjust the following log levels, as shown in Figure 5:
  
  oracle.txnreplay.dispatcher
  
  oracle.txnreplay.txnreplayer
  
  oracle.txnreplay.webservice
  
  oracle.txnreplay.common
  
  Figure 5 Adjust Log Levels in Log Configuration page
4. When you are done, click Apply.

2.1 Configure Public Key Encryption for ADF Mobile Transaction Replay Service

The ADF Mobile transaction replay service establishes a mobile user's credential for authentication during replaying a replay item. The credential consists of a username and a password. The ADF Mobile transaction replay service relies on Public Key Encryption to secure passwords sent from a mobile device.

The ADF Mobile transaction replay service is packaged with a test keystore and a test certificate. A keystore is a database of keys. By default, the ADF Mobile transaction replay service uses the test certificate for public key encryption with a warning message Test certificate is used for public key encryption. This test certificate is provided for ease of set up in the application development stage

2.1.1 Configuring Key Password and Keystore Password

The ADF Mobile transaction replay service requires access to the keystore and the private key of the certificate. You must contact your administrator to create a keystore. The administrator can use the keytool utility that is distributed with the JDK to create and manage the keys and certificates in the Java keystore. For more information about Java keystore, see Java documentation.

Access to the keystore and the private key must be protected by passwords. You must configure the passwords in the credential store framework.

To configure passwords in the credential store

Open Enterprise Manager. Navigate to the following URL and log in using the administrator username and password:

http://<server_name:port>/em
In the left panel of Enterprise Manager console, choose Farm_your_domain > WebLogic Domain > your_domain.
On the right panel, click WebLogic Domain to open the dropdown list. From the Security submenu, choose Credentials.
In the Credentials page, click Create Map. You must create a key map before you create a security key.

Enter a unique name for the key map in the Create Map popup window, and click OK.

Select the key map, and click Create Key.

In the Create Key popup window, enter the values in the fields, as described in Table 3.

Table 2 Key Attributes

Field	Action
Select Map	Select the key map name you created in Step 4.
Key	Enter `KeyStorePass` as the key name.
Type	Select `Password` as the key type.
User Name	Enter the value set in the MBean attribute `KeystorePassCSFKey` from TxnReplayerSettings as described in Figure 6. The default value is `KeyStorePass`.
Password	Enter a password of the keystore.
Description	Enter a description for the key, if desired.

Click OK.
Follow the process described in step 5 and create another key.
1. Set the value of field Key to KeyPass. For the field User Name, enter the value set in the MBean attribute KeyPassCSFKey from TxnReplayerSettings as described in Figure 6. The default value is KeyPass.
2. In the Password field, enter the password for the private key.
3. Click OK.
The above configuration in Credentials page would look similar to Figure 6.

Figure 6 Credentials page in Enterprise Manager console

2.1.2 Configuring Access to Credential Store Framework

For ADF Mobile transaction replay service to read the passwords from the credential store, you must grant permissions to txnreplayer and webservice components to read the trs credential store map. You configure the grants in the domain policy store.

To configure access to credential store framework:

Open the domain policy store file. The file is saved as system-jazn-data.xml in the <DOMAIN_HOME>\config\fmwconfig directory.

For example, if your Middleware Home directory is D:\JDevMobile and your domain name is mtrs_domain, then the domain policy store file is available in D:\JDevMobile\user_projects\domains\mtrs_domain\config\fmwconfig.

Verify the permissions set for txnreplayer and webservice components. The following code shows txnreplayer and webservice settings required to access credential store framework:

<grant>
  <grantee>
    <codesource>
      <url>
  file:${domain.home}/servers/${weblogic.Name}/tmp/_WL_user/txnreplayer/-
      </url>
    </codesource>
  </grantee>
  <permissions>
    <permission>
      <class>
        oracle.security.jps.service.credstore.CredentialAccessPermission
      </class>
      <name>
        context=SYSTEM,mapName=trs,keyName=*
      </name>
      <actions>read</actions>
    </permission>
  </permissions>
</grant>
<grant>
  <grantee>
    <codesource>
      <url>
file:${domain.home}/servers/${weblogic.Name}/tmp/_WL_user/webservice/-
      </url>
    </codesource>
  </grantee>
  <permissions>
    <permission>
      <class>
        oracle.security.jps.service.credstore.CredentialAccessPermission
      </class>
      <name>
        context=SYSTEM,mapName=trs,keyName=*
      </name>
      <actions>read</actions>
    </permission>
  </permissions>
</grant>

2.1.3 Configuring Keystore URL, Keystore Type and Certificate Alias

As an administrator, you should configure keystore URL, keystore type and certificate alias to use the proper certificate.

To configure keystore URL, keystore type, and certificate alias:

Open Enterprise Manager. Navigate to the following URL and log in using the administrator username and password:

http://<server_name:port>/em
In the left panel of Enterprise Manager console, choose Farm_your_domain > WebLogic Domain > your_domain.
On the right panel, click WebLogic Domain, and choose System MBean Browser from the dropdown list.
In the left pane of the System MBean Browser page, select Application Defined MBeans.

Expand Application Defined MBeans and choose oracle.txnreplay > Server:Admin Server >TxnReplayerSettings, as shown in Figure 7.

In the Attributes page of TxnReplayer, update the fields listed in Table 3.

Table 3 TxnReplayer Attributes

Field Value

Field	Value
CertificateAlias	Enter the certificate alias of the key pairs. The certificate alias is a simple name that is defined in the Java keystore file. For example, `testTxn` is a valid alias name.
KeyStoreType	JKS
KeyStoreURL	Enter the URL of keystore file. You can use the KeyStoreURL field to specify the path of the file, if the keystore file exists on the local host machine. For example, `file:///C:/JDevMobile/user_projects/test.jks`.

CertificateAlias

Enter the certificate alias of the key pairs. The certificate alias is a simple name that is defined in the Java keystore file.

For example, testTxn is a valid alias name.

KeyStoreType

JKS

KeyStoreURL

Enter the URL of keystore file.

You can use the KeyStoreURL field to specify the path of the file, if the keystore file exists on the local host machine. For example, file:///C:/JDevMobile/user_projects/test.jks.

Figure 7 TxnReplayer Attributes page

Click Apply.
Again, in the left pane of the System MBean Browser page, select Application Defined MBeans.
Expand Application Defined MBeans and choose oracle.txnreplay > Server:Admin Server > WebServiceSettings.
In the WebService attributes page, add values for CertificateAlias, KeyStoreType, and KeyStoreURL, as described in step 5.
Click Apply when you are done.

3 Configuring ADF Mobile Transaction Replay Service in JDeveloper

You use JDeveloper to integrate the ADF Mobile transaction replay service component with the base ADF Fusion web application, and configure the ADF Mobile client application to use TRS.

3.1 Integrate ADF Mobile Transaction Replay Service with ADF Fusion Web Application

You can integrate ADF Mobile transaction replay service with your ADF Fusion web application to allow the transaction replay service replay entity object events to the base application.

In JDeveloper, select your ViewController project in Application Navigator, right-click and choose Project Properties.
In the Project Properties dialog, select Technology Scope to view the list of available technologies.
Select the ADF Mobile Transaction Replay project technology from the Available list, and add it to the Selected list, as shown in Figure 8.

Figure 8 Project Properties dialog
Click OK to close the Project Properties dialog.
In your Fusion web application, find and configure the target application module for the mobile replay.
1. Select the target application module in Application Navigator, right-click and choose Configurations.
2. In the Manage Configurations dialog, click New to create a local application module configuration, if one does not already exist.
  
  In the Edit Business Components Configuration dialog, ensure that the data source name matches the JNDI name after deployment. For example, use jdbc/FODDS instead of java:comp/env/jdbc/FODDS, as shown in Figure 9.
Figure 9 Edit Business Components Configuration dialog
Redeploy the application.

3.2 Creating Transaction Replay Type

You use the Enable TRS for ADF Mobile Client Application wizard to configure the ADF Mobile client application to enable the use of ADF Mobile transaction replay service. Before you proceed, ensure that the ADF Mobile application has entity object definitions from an ADF library file.

In JDeveloper, select the Model project of your ADF Mobile application. Right-click and choose Project Properties.
In the Project Properties dialog, select ADF Mobile Client.
In the ADF Mobile Client page, click Configure Transaction Replay Service link to open the Enable TRS for ADF Mobile Client Application wizard.
In the TRS Schema page of the wizard, specify the IDE connection. If not created, click the Add icon to create a new database connection.

Click Next to continue.
In the Replay Type page of the wizard, enter the replay type information, or accept the default values.
- Type Name: Enter a unique name for the replay type.
- Application Module Name: Enter the name of the application module of the base Fusion web application. Ensure that it matches the package name of the Application Module in the base Fusion web application library.
- Application Module Configuration Name: Enter the configuration name of the base Fusion web application module.
- Type Properties: Enter additional properties for the replay type using name-value pairs. This will contain the ReplayServletURL—the URL to the replay servlet set up by adding the ADF Mobile Transaction Replay technology to the base application.
- Password Type: Select the password type from the dropdown list.
- Credential Store Map Name: If you choose Oracle Credential Store Framework as the password type, enter the name of the map.
Click Next to continue.
In the Entity Objects page of the wizard, select the entity objects designated for transaction replay service. Note that in most circumstances, you would be using TRS for all entity objects.

Click Next to continue.
In the Summary page of the wizard, review the information, and click Finish to close the wizard.
Click OK to close the Project Properties dialog.

For more information about enabling transaction replay service, see the "Enabling MTRS for an ADF Application" section in the Oracle Fusion Middleware Mobile Client Developer's Guide for Oracle Application Development Framework.

4 Uninstalling ADF Mobile Transaction Replay Service

Uninstall the ADF Mobile transaction replay service to remove its components from the Oracle WebLogic Server.

To uninstall the ADF Mobile Transaction Replay Service Component:

Open Oracle WebLogic Server Administration Console.
In the Deployments page, select the following checkboxes:
- dispatcher
- txnreplayer
- webservice
Figure 10 shows the Deployments page with the dispatcher service. Note that the above services might not be available in the same page of Oracle WebLogic Server Administration Console. In such a case, select each file individually and repeat step 3 for each of the above services.

Figure 10 Uninstall ADF Mobile Transaction Replay Service Components
Click Delete to remove the ADF Mobile transaction replay service files.
When you are done, log out from Oracle WebLogic Server Administration Console.

5 Documentation Accessibility

Our goal is to make Oracle products, services, and supporting documentation accessible to all users, including users that are disabled. To that end, our documentation includes features that make information available to users of assistive technology. This documentation is available in HTML format, and contains markup to facilitate access by the disabled community. Accessibility standards will continue to evolve over time, and Oracle is actively engaged with other market-leading technology vendors to address technical obstacles so that our documentation can be accessible to all of our customers. For more information, visit the Oracle Accessibility Program Web site at http://www.oracle.com/accessibility/.

Accessibility of Code Examples in Documentation

Screen readers may not always correctly read the code examples in this document. The conventions for writing code require that closing braces should appear on an otherwise empty line; however, some screen readers may not always read a line of text that consists solely of a bracket or brace.

Accessibility of Links to External Web Sites in Documentation

This documentation may contain links to Web sites of other companies or organizations that Oracle does not own or control. Oracle neither evaluates nor makes any representations regarding the accessibility of these Web sites.

Access to Oracle Support

Oracle customers have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/support/contact.html or visit http://www.oracle.com/accessibility/support.html if you are hearing impaired.

Oracle Fusion Middleware Installation Guide for ADF Mobile Transaction Replay Service, 11g Release 1 (11.1.1.5.0)

E15492-02

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this software or related documentation is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065.

This software is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications which may create a risk of personal injury. If you use this software in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure the safe use of this software. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software in dangerous applications.

Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.

This software and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.