DOWNLOAD
 Oracle JDeveloper
   TAGS
adf, java, All
product logo Taking an Oracle ADF Application from Design to Reality

By Chris Muir ACE Director and Penny Cookson ACE

Chapter 2 - The "Must-Have" Requirements: A Basic Search Application

Published May 2009

 Click here to see "Taking an Oracle ADF Application from Design to Reality" description and Table of Contents

In this chapter we will build the MUST-have requirements: initially we only need the search fields and a basic search screen.

Figure1

We start with the ADF Business Components View Object, add bind variables and simple validation to be fired before executing the search.

Once we know our table structures we now know what to start building in our Oracle JDeveloper 11g ADF application. We start with an application based on the "Fusion Web Application Template" that gives us the Model and ViewController projects preconfigured with the Oracle ADF Business Component and Oracle ADF Faces RC libraries necessary.

Figure2

Doc Tip: Don't know how to create an application in Oracle JDeveloper 11g? See Chapter 1 Section 1.3.1, "Creating an Application Workspace", in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework 11g Release 1 for instructions.

Creating View Objects

Next with the Model project selected, we run the "Business Components from Tables" wizard to create a read-only View Objects based on the parcels table, and an Application Module to serve the View Object to the ViewController project later.

Figure3

Doc Tip: For more information on creating Business Components from Tables in Oracle JDeveloper 11g, see Chapter 4 of Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework 11g Release 1. For more information on view objects, see Chapter 5.

To ensure that we have everything working OK, we run the Business Component Browser on the AppModule. We can then see the following results from the ParcelsView View Object:

Figure4

One surprise in the View Object is that we seem to have an additional column RowID. Where did that come from? Oracle ADF Business Components View Objects and Entity Objects require at least one attribute to be marked as a primary key to uniquely identify each record for its own internal use. In our case the underlying table had no primary key fields, so Oracle ADF Business Components uses the next-best thing, the Oracle RowID for the underlying record in the database. We're not overly bothered by this and when we create the Web pages we'll just hide the RowID column from the user.

Now that we've created the View Object, our next requirement is to provide the search capabilities. Oracle ADF Business Components supports a number of mechanisms to allow the user to search, one of which is built in by default and can be seen through the Business Component Browser by clicking on the View Criteria button:

Figure5

This invokes the Business Component View Criteria dialog box which allows us to enter search criteria and return matching records in the Business Component Browser.

In our case while this mechanism is useful, we do know that we have the upcoming requirement to convert the string search fields to uppercase to match our database data, and remove the hyphens from the waybill number if supplied.

An alternative mechanism is to create bind variables for the View Object. We modify our View Object query to look like the following:

Figure5

Doc Tip: Don't know how to create an a View Object with bind variables? See Chapter 5 Section 5.9, "Working with Bind Variables", in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework 11g Release 1 for instructions.

We note the addition of the bind variables under the same named option. At this stage, we're not worried about the requirement of converting the search fields to uppercase or fixing the waybill number, so we'll leave the rest of the query alone. We're just being mindful that even though we've placed a requirement in the "should have" category, this doesn't mean that we should totally ignore it. We can make our future job easier by using features that we'll harness later.

Again we test our View Object through the Business Component Browser to ensure that we haven't made a mistake. This time when we run the View Object, a dialog box will appear asking us to enter values for each bind variable. Once we are done, assuming that we've entered valid search values, a record will be returned:

Figure7

As noted in the requirements it is important to ensure that all the bind variable search fields are entered before the query is executed. Oracle ADF Business Components provides a suitable chokepoint method to check that the bind variables have been supplied before the query is executed in the ViewObjectImpl executeQueryForCollection() method. This method is guaranteed to be called before the actual View Object query is fired against the database.

To do this we first need to generate our ViewObjectImpl class for the ParcelsView by opening the View Object editor Java node and then selecting the Edit button and the Generate View Object Class option:

Figure8

With the generated ParcelsViewImpl class we then override the executeQueryForCollection() method as follows:
public class ParcelsViewImpl extends ViewObjectImpl {
  
    @Override
    protected void executeQueryForCollection(Object queryCollection, 
                   Object[] bindParams, int noUserParams) {
      super.executeQueryForCollection(queryCollection, bindParams, noUserParams);
    } 

  ... the rest of the class ...
We can now write a method to extract the bind parameters and check how many we've received:
private void enforceQueryCriteria() {
  Object[] attrValues = getNamedWhereClauseParams().getAttributeValues();

  int i = 0;
  boolean missingParam = false;

  while (i < attrValues.length && !missingParam) {
    if (attrValues[i] == null || (attrValues[i] instanceof String && attrValues[i].equals("")))
      missingParam = true;
    i++;
  }

  if (missingParam)
    throw new JboException("You must enter all the enquiry criteria");
}
Ideally the JboException message should be sourced from a message bundle, but we'll keep this example brief.

Once we have this method we return to our executeQueryForCollection() method and call our enforceQueryCriteria() method before hand to enforce the requirement:

public class ParcelsViewImpl extends ViewObjectImpl {
  
    @Override
    protected void executeQueryForCollection(Object queryCollection, 
                   Object[] bindParams, int noUserParams) {
      enforceQueryCriteria();
      super.executeQueryForCollection(queryCollection, bindParams, noUserParams);
    } 

  ... the rest of the class ...
In testing this solution in the Business Components Browser we hit an error on opening the ParcelsView:

Figure9

It appears that in initializing the View Object by default a query is fired and the executeQueryForCollection() method is called, causing our new enforceQueryCriteria() method to fire too early. So we'll make the following small modification to our ViewObjectImpl to include a firstQuery flag that stops the enforceQueryCriteria() method from being fired on the initial query:
public class ParcelsViewImpl extends ViewObjectImpl {
  
  boolean firstQuery = true;
  
  @Override
  protected void executeQueryForCollection(Object queryCollection, Object[] bindParams, int noUserParams) {
    if (firstQuery)
      firstQuery = false;
    else
      enforceQueryCriteria();
    super.executeQueryForCollection(queryCollection, bindParams, noUserParams);
  }

  ... the rest of the class ...

Building the Search Page

Given that we have the Oracle ADF Business Components working in the manner we require, it's time to create our first Web page. Given an empty page called SearchPage.jspx, we can use the Data Control Palette to drag our View Object onto the page:

Figure10

In addition we add each bind variable for the View Object to the SearchPage, as well as an ExecuteWithParams button which we label Enquiry:

Figure11

Finally we perform a few touch-ups including View Object bind variable and attribute labels, as well as removing the search fields from the result at the bottom.

Figure12

At this time we have our basic application that can be used by our internal ACME Parcels call center staff to query the database.

Figure13

Summary

In this chapter we have learned how to build a basic search screen to satisfy the MUST Have requirements of our application. Chapter 3 covers adding some additional features to the application, including logging of the user's IP address if they accept our terms and conditions.  Click here to see "Taking an Oracle ADF Application from Design to Reality" description and Table of Contents