ProducerUtil (de-unkrig-commons 1.1.10)

java.lang.Object
- de.unkrig.commons.lang.protocol.ProducerUtil

public final class ProducerUtil
extends java.lang.Object

Various Producer-related utility methods.

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static interface ProducerUtil.FromArrayProducer<T>
Extends the concept of the Producer by an "index".

Nested Classes
Modifier and Type	Class and Description
`static interface`	`ProducerUtil.FromArrayProducer<T>` Extends the concept of the `Producer` by an "index".

Method Summary

All Methods Static Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`static Producer<java.lang.Boolean>`	`after(long expirationTime)` Returns a "`Producer<Object>`" that produces `true` iff the current time is after the given `expirationTime` (in milliseconds).
`static <T> Producer<T>`	`alternate(T first, T second)`
`static <T> Producer<T>`	`asProducer(ProducerWhichThrows<? extends T,? extends java.lang.RuntimeException> source)` Converts the `source` into a `Producer<T>`.
`static <T,EX extends java.lang.Throwable> ProducerWhichThrows<T,EX>`	`asProducerWhichThrows(Producer<? extends T> source)` Converts the `source` into a `ProducerWhichThrows<T, EX>`.
`static Producer<java.lang.Boolean>`	`atMostEvery(long milliseconds)` Creates and returns a producer for which the first product is `true`, and, for all following products, the time interval between adjacent `true` products will (A) be minimal and (B) never shorter than `milliseconds`.
`static Producer<java.lang.Boolean>`	`atMostEvery(long milliseconds, boolean firstProduct, boolean startAtTrueProduct)` Creates and returns a producer which first produces `firstProduct`, and afterwards products that are `true` iff they are produced `milliseconds` or more after the most recent `true` product, or, iff `!`
`static <T,EX extends java.lang.Throwable> ProducerWhichThrows<T,EX>`	`cache(ProducerWhichThrows<T,? extends EX> delegate, ProducerWhichThrows<java.lang.Boolean,? extends EX> invalidationCondition)` The first product is the first product of the `delegate`; each following product is the next product of the `delegate` if the `invalidationCondition` evaluates to `true`, otherwise it is the previous product.
`static <T,EX extends java.lang.Throwable> ProducerWhichThrows<T,EX>`	`cache(T firstProduct, ProducerWhichThrows<T,? extends EX> delegate, ProducerWhichThrows<java.lang.Boolean,? extends EX> invalidationCondition)` The first product is the `firstProduct`; each following product is the next product of the `delegate` iff the `invalidationCondition` evaluates to `true`, otherwise it is the previous product.
`static <T,EX extends java.lang.Throwable> ProducerWhichThrows<T,EX>`	`cacheAsynchronously(ProducerWhichThrows<java.util.concurrent.Future<T>,? extends EX> delegate, ProducerWhichThrows<java.lang.Boolean,? extends EX> invalidationCondition)` Creates and returns a producer which caches the products of a `delegate` producer asynchronously.
`static <T> Producer<T>`	`compress(Producer<? extends T> delegate, Predicate<? super T> compressable, T compressed)` Discards the elements that the `delegate` produces while they are `compressable`.
`static <T> Producer<T>`	`concat(Producer<? extends T> delegate1, Producer<? extends T> delegate2)`
`static <T> Producer<T>`	`constantProducer(T constant)`
`static Producer<java.lang.Boolean>`	`every(long interval)` Returns a `Producer<Boolean>` who's first evaluation result is `true`, and each following result is `true` iff the last `true` result was returned at least the given `interval` milliseconds ago.
`static <T> ProducerUtil.FromArrayProducer<T>`	`fromArray(T[] delegate)` Produces the elements of the `delegate` array, in ascending index order, and after that an infinite sequence of `null`s.
`static <T> ProducerUtil.FromArrayProducer<T>`	`fromArray(T[] delegate, int from, int to)` Produces the elements `from` ...
`static <T> Producer<T>`	`fromCollection(java.util.Collection<T> delegate)` Produces the elements of the `delegate` collection, in its iteration order, or `null` iff the collection is empty.
`static <T> Producer<T>`	`fromElements(T... elements)`
`static <T> Producer<T>`	`fromIndexTransformer(Transformer<? super java.lang.Integer,T> indexTransformer)` Produces objects based on the number of preceding invocations, i.e. the `indexTransformer` is invoked with subjects '0', '1', '2', ...
`static <T,EX extends java.lang.Throwable> ProducerWhichThrows<T,EX>`	`fromIndexTransformer(TransformerWhichThrows<? super java.lang.Integer,T,EX> indexTransformer)` Produces objects based on the number of preceding invocations, i.e. the `indexTransformer` is invoked with subjects '0', '1', '2', ...
`static <T> Producer<T>`	`fromIterator(java.util.Iterator<T> iterator)` Produces the products of the `iterator`, or `null` iff the `iterator` has no more elements.
`static <T,EX extends java.lang.Throwable> Producer<T>`	`ignoreExceptions(java.lang.Class<EX> exceptionClass, ProducerWhichThrows<T,EX> delegate, T defaultValue)` Wraps the `delegate` such that its declared exception is caught, ignored, and the `defaultValue` is returned.
`static Producer<java.lang.Integer>`	`increasing()`
`static Producer<java.lang.Byte>`	`randomByteProducer(long seed)`
`static <T,ST> Producer<T>`	`sparingProducer(Producer<? extends T> delegate, Predicate<? super ST> condition, ST subject)` Deprecated. Use `cache(ProducerWhichThrows, ProducerWhichThrows)` instead, which has very similar (but not identical) semantics.
`static <T,EX extends java.lang.Throwable> ProducerWhichThrows<T,EX>`	`synchronizedProducer(ProducerWhichThrows<T,EX> delegate)` Creates and returns a proxy to the `delegate` with a synchronized `produce()` method.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - sparingProducer
```
@Deprecated
public static <T,ST> Producer<T> sparingProducer(Producer<? extends T> delegate,
                                                              Predicate<? super ST> condition,
                                                              ST subject)
```
    Deprecated. Use cache(ProducerWhichThrows, ProducerWhichThrows) instead, which has very similar (but not identical) semantics.
    
    The returned Producer calls the delegate iff the condition returns true, otherwise it returns the previous product of the delegate, or null iff the delegate has not yet been called.
    
    Parameters:
    
    subject - The subject argument for the condition
  - every
```
public static Producer<java.lang.Boolean> every(long interval)
```
    Returns a Producer<Boolean> who's first evaluation result is true, and each following result is true iff the last true result was returned at least the given interval milliseconds ago. In other words, the interval between two returned true values is never shorter than interval milliseconds.
  - asProducerWhichThrows
```
public static <T,EX extends java.lang.Throwable> ProducerWhichThrows<T,EX> asProducerWhichThrows(Producer<? extends T> source)
```
    Converts the source into a ProducerWhichThrows<T, EX>.
    This is always possible, because the source is only allowed to throw RuntimeExceptions.
    
    Notice Producer<T> extends ProducerWhichThrows<T, RuntimeException>, thus you don't need this method to convert to ProducerWhichThrows<T, RuntimeException>.
    
    Type Parameters:
    
    T - The product type
    
    EX - The target producer's exception
  - asProducer
```
public static <T> Producer<T> asProducer(ProducerWhichThrows<? extends T,? extends java.lang.RuntimeException> source)
```
    Converts the source into a Producer<T>.
    This is always possible, because both are only allowed to throw RuntimeExceptions.
    
    Type Parameters:
    
    T - The product type
  - fromElements
```
public static <T> Producer<T> fromElements(T... elements)
```
    Returns:
    
    A Producer that produced the given elements
  - fromCollection
```
public static <T> Producer<T> fromCollection(java.util.Collection<T> delegate)
```
    Produces the elements of the delegate collection, in its iteration order, or null iff the collection is empty. The elements are removed from the collection as they are produced.
  - fromArray
```
public static <T> ProducerUtil.FromArrayProducer<T> fromArray(T[] delegate)
```
    Produces the elements of the delegate array, in ascending index order, and after that an infinite sequence of nulls.
  - fromArray
```
public static <T> ProducerUtil.FromArrayProducer<T> fromArray(T[] delegate,
                                                              int from,
                                                              int to)
```
    Produces the elements from ... to-1 of the delegate array, and after that an infinite sequence of nulls.
    
    Throws:
    
    java.lang.IllegalArgumentException - from is less than 0
    
    java.lang.IllegalArgumentException - to is less than from
    
    java.lang.IllegalArgumentException - to is greater than delegate.length
  - fromIterator
```
public static <T> Producer<T> fromIterator(java.util.Iterator<T> iterator)
```
    Produces the products of the iterator, or null iff the iterator has no more elements.
  - fromIndexTransformer
```
public static <T> Producer<T> fromIndexTransformer(Transformer<? super java.lang.Integer,T> indexTransformer)
```
    Produces objects based on the number of preceding invocations, i.e. the indexTransformer is invoked with subjects '0', '1', '2', ...
  - fromIndexTransformer
```
public static <T,EX extends java.lang.Throwable> ProducerWhichThrows<T,EX> fromIndexTransformer(TransformerWhichThrows<? super java.lang.Integer,T,EX> indexTransformer)
```
    Produces objects based on the number of preceding invocations, i.e. the indexTransformer is invoked with subjects '0', '1', '2', ...
  - randomByteProducer
```
public static Producer<java.lang.Byte> randomByteProducer(long seed)
```
    Returns:
    
    A producer which produces bytes through new java.util.Random(seed).nextInt(0x100)
  - constantProducer
```
public static <T> Producer<T> constantProducer(T constant)
```
    Returns:
    
    A producer which always produces the constant
  - compress
```
public static <T> Producer<T> compress(Producer<? extends T> delegate,
                                       Predicate<? super T> compressable,
                                       T compressed)
```
    Discards the elements that the delegate produces while they are compressable. After that, it produces the elements that the delegate produces and are not compressable, and reduces sequences of one or more compressable elements to compressed. line "".
  - alternate
```
public static <T> Producer<T> alternate(T first,
                                        T second)
```
    Returns:
    
    A Producer that produces first, second, first, second, ...
  - increasing
```
public static Producer<java.lang.Integer> increasing()
```
    Returns:
    
    A Producer that produces 0, 1, 2, 3, ...
  - concat
```
public static <T> Producer<T> concat(Producer<? extends T> delegate1,
                                     Producer<? extends T> delegate2)
```
    Returns:
    
    A producer that produces the products of delegate1, and, when that produces null, the products of delegate2
  - cache
```
public static <T,EX extends java.lang.Throwable> ProducerWhichThrows<T,EX> cache(ProducerWhichThrows<T,? extends EX> delegate,
                                                                                 ProducerWhichThrows<java.lang.Boolean,? extends EX> invalidationCondition)
```
    The first product is the first product of the delegate; each following product is the next product of the delegate if the invalidationCondition evaluates to true, otherwise it is the previous product.
    Example:
```
ProducerUtil.cache(delegate, ProducerUtil.atMostEvery(milliseconds))
```
    caches the products of the delegate for milliseconds' time.
    
    The returned PredicateWhichThrows is not synchronized and therefore not thread-safe.
    See Also:
    
    sparingProducer(Producer, Predicate, Object)
  - cache
```
public static <T,EX extends java.lang.Throwable> ProducerWhichThrows<T,EX> cache(@Nullable
                                                                                 T firstProduct,
                                                                                 ProducerWhichThrows<T,? extends EX> delegate,
                                                                                 ProducerWhichThrows<java.lang.Boolean,? extends EX> invalidationCondition)
```
    The first product is the firstProduct; each following product is the next product of the delegate iff the invalidationCondition evaluates to true, otherwise it is the previous product.
    The returned PredicateWhichThrows is not synchronized and therefore not thread-safe.
    
    See Also:
    
    cache(ProducerWhichThrows, ProducerWhichThrows)
  - cacheAsynchronously
```
public static <T,EX extends java.lang.Throwable> ProducerWhichThrows<T,EX> cacheAsynchronously(ProducerWhichThrows<java.util.concurrent.Future<T>,? extends EX> delegate,
                                                                                               ProducerWhichThrows<java.lang.Boolean,? extends EX> invalidationCondition)
```
    Creates and returns a producer which caches the products of a delegate producer asynchronously.
    On the first call to produce() of the returned ProducerWhichThrows:
    - Invokes delegate.produce() to create a Future.
    - Waits for the future to complete (synchronously!).
    - Remembers the future's result as "the cached value".
    - Returns the cached value.
    On all consecutive calls to produce() of the returned ProducerWhichThrows:
    - Iff no future is pending:
      
      Evaluates the invalidationCondition:
      
      Iff true:
      
      Returns the cached value.
      
      Iff false
      
      Invokes delegate.produce() to create a Future
      
      Still returns the cached value.
      
      Now "a future is pending".
    - Iff a future is pending:
      
      Iff the future has not yet completed:
      
      Returns "the cached value".
      
      Otherwise, iff the future has completed:
      
      Retrieves the future's result
      
      Remembers it as "the cached value".
      
      Returns it.
      
      Now a future is no longer "pending".
    Notice that the invalidationCondition is never evaluated while "a future is pending".
    
    The returned producer is not thread-safe; to get a thread-safe asynchronous cache, use synchronizedProducer(ProducerWhichThrows).
    
    atMostEvery(long) may be a good choice for the invalidationCondition to set up an expiration-time-based cache.
  - atMostEvery
```
public static Producer<java.lang.Boolean> atMostEvery(long milliseconds)
```
    Creates and returns a producer for which the first product is true, and, for all following products, the time interval between adjacent true products will (A) be minimal and (B) never shorter than milliseconds.
    Calling this method is equivalent to calling
```
     ProducerUtil.atMostEvery(milliseconds, true, true)
 
```
    The returned producer is not thread-safe; to get a thread-safe producer, use synchronizedProducer(ProducerWhichThrows).
    See Also:
    
    atMostEvery(long, boolean, boolean)
  - atMostEvery
```
public static Producer<java.lang.Boolean> atMostEvery(long milliseconds,
                                                      boolean firstProduct,
                                                      boolean startAtTrueProduct)
```
    Creates and returns a producer which first produces firstProduct, and afterwards products that are true iff they are produced milliseconds or more after the most recent true product, or, iff !startAtTrueProduct, after the first false product after the most recent true product.
    The returned producer is not thread-safe; to get a thread-safe producer, use synchronizedProducer(ProducerWhichThrows).
  - after
```
public static Producer<java.lang.Boolean> after(long expirationTime)
```
    Returns a "Producer<Object>" that produces true iff the current time is after the given expirationTime (in milliseconds).
    
    Parameters:
    
    expirationTime - Milliseconds since Jan 1 1970, UTC
  - ignoreExceptions
```
public static <T,EX extends java.lang.Throwable> Producer<T> ignoreExceptions(java.lang.Class<EX> exceptionClass,
                                                                              ProducerWhichThrows<T,EX> delegate,
                                                                              T defaultValue)
```
    Wraps the delegate such that its declared exception is caught, ignored, and the defaultValue is returned.
  - synchronizedProducer
```
public static <T,EX extends java.lang.Throwable> ProducerWhichThrows<T,EX> synchronizedProducer(ProducerWhichThrows<T,EX> delegate)
```
    Creates and returns a proxy to the delegate with a synchronized produce() method.
    
    See Also:
    
    ProducerWhichThrows

Class ProducerUtil

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

sparingProducer

every

asProducerWhichThrows

asProducer

fromElements

fromCollection

fromArray

fromArray

fromIterator

fromIndexTransformer

fromIndexTransformer

randomByteProducer

constantProducer

compress

alternate

increasing

concat

cache

cache

cacheAsynchronously

atMostEvery

atMostEvery

after

ignoreExceptions

synchronizedProducer