About Find Mode for JClient Controls

In JClient, you can support parameterized queries by using the JUNavigationBar control in a JClient data panel with the Find mode enabled. Find mode lets users use the data panel to enter search criteria through supported JClient control bindings.

The easiest way to create the data panel for Find mode operations is to bind a JUNavigationBar to the Business Components view object that you want the data panel to search on. The navigation bar provides a Find button that the user selects to toggle the behavior of the JClient control bindings for the JClient form:

When Find mode is enabled on the data panel, the controls provide search criteria for a parameterized query on the queryable attributes of the Business Components view object
When Find mode is disabled, the controls provide data access to display and edit attributes of the view object

The state of the Find-mode button is controlled by the hasFindButton property on the JUNavigationBar (true by default).

About the Iterator Binding in Find Mode

In addition to its basic data iteration functionality, the iterator binding also cooperates with the bound data collection to simplify implementing query-by-example capability for your application data by providing:

A collection of query-by-example criteria rows, and
An easy-to-use Find mode to work with these query criteria

In Oracle ADF, each data collection has an associated view criteria (ViewCriteria) collection of zero or more view criteria rows. Each view criteria row (ViewCriteriaRow) has the same attribute structure as a row in its related data collection, except that the attribute values are all treated as a String data type. This data type allows the user to enter query criteria containing comparison operators and wildcard characters.

For example, to indicate you want to find all departments whose department number is greater than 5 and whose department name matches the string 'ACC%', you would fill in the attributes of a view criteria row related to a DeptView collection (based on a query over the familiar DEPT table in the SCOTT schema) like this:

Deptno > 5
Dname ACC%

The iterator binding's Find mode makes it easy to create search pages that populate the attributes of the view criteria collection for query-by-example functionality. When an iterator binding is set to work in Find mode, it switches to use a different row set iterator over the related view criteria collection instead. This means that when Find mode is enabled, control bindings that reference the iterator binding will display and update attributes in the current view criteria row. Likewise, a range binding that references an iterator binding in Find mode allows you to render a table of current query-by-example view criteria rows.

When Find mode is disabled, the iterator binding switches back to work with its row set iterator over the data collection. This can be done explicitly by calling the iterator binding's setFindMode() method, or implicitly by calling its executeQuery() method.

Note: By calling the createRow() method on the iterator binding's row set iterator while in Find mode, it is possible to create additional view criteria rows and then proceed to populate their attributes with additional criteria. The default semantics are that query-by-example criteria in the same view criteria rows are logically AND-ed together, while criteria resulting from separate view criteria rows are logically OR-ed together. In actual practice using multiple view criteria rows is not a common use case, but knowing it is possible helps to explain functionality. However, after the user enters Find mode, it is no longer possible to create the row on the original collection. Only when the user exits Find mode will it be possible to create a row that does not participate in the view criteria.

While the ADF iterator binding provides its Find mode functionality independent of the kind of backend data control you choose, currently only the ADF Business Components data control makes automatic use of the view criteria collection of view criteria rows at runtime. It delegates the iterator binding's view criteria functionality to the underlying ADF view object, which implements the query-by-example criteria by automatically building appropriate SQL WHERE clause predicates based on the view criteria rows.

Other data control types would currently require a subclassed data control implementaiton containing some custom coding to read the query-by-example criteria from the view criteria collection and translate them into an appropriate runtime search implementation.

About Parameterized Queries

A parameterized query is a query that contains a placeholder that must be supplied at runtime. For example, in the following PL/SQL statement, min_salary is a placeholder for a parameter value that will be supplied at runtime.

SELECT ename, job, mgr FROM emp WHERE sal < :min_salary

The data panel in Find mode uses the JClient control bindings to display fields for each attribute in the bound Business Components view object whose Queriable property is set to true . The view object defines the initial query executed by the business components.

JClient Controls That Can Participate in the Search

Not all of the JClient control bindings support the Find mode. If you want to create a data panel specifically for searches, limit your form to use these controls bound to Business Components view object attributes to provide search criteria:

JTextField, the user must enter a value
JCheckBox, the user selects one of the predefined values
JSlider, the user selects one of the predefined values

It is recommended that your data panel disable controls not in the above list when the user selects the Find mode. Disabling controls that do not support Find mode prevents the user from attempting to submit invalid search criteria.

Additionally, starting in JDeveloper 10g, UI components that utilize an ADF list binding in navigation mode do not participate in the Find mode. However, if you drop a navigation-mode component, such as the databound ComboBox or JList, into a panel and activate Find mode, the component will not be disabled and will still permit the user to unintentionally display data in components that should appear empty in Find mode. To disable the interaction of the navigation component and the other components in Find mode, you can create a secondary iterator and edit the navigation-mode component's data binding to use that iterator:

In the UIModel tab of the Structure window, right-click the UIModel node and choose Create Binding - Data - Iterator.
In the iterator binding editor, select the collection that your other components are bound to and supply a new name for the Iterator Id.
In the UIModel tab, double-click the binding for the component that operates in navigation mode and select the new iterator in the data binding editor.

When you run the panel, notice that the navigation-mode component no longer forces the search criteria components to update in Find mode. They will remain empty in order to permit the user to entry search criteria.

Here is a typical usage for a data panel with Find mode:

The user places the panel in Find mode.

For instance, a user may click the Find button, which is provided by default with a JUNavigationBar (that is bound to a Business Components view object).
The user enters find criteria to restrict the results of the data already returned to the form
The Find mode performs an anchored, wild card search.

It uses the first character of the search column as an anchor, where all the strings that begin with the entered string are matched.
Another control that you bind to the same view object in JClient, such as the JTable control, displays the results of the parameterized query.

For details about the usage of view criteria in Business Components, see the JavaDoc for this class:

oracle.jbo.ViewCriteria