Package it.tidalwave.util
Interface Finder<TYPE>
-
- All Superinterfaces:
java.lang.Cloneable
,java.io.Serializable
- All Known Subinterfaces:
ExtendedFinderSupport<TYPE,EXTENDED_FINDER>
,PersonFinder
- All Known Implementing Classes:
FinderSupport
,PersonFinderImpl2a
,PersonFinderImpl2b
,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 specificFinder.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 tosort(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 emptyFinder
.default TYPE
firstResult()
Deprecated.UseoptionalFirstResult()
insteadFinder<TYPE>
from(int firstResult)
Tells theFinder
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 theFinder
that only a maximum number of found items will be returned.static <T> Finder<T>
ofCloned(java.util.Collection<T> items)
Returns a wrappedFinder
on a given collection of elements.default <ANOTHER_TYPE>
Finder<ANOTHER_TYPE>ofType(java.lang.Class<ANOTHER_TYPE> type)
Tells theFinder
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.UseoptionalResult()
insteadjava.util.List<? extends TYPE>
results()
Performs the search and returns the found items.default Finder<TYPE>
sort(Finder.SortCriterion criterion)
Tells theFinder
that results will be sorted according to the given criterion, in ascending direction.Finder<TYPE>
sort(Finder.SortCriterion criterion, Finder.SortDirection direction)
Tells theFinder
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 theFinder
that results should be created with the given context.
-
-
-
Method Detail
-
from
@Nonnull Finder<TYPE> from(@Nonnegative int firstResult)
Tells theFinder
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 theFinder
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 theFinder
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 theFinder
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 theFinder
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 theFinder
that results will be sorted according to the given criterion and direction.- Parameters:
criterion
- the sort criteriondirection
- 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.UseoptionalResult()
insteadPerforms 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 anythingjava.lang.RuntimeException
- if the search returned more than one single item
-
firstResult
@Nonnull @Deprecated default TYPE firstResult() throws NotFoundException
Deprecated.UseoptionalFirstResult()
insteadPerforms 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 emptyFinder
.- Type Parameters:
T
- the type of theFinder
- Returns:
- the empty
Finder
- Since:
- 3.2-ALPHA-1 (previously in FinderSupport.emptyFinder())
-
ofCloned
@Nonnull static <T> Finder<T> ofCloned(@Nonnull java.util.Collection<T> items)
Returns a wrappedFinder
on a given collection of elements. The collection is cloned and will be immutable- Type Parameters:
T
- the type of theFinder
- Parameters:
items
- the objects to wrap- Returns:
- the wrapped
Finder
- Since:
- 3.2-ALPHA-1
-
-