Class Guavate


  • public final class Guavate
    extends java.lang.Object
    Utilities that help bridge the gap between Java 8 and Google Guava.

    Guava has the FluentIterable concept which is similar to streams. In many ways, fluent iterable is nicer, because it directly binds to the immutable collection classes. However, on balance it seems wise to use the stream API rather than FluentIterable in Java 8.

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static java.lang.Class<?> callerClass​(int callStackDepth)
      Finds the caller class.
      static <T> java.util.concurrent.CompletableFuture<java.util.List<T>> combineFuturesAsList​(java.util.List<? extends java.util.concurrent.CompletableFuture<? extends T>> futures)
      Converts a list of futures to a single future, combining the values into a list.
      static <K,​V,​F extends java.util.concurrent.CompletableFuture<? extends V>>
      java.util.concurrent.CompletableFuture<java.util.Map<K,​V>>
      combineFuturesAsMap​(java.util.Map<K,​F> futures)
      Converts a map of futures to a single future.
      static <T> com.google.common.collect.ImmutableList<T> concatToList​(java.lang.Iterable<? extends T>... iterables)
      Concatenates a number of iterables into a single list.
      static <T> java.util.function.BinaryOperator<T> ensureOnlyOne()
      Reducer used in a stream to ensure there is no more than one matching element.
      static <K,​V>
      java.util.stream.Collector<java.util.Map.Entry<K,​V>,​?,​com.google.common.collect.ImmutableMap<K,​V>>
      entriesToImmutableMap()
      Collector used at the end of a stream to build an immutable map from a stream containing map entries.
      static <K,​V>
      java.util.Map.Entry<K,​V>
      entry​(K key, V value)
      Creates a single Map.Entry.
      static <T> java.util.Optional<T> firstNonEmpty​(java.util.function.Supplier<java.util.Optional<? extends T>>... suppliers)
      Uses a number of suppliers to create a single optional result.
      static <T> java.util.Optional<T> firstNonEmpty​(java.util.Optional<? extends T>... optionals)
      Chooses the first optional that is not empty.
      static <R> java.util.function.Predicate<R> not​(java.util.function.Predicate<R> predicate)
      Returns a predicate that negates the original.
      static <K,​V>
      java.util.stream.Collector<Pair<K,​V>,​?,​com.google.common.collect.ImmutableMap<K,​V>>
      pairsToImmutableMap()
      Collector used at the end of a stream to build an immutable map from a stream containing pairs.
      static <T> java.util.concurrent.CompletableFuture<T> poll​(java.util.concurrent.ScheduledExecutorService executorService, java.time.Duration initialDelay, java.time.Duration frequency, java.util.function.Supplier<T> pollingTask)
      Polls on a regular frequency until a result is found.
      static <T> java.util.stream.Stream<T> stream​(java.lang.Iterable<T> iterable)
      Converts an iterable to a serial stream.
      static <T> java.util.stream.Stream<T> stream​(java.util.Optional<T> optional)
      Converts an optional to a stream with zero or one elements.
      static <T,​S extends java.util.concurrent.CompletableFuture<? extends T>>
      java.util.stream.Collector<S,​?,​java.util.concurrent.CompletableFuture<java.util.List<T>>>
      toCombinedFuture()
      Collector used at the end of a stream to convert a list of futures to a single future, combining the values into a list.
      static <K,​V,​F extends java.util.concurrent.CompletableFuture<? extends V>>
      java.util.stream.Collector<java.util.Map.Entry<K,​F>,​?,​java.util.concurrent.CompletableFuture<java.util.Map<K,​V>>>
      toCombinedFutureMap()
      Collector used at the end of a stream to convert a map of futures to a single future, combining the values into a map.
      static <T> java.util.stream.Collector<T,​com.google.common.collect.ImmutableList.Builder<T>,​com.google.common.collect.ImmutableList<T>> toImmutableList()
      Collector used at the end of a stream to build an immutable list.
      static <T,​K>
      java.util.stream.Collector<T,​?,​com.google.common.collect.ImmutableListMultimap<K,​T>>
      toImmutableListMultimap​(java.util.function.Function<? super T,​? extends K> keyExtractor)
      Collector used at the end of a stream to build an immutable multimap.
      static <T,​K,​V>
      java.util.stream.Collector<T,​?,​com.google.common.collect.ImmutableListMultimap<K,​V>>
      toImmutableListMultimap​(java.util.function.Function<? super T,​? extends K> keyExtractor, java.util.function.Function<? super T,​? extends V> valueExtractor)
      Collector used at the end of a stream to build an immutable multimap.
      static <T,​K>
      java.util.stream.Collector<T,​?,​com.google.common.collect.ImmutableMap<K,​T>>
      toImmutableMap​(java.util.function.Function<? super T,​? extends K> keyExtractor)
      Collector used at the end of a stream to build an immutable map.
      static <T,​K,​V>
      java.util.stream.Collector<T,​?,​com.google.common.collect.ImmutableMap<K,​V>>
      toImmutableMap​(java.util.function.Function<? super T,​? extends K> keyExtractor, java.util.function.Function<? super T,​? extends V> valueExtractor)
      Collector used at the end of a stream to build an immutable map.
      static <T,​K,​V>
      java.util.stream.Collector<T,​java.util.Map<K,​V>,​com.google.common.collect.ImmutableMap<K,​V>>
      toImmutableMap​(java.util.function.Function<? super T,​? extends K> keyExtractor, java.util.function.Function<? super T,​? extends V> valueExtractor, java.util.function.BiFunction<? super V,​? super V,​? extends V> mergeFn)
      Collector used at the end of a stream to build an immutable map.
      static <T> java.util.stream.Collector<T,​com.google.common.collect.ImmutableMultiset.Builder<T>,​com.google.common.collect.ImmutableMultiset<T>> toImmutableMultiset()
      Collector used at the end of a stream to build an immutable multiset.
      static <T> java.util.stream.Collector<T,​com.google.common.collect.ImmutableSet.Builder<T>,​com.google.common.collect.ImmutableSet<T>> toImmutableSet()
      Collector used at the end of a stream to build an immutable set.
      static <T,​K>
      java.util.stream.Collector<T,​?,​com.google.common.collect.ImmutableSetMultimap<K,​T>>
      toImmutableSetMultimap​(java.util.function.Function<? super T,​? extends K> keyExtractor)
      Collector used at the end of a stream to build an immutable multimap.
      static <T,​K,​V>
      java.util.stream.Collector<T,​?,​com.google.common.collect.ImmutableSetMultimap<K,​V>>
      toImmutableSetMultimap​(java.util.function.Function<? super T,​? extends K> keyExtractor, java.util.function.Function<? super T,​? extends V> valueExtractor)
      Collector used at the end of a stream to build an immutable multimap.
      static <T,​K extends java.lang.Comparable<?>>
      java.util.stream.Collector<T,​?,​com.google.common.collect.ImmutableSortedMap<K,​T>>
      toImmutableSortedMap​(java.util.function.Function<? super T,​? extends K> keyExtractor)
      Collector used at the end of a stream to build an immutable sorted map.
      static <T,​K extends java.lang.Comparable<?>,​V>
      java.util.stream.Collector<T,​?,​com.google.common.collect.ImmutableSortedMap<K,​V>>
      toImmutableSortedMap​(java.util.function.Function<? super T,​? extends K> keyExtractor, java.util.function.Function<? super T,​? extends V> valueExtractor)
      Collector used at the end of a stream to build an immutable sorted map.
      static <T extends java.lang.Comparable<?>>
      java.util.stream.Collector<T,​com.google.common.collect.ImmutableSortedSet.Builder<T>,​com.google.common.collect.ImmutableSortedSet<T>>
      toImmutableSortedSet()
      Collector used at the end of a stream to build an immutable sorted set.
      static <T> java.util.stream.Collector<T,​com.google.common.collect.ImmutableSortedSet.Builder<T>,​com.google.common.collect.ImmutableSortedSet<T>> toImmutableSortedSet​(java.util.Comparator<? super T> comparator)
      Collector used at the end of a stream to build an immutable sorted set.
      static <A,​B>
      java.util.stream.Stream<Pair<A,​B>>
      zip​(java.util.stream.Stream<A> stream1, java.util.stream.Stream<B> stream2)
      Creates a stream that combines two other streams, continuing until either stream ends.
      static <T> java.util.stream.Stream<ObjIntPair<T>> zipWithIndex​(java.util.stream.Stream<T> stream)
      Creates a stream that wraps a stream with the index.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Method Detail

      • concatToList

        @SafeVarargs
        public static <T> com.google.common.collect.ImmutableList<T> concatToList​(java.lang.Iterable<? extends T>... iterables)
        Concatenates a number of iterables into a single list.

        This is harder than it should be, a method Stream.of(Iterable) would have been appropriate, but cannot be added now.

        Type Parameters:
        T - the type of element in the iterable
        Parameters:
        iterables - the iterables to combine
        Returns:
        the list that combines the inputs
      • firstNonEmpty

        @SafeVarargs
        public static <T> java.util.Optional<T> firstNonEmpty​(java.util.function.Supplier<java.util.Optional<? extends T>>... suppliers)
        Uses a number of suppliers to create a single optional result.

        This invokes each supplier in turn until a non empty optional is returned. As such, not all suppliers are necessarily invoked.

        The Java 8 Optional class does not have an or method, so this provides an alternative.

        Type Parameters:
        T - the type of element in the optional
        Parameters:
        suppliers - the suppliers to combine
        Returns:
        the first non empty optional
      • firstNonEmpty

        @SafeVarargs
        public static <T> java.util.Optional<T> firstNonEmpty​(java.util.Optional<? extends T>... optionals)
        Chooses the first optional that is not empty.

        The Java 8 Optional class does not have an or method, so this provides an alternative.

        Type Parameters:
        T - the type of element in the optional
        Parameters:
        optionals - the optionals to combine
        Returns:
        the first non empty optional
      • entry

        public static <K,​V> java.util.Map.Entry<K,​V> entry​(K key,
                                                                       V value)
        Creates a single Map.Entry.

        The entry is immutable.

        Type Parameters:
        K - the type of the key
        V - the type of the value
        Parameters:
        key - the key
        value - the value
        Returns:
        the map entry
      • stream

        public static <T> java.util.stream.Stream<T> stream​(java.lang.Iterable<T> iterable)
        Converts an iterable to a serial stream.

        This is harder than it should be, a method Stream.of(Iterable) would have been appropriate, but cannot be added now.

        Type Parameters:
        T - the type of element in the iterable
        Parameters:
        iterable - the iterable to convert
        Returns:
        a stream of the elements in the iterable
      • stream

        public static <T> java.util.stream.Stream<T> stream​(java.util.Optional<T> optional)
        Converts an optional to a stream with zero or one elements.
        Type Parameters:
        T - the type of optional element
        Parameters:
        optional - the optional
        Returns:
        a stream containing a single value if the optional has a value, else a stream with no values.
      • zipWithIndex

        public static <T> java.util.stream.Stream<ObjIntPair<T>> zipWithIndex​(java.util.stream.Stream<T> stream)
        Creates a stream that wraps a stream with the index.

        Each input object is decorated with an ObjIntPair. The int is the index of the element in the stream.

        Type Parameters:
        T - the type of the stream
        Parameters:
        stream - the stream to index
        Returns:
        a stream of pairs, containing the element and index
      • zip

        public static <A,​B> java.util.stream.Stream<Pair<A,​B>> zip​(java.util.stream.Stream<A> stream1,
                                                                               java.util.stream.Stream<B> stream2)
        Creates a stream that combines two other streams, continuing until either stream ends.

        Each pair of input objects is combined into a Pair.

        Type Parameters:
        A - the type of the first stream
        B - the type of the second stream
        Parameters:
        stream1 - the first stream
        stream2 - the first stream
        Returns:
        a stream of pairs, one from each stream
      • not

        public static <R> java.util.function.Predicate<R> not​(java.util.function.Predicate<R> predicate)
        Returns a predicate that negates the original.

        The JDK provides Predicate.negate() however this requires a predicate. Sometimes, it can be useful to have a static method to achieve this.

          stream.filter(not(String::isEmpty))
         
        Type Parameters:
        R - the type of the object the predicate works on
        Parameters:
        predicate - the predicate to negate
        Returns:
        the negated predicate
      • ensureOnlyOne

        public static <T> java.util.function.BinaryOperator<T> ensureOnlyOne()
        Reducer used in a stream to ensure there is no more than one matching element.

        This method returns an operator that can be used with Stream.reduce(BinaryOperator) that returns either zero or one elements from the stream. Unlike Stream.findFirst() or Stream.findAny(), this approach ensures an exception is thrown if there is more than one element in the stream.

        This would be used as follows:

           stream.filter(...).reduce(Guavate.ensureOnlyOne()).get();
         
        Type Parameters:
        T - the type of element in the stream
        Returns:
        the operator
      • toImmutableList

        public static <T> java.util.stream.Collector<T,​com.google.common.collect.ImmutableList.Builder<T>,​com.google.common.collect.ImmutableList<T>> toImmutableList()
        Collector used at the end of a stream to build an immutable list.

        A collector is used to gather data at the end of a stream operation. This method returns a collector allowing streams to be gathered into an ImmutableList.

        Type Parameters:
        T - the type of element in the list
        Returns:
        the immutable list collector
      • toImmutableSet

        public static <T> java.util.stream.Collector<T,​com.google.common.collect.ImmutableSet.Builder<T>,​com.google.common.collect.ImmutableSet<T>> toImmutableSet()
        Collector used at the end of a stream to build an immutable set.

        A collector is used to gather data at the end of a stream operation. This method returns a collector allowing streams to be gathered into an ImmutableSet.

        Type Parameters:
        T - the type of element in the set
        Returns:
        the immutable set collector
      • toImmutableSortedSet

        public static <T extends java.lang.Comparable<?>> java.util.stream.Collector<T,​com.google.common.collect.ImmutableSortedSet.Builder<T>,​com.google.common.collect.ImmutableSortedSet<T>> toImmutableSortedSet()
        Collector used at the end of a stream to build an immutable sorted set.

        A collector is used to gather data at the end of a stream operation. This method returns a collector allowing streams to be gathered into an ImmutableSet.

        Type Parameters:
        T - the type of element in the sorted set
        Returns:
        the immutable sorted set collector
      • toImmutableSortedSet

        public static <T> java.util.stream.Collector<T,​com.google.common.collect.ImmutableSortedSet.Builder<T>,​com.google.common.collect.ImmutableSortedSet<T>> toImmutableSortedSet​(java.util.Comparator<? super T> comparator)
        Collector used at the end of a stream to build an immutable sorted set.

        A collector is used to gather data at the end of a stream operation. This method returns a collector allowing streams to be gathered into an ImmutableSet.

        Type Parameters:
        T - the type of element in the sorted set
        Parameters:
        comparator - the comparator
        Returns:
        the immutable sorted set collector
      • toImmutableMultiset

        public static <T> java.util.stream.Collector<T,​com.google.common.collect.ImmutableMultiset.Builder<T>,​com.google.common.collect.ImmutableMultiset<T>> toImmutableMultiset()
        Collector used at the end of a stream to build an immutable multiset.

        A collector is used to gather data at the end of a stream operation. This method returns a collector allowing streams to be gathered into an ImmutableMultiset.

        Type Parameters:
        T - the type of element in the multiset
        Returns:
        the immutable multiset collector
      • toImmutableMap

        public static <T,​K> java.util.stream.Collector<T,​?,​com.google.common.collect.ImmutableMap<K,​T>> toImmutableMap​(java.util.function.Function<? super T,​? extends K> keyExtractor)
        Collector used at the end of a stream to build an immutable map.

        A collector is used to gather data at the end of a stream operation. This method returns a collector allowing streams to be gathered into an ImmutableMap, retaining insertion order.

        This returns a map by extracting a key from each element. The input stream must resolve to unique keys. The value associated with each key is the stream element. See Collectors.toMap(Function, Function) for more details.

        Type Parameters:
        T - the type of the stream elements
        K - the type of the keys in the result map
        Parameters:
        keyExtractor - function to produce keys from stream elements
        Returns:
        the immutable map collector
        Throws:
        java.lang.IllegalArgumentException - if the same key is generated twice
      • toImmutableMap

        public static <T,​K,​V> java.util.stream.Collector<T,​?,​com.google.common.collect.ImmutableMap<K,​V>> toImmutableMap​(java.util.function.Function<? super T,​? extends K> keyExtractor,
                                                                                                                                                       java.util.function.Function<? super T,​? extends V> valueExtractor)
        Collector used at the end of a stream to build an immutable map.

        A collector is used to gather data at the end of a stream operation. This method returns a collector allowing streams to be gathered into an ImmutableMap, retaining insertion order.

        This returns a map by converting each stream element to a key and value. The input stream must resolve to unique keys. See Collectors.toMap(Function, Function) for more details.

        Type Parameters:
        T - the type of the stream elements
        K - the type of the keys in the result map
        V - the type of the values in the result map
        Parameters:
        keyExtractor - function to produce keys from stream elements
        valueExtractor - function to produce values from stream elements
        Returns:
        the immutable map collector
        Throws:
        java.lang.IllegalArgumentException - if the same key is generated twice
      • toImmutableMap

        public static <T,​K,​V> java.util.stream.Collector<T,​java.util.Map<K,​V>,​com.google.common.collect.ImmutableMap<K,​V>> toImmutableMap​(java.util.function.Function<? super T,​? extends K> keyExtractor,
                                                                                                                                                                              java.util.function.Function<? super T,​? extends V> valueExtractor,
                                                                                                                                                                              java.util.function.BiFunction<? super V,​? super V,​? extends V> mergeFn)
        Collector used at the end of a stream to build an immutable map.

        A collector is used to gather data at the end of a stream operation. This method returns a collector allowing streams to be gathered into an ImmutableMap, retaining insertion order.

        This returns a map by converting each stream element to a key and value. If the same key is generated more than once the merge function is applied to the values and the return value of the function is used as the value in the map.

        Type Parameters:
        T - the type of the stream elements
        K - the type of the keys in the result map
        V - the type of the values in the result map
        Parameters:
        keyExtractor - function to produce keys from stream elements
        valueExtractor - function to produce values from stream elements
        mergeFn - function to merge values with the same key
        Returns:
        the immutable map collector
      • toImmutableSortedMap

        public static <T,​K extends java.lang.Comparable<?>> java.util.stream.Collector<T,​?,​com.google.common.collect.ImmutableSortedMap<K,​T>> toImmutableSortedMap​(java.util.function.Function<? super T,​? extends K> keyExtractor)
        Collector used at the end of a stream to build an immutable sorted map.

        A collector is used to gather data at the end of a stream operation. This method returns a collector allowing streams to be gathered into an ImmutableSortedMap.

        This returns a map by extracting a key from each element. The input stream must resolve to unique keys. The value associated with each key is the stream element. See Collectors.toMap(Function, Function) for more details.

        Type Parameters:
        T - the type of the stream elements
        K - the type of the keys in the result map
        Parameters:
        keyExtractor - function to produce keys from stream elements
        Returns:
        the immutable sorted map collector
        Throws:
        java.lang.IllegalArgumentException - if the same key is generated twice
      • toImmutableSortedMap

        public static <T,​K extends java.lang.Comparable<?>,​V> java.util.stream.Collector<T,​?,​com.google.common.collect.ImmutableSortedMap<K,​V>> toImmutableSortedMap​(java.util.function.Function<? super T,​? extends K> keyExtractor,
                                                                                                                                                                                                   java.util.function.Function<? super T,​? extends V> valueExtractor)
        Collector used at the end of a stream to build an immutable sorted map.

        A collector is used to gather data at the end of a stream operation. This method returns a collector allowing streams to be gathered into an ImmutableSortedMap.

        This returns a map by converting each stream element to a key and value. The input stream must resolve to unique keys. See Collectors.toMap(Function, Function) for more details.

        Type Parameters:
        T - the type of the stream elements
        K - the type of the keys in the result map
        V - the type of the values in the result map
        Parameters:
        keyExtractor - function to produce keys from stream elements
        valueExtractor - function to produce values from stream elements
        Returns:
        the immutable sorted map collector
        Throws:
        java.lang.IllegalArgumentException - if the same key is generated twice
      • toImmutableListMultimap

        public static <T,​K> java.util.stream.Collector<T,​?,​com.google.common.collect.ImmutableListMultimap<K,​T>> toImmutableListMultimap​(java.util.function.Function<? super T,​? extends K> keyExtractor)
        Collector used at the end of a stream to build an immutable multimap.

        A collector is used to gather data at the end of a stream operation. This method returns a collector allowing streams to be gathered into an ImmutableListMultimap.

        This returns a multimap by extracting a key from each element. The value associated with each key is the stream element. Stream elements may be converted to the same key, with the values forming a multimap list. See Collectors.groupingBy(Function) for more details.

        Type Parameters:
        T - the type of the stream elements
        K - the type of the keys in the result multimap
        Parameters:
        keyExtractor - function to produce keys from stream elements
        Returns:
        the immutable multimap collector
      • toImmutableListMultimap

        public static <T,​K,​V> java.util.stream.Collector<T,​?,​com.google.common.collect.ImmutableListMultimap<K,​V>> toImmutableListMultimap​(java.util.function.Function<? super T,​? extends K> keyExtractor,
                                                                                                                                                                         java.util.function.Function<? super T,​? extends V> valueExtractor)
        Collector used at the end of a stream to build an immutable multimap.

        A collector is used to gather data at the end of a stream operation. This method returns a collector allowing streams to be gathered into an ImmutableListMultimap.

        This returns a multimap by converting each stream element to a key and value. Stream elements may be converted to the same key, with the values forming a multimap list.

        Type Parameters:
        T - the type of the stream elements
        K - the type of the keys in the result multimap
        V - the type of the values in the result multimap
        Parameters:
        keyExtractor - function to produce keys from stream elements
        valueExtractor - function to produce values from stream elements
        Returns:
        the immutable multimap collector
      • toImmutableSetMultimap

        public static <T,​K> java.util.stream.Collector<T,​?,​com.google.common.collect.ImmutableSetMultimap<K,​T>> toImmutableSetMultimap​(java.util.function.Function<? super T,​? extends K> keyExtractor)
        Collector used at the end of a stream to build an immutable multimap.

        A collector is used to gather data at the end of a stream operation. This method returns a collector allowing streams to be gathered into an ImmutableSetMultimap.

        This returns a multimap by extracting a key from each element. The value associated with each key is the stream element. Stream elements may be converted to the same key, with the values forming a multimap set. See Collectors.groupingBy(Function) for more details.

        Type Parameters:
        T - the type of the stream elements
        K - the type of the keys in the result multimap
        Parameters:
        keyExtractor - function to produce keys from stream elements
        Returns:
        the immutable multimap collector
      • toImmutableSetMultimap

        public static <T,​K,​V> java.util.stream.Collector<T,​?,​com.google.common.collect.ImmutableSetMultimap<K,​V>> toImmutableSetMultimap​(java.util.function.Function<? super T,​? extends K> keyExtractor,
                                                                                                                                                                       java.util.function.Function<? super T,​? extends V> valueExtractor)
        Collector used at the end of a stream to build an immutable multimap.

        A collector is used to gather data at the end of a stream operation. This method returns a collector allowing streams to be gathered into an ImmutableSetMultimap.

        This returns a multimap by converting each stream element to a key and value. Stream elements may be converted to the same key, with the values forming a multimap set.

        Type Parameters:
        T - the type of the stream elements
        K - the type of the keys in the result multimap
        V - the type of the values in the result multimap
        Parameters:
        keyExtractor - function to produce keys from stream elements
        valueExtractor - function to produce values from stream elements
        Returns:
        the immutable multimap collector
      • entriesToImmutableMap

        public static <K,​V> java.util.stream.Collector<java.util.Map.Entry<K,​V>,​?,​com.google.common.collect.ImmutableMap<K,​V>> entriesToImmutableMap()
        Collector used at the end of a stream to build an immutable map from a stream containing map entries. This is a common case if a map's entrySet has undergone a filter operation. For example:
           
               Map<String, Integer> input = ImmutableMap.of("a", 1, "b", 2, "c", 3, "d", 4);
               ImmutableMap<String, Integer> output =
                 input.entrySet()
                   .stream()
                   .filter(e -> e.getValue() % 2 == 1)
                   .collect(entriesToImmutableMap());
        
               // Produces map with "a" -> 1, "c" -> 3, "e" -> 5
           
         

        A collector is used to gather data at the end of a stream operation. This method returns a collector allowing streams to be gathered into an ImmutableMap.

        This returns a map by converting each Map.Entry to a key and value. The input stream must resolve to unique keys.

        Type Parameters:
        K - the type of the keys in the result map
        V - the type of the values in the result map
        Returns:
        the immutable map collector
        Throws:
        java.lang.IllegalArgumentException - if the same key is generated twice
      • pairsToImmutableMap

        public static <K,​V> java.util.stream.Collector<Pair<K,​V>,​?,​com.google.common.collect.ImmutableMap<K,​V>> pairsToImmutableMap()
        Collector used at the end of a stream to build an immutable map from a stream containing pairs. This is a common case if a map's entrySet has undergone a map operation with the Map.Entry converted to a Pair. For example:
           
               Map<String, Integer> input = ImmutableMap.of("a", 1, "b", 2, "c", 3, "d", 4);
               ImmutableMap<String, Double> output =
                 input.entrySet()
                   .stream()
                   .map(e -> Pair.of(e.getKey().toUpperCase(), Math.pow(e.getValue(), 2)))
                   .collect(pairsToImmutableMap());
        
               // Produces map with "A" -> 1.0, "B" -> 4.0, "C" -> 9.0, "D" -> 16.0
           
         

        A collector is used to gather data at the end of a stream operation. This method returns a collector allowing streams to be gathered into an ImmutableMap.

        This returns a map by converting each stream element to a key and value. The input stream must resolve to unique keys.

        Type Parameters:
        K - the type of the keys in the result map
        V - the type of the values in the result map
        Returns:
        the immutable map collector
        Throws:
        java.lang.IllegalArgumentException - if the same key is generated twice
      • combineFuturesAsList

        public static <T> java.util.concurrent.CompletableFuture<java.util.List<T>> combineFuturesAsList​(java.util.List<? extends java.util.concurrent.CompletableFuture<? extends T>> futures)
        Converts a list of futures to a single future, combining the values into a list.

        The CompletableFuture.allOf(CompletableFuture...) method is useful but it returns Void. This method combines the futures but also returns the resulting value as a list. Effectively, this converts List<CompletableFuture<T>> to CompletableFuture<List<T>>.

        If any input future completes exceptionally, the result will also complete exceptionally.

        Type Parameters:
        T - the type of the values in the list
        Parameters:
        futures - the futures to convert, may be empty
        Returns:
        a future that combines the input futures as a list
      • toCombinedFuture

        public static <T,​S extends java.util.concurrent.CompletableFuture<? extends T>> java.util.stream.Collector<S,​?,​java.util.concurrent.CompletableFuture<java.util.List<T>>> toCombinedFuture()
        Collector used at the end of a stream to convert a list of futures to a single future, combining the values into a list.

        A collector is used to gather data at the end of a stream operation. This method returns a collector allowing a stream of futures to be combined into a single future. This converts List<CompletableFuture<T>> to CompletableFuture<List<T>>.

        Type Parameters:
        S - the type of the input futures
        T - the type of the values
        Returns:
        a collector that combines the input futures as a list
      • combineFuturesAsMap

        public static <K,​V,​F extends java.util.concurrent.CompletableFuture<? extends V>> java.util.concurrent.CompletableFuture<java.util.Map<K,​V>> combineFuturesAsMap​(java.util.Map<K,​F> futures)
        Converts a map of futures to a single future.

        This is similar to combineFuturesAsList(List) but for maps. Effectively, this converts Map<K, CompletableFuture<V>> to CompletableFuture<Map<K, V>>.

        If any input future completes exceptionally, the result will also complete exceptionally.

        Type Parameters:
        K - the type of the keys in the map
        V - the type of the values in the map
        F - the type of the futures
        Parameters:
        futures - the futures to convert, may be empty
        Returns:
        a future that combines the input futures as a map
      • toCombinedFutureMap

        public static <K,​V,​F extends java.util.concurrent.CompletableFuture<? extends V>> java.util.stream.Collector<java.util.Map.Entry<K,​F>,​?,​java.util.concurrent.CompletableFuture<java.util.Map<K,​V>>> toCombinedFutureMap()
        Collector used at the end of a stream to convert a map of futures to a single future, combining the values into a map.

        A collector is used to gather data at the end of a stream operation. This method returns a collector allowing a stream of futures to be combined into a single future. This converts Map<K, CompletableFuture<V>> to CompletableFuture<Map<K, V>>.

        Type Parameters:
        K - the type of the keys in the map
        V - the type of the values in the map
        F - the type of the input futures
        Returns:
        a collector that combines the input futures as a map
      • poll

        public static <T> java.util.concurrent.CompletableFuture<T> poll​(java.util.concurrent.ScheduledExecutorService executorService,
                                                                         java.time.Duration initialDelay,
                                                                         java.time.Duration frequency,
                                                                         java.util.function.Supplier<T> pollingTask)
        Polls on a regular frequency until a result is found.

        Polling is performed via the specified supplier, which must return null until the result is available. If the supplier throws an exception, polling will stop and the future will complete exceptionally.

        If the future is cancelled, the polling will also be cancelled. It is advisable to consider using a timeout when querying the future.

        In most cases, there needs to be an initial request, which might return an identifier to query. This pattern may be useful for that case:

          return CompletableFuture.supplyAsync(initPollingReturningId(), executorService)
              .thenCompose(id -> poll(executorService, delay, freq, performPolling(id)));
          });
         
        Type Parameters:
        T - the result type
        Parameters:
        executorService - the executor service to use for polling
        initialDelay - the initial delay before starting to poll
        frequency - the frequency to poll at
        pollingTask - the task used to poll, returning null when not yet complete
        Returns:
        the future representing the asynchronous operation
      • callerClass

        public static java.lang.Class<?> callerClass​(int callStackDepth)
        Finds the caller class.

        This takes an argument which is the number of stack levels to look back. This will be 2 to return the caller of this method, 3 to return the caller of the caller, and so on.

        Parameters:
        callStackDepth - the depth of the stack to look back
        Returns:
        the caller class