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

java.lang.Object
  |
  +--org.apache.velocity.tools.view.tools.AbstractSearchTool

All Implemented Interfaces:

ViewTool

public abstract class AbstractSearchTool

extends java.lang.Object

implements ViewTool

Abstract context 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.

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);
 }
 

Version:

$Revision: 1.4 $ $Date: 2003/05/28 00:17:16 $

Author:

Nathan Bubna

Nested Class Summary

class

AbstractSearchTool.StoredResults Simple utility class to hold a criteria and its result list This class is by default stored in a user's session, so it implements Serializable, but its members are transient.

Field Summary

private java.lang.Object	criteria
static int	DEFAULT_ITEMS_PER_PAGE the default number of results shown per page
static int	DEFAULT_SLIP_SIZE the default max number of result page indices to list
private int	index
private int	itemsPerPage
private java.util.List	results
protected javax.servlet.http.HttpSession	session
private int	slipSize
protected static java.lang.String	STORED_RESULTS_KEY the key under which StoredResults are kept in session

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.
int	getIndex() Return the current search result index.
int	getItemsPerPage() Return the set number of items to be displayed per page of results
java.lang.Integer	getNextIndex() Return the index for the next page of results (as determined by the current index, items per page, and the number of results).
java.util.List	getPage() Return the current "page" of search results.
java.lang.String	getPageDescription() Returns a description of the current page.
java.lang.Integer	getPageNumber() Returns the "page number" for the current index.
java.lang.Integer	getPageNumber(int i) Returns the "page number" for the specified index.
int	getPagesAvailable() Return the number of pages that can be made from this list given the set number of items per page.
java.lang.Integer	getPrevIndex() Return the index for the previous page of results (as determined by the current index, items per page, and the number of results).
java.util.List	getResults() Return the results for the given criteria.
java.util.List	getSlip() Return a Sliding List of Indices for Pages of search results.
int	getSlipSize() Returns the number of result page indices getSlip() will return per request (if available).
protected AbstractSearchTool.StoredResults	getStoredResults() Retrieves stored search results (if any) from the user's session attributes.
boolean	hasResults() Checks whether or not the result list is empty.
void	init(java.lang.Object obj) Initializes this instance by grabbing the request and session objects from the current ViewContext.
void	reset() Sets the criteria and results to null, page index to zero, and items per page to the default.
private java.util.List	retrieveResults() Gets the results for the given criteria either in memory or by performing a new query for them.
void	setCriteria(java.lang.Object criteria) Sets the criteria for this search and clears existing results.
void	setIndex(int index) Sets the index of the first result in the current page
void	setItemsPerPage(int itemsPerPage) Sets the number of items returned in a page of results
void	setSlipSize(int slipSize) Sets the number of result page indices for getSlip() to list.
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.
abstract void	setup(javax.servlet.http.HttpServletRequest request) Abstract method to make it as obvious as possible just where implementing classes should be retrieving and configuring search/display parameters.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_ITEMS_PER_PAGE

public static final int DEFAULT_ITEMS_PER_PAGE

the default number of results shown per page

See Also:

Constant Field Values

DEFAULT_SLIP_SIZE

public static final int DEFAULT_SLIP_SIZE

the default max number of result page indices to list

See Also:

Constant Field Values

STORED_RESULTS_KEY

protected static final java.lang.String STORED_RESULTS_KEY

the key under which StoredResults are kept in session

results

private java.util.List results

criteria

private java.lang.Object criteria

index

private int index

slipSize

private int slipSize

itemsPerPage

private int itemsPerPage

session

protected javax.servlet.http.HttpSession session

Constructor Detail

AbstractSearchTool

public AbstractSearchTool()

Method Detail

init

public void init(java.lang.Object obj)

Initializes this instance by grabbing the request and session objects from the current ViewContext.

Specified by:

init in interface ViewTool

Parameters:

obj - the current ViewContext

Throws:

java.lang.ClassCastException - if the param is not a ViewContext

setup

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

Abstract method to make it as obvious as possible just where implementing classes should be retrieving and configuring search/display parameters.

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));
 }
 

Parameters:

request - the current HttpServletRequest

reset

public void reset()

Sets the criteria and results to null, page index to zero, and items per page to the default.

setCriteria

public void setCriteria(java.lang.Object criteria)

Sets the criteria for this search and clears existing results.

Parameters:

criteria - - the criteria used for this search

setIndex

public void setIndex(int index)

Sets the index of the first result in the current page

Parameters:

index - - the result index to start the current page with

setItemsPerPage

public void setItemsPerPage(int itemsPerPage)

Sets the number of items returned in a page of results

Parameters:

itemsPerPage - - the number of items to be returned per page

setSlipSize

public void setSlipSize(int slipSize)

Sets the number of result page indices for getSlip() to list. (for google-ish result page links).

Parameters:

slipSize - - the number of result page indices to list

See Also:

getSlip()

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

getItemsPerPage

public int getItemsPerPage()

Return the set number of items to be displayed per page of results

Returns:

current number of results shown per page

getSlipSize

public int getSlipSize()

Returns the number of result page indices getSlip() will return per request (if available).

Returns:

the number of result page indices getSlip() will try to return

getIndex

public int getIndex()

Return the current search result index.

Returns:

the index for the beginning of the current page

hasResults

public boolean hasResults()

Checks whether or not the result list is empty.

Returns:

true if the result list is not empty.

getResults

public java.util.List getResults()

Return the results for the given criteria. This is guaranteed to never return null.

Returns:

List of all results for the criteria

getNextIndex

public java.lang.Integer getNextIndex()

Return the index for the next page of results (as determined by the current index, items per page, and the number of results). If no "next page" exists, then null is returned.

Returns:

index for the next page or null if none exists

getPrevIndex

public java.lang.Integer getPrevIndex()

Return the index for the previous page of results (as determined by the current index, items per page, and the number of results). If no "next page" exists, then null is returned.

Returns:

index for the previous page or null if none exists

getPagesAvailable

public int getPagesAvailable()

Return the number of pages that can be made from this list given the set number of items per page.

getPage

public java.util.List getPage()

Return the current "page" of search results.

Returns:

a List of results for the "current page"

getPageNumber

public java.lang.Integer getPageNumber(int i)

Returns the "page number" for the specified index. Because the page number is used for the user interface, the page numbers are 1-based.

Parameters:

i - the index that you want the page number for

Returns:

the approximate "page number" for the specified index or null if there are no results

getPageNumber

public java.lang.Integer getPageNumber()

Returns the "page number" for the current index. Because the page number is used for the user interface, the page numbers are 1-based.

Returns:

the approximate "page number" for the current index or null if there are no results

getPageDescription

public java.lang.String getPageDescription()

Returns a description of the current page. This implementation displays a 1-based range of result indices and the total number of results. (e.g. "1 - 10 of 42" or "7 of 7")

Sub-classes may override this to provide a customized description (such as one in another language).

Returns:

a description of the current page

getSlip

public java.util.List getSlip()

Return a Sliding List of Indices for Pages of search results.

Essentially, this returns a list of result indices that correspond to available pages of search results (as based on the set items-per-page). This makes it relativly easy to do a google-ish set of links to result pages.

Note that this list of Integers is 0-based to correspond with the underlying result indices and not the displayed page numbers (see getPageNumber(int)).

Returns:

List of Integers representing the indices of result pages or empty list if there's one or less pages available

retrieveResults

private java.util.List retrieveResults()

Gets the results for the given criteria either in memory or by performing a new query for them. This is guaranteed to NOT return null.

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