ADF Faces RC: Generic Query and ListOfValues Model for EJBs

Overview

The <af:query> and <af:inputListOfValues> components of ADF Faces RC are a must-have for applications, but if you are not using ADF Business Components, then you face the challenge of implementing your own query and listOfValues models. This pattern provides an implemented reusable model that you can readily adapt to your enterprise needs when you are using EJBs.

Problem Description

The query and listOfValues models are fairly complex. To build a query model alone, you need to extend and implement at least six abstract classes as depicted in the diagram below:

Figure 1: Query Model Class Diagram

Plus some additional classes to build the listOfValues model as depicted below:

Figure 2: ListOfValues Model Class Diagram

If you try to look into how these were implemented for ADF BC, you could easily get lost in the details, especially that our focus is to build business applications and not UI components, on the other hand, if you look into the DemoQueryModel and DemoListOfValuesModel implemented in the adffacesdemo, then those implementations were suggesting "I'm stiff and useless, don't dare create something like me.". I am telling this because I have been into these hardships.

Technical Pattern Description

Let us get back to the basic requirement and the existing set of capabilities of the technologies that we use. The basic requirement is to provide the end-user a component where he can set criteria based on existing attributes and execute query to get a filtered result.
The following are the existing capabilities:

• EJB's JPQL supports dynamic queries so we can create a session bean method that accepts a JPQL statement, as in the case of "queryByRange()", and create EJB DataControls out of them.
• We can drag the data control on the page to create tables. In the process, a tree binding is created in the page definition file. In this tree binding, we can access the relevant attributes and accessors of the information that we are interested in. On the same tree binding, we can get the resulting class, and the corresponding CollectionModel.
• By implementing some sort of dummy Map interface, we can allow passing of parameters through EL.
• When we declare our model as managed beans, we can inject managed properties. Through managed properties, we can pass the the unique list of saved search per query and the object that will handle persistence.

From the requirement and capabilities described above, I came up with a solution that is simple to use, reusable, and manageable from the complexity perspective. This solution has one basic requirement - a valid treeBinding defined in the pageDefinition file that is based on a method that accepts a "jpqlStmt" parameter. The solution hits three birds in one shot, because it supports the QueryModel, the ListOfValuesModel, and a Dynamic Converter to convert the string input into appropriate entity objects.

The User Experience

The saved searches that are injected on the managed beans will be displayed on the saved search list:

Figure 3: List page showing a query defined from managed bean

If no saved search is injected, the system will generate one, named "System Generated", setting the first attribute defined in the pageDefinition file as a search field.

Figure 4: Job list page showing a query with a system generated saved search.

Users will be able to use the accessor attributes as part of the search criteria. The displayed label supports internationalization.

Figure 5: Add Fields menu showing list of attributes including those of the accessors. 

Search is NOT case-sensitive.

Figure 6: Case In-sensitive search.

Aside from the primary components, the query panel can have selectComboBox, selectOneChoice, and inputListOfValues components as well (inputComboBoxListOfValues can be easily supported too).

Figure 7: A launched job.Job Id inputListOfValues  from the query panel.

Displayed below are three inputListOfValues component based on the same ListOfValuesModel class but different treeBindings.

Figure 8: Job, department, and manager LOVs based on the same model class.

Below is a launched Job Search. Selections made here are ensured to be easily converted to objects by using the dynamic converter.

Figure 9: A launched Job Search having the default system generated criterion

Artifacts

The QueryLOV class alone contains more than a thousand lines of code, so I leave the sample application which do have comments to speak of its own. Instead, in this section, I will show the artifacts in using the solution:

• The employeeQuery managed bean declaration in the employee-list-task-flow:
  

  

  Figure 10: The employeeQuery managed bean definition in employee-list-task-flow.

  
  The employeeQuery has a defined "systemSavedSearchDefList" managed property which is a list. Inside this list is a value that points to another managed bean named "savedSearch1". Inside "savedSearch1" is a list with a value referencing to managed bean "searchField1". These managed properties are optional. If you did not specify a managed saved search list property, the QueryLOV will generate a default.
  
  The "supplementaryMap" property is a map with an entry that points to the jobLOV managed bean. This property supplements the model that made possible the presence of the Job inputListOfValue component on the query panel of the employee search.
  
  
• Below is the source of the query component as used in the employee_list.jsff search page:

  <af:query headerText="Search" disclosed="true" id="q1"
      model="#{pageFlowScope.employeeQuery.param['bindings.Employee'].queryModel}"
      value="#{pageFlowScope.employeeQuery.param['bindings.Employee'].currentDescriptor}"
      resultComponentId="::pc1:t1"
      queryListener="#{pageFlowScope.employeeQuery.processQuery}"/>
  

  The 'bindings.Employee' is the name of the tree binding in the page definition file that is based on a methodAction "findEmployeesByCriteria" that accepts a "jpqlStmt" parameter.
  
  
• Below is the source of the Job Search LOV in employee_details.jsff form page.

  <af:inputListOfValues label="Job"
      popupTitle="Search and Result Dialog" id="ilov2" searchDesc="Job Search"
      model="#{pageFlowScope.jobLOV.param['bindings.Job'].listOfValuesModel}"
      value="#{bindings.findEmployeeByIdIterator.currentRow.dataProvider.job}"
      converter="#{pageFlowScope.jobLOV.param['bindings.Job'].convert['jobId']}"
      autoSubmit="true" readOnly="#{!pageFlowScope.editMode}"/>
  

  The same as the 'bindings.Employee' above, the 'bindings.Job is the name of the tree binding in the page definition file that is based on a methodAction "findJobsByCriteria" that accepts a "jpqlStmt" parameter.
  The string 'jobId' is passed as parameter in .convert['jobId'] so that the dynamic converter will know how to transform our strings into Job objects.
  It is also important that you override the toString() method of your entities to return the id (jobId in the case of Job)representation of your object.

Pattern Implementation

To implement this Reusable Query and ListOfValues Model into your existing application, do the following steps:

1. Download the accompanying sample application.
2. Inside your existing application, open the EJBQueryLOV project by invoking "Open Project" menu and navigating to the directory of the sample application.
3. Open project properties of your ViewController project and add a dependency on the EJBQueryLOV build output.
4. The EJBQueryLOV projects has some dependency on the utility classes in the Utils project in the sample application. You could add the JSFUtils.jar inside the deploy folder into your classpath.

Prototype

You can download the sample application with the reusable query and listOfValues model project from here.

Known Issues

Sometimes, invoking the "Search" button on the Query component do not raise the necessary lifecycle process that will trigger the result component to refresh. In this case, the "Search" button needs to be invoked again.

When you drag a data control with a resulting entity that do have a recursive relation to itself - like in the case of Employee with attribute manager, in which manager is also an employee, for some reasons, JDeveloper do not create a separate node binding for the manager inside the tree binding in the pageDefinition file. In this case, you need to manually add the necessary node definition to support the query by manager attributes and to comply with underlying assumption of the QueryLOV that the sequence of the defined accessors in the primary node definition of the tree binding is laid out on the same sequence in the subsequent nodes.
To illustrate the case please see the default generated code VS. the necessary modified version of the tree binding
Generated Default:

    <tree IterBinding="findEmployeesByCriteriaIterator" id="Employee">
      <nodeDefinition DefName="src.model.Employee" Name="Employee0">
        <AttrNames>
          <Item Value="employeeId"/>
          <Item Value="firstName"/>
          <Item Value="lastName"/>
          <Item Value="email"/>
          <Item Value="commissionPct"/>
          <Item Value="hireDate"/>
          <Item Value="phoneNumber"/>
          <Item Value="salary"/>
        </AttrNames>
        <Accessors>
          <Item Value="department"/>
          <Item Value="manager"/>
          <Item Value="job"/>
        </Accessors>
      </nodeDefinition>
      <nodeDefinition DefName="src.model.Department" Name="Employee1">
        <AttrNames>
          <Item Value="departmentId"/>
          <Item Value="departmentName"/>
          <Item Value="locationId"/>
        </AttrNames>
      </nodeDefinition>
      <nodeDefinition DefName="src.model.Job" Name="Employee2">
        <AttrNames>
          <Item Value="jobId"/>
          <Item Value="jobTitle"/>
          <Item Value="maxSalary"/>
          <Item Value="minSalary"/>
        </AttrNames>
      </nodeDefinition>
    </tree>

The necessary modified version to comply with the QueryLOV assumption:

    <tree IterBinding="findEmployeesByCriteriaIterator" id="Employee">
      <nodeDefinition DefName="src.model.Employee" Name="Employee0">
        <AttrNames>
          <Item Value="employeeId"/>
          <Item Value="firstName"/>
          <Item Value="lastName"/>
          <Item Value="email"/>
          <Item Value="commissionPct"/>
          <Item Value="hireDate"/>
          <Item Value="phoneNumber"/>
          <Item Value="salary"/>
        </AttrNames>
        <Accessors>
          <Item Value="department"/>
          <Item Value="manager"/>
          <Item Value="job"/>
        </Accessors>
      </nodeDefinition>
      <nodeDefinition DefName="src.model.Department" Name="department">
        <AttrNames>
          <Item Value="departmentId"/>
          <Item Value="departmentName"/>
          <Item Value="locationId"/>
        </AttrNames>
      </nodeDefinition>
       <nodeDefinition DefName="src.model.Employee" Name="manager">
        <AttrNames>
          <Item Value="employeeId"/>
          <Item Value="firstName"/>
          <Item Value="lastName"/>
          <Item Value="email"/>
          <Item Value="commissionPct"/>
          <Item Value="hireDate"/>
          <Item Value="phoneNumber"/>
          <Item Value="salary"/>
        </AttrNames>
      </nodeDefinition>
      <nodeDefinition DefName="src.model.Job" Name="job">
        <AttrNames>
          <Item Value="jobId"/>
          <Item Value="jobTitle"/>
          <Item Value="maxSalary"/>
          <Item Value="minSalary"/>
        </AttrNames>
      </nodeDefinition>
    </tree>

Note that the node names are not necessary but the sequence. The sequence of the node definition after the primary should be the same as the sequence of the defined accessors (department, manager, then job).

Related Patterns

The sample application is based on the ADF UI Shell Functional Pattern.

Authors Notes

I would to recognize other people who also have contributed on the evolution of this solution, specifically, Java Powers of http://javainthedesert.blogspot.com/.