All Superinterfaces:

java.lang.Cloneable, java.io.Serializable

All Known Subinterfaces:

ExtendedFinderSupport<TYPE,EXTENDED_FINDER>

All Known Implementing Classes:

HierarchicFinderSupport, SimpleFinderSupport
```
public interface Finder<TYPE>
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<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

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 <T> Finder<T>`	`empty()`	Returns an empty `Finder`.
`default TYPE`	`firstResult()`	Deprecated. Use `optionalFirstResult()` instead
`Finder<TYPE>`	`from(int firstResult)`	Tells the `Finder` that only a subset of found items will be returned, starting from the given position.
`default java.util.Iterator<TYPE>`	`iterator()`	Returns am iterator of results.
`Finder<TYPE>`	`max(int maxResults)`	Tells the `Finder` that only a maximum number of found items will be returned.
`static <T> Finder<T>`	`ofCloned(java.util.Collection<T> items)`	Returns a wrapped `Finder` on a given collection of elements.
`default <ANOTHER_TYPE> Finder<ANOTHER_TYPE>`	`ofType(java.lang.Class<ANOTHER_TYPE> type)`	Tells the `Finder` that the specified type of results is expected.
`default java.util.Optional<TYPE>`	`optionalFirstResult()`	Performs the search and returns only the first found item.
`default java.util.Optional<TYPE>`	`optionalResult()`	Performs the search assuming that it will return a single item and returns it.
`default TYPE`	`result()`	Deprecated. Use `optionalResult()` instead
`java.util.List<? extends TYPE>`	`results()`	Performs the search and returns the found items.
`default 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.
`default java.util.stream.Stream<TYPE>`	`stream()`	Returns a stream of results.
`default Finder<TYPE>`	`withContext(java.lang.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
default Finder<TYPE> 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 <ANOTHER_TYPE> Finder<ANOTHER_TYPE> ofType(@Nonnull
                                                   java.lang.Class<ANOTHER_TYPE> type)
```
    Tells the Finder that the specified type of results is expected.
    
    Type Parameters:
    
    ANOTHER_TYPE - the static type
    
    Parameters:
    
    type - the dynamic type
    
    Returns:
    
    the Finder
  - sort
```
@Nonnull
default 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
  - results
```
@Nonnull
java.util.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
  - optionalResult
```
@Nonnull
default java.util.Optional<TYPE> 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<TYPE> 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<TYPE> stream()
```
    Returns a stream of results.
    
    Returns:
    
    the stream
    
    Since:
    
    3.2-ALPHA-1 (previously in Finder8)
  - iterator
```
@Nonnull
default java.util.Iterator<TYPE> iterator()
```
    Returns am iterator of results.
    
    Returns:
    
    the iterator
    
    Since:
    
    3.2-ALPHA-1 (previously in Finder8)
  - result
```
@Nonnull
@Deprecated
default TYPE 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 TYPE 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 <T> Finder<T> empty()
```
    Returns an empty Finder.
    
    Type Parameters:
    
    T - the type of the Finder
    
    Returns:
    
    the empty Finder
    
    Since:
    
    3.2-ALPHA-1 (previously in HierarchicFinderSupport.emptyFinder())
  - ofCloned
```
@Nonnull
static <T> Finder<T> ofCloned(@Nonnull
                              java.util.Collection<T> items)
```
    Returns a wrapped Finder on a given collection of elements. The collection is cloned and will be immutable
    
    Type Parameters:
    
    T - the type of the Finder
    
    Parameters:
    
    items - the objects to wrap
    
    Returns:
    
    the wrapped Finder
    
    Since:
    
    3.2-ALPHA-1

Interface Finder<TYPE>

Nested Class Summary

Method Summary

Method Detail

from

max

withContext

ofType

sort

sort

results

count

optionalResult

optionalFirstResult

stream

iterator

result

firstResult

empty

ofCloned