All Superinterfaces:

java.lang.Cloneable, java.io.Serializable

All Known Subinterfaces:

ExtendedFinderSupport<T,F>, FinderWithId<T,F>

All Known Implementing Classes:

FinderWithIdMapSupport, FinderWithIdSupport, HierarchicFinderSupport, SimpleFinderSupport
```
public interface Finder<T>
extends java.lang.Cloneable, java.io.Serializable
```
A factory for providing results of a search. Finder implementations must be immutable.

Author:

Fabrizio Giudici

Status: draft API

Nested Class Summary

Nested Classes
Modifier and Type	Interface	Description
`static interface`	`Finder.InMemorySortCriterion<U>`	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

All Methods Static Methods Instance Methods Abstract Methods Default Methods Deprecated Methods
Modifier and Type	Method	Description
`int`	`count()`	Performs the search and returns the count of found items.
`static <U> Finder<U>`	`empty()`	Returns an empty `Finder`.
`default T`	`firstResult()`	Deprecated. Use `optionalFirstResult()` instead
`Finder<T>`	`from(int firstResult)`	Tells the `Finder` that only a subset of found items will be returned, starting from the given position.
`default Finder<T>`	`from(java.util.Optional<java.lang.Integer> firstResult)`	Tells the `Finder` that only a subset of found items will be returned, starting from the given position.
`default java.util.Iterator<T>`	`iterator()`	Returns am iterator of results.
`static <U,V> Finder<U>`	`mapping(Finder<V> delegate, java.util.function.Function<? super V,? extends U> mapper)`	Returns a mapping `Finder` on a given delegate `Finder`.
`Finder<T>`	`max(int maxResults)`	Tells the `Finder` that only a maximum number of found items will be returned.
`default Finder<T>`	`max(java.util.Optional<java.lang.Integer> maxResults)`	Tells the `Finder` that only a maximum number of found items will be returned.
`static <U> Finder<U>`	`ofCloned(java.util.Collection<? extends U> items)`	Returns a wrapped `Finder` on a given collection of elements.
`static <U> Finder<U>`	`ofProvider(java.util.function.BiFunction<java.lang.Integer,java.lang.Integer,? extends java.util.Collection<? extends U>> provider)`	Returns a wrapped `Finder` on a given function to provide results.
`static <U> Finder<U>`	`ofSupplier(java.util.function.Supplier<? extends java.util.Collection<? extends U>> supplier)`	Returns a wrapped `Finder` on a given supplier.
`default <U> Finder<U>`	`ofType(java.lang.Class<U> type)`	Tells the `Finder` that the specified type of results is expected.
`default java.util.Optional<T>`	`optionalFirstResult()`	Performs the search and returns only the first found item.
`default java.util.Optional<T>`	`optionalResult()`	Performs the search assuming that it will return a single item and returns it.
`default T`	`result()`	Deprecated. Use `optionalResult()` instead
`java.util.List<T>`	`results()`	Performs the search and returns the found items.
`default Finder<T>`	`sort(Finder.SortCriterion criterion)`	Tells the `Finder` that results will be sorted according to the given criterion, in ascending direction.
`Finder<T>`	`sort(Finder.SortCriterion criterion, Finder.SortDirection direction)`	Tells the `Finder` that results will be sorted according to the given criterion and direction.
`default java.util.stream.Stream<T>`	`stream()`	Returns a stream of results.
`default Finder<T>`	`withContext(java.lang.Object context)`	Tells the `Finder` that results should be created with the given context.

- Method Detail
 - from
```
@Nonnull
Finder<T> 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
 - from
```
@Nonnull
default Finder<T> from(@Nonnull
 java.util.Optional<java.lang.Integer> 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
 
 Since:
 
 3.2-ALPHA-19
 - max
```
@Nonnull
Finder<T> 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
 - max
```
@Nonnull
default Finder<T> max(@Nonnull
 java.util.Optional<java.lang.Integer> 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
 
 Since:
 
 3.2-ALPHA-19
 - withContext
```
@Nonnull
default Finder<T> withContext(@Nonnull
 java.lang.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
default  Finder ofType(@Nonnull
 java.lang.Class type)
```
 Tells the Finder that the specified type of results is expected.
 
 Type Parameters:
 
 U - the static type
 
 Parameters:
 
 type - the dynamic type
 
 Returns:
 
 the Finder
 - sort
```
@Nonnull
default Finder<T> 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<T> 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
 - results
```
@Nonnull
java.util.List<T> 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
 - optionalResult
```
@Nonnull
default java.util.Optional<T> optionalResult()
```
 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 optional result
 
 Throws:
 
 java.lang.RuntimeException - if the search returned more than one single item
 
 Since:
 
 3.2-ALPHA-1 (previously in Finder8)
 - optionalFirstResult
```
@Nonnull
default java.util.Optional<T> optionalFirstResult()
```
 Performs the search and returns only the first found item.
 
 Returns:
 
 the first result
 
 Since:
 
 3.2-ALPHA-1 (previously in Finder8)
 - stream
```
@Nonnull
default java.util.stream.Stream<T> stream()
```
 Returns a stream of results.
 
 Returns:
 
 the stream
 
 Since:
 
 3.2-ALPHA-1 (previously in Finder8)
 - iterator
```
@Nonnull
default java.util.Iterator<T> iterator()
```
 Returns am iterator of results.
 
 Returns:
 
 the iterator
 
 Since:
 
 3.2-ALPHA-1 (previously in Finder8)
 - result
```
@Nonnull
@Deprecated
default T result()
 throws NotFoundException,
 java.lang.RuntimeException
```
 Deprecated.
 Use optionalResult() instead
 
 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
 
 java.lang.RuntimeException - if the search returned more than one single item
 - firstResult
```
@Nonnull
@Deprecated
default T firstResult()
 throws NotFoundException
```
 Deprecated.
 Use optionalFirstResult() instead
 
 Performs the search and returns only the first found item.
 
 Returns:
 
 the first found item
 
 Throws:
 
 NotFoundException - if the search didn't find anything
 - empty
```
@Nonnull
static  Finder empty()
```
 Returns an empty Finder.
 
 Type Parameters:
 
 U - the type of the Finder
 
 Returns:
 
 the empty Finder
 
 Since:
 
 3.2-ALPHA-1 (previously in HierarchicFinderSupport.emptyFinder())
 - ofCloned
```
@Nonnull
static  Finder ofCloned(@Nonnull
 java.util.Collection<? extends U> items)
```
 Returns a wrapped Finder on a given collection of elements. The collection is cloned and will be immutable. If you need to compute the collection on demand, use ofSupplier(Supplier). This method retrieves the full range of results that will be later segmented in compliance with the values specified by from(int) and max(int); this is ok if the whole list of results is already available of if it is not expensive to compute. The alternate method ofProvider(BiFunction) allows to access the 'from' and 'max' parameter, so only the required items need to be provided.
 
 Type Parameters:
 
 U - the type of the Finder
 
 Parameters:
 
 items - the objects to wrap
 
 Returns:
 
 the wrapped Finder
 
 Since:
 
 3.2-ALPHA-1
 
 See Also:
 
 ofSupplier(Supplier), ofProvider(BiFunction)
 - ofSupplier
```
@Nonnull
static  Finder ofSupplier(@Nonnull
 java.util.function.Supplier<? extends java.util.Collection<? extends U>> supplier)
```
 Returns a wrapped Finder on a given supplier. The collection will be cloned after being supplied. This method retrieves the full range of results that will be later segmented in compliance with the values specified by from(int) and max(int); this is ok if the whole list of results is already available of if it is not expensive to compute. The alternate method ofProvider(BiFunction) allows to access the 'from' and 'max' parameter, so only the required items need to be provided.
 
 Type Parameters:
 
 U - the type of the Finder
 
 Parameters:
 
 supplier - the supplier
 
 Returns:
 
 the wrapped Finder
 
 Since:
 
 3.2-ALPHA-15
 
 See Also:
 
 ofCloned(Collection), ofProvider(BiFunction)
 - ofProvider
```
@Nonnull
static  Finder ofProvider(@Nonnull
 java.util.function.BiFunction<java.lang.Integer,java.lang.Integer,? extends java.util.Collection<? extends U>> provider)
```
 Returns a wrapped Finder on a given function to provide results. The function receives the 'from' and 'max' arguments to select a subrange of the results. The collection will be cloned after being supplied.
 
 Type Parameters:
 
 U - the type of the Finder
 
 Parameters:
 
 provider - the function providing results
 
 Returns:
 
 the wrapped Finder
 
 Since:
 
 3.2-ALPHA-15
 
 See Also:
 
 ofCloned(Collection), ofSupplier(Supplier)
 - mapping
```
@Nonnull
static <U,V> Finder mapping(@Nonnull
 Finder<V> delegate,
 @Nonnull
 java.util.function.Function<? super V,? extends U> mapper)
```
 Returns a mapping Finder on a given delegate Finder. The mapper finder provides the same results as the delegate, transformed by a mapper function.
 
 Type Parameters:
 
 U - the type of the Finder
 
 V - the type of the delegate Finder
 
 Parameters:
 
 delegate - the delegate finder
 
 mapper - the mapper function
 
 Returns:
 
 the wrapped Finder
 
 Since:
 
 3.2-ALPHA-15

Interface Finder<T>

Nested Class Summary

Method Summary

Method Detail

from

from

max

max

withContext

ofType

sort

sort

results

count

optionalResult

optionalFirstResult

stream

iterator

result

firstResult

empty

ofCloned

ofSupplier

ofProvider

mapping