Package it.tidalwave.util

Interface Finder<T>

All Superinterfaces:
Cloneable, Serializable
All Known Subinterfaces:
ExtendedFinderSupport<T,F>, FinderWithId<T,F>
All Known Implementing Classes:
FinderWithIdMapSupport, FinderWithIdSupport, HierarchicFinderSupport, SimpleFinderSupport
public interface Finder<T> extends Cloneable, 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 enum 
    Finder.SortDirection
    An enumeration to define the direction of a sort (ascending or descending).

  • Method Summary

    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
    default void
    forEach(Consumer<? super T> consumer)
    Iterates through results.
    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(Optional<Integer> firstResult)
    Tells the Finder that only a subset of found items will be returned, starting from the given position.
    default Finder<T>
    from(OptionalInt firstResult)
    Tells the Finder that only a subset of found items will be returned, starting from the given position.
    default Iterator<T>
    iterator()
    Returns an iterator of results.
    static <U, V> Finder<U>
    mapping(Finder<V> delegate, 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(Optional<Integer> maxResults)
    Tells the Finder that only a maximum number of found items will be returned.
    default Finder<T>
    max(OptionalInt maxResults)
    Tells the Finder that only a maximum number of found items will be returned.
    static <U> Finder<U>
    ofCloned(Collection<? extends U> items)
    Returns a wrapped Finder on a given collection of elements.
    static <U> Finder<U>
    ofProvider(BiFunction<Integer,Integer,? extends Collection<? extends U>> provider)
    Returns a wrapped Finder on a given function to provide results.
    static <U> Finder<U>
    ofSupplier(Supplier<? extends Collection<? extends U>> supplier)
    Returns a wrapped Finder on a given supplier.
    default <U> Finder<U>
    ofType(Class<U> type)
    Tells the Finder that the specified type of results is expected.
    default Optional<T>
    optionalFirstResult()
    Performs the search and returns only the first found item.
    default Optional<T>
    optionalResult()
    Performs the search assuming that it will return a single item and returns it.
    default T
    result()
    Deprecated.
    Use optionalResult() instead
    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 Stream<T>
    stream()
    Returns a stream of results.
    default Finder<T>
    withContext(Object context)
    Tells the Finder that results should be created with the given context.

  • Method Details

    • 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 Optional<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

    • from

      @Nonnull default Finder<T> from(@Nonnull OptionalInt 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-22

    • 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 Optional<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

    • max

      @Nonnull default Finder<T> max(@Nonnull OptionalInt 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-22

    • withContext

      @Nonnull default Finder<T> 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 default <U> Finder<U> ofType(@Nonnull Class<U> 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 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 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:
      RuntimeException - if the search returned more than one single item
      Since:
      3.2-ALPHA-1 (previously in Finder8)

    • optionalFirstResult

      @Nonnull default 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 Stream<T> stream()
      Returns a stream of results.
      Returns:
      the stream
      Since:
      3.2-ALPHA-1 (previously in Finder8)

    • iterator

      @Nonnull default Iterator<T> iterator()
      Returns an iterator of results.
      Returns:
      the iterator
      Since:
      3.2-ALPHA-1 (previously in Finder8)

    • forEach

      default void forEach(@Nonnull Consumer<? super T> consumer)
      Iterates through results.
      Parameters:
      consumer - the consumer
      Since:
      3.2-ALPHA-22

    • result

      @Nonnull @Deprecated default T result() throws NotFoundException, 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
      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 <U> Finder<U> 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 <U> Finder<U> ofCloned(@Nonnull 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

      @Nonnull static <U> Finder<U> ofSupplier(@Nonnull Supplier<? extends 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:

    • ofProvider

      @Nonnull static <U> Finder<U> ofProvider(@Nonnull BiFunction<Integer,Integer,? extends 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:

    • mapping

      @Nonnull static <U, V> Finder<U> mapping(@Nonnull Finder<V> delegate, @Nonnull 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