org.apache.velocity.tools.view

Class AbstractSearchTool

java.lang.Object

org.apache.velocity.tools.generic.SafeConfig

org.apache.velocity.tools.view.PagerTool

org.apache.velocity.tools.view.AbstractSearchTool

Direct Known Subclasses:

MySearchTool

@DefaultKey(value="search")
 @InvalidScope(value={"application","session"})
public abstract class AbstractSearchTool
extends PagerTool

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 executeQuery(Object) method.

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:

   <form method="get" action="">
    <input type="text" value="foo">
    <input type="submit" value="Find">
   </form>
   Showing 1-5 of 8<br>
   1. foo<br>
   2. bar<br>
   3. blah<br>
   4. woogie<br>
   5. baz<br><br>
   <b>1</b> <a href="">2</a> <a href="">Next</a>
 

Example tools.xml configuration:

 <tools>
   <toolbox scope="request">
     <tool class="com.foo.tools.MySearchTool"/>
   </toolbox>
 </tools>
 

Since:

VelocityTools 2.0

Version:

$Revision$ $Date$

Author:

Nathan Bubna

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	AbstractSearchTool.StoredResults Simple utility class to hold a criterion and its result list.

Field Summary

Fields

Modifier and Type	Field and Description
static String	DEFAULT_CRITERIA_KEY
protected static String	STORED_RESULTS_KEY the key under which StoredResults are kept in session

Fields inherited from class org.apache.velocity.tools.view.PagerTool

DEFAULT_INDEX_KEY, DEFAULT_ITEMS_PER_PAGE, DEFAULT_ITEMS_PER_PAGE_KEY, DEFAULT_NEW_ITEMS_KEY, DEFAULT_SLIP_SIZE, DEFAULT_SLIP_SIZE_KEY, session, STORED_ITEMS_KEY

Fields inherited from class org.apache.velocity.tools.generic.SafeConfig

LOCK_CONFIG_KEY, log, LOGGER_NAME_KEY, SAFE_MODE_KEY, USE_CLASS_LOGGER_KEY

Constructor Summary

Constructors

Constructor and Description
AbstractSearchTool()

Method Summary

Modifier and Type	Method and Description
protected abstract List	executeQuery(Object criteria) Executes a query for the specified criteria.
Object	getCriteria() Return the criteria object for this request.
String	getCriteriaKey()
List	getItems() Gets the results for the given criteria either in memory or by performing a new query for them.
protected 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.
void	reset() Sets the criteria and results to null, page index to zero, and items per page to the default.
void	setCriteria(Object criteria) Sets the criteria for this search.
void	setCriteriaKey(String key)
protected void	setStoredItems(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.
void	setup(javax.servlet.http.HttpServletRequest request) Sets the criteria *if* it is set in the request parameters.

Methods inherited from class org.apache.velocity.tools.view.PagerTool

getCreateSession, getFirstIndex, getIndex, getIndexKey, getItemsPerPage, getItemsPerPageKey, getLastIndex, getNewItemsKey, getNextIndex, getPage, getPageDescription, getPageNumber, getPageNumber, getPagesAvailable, getPrevIndex, getSlip, getSlipSize, getSlipSizeKey, getTotal, hasItems, setCreateSession, setIndex, setIndexKey, setItems, setItemsPerPage, setItemsPerPageKey, setNewItemsKey, setRequest, setSlipSize, setSlipSizeKey

Methods inherited from class org.apache.velocity.tools.generic.SafeConfig

configure, configure, getLog, initLogger, isConfigLocked, isSafeMode, setLockConfig, setSafeMode

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_CRITERIA_KEY

public static final String DEFAULT_CRITERIA_KEY

See Also:

Constant Field Values

STORED_RESULTS_KEY

protected static final String STORED_RESULTS_KEY

the key under which StoredResults are kept in session

Constructor Detail

AbstractSearchTool

public AbstractSearchTool()

Method Detail

setup

public void setup(javax.servlet.http.HttpServletRequest request)

Sets the criteria *if* it is set in the request parameters.

Overrides:

setup in class PagerTool

Parameters:

request - the current HttpServletRequest

setCriteriaKey

public void setCriteriaKey(String key)

getCriteriaKey

public String getCriteriaKey()

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 PagerTool

setCriteria

public void setCriteria(Object criteria)

Sets the criteria for this search.

Parameters:

criteria - - the criteria used for this search

getCriteria

public 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

getItems

public 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 PagerTool

Returns:

List of all items for the criteria

getStoredItems

protected List getStoredItems()

Description copied from class: PagerTool

Retrieves stored search items (if any) from the user's session attributes.

Overrides:

getStoredItems in class PagerTool

Returns:

the List retrieved from memory

setStoredItems

protected void setStoredItems(List items)

Description copied from class: PagerTool

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 PagerTool

Parameters:

items - the List to be stored

executeQuery

protected abstract List executeQuery(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);
 }
 

Parameters:

criteria - search criteria

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