org.apache.velocity.tools.view.tools
Class AbstractSearchTool

java.lang.Object
  extended byorg.apache.velocity.tools.view.tools.AbstractPagerTool
      extended byorg.apache.velocity.tools.view.tools.AbstractSearchTool
All Implemented Interfaces:
ViewTool

public abstract class AbstractSearchTool
extends AbstractPagerTool

Abstract view tool for doing "searching" and robust pagination of search results. The goal here is to provide a simple and uniform API for "search tools" that can be used in velocity templates (or even a standard Search.vm template). In particular, this class provides good support for result pagination and some very simple result caching.

Usage:
To use this class, you must extend it and implement the setup(HttpServletRequest) and executeQuery(Object) methods.

The setup(HttpServletRequest) method ought to extract from the current request the search criteria, the current list index, and optionally, the number of items to display per page of results. Upon extracting these parameters, they should be set using the provided setCriteria(Object), setIndex(int), and setItemsPerPage(int) methods. A simple implementation would be:

 public void setup(HttpServletRequest req)
 {
     ParameterParser pp = new ParameterParser(req);
     setCriteria(pp.getString("find"));
     setIndex(pp.getInt("index", 0));
     setItemsPerPage(pp.getInt("show", DEFAULT_ITEMS_PER_PAGE));
 }
 

The setCriteria(Object) method takes an Object in order to allow the search criteria to meet your needs. Your criteria may be as simple as a single string, an array of strings, or whatever you like. The value passed into this method is that which will ultimately be passed into executeQuery(Object) to perform the search and return a list of results. A simple implementation might be like:

 protected List executeQuery(Object crit)
 {
     return MyDbUtils.getFooBarsMatching((String)crit);
 }
 

Here's an example of how your subclass would be used in a template:

   <form name="search" method="get" action="$link.setRelative('search.vm')">
     <input type="text"name="find" value="$!search.criteria">
     <input type="submit" value="Find">
   </form>
   #if( $search.hasItems() )
   Showing $!search.pageDescription<br>
     #set( $i = $search.index )
     #foreach( $item in $search.page )
       ${i}. $!item <br>
       #set( $i = $i + 1 )
     #end
     <br>
     #if ( $search.pagesAvailable > 1 )
       #set( $pagelink = $link.setRelative('search.vm').addQueryData("find",$!search.criteria).addQueryData("show",$!search.itemsPerPage) )
       #if( $search.prevIndex )
           <a href="$pagelink.addQueryData('index',$!search.prevIndex)">Prev</a>
       #end
       #foreach( $index in $search.slip )
         #if( $index == $search.index )
           <b>$search.pageNumber</b>
         #else
           <a href="$pagelink.addQueryData('index',$!index)">$!search.getPageNumber($index)</a>
         #end
       #end
       #if( $search.nextIndex )
           <a href="$pagelink.addQueryData('index',$!search.nextIndex)">Next</a>
       #end
     #end
   #elseif( $search.criteria )
   Sorry, no matches were found for "$!search.criteria".
   #else
   Please enter a search term
   #end
 
The output of this might look like:

Showing 1-5 of 8
1. foo
2. bar
3. blah
4. woogie
5. baz

1 2 Next

Example toolbox.xml configuration:

<tool>
   <key>search</key>
   <scope>request</scope>
   <class>com.foo.tools.MySearchTool</class>
 </tool>
 

Since:
VelocityTools 1.0
Version:
$Revision: 155305 $ $Date: 2005-02-24 20:40:59 -0800 (Thu, 24 Feb 2005) $
Author:
Nathan Bubna

Nested Class Summary
 class AbstractSearchTool.StoredResults
          Simple utility class to hold a criterion and its result list.
 
Field Summary
private  java.lang.Object criteria
           
protected static java.lang.String STORED_RESULTS_KEY
          the key under which StoredResults are kept in session
 
Fields inherited from class org.apache.velocity.tools.view.tools.AbstractPagerTool
DEFAULT_ITEMS_PER_PAGE, DEFAULT_SLIP_SIZE, session, STORED_ITEMS_KEY
 
Constructor Summary
AbstractSearchTool()
           
 
Method Summary
protected abstract  java.util.List executeQuery(java.lang.Object criteria)
          Executes a query for the specified criteria.
 java.lang.Object getCriteria()
          Return the criteria object for this request.
 java.util.List getItems()
          Gets the results for the given criteria either in memory or by performing a new query for them.
 java.util.List getResults()
          Deprecated. Use AbstractPagerTool.getItems().
protected  java.util.List getStoredItems()
          Retrieves stored search items (if any) from the user's session attributes.
protected  AbstractSearchTool.StoredResults getStoredResults()
          Retrieves stored search results (if any) from the user's session attributes.
 boolean hasResults()
          Deprecated. Use AbstractPagerTool.hasItems()
 void reset()
          Sets the criteria and results to null, page index to zero, and items per page to the default.
 void setCriteria(java.lang.Object criteria)
          Sets the criteria for this search.
protected  void setStoredItems(java.util.List items)
          Stores current search items in the user's session attributes (if one currently exists) in order to do efficient result pagination.
protected  void setStoredResults(AbstractSearchTool.StoredResults results)
          Stores current search results in the user's session attributes (if one currently exists) in order to do efficient result pagination.
 
Methods inherited from class org.apache.velocity.tools.view.tools.AbstractPagerTool
getIndex, getItemsPerPage, getNextIndex, getPage, getPageDescription, getPageNumber, getPageNumber, getPagesAvailable, getPrevIndex, getSlip, getSlipSize, hasItems, init, setIndex, setItems, setItemsPerPage, setSlipSize, setup
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

STORED_RESULTS_KEY

protected static final java.lang.String STORED_RESULTS_KEY
the key under which StoredResults are kept in session


criteria

private java.lang.Object criteria
Constructor Detail

AbstractSearchTool

public AbstractSearchTool()
Method Detail

reset

public void reset()
Sets the criteria and results to null, page index to zero, and items per page to the default.

Overrides:
reset in class AbstractPagerTool

setCriteria

public void setCriteria(java.lang.Object criteria)
Sets the criteria for this search.

Parameters:
criteria - - the criteria used for this search

getCriteria

public java.lang.Object getCriteria()
Return the criteria object for this request. (for a simple search mechanism, this will typically be just a java.lang.String)

Returns:
criteria object

hasResults

public boolean hasResults()
Deprecated. Use AbstractPagerTool.hasItems()


getResults

public java.util.List getResults()
Deprecated. Use AbstractPagerTool.getItems().


getItems

public java.util.List getItems()
Gets the results for the given criteria either in memory or by performing a new query for them. If the criteria is null, an empty list will be returned.

Overrides:
getItems in class AbstractPagerTool
Returns:
List of all items for the criteria

getStoredItems

protected java.util.List getStoredItems()
Description copied from class: AbstractPagerTool
Retrieves stored search items (if any) from the user's session attributes.

Overrides:
getStoredItems in class AbstractPagerTool
Returns:
the List retrieved from memory

setStoredItems

protected void setStoredItems(java.util.List items)
Description copied from class: AbstractPagerTool
Stores current search items in the user's session attributes (if one currently exists) in order to do efficient result pagination.

Override this to store search items somewhere besides the HttpSession or to prevent storage of items across requests. In the former situation, you must also override getStoredItems().

Overrides:
setStoredItems in class AbstractPagerTool
Parameters:
items - the List to be stored

executeQuery

protected abstract java.util.List executeQuery(java.lang.Object criteria)
Executes a query for the specified criteria.

This method must be implemented! A simple implementation might be something like:

 protected List executeQuery(Object crit)
 {
     return MyDbUtils.getFooBarsMatching((String)crit);
 }
 

Returns:
a List of results for this query

getStoredResults

protected AbstractSearchTool.StoredResults getStoredResults()
Retrieves stored search results (if any) from the user's session attributes.

Returns:
the AbstractSearchTool.StoredResults retrieved from memory

setStoredResults

protected void setStoredResults(AbstractSearchTool.StoredResults results)
Stores current search results in the user's session attributes (if one currently exists) in order to do efficient result pagination.

Override this to store search results somewhere besides the HttpSession or to prevent storage of results across requests. In the former situation, you must also override getStoredResults().

Parameters:
results - the AbstractSearchTool.StoredResults to be stored


Copyright (c) 2003 Apache Software Foundation