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

    @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
`static class` `AbstractSearchTool.StoredResults` Simple utility class to hold a criterion and its result list.

### Field Summary

Fields
`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

All Methods Instance Methods Abstract Methods Concrete Methods
`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