Using the InputComboboxListOfValues Component

12 Using Query Components 12-1 12 Using Query Components This chapter describes how to use the query and quickQuery search panel components. This chapter includes the following sections: ■ Section 12.1, Introduction to Query Components ■ Section 12.2, Implementing the Model for Your Query ■ Section 12.3, Using the quickQuery Component ■ Section 12.4, Using the query Component

12.1 Introduction to Query Components

The query and quickQuery components are used to search through data sets. The query component provides a comprehensive set of search criteria and controls, while the quickQuery component can be used for searching on a single criterion. The query component supports the following functionality: ■ Selecting and searching against multiple search criteria ■ Dynamically adding and deleting criteria items ■ Selecting search operators associated to a single criterion ■ Choosing match all or match any conjunction ■ Displaying in a basic, advanced, compact, simple, or design mode ■ Creating saved searches ■ Personalizing saved searches By default, the advanced mode of the query component allows the user to add and delete criteria items to the currently displayed search. However you can implement your own QueryModel class that can hide certain features in basic mode and expose them only in advanced mode. For example, you might display operators only in advanced mode or display more criteria in advanced mode than in basic mode. Typically, the results of the query are displayed in a table or tree table, which is identified using the resultComponentId attribute of the query component. However, you can display the results in any other output components as well. The component configured to display the results is automatically rerendered when a search is performed. Figure 12–1 shows an advanced mode query component with three search criteria. 12-2 Web User Interface Developers Guide for Oracle Application Development Framework Figure 12–1 Query Component with Three Search Criteria You can create seeded searches, that is, searches whose criteria are already determined and from which the user can choose, or you can allow the user to add criterion and then save those searches. For example, Figure 12–1 shows a seeded search for an employee. The user can enter values for the criteria on which the search will execute. The user can also choose the operands greater than, equals, less than and the conjunction matches all or matches any, which creates either an and or or query. The user can click the Add Fields dropdown list to add one or more criteria and then save that search. If the application is configured to use persistence, then those search criteria, along with the chosen operands and conjunctions, can be saved and reaccessed using a given search name for more information about persistence, see Chapter 31, Allowing User Customization on JSF Pages . The quickQuery component is a simplified version of the query component. The user can perform a search on any one of the searchable attributes by selecting it from a dropdown list. Figure 12–2 shows a quickQuery component in horizontal layout. Figure 12–2 A QuickQuery Component in Horizontal Layout Both the query and quickQuery components use the QueryModel class to define and execute searches. Create the associated QueryModel classes for each specific search you want users to be able to execute. The QueryModel class manages QueryDescriptor objects, which define a set of search criteria. The QueryModel class is responsible for creating, deleting, and updating QueryDescriptor objects. The QueryModel class also retrieves saved searches, both those that are seeded and those that the user personalizes. For more information, refer to the ADF Faces Javadoc. You must create a QueryDescriptor class for each set of search criteria items. The QueryDescriptor class is responsible for accessing the criteria and conjunction needed to build each seeded search. It is also responsible for dynamically adding, deleting, or adding and deleting criteria in response to end-users actions. The QueryDescriptor class also provides various UI hints such as mode, auto-execute, and so on. For more information, refer to the ADF Faces Javadoc. One QueryModel class can manage multiple QueryDescriptor objects. When a user creates a new saved search, a new QueryDescriptor object is created for that saved search. The user can perform various operations on the saved search, such as deleting, selecting, resetting, and updating. When a search is executed or Tip: Instead of having to build your own QueryModel implementation, you can use ADF Business Components, which provide the needed functionality. For more information, see the Creating ADF Databound Search Forms chapter of the Oracle Fusion Middleware Fusion Developers Guide for Oracle Application Development Framework. Using Query Components 12-3 changed, in addition to calling the appropriate QueryModel method to return the correct QueryDescriptor object, a QueryOperationEvent event is broadcast during the Apply Request Values phase. This event is consumed by the QueryOperationListener handlers during the Invoke Application phase of the JSF lifecycle. The QueryOperationEvent event takes the QueryDescriptor object as an argument and passes it to the listener. ADF Faces provides a default implementation of the listener. For details of what the listener does, see Table 12–2 . For example, updating a saved search would be accomplished by calling the QueryModel’s update method. A QueryOperationEvent event is queued, and then consumed by the QueryOperationListener handler, which performs processing to change the model information related to the update operation. The query operation actions that generate a QueryOperationEvent event are: ■ Saving a search ■ Deleting a saved search ■ Toggling between the basic and advanced mode ■ Resetting a saved search ■ Selecting a different saved search ■ Updating a saved search ■ Updating the value of a criterion that has dependent criteria The hasDependentCriterion method of the AttributeCriterion class can be called to check to see whether a criterion has dependents. By default, the method returns false, but it returns true if the criterion has dependent criteria. When that criterion’s value has changed, a QueryOperationEvent is queued for the Update Model Values JSF lifecycle phase. The model will need a listener to update the values of the dependent criterion based on the value entered in its root criteria.

12.2 Implementing the Model for Your Query

Before you can use the query components, you must to create your QueryModel classes. Figure 12–3 shows the class diagram for a QueryModel class. Tip: You can use the quickQuery component without implementing a QueryModel class. However, you will have to add some additional logic to a managed bean. For more information, see Section 12.3.2, How to Use a quickQuery Component Without a Model. 12-4 Web User Interface Developers Guide for Oracle Application Development Framework Figure 12–3 Class Diagram for QueryModel To create the model classes: 1. Create implementations of each of the interface classes shown in Figure 12–3 . Implement one QueryModel class and then a QueryDescriptor class with appropriate criteria operators and values for each system-seeded search. For example implementations of the different model classes for a query, see the classes located in the oracle.adfdemo.view.query.rich package of the ADF Faces sample application.

2. Create a QueryListener handler method on a managed bean that listens for the

QueryEvent event this will be referenced by a button on the query component. This listener will invoke the proper APIs in the QueryModel to execute the query. Example 12–1 shows the listener method of a basic QueryListener implementation that constructs a String representation of the search criteria. This String is then displayed as the search result. Note: If your query uses composition for example, ConjunctionCriterion 1...n with AttributeCriterionConjunctionCriterion, this relationship is not enforced by the abstract interfaces. Your implementation must decide whether to use composition over association, and determine how the lifecyle of these objects are managed.