10.5 Application Module Databinding Tips and Techniques

10.5.1 How to Create a Record Status Display

When building pages you'll often want to display some kind of record status indicator like: "Record 5 of 25". If you display multiple rows on a page, then you may also want to display a variant like "Record 5-10 of 25". You can build a record indicator like this using simple text components, each of which displays an appropriate value from an iterator binding or table binding using an EL expression. The iterator binding's rangeSize property defines how many rows per page it makes available to display in the user interface. If your page definition contains either an iterator binding named SomeViewIter or a table binding named SomeView, you can reference the following EL expressions:

• Number of Rows per Page

  #{bindings.SomeViewIter.rangeSize}

  #{bindings.SomeView.rangeSize}

• Total Rows

  #{bindings.SomeViewIter.estimatedRowCount}

  #{bindings.SomeView.estimatedRowCount}

• First Row on the Current Page

  #{bindings.SomeViewIter.rangeStart + 1}

  #{bindings.SomeView.rangeStart + 1}

• Last Row on the Current Page

  #{bindings.SomeViewIter.rangeStart + bindings.SomeViewIter.rangeSize}

  #{bindings.SomeView.rangeStart + bindings.SomeView.rangeSize}

• Current Row Number

  #{bindings.SomeViewIter.rangeStart + bindings.SomeViewIter.currentRowIndexInRange + 1}

  #{bindings.SomeView.currentRowIndex + 1}

10.5.2 How to Work with Named View Object Bind Variables

When a view object has named bind variables, an additional ExecuteWithParams operation appears in the corresponding data collection's Operations folder. As shown in Figure 10-9, this built-in operation accepts one parameter corresponding to each named bind variable. For example, the StaffListByEmailNameRole view object in the figure has four named bind variables — EmailAddress, Role, TheFirstName, and TheLastName — so the parameters appear for the ExecuteWithParams action having these same names. At runtime, when the ExecuteWithParams built-in operation is invoked by name by the data binding layer, each named bind variable value is set to the respective parameter value passed by the binding layer, and then the view object's query is executed to refresh its row set of results.

Figure 10-9 Work with Named Bind Variables Using Either a Built-in or Custom Operation

An alternative approach, also shown in Figure 10-9, involves creating a custom view object "finder" method that accepts the arguments you want to allow the user to set and then including this method on the client interface of the view object in the View Object Editor. Example 10-1 shows what the code for such a custom method would look like. It is taken from the StaffListByEmailNameRole view object in the SRDemo application. Notice that due to the application module's active data model, the method does not need to return the data to the client. The method has a void return type, sets the bind variable values to the parameter values passed into the method using the generated bind variable accessor methods setEmailAddress(), setRole(), setTheFirstName(), and setTheLastName(). Then, it calls executeQuery() to execute the query to refresh the view object's row set of results.

// From SRDemo Sample's StaffListByEmailNameRoleImpl.java
public void findStaffByEmailNameRole(String email,
                                     String firstName,
                                     String lastName,
                                     String role) 
{
  setEmailAddress(email);
  setRole(role);
  setTheFirstName(firstName);
  setTheLastName(lastName);
  executeQuery();
}

Both of these approaches accomplish the same end result. Both can be used with equal ease from the Data Control Palette to create a search form. The key differences between the approaches are the following:

Using the built-in ExecuteWithParams operation

• You don't need to write code since it's a built-in feature.

• You can drop the operation from the Data Control Palette to create an ADF Search Form to allow users to search the view object on the named bind variable values.

• Your search fields corresponding to the named bind variables inherit bind variables UI control hints for their label text that you can define as part of the view object component.

Using the custom View Object "finder" operation

• You need to write a little custom code, but you see a top-level operation in the Data Control Palette whose name can help clarify the intent of the find operation.

• You can drop the custom operation from the Data Control Palette to create an ADF Search Form to allow users to search the view object on the parameter values.

• Your search fields corresponding to the method arguments do not inherit label text UI control hints you define on the view object's named bind variables themselves. Instead, you need to define UI control hints for their label text by using the Properties... choice from the context menu of the page definition variable corresponding to the method argument as shown in Figure 10-10.

Figure 10-10 Accessing Properties of Page Definition Variables to Set UI Control Hints

In short, it's good to be aware of both approaches and you can decide for yourself which approach you prefer. As described in Section 10.6.5, "The SRStaffSearch Page", while the StaffListByEmailNameRole view object contains the above findStaffByEmailNameRole() custom method for educational purposes, the demo's JSF page uses the declarative ExecuteWithParams built-in action.

10.5.3 How to Use Find Mode to Implement Query-by-Example

In the ADF Model layer, an iterator binding supports a feature called "find mode" when working with data collections that support query-by-example. As cited in Section 5.8, "Filtering Results Using Query-By-Example View Criteria", view objects support query-by-example when view criteria row set of view criteria rows has been applied. The view criteria rows have the same structure as the rows in the view object, but the datatype of each attribute is String to allow criteria like "> 304" or "IN (314,326)" to be entered as search criteria.

In support of the find mode feature, an iterator binding has a boolean findMode property that defaults to false. As shown in Figure 10-11, when findMode is false the iterator binding points at the row set containing the rows of data in the data collection. In contrast, when you set findMode to true the iterator binding switches to point at the row set of view criteria rows.

Figure 10-11 When Find Mode is True, Iterator Binding Points at ViewCriteria Row Set Instead

In the binding layer, action bindings that invoke built-in data control operations are associated to an iterator binding in the page definition metadata. This enables the binding layer to apply an operation like Create or Delete, for example, to the correct data collection at runtime. When an operation like Create or Delete is invoked for an iterator binding that has findMode set to false, these operations affect the row set containing the data. In contrast, if the operations are invoked for an iterator binding that has findMode set to true, then they affect the row set containing the view criteria row, effectively creating or deleting a row of query-by-example criteria.

The built-in Find operation allows you to toggle an iterator binding's findMode flag. If an iterator binding's findMode is false, invoking the Find operation for that iterator binding sets the flag to true. The UI components that are bound to attribute bindings related to this iterator switch accordingly to displaying the current view criteria row in the view criteria row set. If the user modifies the values of UI components while their related iterator is in find mode, the values are applied to the view criteria row in the view criteria row set. If you invoke the Execute or ExecuteWithParams built-in operation on an iterator that is in find mode, each will first toggle find mode to false, apply the find mode criteria, and refresh the data collection.

If an iterator binding's findMode is true invoking the Find operation sets it to false and removes the view criteria rows in the view criteria row set. This effectively cancels the query-by-example mode.

10.5.4 How to Customize the ADF Page Lifecycle to Work Programmatically with Bindings

The ADF Controller layer integrates the JSF page lifecycle with the ADF Model data binding layer. You can customize this integration either globally for your entire application, or on a per-page basis. This section highlights some tips related to how the SRDemo application illustrates using both of these techniques.

10.5.4.1 Globally Customizing the ADF Page Lifecycle

To globally customize the ADF Page Lifecycle, do the following:

• Create a class that extends oracle.adf.controller.faces.lifecycle.FacesPageLifecycle

• Create a class that extends ADFPhaseListener and overrides the createPageLifecycle() method to return an instance of your custom page lifecycle class.

• Change your faces-config.xml file to use your subclass of ADFPhaseListener instead of the default ADFPhaseListener. As shown in Figure 10-12, you can do this on the Overview tab of the JDeveloper faces-config.xml editor, in the Life Cycle category.

Note: Make sure to replace the existing ADFPhaseListener with your custom subclass of ADFPhaseListener, or everything in the JSF / ADF lifecycle coordination will happen twice!

Figure 10-12 Setting Up a Custom ADFPhaseListener To Install a Custom Page Lifecycle Globally

The SRDemo application includes a SRDemoPageLifecycle class that globally overrides the reportErrors() method of the page lifecycle to change the default way that exceptions caught and cached by the ADF Model layer are reported to JSF. The changed implementation reduces the exceptions reported to the user to include only the exceptions that they can directly act upon, suppressing additional "wrapping" exceptions that will not make much sense to the end user.

10.5.4.2 Customizing the Page Lifecycle for a Single Page

You can customize the lifecycle of a single page setting the ControllerClass attribute of the pageDefinition to identify a class that either:

• Extends oracle.adf.controller.v2.PageController class

• Implements oracle.adf.controller.v2.PagePhaseListener interface

The value of the page definition's ControllerClass attribute can either be:

• A fully qualified class name

• An EL expression that resolves to a class that meets the requirements above

Using an EL expression for the value of the ControllerClass, it is possible to specify the name of a custom page controller class (or page phase listener implementation) that you've configured as a managed bean in the faces-config.xml file. This includes a backing bean for a JSF page, provided that it either extended PageController or implements PagePhaseListener.

Figure 10-13 illustrates how to select the root node of the page definition in the Structure window to set.

Figure 10-13 Setting the ControllerClass of a Page Definition

Note: When using an EL expression for the value of the ControllerClass attribute, the Structure window may show a warning, saying the "#{YourExpression}" is not a valid class. You can safely ignore this warning.

// In class oracle.srdemo.view.util.OnPageLoadBackingBeanBase
/**
 * Before the ADF page lifecycle's prepareModel phase, invoke a
 * custom onPageLoad() method. Subclasses override the onPageLoad()
 * to do something interesting during this event.
 * @param event
 */
public void beforePhase(PagePhaseEvent event) {
  FacesPageLifecycleContext ctx =
    (FacesPageLifecycleContext)event.getLifecycleContext();
  if (event.getPhaseId() == Lifecycle.PREPARE_MODEL_ID) {
    bc = ctx.getBindingContainer();
    onPageLoad();
    bc = null;
  }
}
/**
 * After the ADF page lifecycle's prepareRender phase, invoke a
 * custom onPagePreRender() method. Subclasses override the onPagePreRender()
 * to do something interesting during this event.
 * @param event
 */    
public void afterPhase(PagePhaseEvent event) {
  FacesPageLifecycleContext ctx =
   (FacesPageLifecycleContext)event.getLifecycleContext();
  if (event.getPhaseId() == Lifecycle.PREPARE_RENDER_ID) {
    bc = ctx.getBindingContainer();
    onPagePreRender();
    bc = null;
  }
}
public void onPageLoad() {
  // Subclasses can override this.
}
public void onPagePreRender() {
  // Subclasses can override this.
}

10.5.5 How to Use Refresh Correctly for InvokeAction and Iterator Bindings

Figure 10-14 illustrates how the JSF page lifecycle relates to the extended page processing phases that the ADF page lifecycle adds. You can use the Refresh property on iterator bindings and invokeAction executables in your page definition to control when each are evaluated during the ADF page lifecycle, either during the prepareModel phase, the prepareRender phase, or both. Since the term "refresh" isn't exactly second-nature, this section clarifies what it means for each kind of executable and how you should set their Refresh property correctly to achieve the behavior you need.

Figure 10-14 How JSF Page Lifecycle and ADF Page Lifecycle Phases Relate

#{adfFacesContext.postback == true}

10.5.6 Understanding the Difference Between setCurrentRowWithKey and setCurrentRowWithKeyValue

You can call the getKey() method on any view row get a Key object that encapsulates the one or more key attributes that identify the row. As you've seen in various examples, you can also use a Key object like this to find a view row in a row set using the findByKey(). At runtime, when either the setCurrentRowWithKey or the setCurrentRowWithKeyValue built-in operations is invoked by name by the data binding layer, the findByKey() method is used to find the row based on the value passed in as a parameter before setting the found row as the current row.

Confusingly, as shown in Figure 10-15, the setCurrentRowWithKey and setCurrentRowWithKeyValue operations both expect a parameter named rowKey, but they differ precisely by what each expects that rowKey parameter value to be at runtime:

setCurrentRowWithKey

setCurrentRowWithKey expects the rowKey parameter value to be the serialized string representation of a view row key. This is a hexadecimal-encoded string that looks like this:

000200000002C20200000002C102000000010000010A5AB7DAD9

The serialized string representation of a key encodes all of the key attributes that might comprise a view row's key in a way that can be conveniently passed as a single value in a browser URL string or form parameter. At runtime, if you inadvertently pass a parameter value that is not a legal serialized string key, you may receive exceptions like oracle.jbo.InvalidParamException or java.io.EOFException as a result. In your web page, you can access the value of the serialized string key of a row by referencing the rowKeyStr property of an ADF control binding (e.g. #{bindings.SomeAttrName.rowKeyStr}) or the row variable of an ADF Faces table (e.g. #{row.rowKeyStr}).

setCurrentRowWithKeyValue

setCurrentRowWithKeyValue expects the rowKey parameter value to be the literal value representing the key of the view row. For example, it's value would be simply "201" to find service request number 201.

Figure 10-15 The setCurrentRowWithKeyValue Operation Expects a Literal Attribute Value as the Key

static public Row getRowFromKey(RowSetIterator rsi, String sKey)

10.5.7 Understanding Bundled Exception Mode

An application module provides a feature called bundled exception mode which allows web applications to easily present a maximal set of failed validation exceptions to the end user, instead of presenting only the first error that gets raised. By default, the ADF Business Components application module pool enables bundled exception mode for web applications.

You typically will not need to change this default setting. However it is important to understand that it is enabled by default since it effects how validation exceptions are thrown. Since the Java language and runtime only support throwing a single exception object, the way that bundled validation exceptions are implemented is by wrapping a set of exceptions as details of a new "parent" exception that contains them. For example, if multiple attributes in a single entity object fail attribute-level validation, then these multiple ValidationException objects will be wrapped in a RowValException. This wrapping exception contains the row key of the row that has failed validation. At transaction commit time, if multiple rows do not successfully pass the validation performed during commit, then all of the RowValException objects will get wrapped in an enclosing TxnValException object.

When writing custom error processing code, as illustrated by the overridden reportErrors() method in the SRDemoPageLifecycle class in the SRDemo application, you can use the getDetails() method of the JboException base exception class to recursively process the bundled exceptions contained inside it.