Interface Finder<T>

    • 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.
      Finder<T> 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<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.
      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
      • 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
      • 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 <U> Finder<U> ofType​(@Nonnull
                                     java.lang.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
        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.
        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
                                      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 <U> Finder<U> 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 <U> Finder<U> 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<U> 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