ObjectAsyncBuilder (Primitive-Collections 0.7.0 API)

java.lang.Object
- speiger.src.collections.objects.utils.ObjectAsyncBuilder<T>

Type Parameters:

T - the type of elements maintained by this Collection
```
public class ObjectAsyncBuilder<T>
extends java.lang.Object
```
The Async API allows you to process collections on a different thread without having to deal with the Multithreading complexity.
It uses the Lightweight Stream Replace API to do its work, which can make it faster then sequential streams.
This feature isn't designed to do Multithreading work, but to allow moving work off the main thread into a worker thread.
So anything executed on this is still Singlethreaded.

How it works is you create the AsyncBuilder using a Iterable of the Type.
Then select things you want to use on the Iterable.
- For example: map/filter/peek/limit/etc

After that you select your action the Iterable should be applied on.
- For Example: forEach/findFirst/matchAny/etc

Then optionally a custom Executor or callback can be applied
At the end either execute or join can be called to start the task.
- execute will return the Task reference so that the task can be traced back.
- join will await the completion of the task and return the return value

During Construction a couple Disposable Builder Objects will be created.
These will be only used during construction.

The Task Object is also pause-able/Interruptable at any moment during the Processing.
A small example
```
 public void processFiles(ObjectCollection<String> potentialFiles) {
        potentialFiles.asAsync()
                .map(Paths::get).filter(Files::exists) //Modifies the collection (Optional)
                .forEach(Files::delete) //Creates the action (Required)
                .onCompletion(T -> {}} //Callback on completion (Optional)
                .execute() //Starts the task. (Required)
 }
 
```

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class ObjectAsyncBuilder.BaseObjectTask<T>
Base Task of the Actions that can be performed.

Nested Classes
Modifier and Type	Class and Description
`static class`	`ObjectAsyncBuilder.BaseObjectTask<T>` Base Task of the Actions that can be performed.

Constructor Summary

Constructors
Constructor and Description
`ObjectAsyncBuilder(ObjectAsyncBuilder.BaseObjectTask<T> task)` Helper constructor.
`ObjectAsyncBuilder(ObjectIterable<T> iterable)` Main Constructor that uses a Iterable to build a Offthread Task.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`<E> ObjectAsyncBuilder<E>`	`arrayflatMap(Object2ObjectFunction<T,E[]> mapper)` Maps the elements to something else
`IntAsyncBuilder`	`count(Object2BooleanFunction<T> filter)` Counts all desired elements inside the Iterable
`ObjectAsyncBuilder<T>`	`distinct()` Removes duplicated elements out of the Iterable
`ObjectTask<T>`	`execute()` Starts the Execution of the task without awaiting its result
`ObjectAsyncBuilder<T>`	`executor(java.util.concurrent.Executor executor)` Optional way to add a custom executor that runs this offthread task.
`ObjectAsyncBuilder<T>`	`filter(Object2BooleanFunction<T> filter)` Filters out the unwanted elements out of the Iterable
`ObjectAsyncBuilder<T>`	`findFirst(Object2BooleanFunction<T> filter)` Searches through the elements of the Iterable to find if the desired element.
`<E,V extends java.lang.Iterable<E>> ObjectAsyncBuilder<E>`	`flatMap(Object2ObjectFunction<T,V> mapper)` Maps the elements to something else
`ObjectAsyncBuilder<java.lang.Void>`	`forEach(java.util.function.Consumer<T> action)` Iterates over the Iterable with a desired action
`T`	`join()` Starts the Execution of the task and will await its completion, returning the result.
`T`	`join(long timeout, java.util.concurrent.TimeUnit unit)` Starts the Execution of the task and will await its completion with a timeout, returning the result.
`ObjectAsyncBuilder<T>`	`limit(long limit)` Limits how many elements are inside of the Iterable
`<E> ObjectAsyncBuilder<E>`	`map(Object2ObjectFunction<T,E> mapper)` Maps the elements to something else
`BooleanAsyncBuilder`	`matchAll(Object2BooleanFunction<T> filter)` Searches through the elements of the Iterable to find if all the desired elements are present.
`BooleanAsyncBuilder`	`matchAny(Object2BooleanFunction<T> filter)` Searches through the elements of the Iterable to find if the desired element is present.
`BooleanAsyncBuilder`	`matchNone(Object2BooleanFunction<T> filter)` Searches through the elements of the Iterable to find if unwanted elements are present.
`static <T> ObjectAsyncBuilder<T>`	`of(java.lang.Iterable<T> iterable)` Helper function that automatically wraps a Iterable into a AsyncBuilder since it forces this collections Iterable.
`static <T> ObjectAsyncBuilder<T>`	`of(T... values)` Helper function that automatically wraps a array into a AsyncBuilder since it forces this collections Iterable.
`ObjectAsyncBuilder<T>`	`onCompletion(java.util.function.Consumer<ObjectTask<T>> callback)` Optional way to set a callback that allows to compute actions after the task was completed.
`ObjectAsyncBuilder<T>`	`peek(java.util.function.Consumer<T> action)` Allows to preview elements before they are processed
`<E extends ObjectCollection<T>> ObjectAsyncBuilder<E>`	`pour(E collection)` Pours all elements into a collection that can be later
`ObjectAsyncBuilder<ObjectList<T>>`	`pourAsList()` Pours all elements into a List that can be later
`ObjectAsyncBuilder<ObjectSet<T>>`	`pourAsSet()` Pours all elements into a Set that can be later
`<E> ObjectAsyncBuilder<E>`	`reduce(E identity, java.util.function.BiFunction<E,T,E> operator)` Reduces the elements inside of the Iterable down to one element using a identity element.
`ObjectAsyncBuilder<T>`	`reduce(ObjectObjectUnaryOperator<T,T> operator)` Reduces the elements inside of the Iterable down to one element
`ObjectAsyncBuilder<T>`	`sorted(java.util.Comparator<T> sorter)` Sorts the elements inside of the Iterable.

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

- Constructor Detail
  - ObjectAsyncBuilder
```
public ObjectAsyncBuilder(ObjectIterable<T> iterable)
```
    Main Constructor that uses a Iterable to build a Offthread Task.
    
    Parameters:
    
    iterable - that should be processed
  - ObjectAsyncBuilder
```
public ObjectAsyncBuilder(ObjectAsyncBuilder.BaseObjectTask<T> task)
```
    Helper constructor.
    
    Parameters:
    
    task - that had been build
- Method Detail
  - of
```
public static <T> ObjectAsyncBuilder<T> of(java.lang.Iterable<T> iterable)
```
    Helper function that automatically wraps a Iterable into a AsyncBuilder since it forces this collections Iterable.
    
    Type Parameters:
    
    T - the type of elements maintained by this Collection
    
    Parameters:
    
    iterable - that should be wrapped
    
    Returns:
    
    a AsyncBuilder with the iterable wrapped
  - of
```
public static <T> ObjectAsyncBuilder<T> of(T... values)
```
    Helper function that automatically wraps a array into a AsyncBuilder since it forces this collections Iterable.
    
    Type Parameters:
    
    T - the type of elements maintained by this Collection
    
    Parameters:
    
    values - that should be wrapped
    
    Returns:
    
    a AsyncBuilder with the values wrapped
  - map
```
public <E> ObjectAsyncBuilder<E> map(Object2ObjectFunction<T,E> mapper)
```
    Maps the elements to something else
    
    Type Parameters:
    
    E - The return type.
    
    Parameters:
    
    mapper - the mapping function
    
    Returns:
    
    a new Builder Object with the mapped Iterable
  - flatMap
```
public <E,V extends java.lang.Iterable<E>> ObjectAsyncBuilder<E> flatMap(Object2ObjectFunction<T,V> mapper)
```
    Maps the elements to something else
    
    Type Parameters:
    
    V - The return type supplier.
    
    E - The return type.
    
    Parameters:
    
    mapper - the flatMapping function
    
    Returns:
    
    a new Builder Object with the mapped Iterable
  - arrayflatMap
```
public <E> ObjectAsyncBuilder<E> arrayflatMap(Object2ObjectFunction<T,E[]> mapper)
```
    Maps the elements to something else
    
    Type Parameters:
    
    E - The return type.
    
    Parameters:
    
    mapper - the flatMapping function
    
    Returns:
    
    a new Builder Object with the mapped Iterable
  - filter
```
public ObjectAsyncBuilder<T> filter(Object2BooleanFunction<T> filter)
```
    Filters out the unwanted elements out of the Iterable
    
    Parameters:
    
    filter - the elements that should be kept
    
    Returns:
    
    Self with a filter applied
  - distinct
```
public ObjectAsyncBuilder<T> distinct()
```
    Removes duplicated elements out of the Iterable
    
    Returns:
    
    Self with a deduplicator applied
  - limit
```
public ObjectAsyncBuilder<T> limit(long limit)
```
    Limits how many elements are inside of the Iterable
    
    Parameters:
    
    limit - how many elements should max be iterated through
    
    Returns:
    
    self with a limiter applied
  - sorted
```
public ObjectAsyncBuilder<T> sorted(java.util.Comparator<T> sorter)
```
    Sorts the elements inside of the Iterable. This operation is heavily hurting performance because it rebuilds the entire iterator and then sorts it, and this will affect the pausing feature.
    
    Parameters:
    
    sorter - that sorts the elements.
    
    Returns:
    
    self with a sorter applied
  - peek
```
public ObjectAsyncBuilder<T> peek(java.util.function.Consumer<T> action)
```
    Allows to preview elements before they are processed
    
    Parameters:
    
    action - the action that should be applied
    
    Returns:
    
    self with a preview applied
  - forEach
```
public ObjectAsyncBuilder<java.lang.Void> forEach(java.util.function.Consumer<T> action)
```
    Iterates over the Iterable with a desired action
    
    Parameters:
    
    action - that should be applied
    
    Returns:
    
    a new Builder with the forEach action applied.
  - reduce
```
public ObjectAsyncBuilder<T> reduce(ObjectObjectUnaryOperator<T,T> operator)
```
    Reduces the elements inside of the Iterable down to one element
    
    Parameters:
    
    operator - that reduces the elements.
    
    Returns:
    
    self with the reduce action applied
  - reduce
```
public <E> ObjectAsyncBuilder<E> reduce(E identity,
                                        java.util.function.BiFunction<E,T,E> operator)
```
    Reduces the elements inside of the Iterable down to one element using a identity element.
    
    Type Parameters:
    
    E - the return type
    
    Parameters:
    
    identity - the element the reduce function should start with
    
    operator - that reduces the elements.
    
    Returns:
    
    a new Builder with the reduce function applied
  - pourAsList
```
public ObjectAsyncBuilder<ObjectList<T>> pourAsList()
```
    Pours all elements into a List that can be later
    
    Returns:
    
    a new Builder with the pour function applied
  - pourAsSet
```
public ObjectAsyncBuilder<ObjectSet<T>> pourAsSet()
```
    Pours all elements into a Set that can be later
    
    Returns:
    
    a new Builder with the pour function applied
  - pour
```
public <E extends ObjectCollection<T>> ObjectAsyncBuilder<E> pour(E collection)
```
    Pours all elements into a collection that can be later
    
    Type Parameters:
    
    E - the return type
    
    Parameters:
    
    collection - the collection the elements
    
    Returns:
    
    a new Builder with the pour function applied
  - matchAny
```
public BooleanAsyncBuilder matchAny(Object2BooleanFunction<T> filter)
```
    Searches through the elements of the Iterable to find if the desired element is present.
    
    Parameters:
    
    filter - that decides the desired elements
    
    Returns:
    
    a new Builder with the matchAny function applied
  - matchNone
```
public BooleanAsyncBuilder matchNone(Object2BooleanFunction<T> filter)
```
    Searches through the elements of the Iterable to find if unwanted elements are present.
    
    Parameters:
    
    filter - that decides the unwanted elements
    
    Returns:
    
    a new Builder with the matchNone function applied
  - matchAll
```
public BooleanAsyncBuilder matchAll(Object2BooleanFunction<T> filter)
```
    Searches through the elements of the Iterable to find if all the desired elements are present.
    
    Parameters:
    
    filter - that decides the desired elements
    
    Returns:
    
    a new Builder with the matchAll function applied
  - findFirst
```
public ObjectAsyncBuilder<T> findFirst(Object2BooleanFunction<T> filter)
```
    Searches through the elements of the Iterable to find if the desired element. If not present it will return the default value of the type
    
    Parameters:
    
    filter - that decides the desired elements
    
    Returns:
    
    self with the findFirst function applied
  - count
```
public IntAsyncBuilder count(Object2BooleanFunction<T> filter)
```
    Counts all desired elements inside the Iterable
    
    Parameters:
    
    filter - that decides the desired elements
    
    Returns:
    
    a new Builder with the count function applied
  - executor
```
public ObjectAsyncBuilder<T> executor(java.util.concurrent.Executor executor)
```
    Optional way to add a custom executor that runs this offthread task. Can only be set after the action was decided on.
    
    Parameters:
    
    executor - that executes the task, defaults to SanityChecks.invokeAsyncTask(Runnable)
    
    Returns:
    
    self with the executor set
    
    Note:
    
    has to be NonNull
  - onCompletion
```
public ObjectAsyncBuilder<T> onCompletion(java.util.function.Consumer<ObjectTask<T>> callback)
```
    Optional way to set a callback that allows to compute actions after the task was completed. The state of the task has to be validated by the callback.
    
    Parameters:
    
    callback - that should be notified after completion of the task
    
    Returns:
    
    self with the callback set
    
    Note:
    
    can be null
  - execute
```
public ObjectTask<T> execute()
```
    Starts the Execution of the task without awaiting its result
    
    Returns:
    
    the task object that allow to trace it.
  - join
```
public T join()
       throws java.util.concurrent.ExecutionException,
              java.lang.InterruptedException
```
    Starts the Execution of the task and will await its completion, returning the result.
    
    Returns:
    
    the result of the task provided.
    
    Throws:
    
    java.util.concurrent.ExecutionException - if the task threw a exception
    
    java.lang.InterruptedException - if the caller thread was interrupted
  - join
```
public T join(long timeout,
              java.util.concurrent.TimeUnit unit)
       throws java.lang.InterruptedException,
              java.util.concurrent.ExecutionException,
              java.util.concurrent.TimeoutException
```
    Starts the Execution of the task and will await its completion with a timeout, returning the result.
    
    Parameters:
    
    timeout - of how long the thread should wait the task to be completed
    
    unit - of the desired waiting time.
    
    Returns:
    
    the result of the provided task
    
    Throws:
    
    java.lang.InterruptedException - if the caller thread was interrupted
    
    java.util.concurrent.ExecutionException - if the task threw a exception
    
    java.util.concurrent.TimeoutException - if the timeout was reached before the task was finished

Class ObjectAsyncBuilder<T>

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

ObjectAsyncBuilder

ObjectAsyncBuilder

Method Detail

of

of

map

flatMap

arrayflatMap

filter

distinct

limit

sorted

peek

forEach

reduce

reduce

pourAsList

pourAsSet

pour

matchAny

matchNone

matchAll

findFirst

count

executor

onCompletion

execute

join

join