it.tidalwave.util.spi

Class FinderSupport<TYPE,EXTENDED_FINDER extends Finder<TYPE>>

java.lang.Object

it.tidalwave.util.spi.FinderSupport<TYPE,EXTENDED_FINDER>

All Implemented Interfaces:

Finder<TYPE>, Serializable, Cloneable

Direct Known Subclasses:

SimpleFinderSupport

public class FinderSupport<TYPE,EXTENDED_FINDER extends Finder<TYPE>>
extends Object
implements Finder<TYPE>, Cloneable

A support class for implementing a Finder. Subclasses only need to implement the computeResults() method where raw results are retrieved (with raw we mean that they shouldn't be filtered or sorted, as post-processing will be performed by this class) and a clone constructor. If you don't need to extend the Finder with extra methods, please use the simplified SimpleFinderSupport.

Version:

$Id$

Author:

Fabrizio Giudici

See Also:

Serialized Form

Status: draft API

Nested Class Summary

Nested classes/interfaces inherited from interface it.tidalwave.util.Finder

Finder.FilterSortCriterion<TYPE>, Finder.SortCriterion, Finder.SortDirection

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	FinderSupport() Default constructor.
protected	FinderSupport(FinderSupport<TYPE,EXTENDED_FINDER> other, Object override) Clone constructor for subclasses.
protected	FinderSupport(String name) Creates an instance with the given name (that will be used for diagnostics).

Method Summary

Modifier and Type	Method and Description
FinderSupport<TYPE,EXTENDED_FINDER>	clone() Deprecated.
protected EXTENDED_FINDER	clone(Object override)
protected List<? extends TYPE>	computeNeededResults() Subclasses can implement this method where *only the requested* raw results must be retrieved.
protected List<? extends TYPE>	computeResults() Subclasses can implement this method where *all* the raw results must be actually retrieved.
int	count() Performs the search and returns the count of found items.
static <T> Finder<T>	emptyFinder() Returns an empty Finder.
TYPE	firstResult() Performs the search and returns only the first found item.
EXTENDED_FINDER	from(int firstResult) Tells the Finder that only a subset of found items will be returned, starting from the given position.
protected static <T> T	getSource(Class<T> clazz, T other, Object override)
EXTENDED_FINDER	max(int maxResults) Tells the Finder that only a maximum number of found items will be returned.
<ANOTHER_TYPE> Finder<ANOTHER_TYPE>	ofType(Class<ANOTHER_TYPE> type) Tells the Finder that the specified type of results is expected.
TYPE	result() Performs the search assuming that it will return a single item and returns it.
List<? extends TYPE>	results() Performs the search and returns the found items.
EXTENDED_FINDER	sort(Finder.SortCriterion criterion) Tells the Finder that results will be sorted according to the given criterion, in ascending direction.
EXTENDED_FINDER	sort(Finder.SortCriterion criterion, Finder.SortDirection direction) Tells the Finder that results will be sorted according to the given criterion and direction.
EXTENDED_FINDER	withContext(Object context) Tells the Finder that results should be created with the given context.

Methods inherited from class java.lang.Object

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

Constructor Detail

FinderSupport

protected FinderSupport(@Nonnull
                        String name)

Creates an instance with the given name (that will be used for diagnostics).

Parameters:

name - the name

FinderSupport

protected FinderSupport()

Default constructor.

FinderSupport

protected FinderSupport(@Nonnull
                        FinderSupport<TYPE,EXTENDED_FINDER> other,
                        @Nonnull
                        Object override)

Clone constructor for subclasses.

Method Detail

emptyFinder

@Nonnull
public static <T> Finder<T> emptyFinder()

Returns an empty Finder.

Type Parameters:

T - the type of the Finder

Returns:

the empty Finder

getSource

@Nonnull
protected static <T> T getSource(Class<T> clazz,
                                          @Nonnull
                                          T other,
                                          @Nonnull
                                          Object override)

clone

@Nonnull
public final FinderSupport<TYPE,EXTENDED_FINDER> clone()

Deprecated.

Overrides:

clone in class Object

clone

@Nonnull
protected EXTENDED_FINDER clone(@Nonnull
                                         Object override)

from

@Nonnull
public EXTENDED_FINDER from(@Nonnegative
                                     int firstResult)

Tells the Finder that only a subset of found items will be returned, starting from the given position.

Specified by:

from in interface Finder<TYPE>

Parameters:

firstResult - the index of the first result to return

Returns:

the Finder

max

@Nonnull
public EXTENDED_FINDER max(@Nonnegative
                                    int maxResults)

Tells the Finder that only a maximum number of found items will be returned.

Specified by:

max in interface Finder<TYPE>

Parameters:

maxResults - the max number of results to return

Returns:

the Finder

withContext

@Nonnull
public EXTENDED_FINDER withContext(@Nonnull
                                            Object context)

Tells the Finder that results should be created with the given context. This method can be called multiple times; contexts are accumulated.

Specified by:

withContext in interface Finder<TYPE>

Parameters:

context - the context

Returns:

the Finder

ofType

@Nonnull
public <ANOTHER_TYPE> Finder<ANOTHER_TYPE> ofType(@Nonnull
                                                           Class<ANOTHER_TYPE> type)

Tells the Finder that the specified type of results is expected.

Specified by:

ofType in interface Finder<TYPE>

Parameters:

type - the expected type of results

Returns:

the Finder

sort

@Nonnull
public EXTENDED_FINDER sort(@Nonnull
                                     Finder.SortCriterion criterion,
                                     @Nonnull
                                     Finder.SortDirection direction)

Tells the Finder that results will be sorted according to the given criterion and direction.

Specified by:

sort in interface Finder<TYPE>

Parameters:

criterion - the sort criterion

direction - the sort direction

Returns:

the Finder

sort

@Nonnull
public final EXTENDED_FINDER sort(@Nonnull
                                           Finder.SortCriterion criterion)

Tells the Finder that results will be sorted according to the given criterion, in ascending direction.

Specified by:

sort in interface Finder<TYPE>

Parameters:

criterion - the sort criterion

Returns:

the Finder

result

@Nonnull
public TYPE result()
                     throws NotFoundException

Performs the search assuming that it will return a single item and returns it. This method fails if the search returns more than one single item.

Specified by:

result in interface Finder<TYPE>

Returns:

the found item

Throws:

NotFoundException - if the search didn't find anything

firstResult

@Nonnull
public TYPE firstResult()
                          throws NotFoundException

Performs the search and returns only the first found item.

Specified by:

firstResult in interface Finder<TYPE>

Returns:

the first found item

Throws:

NotFoundException - if the search didn't find anything

results

@Nonnull
public List<? extends TYPE> results()

Performs the search and returns the found items.

Specified by:

results in interface Finder<TYPE>

Returns:

the searched items

count

@Nonnegative
public int count()

Performs the search and returns the count of found items.

Specified by:

count in interface Finder<TYPE>

Returns:

the count of found items

computeResults

@Nonnull
protected List<? extends TYPE> computeResults()

Subclasses can implement this method where *all* the raw results must be actually retrieved.

Returns:

the unprocessed results

computeNeededResults

@Nonnull
protected List<? extends TYPE> computeNeededResults()

Subclasses can implement this method where *only the requested* raw results must be retrieved.

Returns:

the unprocessed results