it.tidalwave.util

Interface Finder<TYPE>

All Superinterfaces:

Cloneable, Serializable

All Known Subinterfaces:

ExtendedFinderSupport<TYPE,EXTENDED_FINDER>

All Known Implementing Classes:

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

Nested Classes

Modifier and Type	Interface and Description
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

Modifier and Type	Method and Description
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) 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.
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.
Finder<TYPE>	withContext(Object context) Tells the Finder that results should be created with the given context.

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.

Parameters:

firstResult - the index of the first result to return

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.

Parameters:

maxResults - the max number of results to return

Returns:

the Finder

withContext

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

Parameters:

context - the context

Returns:

the Finder

ofType

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

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

Parameters:

type - the expected type of results

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,
                     RuntimeException

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