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 Link icon

    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 Link icon

    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 Link icon

    • from Link icon

      @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 Link icon

      @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 Link icon

      @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 Link icon

      @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 Link icon

      @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 Link icon

      @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 Link icon

      @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 Link icon

      @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 Link icon

      @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 Link icon

      @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 Link icon

      @Nonnull List<T> results()
      Performs the search and returns the found items.
      Returns:
      the searched items

    • count Link icon

      @Nonnegative int count()
      Performs the search and returns the count of found items.
      Returns:
      the count of found items

    • optionalResult Link icon

      @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 Link icon

      @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 Link icon

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

    • iterator Link icon

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

    • forEach Link icon

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

    • result Link icon

      @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 Link icon

      @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 Link icon

      @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 Link icon

      @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 Link icon

      @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 Link icon

      @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 Link icon

      @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