27.4 Working with Multiple Named View Criteria

You can define multiple named view criteria and then selectively apply any combination of them to your view object at runtime as needed.

Note: The examples in this section refer to the MultipleViewCriterias project in the AdvancedViewObjectExamples workspace. See the note at the beginning of this chapter for download instructions.

27.4.1 Defining Named View Criteria

To define named view criteria, you override the create() method in your view object's custom Java class and call the putViewCriteria() method to define one or more named ViewCriteria objects.

For example, given a Users view object based on the USERS table in the SRDemo schema, you could override the create() method as shown in Example 27-5 to define named view criteria called CountryIsUS, CountryIsNotUS, IsStaff, and IsCustomer by calling appropriate helper methods.

Example 27-5 Defining Multiple Named View Criteria in an Overridden create() Method

package devguide.advanced.multiplevc;
// Imports omitted
public class UsersImpl extends ViewObjectImpl implements Users {
  // etc.
  protected void create() {
    super.create();
    defineCountryIsUSCriteria();
    defineCountryIsNotUSCriteria();
    defineIsStaffCriteria();
    defineIsCustomerCriteria();
  }
  private void defineCountryIsUSCriteria() {
    ViewCriteria vc = createViewCriteria();
    ViewCriteriaRow vcr = vc.createViewCriteriaRow();
    vcr.setAttribute("CountryId","US");
    vc.add(vcr);
    putViewCriteria("CountryIsUS",vc);
  }
  private void defineCountryIsNotUSCriteria() {
    ViewCriteria vc = createViewCriteria();
    ViewCriteriaRow vcr = vc.createViewCriteriaRow();
    vcr.setAttribute("CountryId","US");
    vcr.setConjunction(ViewCriteriaRow.VCROW_CONJ_NOT);
    vc.add(vcr);
    putViewCriteria("CountryIsNotUS",vc);
  }
  private void defineIsStaffCriteria() {
    ViewCriteria vc = createViewCriteria();
    ViewCriteriaRow vcr = vc.createViewCriteriaRow();
    vcr.setAttribute("UserRole","IN ('technician','manager')");
    vc.add(vcr);
    putViewCriteria("IsStaff",vc);
  }
  private void defineIsCustomerCriteria() {
    ViewCriteria vc = createViewCriteria();
    ViewCriteriaRow vcr = vc.createViewCriteriaRow();
    vcr.setAttribute("UserRole","user");
    vc.add(vcr);
    putViewCriteria("IsCustomer",vc);
  } 
  // etc.  
}

27.4.2 Applying One or More Named View Criteria

To apply one or more named view criteria, use the setApplyViewCriteriaNames() method. This method accepts a String array of the names of the criteria you want to apply. If you apply more than one named criteria, they are AND-ed together in the WHERE clause produced at runtime. Then, you can expose custom methods on the client interface of the view object to encapsulate applying combinations of the named view criteria. For example, Example 27-6 shows custom methods showStaffInUS(), showCustomersOutsideUS(), and showCustomersInUS(), each of which uses the setApplyViewCriteriaNames() method to apply an appropriate combination of named view criteria. Once these methods are exposed on the view object's client interface, at runtime clients can invoke these methods as needed to change the information displayed by the view object.

Example 27-6 Exposing Client Methods to Enable Appropriate Named Criterias

// In UsersImpl.java
public void showStaffInUS() {
  setApplyViewCriteriaNames(new String[]{"CountryIsUS","IsStaff"});
  executeQuery();
}
public void showCustomersOutsideUS() {
  setApplyViewCriteriaNames(new String[]{"CountryIsNotUS","IsCustomer"});
  executeQuery();
}
public void showCustomersInUS() {
  setApplyViewCriteriaNames(new String[]{"CountryIsUS","IsCustomer"});
  executeQuery();
}   

27.4.3 Removing All Applied Named View Criteria

To remove any currently applied named view criteria, use setApplyViewCriteriaNames(null). For example, you could add the showAll() method in Example 27-7 to the Users view object and expose it on the client interface. This would allow clients to return to an unfiltered view of the data when needed.

Example 27-7 Removing All Applied Named View Criterias

// In UsersImpl.java
public void showAll() {
  setApplyViewCriteriaNames(null);
  executeQuery();
}

Note: The setApplyViewCriterias(null) removes all applied view criteria, but allows you to later reapply any combination of them. In contrast, the clearViewCriterias() method deletes all named view criteria. After calling clearViewCriterias() you would have to use putViewCriteria() again to define new named criteria before you could apply them.

27.4.4 Using the Named Criteria at Runtime

Example 27-8 shows the interesting lines of a TestClient class that works with the Users view object described above. It invokes different client methods on the Users view object interface to show different filtered sets of data. The showRows() method is a helper method that iterates over the rows in the view object to display some attributes.

Example 27-8 Test Client Code Working with Named View Criterias

// In TestClientMultipleViewCriterias.java
Users vo = (Users)am.findViewObject("Users");
vo.showCustomersOutsideUS();
showRows(vo,"After applying view criterias for customers outside US");
vo.showStaffInUS();
showRows(vo,"After applying view criterias for staff in US");
vo.showCustomersInUS();
showRows(vo,"After applying view criterias for customers in US");
vo.showAll();
showRows(vo,"After clearing all view criterias");

Running the TestClient program produces output as follows:

--- After applying view criterias for customers outside US ---
Hermann Baer [user, DE]
John Chen [user, TH]
:
--- After applying view criterias for staff in US ---
David Austin [technician, US]
Bruce Ernst [technician, US]
:
--- After applying view criterias for customers in US ---
Shelli Baida [user, US]
Emerson Clabe [user, US]
:
--- After clearing all view criterias ---
David Austin [technician, US]
Hermann Baer [user, DE]
: