it.tidalwave.util
Interface Finder<Type>

All Superinterfaces:

Cloneable, Serializable

All Known Subinterfaces:

ExtendedFinderSupport<Type,ExtendedFinder>

All Known Implementing Classes:

Composite.EmptyFinder, FinderSupport, SimpleFinderSupport

public interface Finder<Type>
extends Cloneable, Serializable

A factory for providing results of a search. Finder implementations must be immutable.

Version:

$Id$

Author:

Fabrizio Giudici

Status: draft API

Nested Class Summary

static interface	Finder.FilterSortCriterion<Type> An interface that should be implemented by specific Finder.SortCriterion objects which are capable to implement by themselves the sorting of objects, by post-processing an existing collection of objects.
static interface	Finder.SortCriterion A tag interface to mark objects which are meaningful sort criteria that can be passed to sort(it.tidalwave.util.Finder.SortCriterion).
static class	Finder.SortDirection An enumeration to define the direction of a sort (ascending or descending).

Method Summary

int	count() Performs the search and returns the count of found items.
Type	firstResult() Performs the search and returns only the first found item.
Finder<Type>	from(int firstResult) Tells the Finder that only a subset of found items will be returned, starting from the given position.
Finder<Type>	max(int maxResults) Tells the Finder that only a maximum number of found items will be returned.
<AnotherType> Finder<AnotherType>	ofType(Class<AnotherType> type)
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.
Finder<Type>	sort(Finder.SortCriterion criterion) Tells the Finder that results will be sorted according to the given criterion, in ascending direction.
Finder<Type>	sort(Finder.SortCriterion criterion, Finder.SortDirection direction) Tells the Finder that results will be sorted according to the given criterion and direction.

Method Detail

from

@Nonnull
Finder<Type> from(@Nonnegative
                          int firstResult)

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

Returns:

the Finder

max

@Nonnull
Finder<Type> max(@Nonnegative
                         int maxResults)

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

Returns:

the Finder

ofType

@Nonnull
<AnotherType> Finder<AnotherType> ofType(@Nonnull
                                                 Class<AnotherType> type)

Returns:

the Finder

sort

@Nonnull
Finder<Type> sort(@Nonnull
                          Finder.SortCriterion criterion)

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

Parameters:

criterion - the sort criterion

Returns:

the Finder

sort

@Nonnull
Finder<Type> sort(@Nonnull
                          Finder.SortCriterion criterion,
                          @Nonnull
                          Finder.SortDirection direction)

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

Parameters:

criterion - the sort criterion

direction - the sort direction

Returns:

the Finder

result

@Nonnull
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.

Returns:

the found item

Throws:

NotFoundException - if the search didn't find anything

RuntimeException - if the search returned more than one single item

firstResult

@Nonnull
Type firstResult()
                 throws NotFoundException

Performs the search and returns only the first found item.

Returns:

the first found item

Throws:

NotFoundException - if the search didn't find anything

results

@Nonnull
List<? extends Type> results()

Performs the search and returns the found items.

Returns:

the searched items

count

@Nonnegative
int count()

Performs the search and returns the count of found items.

Returns:

the count of found items