5 Developing the ADF Mobile Client Data Model

5.1.1 Support for the Core ADF Business Components

As the mobile implementation of the Oracle ADF architecture, ADF Mobile client utilizes the core ADF Business Components but with some modifications:

• entity object

  An entity object represents a row in a database table. It simplifies modifying the row's data by handling all data manipulation language (DML) operations for you. An entity object encapsulates business logic for the row to ensure your business rules are consistently enforced. You associate an entity object with others to reflect relationships in the underlying database schema to create a layer of business domain objects to reuse in multiple applications. Association objects define relationships between entity objects.

• view object

  View objects provide the means to retrieve data from a data source. In most cases, the data source will be a database and the mechanism to retrieve data is the SQL query. The view object simplifies working with the results of the SQL query. A data model project can include the following types of view objects:

  • Read-only view objects when updates to data are not necessary (may be entity-based)

  • Entity-based view objects when data updates will be performed

  ADF Mobile client applications generally use entity-based view objects. These rows are not populated until run time.

• application module

  An application module is the transactional component that UI clients use to work with application data. It defines an updatable data model and top-level procedures and functions (called service methods) related to a logical unit of work related to an end-user task. Unlike ADF Faces applications, ADF Mobile client supports only a single, globally accessible application module. For more information, see "Getting Started with ADF Business Components" in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

  Because the application module component supports a "UI- aware" data model of row sets, you do not need to write additional code for typical Create, Update, and Delete operations. By declaratively binding such client UI components to active view object instances in the application module's data model, the components in an MCX page automatically update to reflect changes in the rows of the view object row sets of the data model. For more information, see "Overview of the UI-Aware Data Model" in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

5.1.2 Support for Mobile Database Transactions

The ADF Mobile client framework does the following after the user saves changes made to the data using an ADF Mobile client application:

1. DBTransaction.commit() is invoked, which in turn generates appropriate DML statements for all changes to the data model.

2. As each statement is posted to the database, an event is fired, which in turn generates an XML record—an entity Replay Item—which encapsulates the details of the INSERT, UPDATE, or DELETE statement.

3. After the transaction is committed, another event is fired, which causes the previously generated XML records to be written to the database in a separate transaction.

4. At some later point, data synchronization is initiated, either on-demand or in the background, and Oracle Database Lite Mobile Server (Mobile Server) transfers the Replay Item(s) up to the Mobile Server instance.

5. If data satisfies all necessary criteria, then it is committed to the enterprise database. Otherwise, an error is recorded in Mobile Server and then delivered to the mobile client the next time synchronization occurs.

5.2.1 How to Create Subsets of Entity Objects and View Objects

The Create Business Components from ADF Library wizard provides a multi-step approach to adding business components to the ADF Mobile client application. First, you point to the ADF library JAR file that was previously exported from the base ADF application. The ADF library JAR enables you to reuse the ADF Business Components defined in the base application. Next, you select the entity objects and entity attributes that are required for the mobile client application. Lastly, you create updatable view objects based on the previously selected entity objects and add them to a new application module.

Before you begin:

As described in Section 4.4.1, "How to Create an Application Workspace," you must have an ADF library JAR of the model project containing the entity objects and view objects on which you base the ADF Mobile client application. For information on creating an ADF library JAR, see "Packaging a Reusable ADF Component into an ADF Library" in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

To create subsets of entity objects:

1. In the Application Navigator, right-click the model project you created in Section 4.4.1, "How to Create an Application Workspace," and choose New.

2. In the New Gallery, expand Business Tier, select ADF Mobile Client Business Components and then Business Components from ADF Library. Click OK.

   If this is the first component that you are creating in the project, the Initialize Business Components Project dialog appears to allow you to select a database connection to the server (base) application. You use this application to develop the business components for an ADF Mobile client application.

   Note:

   ADF Mobile client only supports SQL92 as the SQL flavor for the database connection.

   Figure 5-1 Selecting the Business Components from ADF Library Wizard

   
   

3. In the Initialize Business Components Project dialog, select the database connection or choose New to create a connection. Click OK.

   Note:

   You must use the same connection used by the base (server) application. Do not use the connection to the Oracle database schema where Mobile Server artifacts are stored.

4. After JDeveloper establishes the connection, Business Components from ADF Library wizard appears. In the Select Entities page, enter the location (or browse for) the ADF library JAR created from the base application, and click Open.

   Note:

   Because the location of the ADF Library JAR used to create an ADF Mobile client application is hard-coded in the model project, you must update the JAR's location for the NMCBaseLibraryFilePath property in Model.jpx if you move the mobile application to another computer or change or delete the JAR. The application will not run unless you change this value.

   For example, Figure 5-2 shows the result of shuttling the ProductBaseEO, OrderEO, and ProductBaseEO entity objects into the Selected list from the Available list, which includes all of the entity objects.

5. Shuttle the entity objects that you want to base the mobile entity objects on to the Selected list. Click Next.

   Figure 5-2 Selecting Entity Objects for the Mobile Client Application

   
   

6. In the Select Entity Attributes page, select the attributes that you want to include from each entity usage in the Selected list. Shuttle the ones that you do not want to the Available list. Click Next.

   Note:

   The attributes that appear by default in the Available window are calculated fields that do not have a mapping in the database table definition. You cannot move any attribute that is a primary key from the Selected list.

   For example, Figure 5-3 shows the attributes have been selected from the ProductBaseEO entity object.

   Figure 5-3 Selecting Attributes for the Entity Objects of the Mobile Client Application

   
   

7. In the Updatable View Objects page, select the entity objects to create a default view object. Click Next.

   For example, Figure 5-4 shows that OrderEO and OrderItemEO have been selected to create the view objects OrderEOView and OrderItemEOView.

   Figure 5-4 Selecting View Objects

   
   

8. In the Application Module page, select Application Module and then enter a name for the application module. For more information on application modules, see "Getting Started with ADF Business Components" in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework. Click Next.

9. In the Summary page, click Finish.

5.2.2 What Happens When You Create a Subset of Entity Objects and View Objects

When you create a subset of the entity objects and view objects, JDeveloper creates the new application module, along with the entity objects, view objects, associations, and view links. It lists them in the Application Navigator.

For example, Figure 5-5 illustrates the model project and its contents in the Application Navigator.

Figure 5-5 Model Project in the Application Navigator

5.3.1 About Using the Overview Editors for Mobile Objects

The overview editors for entity objects, view objects, and application modules include only the features that pertain to ADF Mobile client. Table 5-1 lists the editor features that are not present for ADF Mobile client development.

5.3.2 About Editing Entity Objects

Because the mobile client application synchronizes with its server-side counterpart, this editor allows you to create transient attributes. You cannot create persistent attributes because a mobile client application synchronizes data as exposed through its entity objects against server-side data, which is exposed on an attribute-by-attribute basis, through server-side entity objects backed by a database table. If you create an entity object attribute that only exists in a mobile application, then this attribute cannot be synchronized against a server-side counterpart because one does not exist. You can create transient attributes using this editor, because by definition, a transient attribute does not persist and thus is not synchronized against server-side data.

Figure 5-6 The Overview Editor for an Entity Object

5.3.3 How to Add Attributes to an Entity Object

You use the entity editor to modify the attributes belonging to a mobile entity object, or to add transient attributes to one. Because the mobile application must synchronize with the base application, you cannot change certain properties for an attribute. Otherwise, synchronization fails.

Use the Attributes page of the overview editor to create an attribute.

Before you begin:

Create a subset of entity objects for the ADF Mobile client application as described in Section 5.2.1, "How to Create Subsets of Entity Objects and View Objects."

To add attributes:

1. Double-click an entity object in the Application Navigator.

   Note:

   The Name and Extends properties are read-only values.

2. Click the Attributes tab.

3. In the Attributes page, click Add from Base Entity. In the Create New Entity Attributes for Columns dialog, shown in Figure 5-7, the attributes that you did not select for the entity object using the Model Wizard appear in the Available list.

   Figure 5-7 Selecting Attributes

   
   

4. Select the attributes by moving them from the Available window to the Selected window.

5. Click OK. The selected attributes display in the table.

   Note:

   You cannot use this editor to correct or update persistent attributes. If an attribute has been designed improperly, you can only correct it in the server-side application. You cannot edit the persistent attributes because they must match the attributes of the server object. For example, changing an attribute type from a date to a number causes synchronization to fail.

5.3.4 How to Add Transient Attributes

Use the Attributes page of the overview editor to create a transient attribute.

Before you begin:

Create a subset of entity objects for the ADF Mobile client application as described in Section 5.2.1, "How to Create Subsets of Entity Objects and View Objects."

To Add transient attributes:

1. Click Add in the Attributes page.

   Note:

   ADF Mobile client supports only transient attributes based on literal values.

2. In the New Entity Attribute dialog, define the properties for the transient attribute (listed in Table 5-2).

   Table 5-2 Attribute Properties

   Property	Description
   Name	The name of the attribute. This must be a valid Java identifier.
   Type	Choose the Java type for the attribute
   Property Set	Choose the type of element that this attribute represents. This field is not available for all attribute types.
   Value Type	Select Literal to use a literal value for the default
   Value	For discriminator columns in subtypes of polymorphic entity objects, enter the discriminator value for the subtype. ADF Mobile client does not support expressions.
   Mandatory	Select if this attribute is mandatory. This option is selected by default if the corresponding database column has a NOT NULL constraint.
   Derived from SQL Expression	ADF Mobile client does not support this option. Do not use it.
   Discriminator	ADF Mobile client does not support this option. Do not use it.
   Updatable	The view attribute setting is based on the entity attribute setting and can made more restrictive. Always Select to make an attribute updatable. While New Select to make an attribute updatable before an entity is first posted. Never Select to make an attribute read-only.

   
   

3. Click OK. The attribute appears in the table.

5.3.5 Adding Validation Rules

The Validators page of the overview editor enables you add the built-in Oracle ADF declarative validation rules described in "Defining Validation and Business Rules Declaratively" in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework. When you create a validation rule using the overview editor, they are stored in the entity object's XML file.

Figure 5-8 shows the Validators page for the entity object, OrderEO.

Figure 5-8 The Validators Page

ADF Mobile client supports the following validators, which are available from the Rule Type list of the Add Validation Rule dialog, which you invoke by first selecting an entity or attribute and then by clicking Add.

Figure 5-9 shows the Add Rule Validation dialog.

Figure 5-9 The Add Validation Rule Dialog

Table 5-3 lists the validators and the classes that they support.

For more information, see "Using the Built-In Declarative Validation Rules" and "Implementing Validation and Business Rules Programmatically" in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

5.3.6 Overriding Default Validation Error Handling

When a validation error occurs, a message box showing error messages appears by default. You can override the default behavior if you prefer the validation error message as an outputText component rather than as a message box.

Example 5-1 and Example 5-2 are two versions of the same application, CustomErrorHandler.java. Example 5-1, describes how to use a message box for the validation error message (similar to the default behavior) and how the main error handling method, reportException, handles the error messages in this context. Example 5-2 describes how to put the validating error messages into an outputText component by overriding the reportException method.

package view.backing;
 
import oracle.adfnmc.bindings.BindingContainer;
import oracle.adfnmc.bindings.dbf.BindingContext;
import oracle.adfnmc.component.ErrorHandler;
import oracle.adfnmc.component.MessageBox;
import oracle.adfnmc.component.ui.Form;
import oracle.adfnmc.java.util.List;
 
 
public class CustomErrorHandler
  implements ErrorHandler
{
  public CustomErrorHandler()
  {
  }
 
  public boolean reportException(Form form, BindingContainer formBnd, Exception ex)
  {
    // do error handling here
    List errors = null;
    if (formBnd != null)
    {
      errors = formBnd.getErrors();
    }
 
    if ((errors != null) && (errors.size() > 0))
    {
      String[] messages = new String[errors.size()];
      for (int i = 0; i < errors.size(); ++i)
      {
        Exception exListElement = (Exception) errors.get(i);
        messages[i] = this.getDisplayMessage(BindingContext.getInstance(), exListElement);
      }
      MessageBox.show(messages);
    }
    else
    {
      String message = this.getDisplayMessage(BindingContext.getInstance(), ex);
      MessageBox.show(message);
    }
 
    // return true so that the form knows the error has been handled
    return true;
  }
 
  public String getDisplayMessage(BindingContext ctx, Exception ex)
  {
    if (ex != null)
    {
      return ex.getMessage();
    }
    else
    {
      return "";
    }
  }
}

package view.backing;
 
import oracle.adfnmc.bindings.BindingContainer;
import oracle.adfnmc.bindings.dbf.BindingContext;
import oracle.adfnmc.component.ErrorHandler;
import oracle.adfnmc.component.ui.Form;
import oracle.adfnmc.el.ValueExpression;
import oracle.adfnmc.el.impl.SimpleContext;
import oracle.adfnmc.java.util.List;
 
 
public class CustomErrorHandler
 
  implements ErrorHandler
{
  public CustomErrorHandler()
  {
  }
 
  public boolean reportException(Form form, BindingContainer formBnd, Exception ex)
  {
    // do error handling here
    List errors = null;
    if (formBnd != null)
    {
      errors = formBnd.getErrors();
    }
 
    String message = "";
    if ((errors != null) && (errors.size() > 0))
    {
      for (int i = 0; i < errors.size(); ++i)
      {
        Exception exListElement = (Exception) errors.get(i);
        message += this.getDisplayMessage(BindingContext.getInstance(), exListElement) + "\n";
      }
    }
    else
    {
      message = this.getDisplayMessage(BindingContext.getInstance(), ex);
 
    }
 
    ValueExpression valueExpression =
      SimpleContext.getValueExpression("#{applicationScope.validationMessage}", String.class);
    valueExpression.setValue(message);
 
    // return true so that the form knows the error has been handled
    return true;
  }
 
  public String getDisplayMessage(BindingContext ctx, Exception ex)
  {
    if (ex != null)
    {
      return ex.getMessage();
    }
    else
    {
      return "";
    }
  }
}

5.3.7 About Synchronization for Entity Objects

Data synchronization is not enabled be default for entity objects. Only the entity objects that are imported from a known schema context can be enabled for synchronization.

You can enable or disable synchronization for each entity object using the Synchronization page of the overview editor for entity objects, shown in Figure 5-10. This page enables you to do the following:

• Set data updates—You can set how the entity objects receive updates from the server and also how the entity objects can update the server. The downstream updates (from the server to the client) are accomplished through Oracle Database Lite Mobile Server (Mobile Server). To perform upstream updates, an entity object must be enabled for ADF Mobile transaction replay service.

• Set conflict resolution rules—You can also use this page to set the rules for resolving data conflicts between the client and server, as conflicts can arise if a mobile client updates a stale record while the original record may have been changed on the server.

• Create a data set appropriate for a small database—You can refine the entity object's SQL statement by adding WHERE and ORDER BY clauses to the JDeveloper-generated SELECT statement based on the selected entity attributes.

Figure 5-10 Setting the Synchronization for an Entity Object

5.3.8 View Accessor Support for Entity Objects and View Objects

View accessors are value-accessor objects in ADF Business Components. You create a view accessor to point from a base entity object attribute or view object attribute to a source view row set. The view accessor returns a list of all possible values to the attribute of the base object.

View Accessors are set in the View Accessors page of the Overview Editor for entity objects and view objects, shown in Figure 5-11. For more information, refer to "How to Create a View Accessor for an Entity Object or View Object" in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

Figure 5-11 The Overview Editor for View Accessor Page

5.3.9 Using List UI Hints for View Objects

You can associate a control hint with the current entity attribute. View objects will inherit the hint values at runtime. For more information, see "Defining Attribute Control Hints for Entity Objects" in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

Because any attribute-specific information that is added to the base application is available to the ADF Mobile application after you complete the Create Mobile Business Components from ADF Library wizard, you must re-import objects from the base application if attribute-specific changes have been made to it. Otherwise, control hints are not available to the ADF Mobile client application.

5.3.10 Using Display Hints for Entity Objects

You can specify default LOV (list of values) hints when you want the LOV-enabled attributes of other view objects to inherit the list UI hints from the current view object. To define LOV-enabled attributes, you must create a view accessor that points to the view object that supplies the values. At design time, the LOV-enabled attributes whose view accessor points to this source view object will inherit any list UI hints you have defined. At runtime, the UI will display the same LOV usage for these LOV-enabled attributes. For more information, see "Working with List of Values (LOV) in View Object Attributes" in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework

For example, Figure 5-12 shows the List UI Hints page of the Overview Editor for AddressEOView, a view object.

Figure 5-12 The Overview Editor for List UI Hints

5.3.11 Adding Bind Variables to View Objects

The Query page of the overview editor for a view object (illustrated in Figure 5-13 and described in "Working with Bind Variables" in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework) enables you to add bind variables to a query. Although ADF Mobile client supports JDBC Positional, Oracle Named, and Oracle Positional binding styles, Oracle Named is the preferred binding style and is the only one supported in the overview editor for mobile client view objects.

Figure 5-13 The Query Page of the Overview Editor for View Objects

You edit the binding using the Bind Variable dialog, shown in Figure 5-14. For more information on Oracle Named binding style, see the online help available from JDeveloper.

Figure 5-14 The Bind Variable Dialog

5.3.12 Working with Resource Bundles

ADF Mobile client provides design-time localization support by enabling the use of the standard localization structures of ADF to specify resource strings in multiple languages. As with standard ADF applications, you can configure an ADF Mobile client application to store translatable strings such as control hints in a resource bundle as described in "Working with Resource Bundles" in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework. As shown in Figure 5-15, in addition to the default .properties bundle file, ADF Mobile also supports the XLFF (XML Localization Interchange File Format) properties bundles used for exchanging localization data. ADF Mobile client supports multiple resource bundles. For more information, see Section 7.4.2, "Supporting Localization through XLFF Resource Bundles."

Figure 5-15 Selecting Resource Bundle Type for an ADF Mobile Client Project

5.4.1 Supported Constructs

The following JDeveloper-generated Java classes are supported by the runtime:

• entity object

• view object

• view row

• application module

The following are not used by the runtime, but can safely be generated and used at design time.

• view row client Interface

• view row client

The following are explicitly not supported:

• entity collection

• entity definition

• view object definition

• application module definition

5.4.2 Unsupported Methods

Even though the classes listed in Section 5.4.1, "Supported Constructs" are supported by the runtime, ADF Mobile client does not support every method in those classes. Do not override or otherwise call the following methods:

entity object (oracle.jbo.server.EntityImpl)

• doDMLWithLOBs(int operation, TransactionEvent e)

• handleEffectiveDateOperations()

• validateDateEffectivity()

• removeAndRetain()

view object (oracle.jbo.server.ViewObjectImpl)

• addEffectiveDateDstAttributes()

• buildEffectiveDateFromClauseFragment(StringBuffer fromClause, int noUserParams)

• sortRows(Row[] rows)

• activateNewRowTracker(ViewRowSetImpl vrs, KXmlParser parent)

• validateRangeSizeForRangePaging(ViewRowSetImpl vrs, int rangeSize)

• activateState(ViewRowSetImpl vrs, ViewRowImpl currentRow, KXmlParser parent)

view row (oracle.jbo.server.ViewRowImpl)

application module (oracle.jbo.server.ApplicationModuleImpl)

• activateState(int id, SessionData info, int flags)

• passivateStateForUndo(String id, byte[] clientData, int flags)

• getAMSerializer()

5.6.1 Differences Between SQLite and Other Relational Databases

SQLite is designed for use as an embedded database system, one typically used by a single user and often linked directly into the application. Enterprise databases, on the other hand, are designed for high concurrency in a distributed client-server environment. Because of these differences, there are a number of limitations that may be foreign to developers accustomed to working with Oracle databases. The most important differences are:

• Concurrency

• SQL Support

• Data Types

• Foreign Keys

• Database Transactions

5.7.1 How to Test Against a SQLite Database

Use JDeveloper's Database Navigator to create a database connection to the SQLite database. Use the SQL Worksheet to test SQL statements and the update SQLite database schema.

Before you begin:

Download Oracle JDeveloper and the ADF Mobile client extension as described in Section 2.3, "Setting Up JDeveloper."

Download the SQLiteJDBC driver from http://www.zentus.com/sqlitejdbc/. This driver is contained in a JAR file called sqlitejdbc-v0xx.jar. Save this file to an easily accessed location.

To register the Zentus SQLite JDBC driver and test against the SQLite database:

1. In JDeveloper, create a new database connection. You can create this connection in the application or in the IDE shows how a finished connection may look. The name and password fields are dummy values.

2. In the Database Navigator, select File > New > Connections and then Database Connections.

3. Select Generic JDBC from the Connection drop-down menu.

4. Click New.

5. Enter org.sqlite.JDBC as the Driver Class in the Register JDBC Driver dialog, as shown in Figure 5-16.

   Figure 5-16 Registering the Zentus SQLite JDBC Driver

   
   

6. Click Browse, click New, and then click Add Entry.

7. Select the sqlitejdbc-v0xx.jar on your file system. Click OK.

8. Click OK until you return to the Create Database Connection page.

9. In the JDBC URL window, enter

   jdbc:sqlite:<Path to your SQLite data file> as shown in Figure 5-17.

   For example, enter jdbc:sqlite:C:\Documents and Settings\<your name>\Desktop\sqlite-3_6_22\MOBILEFOD.db, where MOBILEFOD.db is the SQLite file containing the data.

   Figure 5-17 The Create Database Connection Dialog

   
   

10. Enter dummy values in the name and password fields.

11. Click Test Connection. A Success! message appears if the connection is configured correctly.

12. In the Database Navigator, right-click the connection and select SQL Worksheet, from the context menu. The SQL Worksheet enables you to test SQL statements and also review, modify, and export the SQLite database.

5.8.1 How to Add the ADF Mobile Transaction Replay Service Technology to an ADF Application

You can add the ADF Mobile transaction replay service technology to a new or existing ADF project. You can enable transaction replay service for any application that has the web.xml deployment descriptor file.

Before you begin:

You must have an ADF application model project containing the entity objects and view objects on which you base the ADF Mobile client application.

To add the ADF Mobile transaction replay service technology:

1. Select the a project in the Application Navigator, then select Edit and then Properties.

2. In the Technology Scope page, select ADF Mobile Transaction Replay from the Available window and move it to the Selected window as shown in Figure 5-18. Click OK.

   Figure 5-18 Adding the ADF Mobile Transaction Replay Service Technology

   
   

3. Deploy the application as an ADF JAR as described in "Packaging a Reusable ADF Component into an ADF Library" in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

5.8.2 What Happens When You Add the ADF Mobile Transaction Replay Service Technology to an Application

When you add the ADF Mobile transaction replay service technology to an application, JDeveloper adds the transaction replay service servlet JAR, ReplayServlet, and updates web.xml with transaction replay service configuration parameters as shown in Example 5-4.

<servlet-name>ReplayServlet</servlet-name>
    <servlet-class>oracle.txnreplay.adfadapter.ReplayServlet</servlet-class>
  </servlet>
  <servlet-mapping>
    <servlet-name>Faces Servlet</servlet-name>
    <url-pattern>/faces/*</url-pattern>
  </servlet-mapping>
  <servlet-mapping>
    <servlet-name>ReplayServlet</servlet-name>
    <url-pattern>/replayservlet</url-pattern>
  </servlet-mapping>

In addition, JDeveloper updates the web.xml file's <filter-mapping> element for ReplayServlet, as shown in Example 5-5.

<filter-mapping>
    <filter-name>adfBindings</filter-name>
    <servlet-name>ReplayServlet</servlet-name>
    <dispatcher>FORWARD</dispatcher>
    <dispatcher>REQUEST</dispatcher>
  </filter-mapping>
  <filter-mapping>
    <filter-name>JpsFilter</filter-name>
    <servlet-name>ReplayServlet</servlet-name>
    <dispatcher>FORWARD</dispatcher>
    <dispatcher>REQUEST</dispatcher>
    <dispatcher>INCLUDE</dispatcher>
  </filter-mapping>

5.8.3 What Happens When JDeveloper Creates an ADF Mobile Transaction Replay Service-Enabled Application

If a project already is already configured with the ADF Faces technology, then you can enable the transaction replay service Object Replay mechanism in the application.

5.8.4 How to Create a Transaction Replay Type

The TRS Enablement Wizard configures the ADF Mobile client application, project, and entity objects to enable the use of transaction replay service. The wizard verifies that the ADF Mobile application has entity object definitions from an ADF library file. When you create the entities for an ADF Mobile client application using the Create Business Components from ADF Library wizard as described in Section 5.2.1, "How to Create Subsets of Entity Objects and View Objects," the entity objects imported by this wizard are enabled for synchronization because they have been given create, update, and delete actions. For applications that have not been created using this wizard, you can enable transaction replay service for the entity objects using the TRS Enablement Wizard.

Before you begin:

Only applications whose Model projects contain the ADF Mobile Client Model technology can be enabled for transaction replay service; this technology enables the transaction replay service logging mechanism for the application. You can verify if an application includes this technology by opening the Project Properties dialog for a Model project and then selecting ADF Mobile Client. As shown in Figure 5-19, JDeveloper notes that the project lacks the ADF Mobile Client Model technology required for transaction replay service.

Figure 5-19 ADF Mobile Client Project Properties

When you create the entities for an ADF Mobile client application using the Create Business Components from ADF Library wizard as described in Section 5.2.1, "How to Create Subsets of Entity Objects and View Objects," the entity objects imported by this wizard are enabled for synchronization because they have been given CREATE, UPDATE, and DELETE actions.

You should have a connection that has a transaction replay service schema deployed to it. If such a connection does not exist, then the wizard prompts you to create one.

To add the transaction replay service to an ADF Mobile client application:

1. In the Application Navigator, right-click the Model project.

2. In Project Properties, choose ADF Mobile Client.

3. Click Configure Transaction Replay Service and then click OK.

   As shown in Figure 5-20, if Configure Transaction Replay Service displays, then the entity objects are not transaction replay service-enabled.

   Figure 5-20 ADF Mobile Client Project Properties

   
   

4. In the TRS Schema page, shown in Figure 5-21, select an IDE connection or an application connection. The transaction replay service schema must already be deployed to this connection.

   Figure 5-21 Selecting the ADF Mobile Transaction Replay Service Schema Connection

   
   

   If the schema is not in the selected connection, you must create a new connection. Click Next. The wizard proceeds after it verifies that the selected connection contains the transaction replay service schema.

5. In the Replay Type page, shown in Figure 5-22, enter the replay type information. The wizard defines the replay type by reviewing the imported entity object data from the base (server) application and then populates the Type Name field with a suggested name. You can override this value with any name as long as it is unique in the REPLAY_TYPE table in the transaction replay service schema. The page also enables you to designate how transaction replay service manages passwords.

   Figure 5-22 The Replay Type Page

   
   

   Table 5-4 describes the properties of the Replay Type page.

   Table 5-4 Defining the Reply Type

   Property	Description
   Type Name	If needed, enter a name for the replay type or accept the name populated by the wizard.
   Application Module Name	Enter the application module of the base (server) application. Open the base server application's model project and locate the application module. Include the application module package and application module name. For example, if the package is model and the name is AppModule, enter model.AppModule. You can find these properties on the General page of the overview editor for the application module.
   Application Module Configuration Name	Enter the configuration name of the base (server) application module. You can select the application module configuration name using the Manage Configurations dialog. To access this dialog: Open the base (server) application in JDeveloper. In the Application Navigator, right-click the application module. Choose Configurations from the context menu. Choose the configuration from the Names column. Enter this configuration name in the Application Module Configuration Name field.
   Type Properties	This field contains a group of name-value pairs that you can configure for a replay type. This field has the format of name1=value1;name2=value2;name3=value3. The ADF Entity Event type has the following two properties: Name: server.win Values: true (the default) or false (optional) Name: ReplayServletURL Value: The URL to the replay servlet set up by adding the ADF Mobile Transaction Replay technology as described in Section 5.8.1, "How to Add the ADF Mobile Transaction Replay Service Technology to an ADF Application." This is a required value. Example: server.win=false;ReplayServletURL=http://test.example.com:7001/CCare-ViewController-context-root/replayservlet
   Password Type	Select from among the following password types: Public Key Encryption (PKE) Credential Store Framework (CSF). A credential store is a repository for user name-password or generic credentials. When a credential store is used, an application does not store its passwords in clear text or invent solutions for protecting passwords. The Credential Store Framework (CSF) used by Oracle Platform Security Services (OPSS) is a set of APIs that enable secure Create, Read, Write, and Update operations. For more information, see "Configuring the Credential Store" in Oracle Fusion Middleware Security Guide. If you select this option, then you must also enter the name of the CSF map for the credentials. No Password Type—Select this option if neither PKE nor CSF apply. Use this option for testing only. Do not select this option for a live deployment.
   Credential Store Map Name	If you select Credential Store Framework as the means by which transaction replay service retrieves the password, then you must enter the name of the map for the credentials.

   
   

   Note:

   Although you can change the name of the replay type, you cannot rename the underlying application references that are needed to successfully replay events from the client to the server.

6. Click Next.

   Figure 5-23 Selecting ADF Mobile Transaction Replay Service Entity Objects

   
   

   The Entity objects page displays all of the entity objects defined in the ADF Mobile client Model project. As illustrated in Figure 5-23, all entity objects are selected by default. Transaction replay service events (INSERT, UPDATE, and DELETE) are enabled for each selected entity object. Select the entity objects designated for transaction replay service by moving the entity objects from the Selected window to the Available window. Click Next.

   Note:

   You can enable or disable transaction replay service for entity objects using the overview editor for entity objects. For more information see Section 5.3.7, "About Synchronization for Entity Objects."

7. Review the information displayed on the Summary page. To make changes to the replay type, click Back. Otherwise, click Finish.

5.8.5 What Happens When JDeveloper Creates a Transaction Replay Type

When you complete the wizard, the ADF Mobile Client page is updated with the information configured for the transaction replay type. Figure 5-24 shows this page. By clicking Reconfigure TRS Connection, you can access the TRS Enablement Wizard starting at the TRS schema page. You can update the transaction replay type's current connection to the ADF Mobile transaction replay service schema, or select a new one. In addition, you can edit the replay type properties and entity objects using the wizard's pages.

Figure 5-24 ADF Mobile Client Page (After Creation of a Replay Type)

In addition, JDeveloper updates adf-config.xml, writes the TRS replay type for the identified server application to the REPLAY_TYPE table in the transaction replay service Schema, and sets appropriate application, project, and entity object properties to reflect that transaction replay service has been enabled. As shown in Figure 5-25, JDeveloper also creates a transaction replay service data control named ADFmcTransactionReplayDataControl. JDeveloper overwrites this data control each time you complete the wizard.

Figure 5-25 The Transaction Replay Service Data Control

You can use this data control to create a view for reviewing Replay Items. Creating such a view enables you to review any conflicts that occurred during a prior synchronization with the server.

You do not need to use the transaction replay service data control to log the standard Replay Items that are generated from the ADF business components used by the mobile client entity objects if you enabled transaction replay service for the entity objects as described in Section 5.3.7.1, "How to Enable or Disable Synchronization for Entity Objects." The ADF Mobile client framework handles this logging automatically for the transaction replay service-enabled entity objects. If you create a mobile application that uses transaction replay service to invoke some business logic outside of ADF Business Components, then you can use the transaction replay service data control to manually log those Replay Items.

5.9.1 What You May Need to Know About the AuthenticationManager Class

Example 5-6 illustrates a mobile client login page containing components that use EL expressions. For more information, see Section 5.9.2.1, "Using EL Expressions for Authentication."

<?xml version='1.0' encoding='windows-1252'?>
<amc:view xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:amc="http://xmlns.oracle.com/jdev/amc">
    <amc:form id="form1">
    <amc:menuControl refId="altMain" />
            <amc:panelGroupLayout id="home" layout="vertical">
            <amc:panelGroupLayout layout="vertical">
                <amc:inputText id="txtUserName" label="User Name: "                  value="#{securityContext.userName}" />
                <amc:inputText id="txtPassword" label="Password: "                     value="#{securityContext.password}" secret="true" />
            </amc:panelGroupLayout>
            <amc:panelGroupLayout layout="horizontal">
            <amc:commandButton disabled="#{securityContext.loggingIn}"                 actionListener="#{LoginBean.onLogin}" text="Login" />
            <amc:commandButton disabled="#{!securityContext.loggingIn}"                 actionListener="#{LoginBean.onCancel}" text="Cancel" />
             </amc:panelGroupLayout>
                <amc:outputText id="lblStatus" value="Status:                    #{securityContext.statusMessage}" rendered="#{securityContext.loggingIn}" />
                <amc:outputText id="lblError" value="#{securityContext.errorMessage}"                    rendered="#{securityContext.hasError}" foregroundColor="#FF0000" />
            </amc:panelGroupLayout>
         </amc:form>
         <amc:menu id="altMain" type="alt" platform="wm">
        <amc:menuGroup id="menuGroup1" index="200">        
                  <amc:commandMenuItem label="Exit" index="0" action="appExit"/>
        </amc:menuGroup>
         </amc:menu>
</amc:view>

Example 5-7 illustrates a backing bean called LoginBean that uses the AuthenticationManager class.

package view.backing;
 
import oracle.adfnmc.el.util.BeanResolver;
import oracle.adfnmc.model.security.AuthenticationManager;
import oracle.adfnmc.model.security.CredentialsCache;
import oracle.adfnmc.util.Utility;
 
 
public class LoginBean
  extends BeanResolver
{
  private static final String HOME_ACTION = "toHome"; // defined in the task flow definition files, typically task-flow-definition.xml
 
  private AuthenticationManager m_mgr;
 
  public LoginBean()
  {
  }
 
  private synchronized AuthenticationManager getAuthenticationManager()
  {
    if (m_mgr == null)
    {
      m_mgr = new AuthenticationManager();
      m_mgr.setNavigationAction(HOME_ACTION);
      m_mgr.setWebServiceUrl("<enter value here>");
    }
    return m_mgr;
  }
 
  private void onLogin()
  {
    AuthenticationManager mgr = getAuthenticationManager();
 
    String replayTypeName = "<enter value here>";
    mgr.authenticate(replayTypeName);
  }
 
  private void onCancel()
  {
    AuthenticationManager mgr = getAuthenticationManager();
    mgr.cancel();
  }
 
  public Object invokeMethod(String methodName, Object[] params)
  {
    if (methodName.equals("onLogin"))
    {
      this.onLogin();
    }
    else if (methodName.equals("onCancel"))
    {
      this.onCancel();
    }
 
    return null;
  }
}

As illustrated in Example 5-7, the authenticate method of the AuthenticationManger class is called and returns immediately after a user clicks a login button. The bean's onLogin and onCancel methods are hooked to the action listeners (such as actionListener="#{LoginBean.onLogin}" text="Login" and actionListener="#{LoginBean.onCancel}" text="Cancel" in Example 5-8). The AuthenticationManager class spawns a background authentication thread that checks if the user has the permission to update a transaction replay service replay type. If authentication succeeds, it calls a NavigationAction, which is set in the mobile client task flow. In this example, the NavigationAction leads to the home page.

public void response(int value, Exception e);

/**
             * This denotes a successful login
             */
            public static final int AUTH_SUCCESS = 0;
 
            /**
             * This denotes a general failure
             */
            public static final int AUTH_FAILURE = 1;
 
            /**
             * This denotes a failure due to invalid credentials
             */
            public static final int AUTH_FAILURE_CREDENTIALS = 2;
 
            /**
             * This denotes a failure due to the device being offline with no    stored credentials
             */
            public static final int AUTH_FAILURE_OFFLINE = 3;
 
            /**
             * This denotes a failure resolving the URL
             */
            public static final int AUTH_FAILURE_INVALID_URL = 4;

5.9.2 What You May Need to Know About SecurityContext EL Expressions

Write to the expressions listed in Table 5-7 and read from the expressions listed in Table 5-8.

Table 5-8 lists the EL expressions that are read from.

<amc:commandButton disabled="#{securityContext.loggingIn}" actionListener="#{LoginBean.onLogin.execute}" text="Login" />
<amc:commandButton disabled="#{!securityContext.loggingIn}" actionListener="#{LoginBean.onCancel.execute}" text="Cancel" />

<amc:outputText id="lblStatus" value="Status: #{securityContext.statusMessage}" rendered="#{securityContext.loggingIn}" />

<amc:outputText id="lblError" value="#{securityContext.errorMessage}" rendered="#{securityContext.hasError}" foregroundColor="#FF0000" />

<amc:outputText id="lblError" value="#{securityContext.errorMessage}" rendered="#{securityContext.hasError}" foregroundColor="#FF0000" />

1: <?xml version='1.0' encoding='windows-1252'?>
2:   <amc:view>
3:      <amc:form xmlns:amc="http://xmlns.oracle.com/jdev/amc">
4:      <amc:menuControl refId="altMain" />
5:      <amc:panelGroupLayout id="home" layout="vertical">
6:      <amc:panelGroupLayout layout="vertical">
7:         <amc:inputText id="txtUserName" label="User Name: " value="#{securityContext.userName}" />
8:         <amc:inputText id="txtPassword" label="Password: " value="#{securityContext.password}" secret="true" />
9:      </amc:panelGroupLayout>
10:      <amc:panelGroupLayout layout="horizontal">
11:      <amc:commandButton disabled="#{securityContext.loggingIn}"             actionListener="#{LoginBean.onLogin}" text="Login" />
12:      <amc:commandButton disabled="#{!securityContext.loggingIn}"            actionListener="#{LoginBean.onCancel}" text="Cancel" />
13:      </amc:panelGroupLayout>
14:      <amc:outputText id="lblStatus" value="Status: #{securityContext.statusMessage}"           rendered="#{securityContext.loggingIn}" />
15:      <amc:outputText id="lblError" value="#{securityContext.errorMessage}"       rendered="#{securityContext.hasError}" foregroundColor="#FF0000" />
16:      </amc:panelGroupLayout>
17:      </amc:form>
18:      <amc:menu id="altMain" type="alt" platform="wm">
19:      <amc:menuGroup index="200">
20:      <amc:commandMenuItem label="Exit" index="0" action="appExit"/>
21:      </amc:menuGroup>
22:      </amc:menu>
23:   </amc:view>