# SubmissionPublisher

Added in[API level 33](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  
Summary:[Ctors](https://developer.android.com/reference/java/util/concurrent/SubmissionPublisher#pubctors)\|[Methods](https://developer.android.com/reference/java/util/concurrent/SubmissionPublisher#pubmethods)\|[Inherited Methods](https://developer.android.com/reference/java/util/concurrent/SubmissionPublisher#inhmethods)  

# SubmissionPublisher

`
public


class
SubmissionPublisher
`  
`

extends `[Object](https://developer.android.com/reference/java/lang/Object)`


``


implements

`[AutoCloseable](https://developer.android.com/reference/java/lang/AutoCloseable)`,

`[Publisher](https://developer.android.com/reference/java/util/concurrent/Flow.Publisher)`<T>


`

|---|-----------------------------------------------|
| [java.lang.Object](https://developer.android.com/reference/java/lang/Object) ||
| ↳ | java.util.concurrent.SubmissionPublisher\<T\> |

<br />

*** ** * ** ***

A[Flow.Publisher](https://developer.android.com/reference/java/util/concurrent/Flow.Publisher)that asynchronously issues submitted (non-null) items to current subscribers until it is closed. Each current subscriber receives newly submitted items in the same order unless drops or exceptions are encountered. Using a SubmissionPublisher allows item generators to act as compliant[reactive-streams](http://www.reactive-streams.org/)Publishers relying on drop handling and/or blocking for flow control.

A SubmissionPublisher uses the[Executor](https://developer.android.com/reference/java/util/concurrent/Executor)supplied in its constructor for delivery to subscribers. The best choice of Executor depends on expected usage. If the generator(s) of submitted items run in separate threads, and the number of subscribers can be estimated, consider using a[Executors.newFixedThreadPool(int)](https://developer.android.com/reference/java/util/concurrent/Executors#newFixedThreadPool(int)). Otherwise consider using the default, normally the[ForkJoinPool.commonPool](https://developer.android.com/reference/java/util/concurrent/ForkJoinPool#commonPool()).

Buffering allows producers and consumers to transiently operate at different rates. Each subscriber uses an independent buffer. Buffers are created upon first use and expanded as needed up to the given maximum. (The enforced capacity may be rounded up to the nearest power of two and/or bounded by the largest value supported by this implementation.) Invocations of[request](https://developer.android.com/reference/java/util/concurrent/Flow.Subscription#request(long))do not directly result in buffer expansion, but risk saturation if unfilled requests exceed the maximum capacity. The default value of[Flow.defaultBufferSize()](https://developer.android.com/reference/java/util/concurrent/Flow#defaultBufferSize())may provide a useful starting point for choosing a capacity based on expected rates, resources, and usages.

A single SubmissionPublisher may be shared among multiple sources. Actions in a source thread prior to publishing an item or issuing a signal[*happen-before*](https://developer.android.com/reference/java/util/concurrent/package-summary#MemoryVisibility)actions subsequent to the corresponding access by each subscriber. But reported estimates of lag and demand are designed for use in monitoring, not for synchronization control, and may reflect stale or inaccurate views of progress.

Publication methods support different policies about what to do when buffers are saturated. Method[submit](https://developer.android.com/reference/java/util/concurrent/SubmissionPublisher#submit(T))blocks until resources are available. This is simplest, but least responsive. The`offer`methods may drop items (either immediately or with bounded timeout), but provide an opportunity to interpose a handler and then retry.

If any Subscriber method throws an exception, its subscription is cancelled. If a handler is supplied as a constructor argument, it is invoked before cancellation upon an exception in method[onNext](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber#onNext(T)), but exceptions in methods[onSubscribe](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber#onSubscribe(java.util.concurrent.Flow.Subscription)),[onError](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber#onError(java.lang.Throwable))and[onComplete](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber#onComplete())are not recorded or handled before cancellation. If the supplied Executor throws[RejectedExecutionException](https://developer.android.com/reference/java/util/concurrent/RejectedExecutionException)(or any other RuntimeException or Error) when attempting to execute a task, or a drop handler throws an exception when processing a dropped item, then the exception is rethrown. In these cases, not all subscribers will have been issued the published item. It is usually good practice to[closeExceptionally](https://developer.android.com/reference/java/util/concurrent/SubmissionPublisher#closeExceptionally(java.lang.Throwable))in these cases.

Method[consume(java.util.function.Consumer)](https://developer.android.com/reference/java/util/concurrent/SubmissionPublisher#consume(java.util.function.Consumer<?%20super%20T>))simplifies support for a common case in which the only action of a subscriber is to request and process all items using a supplied function.

This class may also serve as a convenient base for subclasses that generate items, and use the methods in this class to publish them. For example here is a class that periodically publishes the items generated from a supplier. (In practice you might add methods to independently start and stop generation, to share Executors among publishers, and so on, or use a SubmissionPublisher as a component rather than a superclass.)  

     class PeriodicPublisher<T> extends SubmissionPublisher<T> {
       final ScheduledFuture<?> periodicTask;
       final ScheduledExecutorService scheduler;
       PeriodicPublisher(Executor executor, int maxBufferCapacity,
                         Supplier<? extends T> supplier,
                         long period, TimeUnit unit) {
         super(executor, maxBufferCapacity);
         scheduler = new ScheduledThreadPoolExecutor(1);
         periodicTask = scheduler.scheduleAtFixedRate(
           () -> submit(supplier.get()), 0, period, unit);
       }
       public void close() {
         periodicTask.cancel(false);
         scheduler.shutdown();
         super.close();
       }
     }

Here is an example of a[Flow.Processor](https://developer.android.com/reference/java/util/concurrent/Flow.Processor)implementation. It uses single-step requests to its publisher for simplicity of illustration. A more adaptive version could monitor flow using the lag estimate returned from`submit`, along with other utility methods.  

     class TransformProcessor<S,T> extends SubmissionPublisher<T>
       implements Flow.Processor<S,T> {
       final Function<? super S, ? extends T> function;
       Flow.Subscription subscription;
       TransformProcessor(Executor executor, int maxBufferCapacity,
                          Function<? super S, ? extends T> function) {
         super(executor, maxBufferCapacity);
         this.function = function;
       }
       public void onSubscribe(Flow.Subscription subscription) {
         (this.subscription = subscription).request(1);
       }
       public void onNext(S item) {
         subscription.request(1);
         submit(function.apply(item));
       }
       public void onError(Throwable ex) { closeExceptionally(ex); }
       public void onComplete() { close(); }
     }

<br />

## Summary

|                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ### Public constructors                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   ||
|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---|
| ` `[SubmissionPublisher](https://developer.android.com/reference/java/util/concurrent/SubmissionPublisher#SubmissionPublisher())`() ` Creates a new SubmissionPublisher using the[ForkJoinPool.commonPool()](https://developer.android.com/reference/java/util/concurrent/ForkJoinPool#commonPool())for async delivery to subscribers (unless it does not support a parallelism level of at least two, in which case, a new Thread is created to run each task), with maximum buffer capacity of[Flow.defaultBufferSize](https://developer.android.com/reference/java/util/concurrent/Flow#defaultBufferSize()), and no handler for Subscriber exceptions in method[onNext](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber#onNext(T)).                                                                                                                                                                                                                                                                                                                    |
| ` `[SubmissionPublisher](https://developer.android.com/reference/java/util/concurrent/SubmissionPublisher#SubmissionPublisher(java.util.concurrent.Executor,%20int))`(`[Executor](https://developer.android.com/reference/java/util/concurrent/Executor)` executor, int maxBufferCapacity) ` Creates a new SubmissionPublisher using the given Executor for async delivery to subscribers, with the given maximum buffer size for each subscriber, and no handler for Subscriber exceptions in method[onNext](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber#onNext(T)).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ` `[SubmissionPublisher](https://developer.android.com/reference/java/util/concurrent/SubmissionPublisher#SubmissionPublisher(java.util.concurrent.Executor,%20int,%20java.util.function.BiConsumer<?%20super%20java.util.concurrent.Flow.Subscriber<?%20super%20T>,?%20super%20java.lang.Throwable>))`(`[Executor](https://developer.android.com/reference/java/util/concurrent/Executor)` executor, int maxBufferCapacity, `[BiConsumer](https://developer.android.com/reference/java/util/function/BiConsumer)`<? super `[Subscriber](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber)`<? super T>, ? super `[Throwable](https://developer.android.com/reference/java/lang/Throwable)`> handler) ` Creates a new SubmissionPublisher using the given Executor for async delivery to subscribers, with the given maximum buffer size for each subscriber, and, if non-null, the given handler invoked when any Subscriber throws an exception in method[onNext](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber#onNext(T)). |

|                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   ### Public methods                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    ||
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ` void`                                                                                                                                                                      | ` `[close](https://developer.android.com/reference/java/util/concurrent/SubmissionPublisher#close())`() ` Unless already closed, issues[onComplete](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber#onComplete())signals to current subscribers, and disallows subsequent attempts to publish.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ` void`                                                                                                                                                                      | ` `[closeExceptionally](https://developer.android.com/reference/java/util/concurrent/SubmissionPublisher#closeExceptionally(java.lang.Throwable))`(`[Throwable](https://developer.android.com/reference/java/lang/Throwable)` error) ` Unless already closed, issues[onError](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber#onError(java.lang.Throwable))signals to current subscribers with the given error, and disallows subsequent attempts to publish.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ` `[CompletableFuture](https://developer.android.com/reference/java/util/concurrent/CompletableFuture)`<`[Void](https://developer.android.com/reference/java/lang/Void)`>`   | ` `[consume](https://developer.android.com/reference/java/util/concurrent/SubmissionPublisher#consume(java.util.function.Consumer<?%20super%20T>))`(`[Consumer](https://developer.android.com/reference/java/util/function/Consumer)`<? super T> consumer) ` Processes all published items using the given Consumer function.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ` int`                                                                                                                                                                       | ` `[estimateMaximumLag](https://developer.android.com/reference/java/util/concurrent/SubmissionPublisher#estimateMaximumLag())`() ` Returns an estimate of the maximum number of items produced but not yet consumed among all current subscribers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ` long`                                                                                                                                                                      | ` `[estimateMinimumDemand](https://developer.android.com/reference/java/util/concurrent/SubmissionPublisher#estimateMinimumDemand())`() ` Returns an estimate of the minimum number of items requested (via[request](https://developer.android.com/reference/java/util/concurrent/Flow.Subscription#request(long))) but not yet produced, among all current subscribers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ` `[Throwable](https://developer.android.com/reference/java/lang/Throwable)                                                                                                  | ` `[getClosedException](https://developer.android.com/reference/java/util/concurrent/SubmissionPublisher#getClosedException())`() ` Returns the exception associated with[closeExceptionally](https://developer.android.com/reference/java/util/concurrent/SubmissionPublisher#closeExceptionally(java.lang.Throwable)), or null if not closed or if closed normally.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ` `[Executor](https://developer.android.com/reference/java/util/concurrent/Executor)                                                                                         | ` `[getExecutor](https://developer.android.com/reference/java/util/concurrent/SubmissionPublisher#getExecutor())`() ` Returns the Executor used for asynchronous delivery.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ` int`                                                                                                                                                                       | ` `[getMaxBufferCapacity](https://developer.android.com/reference/java/util/concurrent/SubmissionPublisher#getMaxBufferCapacity())`() ` Returns the maximum per-subscriber buffer capacity.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ` int`                                                                                                                                                                       | ` `[getNumberOfSubscribers](https://developer.android.com/reference/java/util/concurrent/SubmissionPublisher#getNumberOfSubscribers())`() ` Returns the number of current subscribers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ` `[List](https://developer.android.com/reference/java/util/List)`<`[Subscriber](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber)`<? super T>>` | ` `[getSubscribers](https://developer.android.com/reference/java/util/concurrent/SubmissionPublisher#getSubscribers())`() ` Returns a list of current subscribers for monitoring and tracking purposes, not for invoking[Flow.Subscriber](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber)methods on the subscribers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ` boolean`                                                                                                                                                                   | ` `[hasSubscribers](https://developer.android.com/reference/java/util/concurrent/SubmissionPublisher#hasSubscribers())`() ` Returns true if this publisher has any subscribers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ` boolean`                                                                                                                                                                   | ` `[isClosed](https://developer.android.com/reference/java/util/concurrent/SubmissionPublisher#isClosed())`() ` Returns true if this publisher is not accepting submissions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ` boolean`                                                                                                                                                                   | ` `[isSubscribed](https://developer.android.com/reference/java/util/concurrent/SubmissionPublisher#isSubscribed(java.util.concurrent.Flow.Subscriber<?%20super%20T>))`(`[Subscriber](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber)`<? super T> subscriber) ` Returns true if the given Subscriber is currently subscribed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ` int`                                                                                                                                                                       | ` `[offer](https://developer.android.com/reference/java/util/concurrent/SubmissionPublisher#offer(T,%20long,%20java.util.concurrent.TimeUnit,%20java.util.function.BiPredicate<java.util.concurrent.Flow.Subscriber<?%20super%20T>,?%20super%20T>))`(T item, long timeout, `[TimeUnit](https://developer.android.com/reference/java/util/concurrent/TimeUnit)` unit, `[BiPredicate](https://developer.android.com/reference/java/util/function/BiPredicate)`<`[Subscriber](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber)`<? super T>, ? super T> onDrop) ` Publishes the given item, if possible, to each current subscriber by asynchronously invoking its[onNext](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber#onNext(T))method, blocking while resources for any subscription are unavailable, up to the specified timeout or until the caller thread is interrupted, at which point the given handler (if non-null) is invoked, and if it returns true, retried once. |
| ` int`                                                                                                                                                                       | ` `[offer](https://developer.android.com/reference/java/util/concurrent/SubmissionPublisher#offer(T,%20java.util.function.BiPredicate<java.util.concurrent.Flow.Subscriber<?%20super%20T>,?%20super%20T>))`(T item, `[BiPredicate](https://developer.android.com/reference/java/util/function/BiPredicate)`<`[Subscriber](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber)`<? super T>, ? super T> onDrop) ` Publishes the given item, if possible, to each current subscriber by asynchronously invoking its[onNext](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber#onNext(T))method.                                                                                                                                                                                                                                                                                                                                                                                         |
| ` int`                                                                                                                                                                       | ` `[submit](https://developer.android.com/reference/java/util/concurrent/SubmissionPublisher#submit(T))`(T item) ` Publishes the given item to each current subscriber by asynchronously invoking its[onNext](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber#onNext(T))method, blocking uninterruptibly while resources for any subscriber are unavailable.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ` void`                                                                                                                                                                      | ` `[subscribe](https://developer.android.com/reference/java/util/concurrent/SubmissionPublisher#subscribe(java.util.concurrent.Flow.Subscriber<?%20super%20T>))`(`[Subscriber](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber)`<? super T> subscriber) ` Adds the given Subscriber unless already subscribed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |

| ### Inherited methods |
|-----------------------|---|
| From class` `[java.lang.Object](https://developer.android.com/reference/java/lang/Object)` ` |--------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ` `[Object](https://developer.android.com/reference/java/lang/Object)          | ` `[clone](https://developer.android.com/reference/java/lang/Object#clone())`() ` Creates and returns a copy of this object.                                                                                                                                                      | | ` boolean`                                                                     | ` `[equals](https://developer.android.com/reference/java/lang/Object#equals(java.lang.Object))`(`[Object](https://developer.android.com/reference/java/lang/Object)` obj) ` Indicates whether some other object is "equal to" this one.                                           | | ` void`                                                                        | ` `[finalize](https://developer.android.com/reference/java/lang/Object#finalize())`() ` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.                                                          | | ` final `[Class](https://developer.android.com/reference/java/lang/Class)`<?>` | ` `[getClass](https://developer.android.com/reference/java/lang/Object#getClass())`() ` Returns the runtime class of this`Object`.                                                                                                                                                | | ` int`                                                                         | ` `[hashCode](https://developer.android.com/reference/java/lang/Object#hashCode())`() ` Returns a hash code value for the object.                                                                                                                                                 | | ` final void`                                                                  | ` `[notify](https://developer.android.com/reference/java/lang/Object#notify())`() ` Wakes up a single thread that is waiting on this object's monitor.                                                                                                                            | | ` final void`                                                                  | ` `[notifyAll](https://developer.android.com/reference/java/lang/Object#notifyAll())`() ` Wakes up all threads that are waiting on this object's monitor.                                                                                                                         | | ` `[String](https://developer.android.com/reference/java/lang/String)          | ` `[toString](https://developer.android.com/reference/java/lang/Object#toString())`() ` Returns a string representation of the object.                                                                                                                                            | | ` final void`                                                                  | ` `[wait](https://developer.android.com/reference/java/lang/Object#wait(long,%20int))`(long timeoutMillis, int nanos) ` Causes the current thread to wait until it is awakened, typically by being*notified* or*interrupted*, or until a certain amount of real time has elapsed. | | ` final void`                                                                  | ` `[wait](https://developer.android.com/reference/java/lang/Object#wait(long))`(long timeoutMillis) ` Causes the current thread to wait until it is awakened, typically by being*notified* or*interrupted*, or until a certain amount of real time has elapsed.                   | | ` final void`                                                                  | ` `[wait](https://developer.android.com/reference/java/lang/Object#wait())`() ` Causes the current thread to wait until it is awakened, typically by being*notified* or*interrupted*.                                                                                             | ||
| From interface` `[java.lang.AutoCloseable](https://developer.android.com/reference/java/lang/AutoCloseable)` ` |------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------| | ` abstract void` | ` `[close](https://developer.android.com/reference/java/lang/AutoCloseable#close())`() ` Closes this resource, relinquishing any underlying resources. | ||
| From interface` `[java.util.concurrent.Flow.Publisher](https://developer.android.com/reference/java/util/concurrent/Flow.Publisher)` ` |------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ` abstract void` | ` `[subscribe](https://developer.android.com/reference/java/util/concurrent/Flow.Publisher#subscribe(java.util.concurrent.Flow.Subscriber<?%20super%20T>))`(`[Subscriber](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber)`<? super T> subscriber) ` Adds the given Subscriber if possible. | ||

## Public constructors

### SubmissionPublisher

Added in[API level 33](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public SubmissionPublisher ()
```

Creates a new SubmissionPublisher using the[ForkJoinPool.commonPool()](https://developer.android.com/reference/java/util/concurrent/ForkJoinPool#commonPool())for async delivery to subscribers (unless it does not support a parallelism level of at least two, in which case, a new Thread is created to run each task), with maximum buffer capacity of[Flow.defaultBufferSize](https://developer.android.com/reference/java/util/concurrent/Flow#defaultBufferSize()), and no handler for Subscriber exceptions in method[onNext](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber#onNext(T)).

<br />

### SubmissionPublisher

Added in[API level 33](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public SubmissionPublisher (Executor executor, 
                int maxBufferCapacity)
```

Creates a new SubmissionPublisher using the given Executor for async delivery to subscribers, with the given maximum buffer size for each subscriber, and no handler for Subscriber exceptions in method[onNext](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber#onNext(T)).

<br />

|                                                                                                                                                                                            Parameters                                                                                                                                                                                            ||
|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `executor`          | `Executor`: the executor to use for async delivery, supporting creation of at least one independent thread <br />                                                                                                                                                                                                                                                           |
| `maxBufferCapacity` | `int`: the maximum capacity for each subscriber's buffer (the enforced capacity may be rounded up to the nearest power of two and/or bounded by the largest value supported by this implementation; method[getMaxBufferCapacity()](https://developer.android.com/reference/java/util/concurrent/SubmissionPublisher#getMaxBufferCapacity())returns the actual value) <br /> |

|                                                                  Throws                                                                   ||
|--------------------------------------------------------------------------------------------------------|-----------------------------------|
| [NullPointerException](https://developer.android.com/reference/java/lang/NullPointerException)         | if executor is null               |
| [IllegalArgumentException](https://developer.android.com/reference/java/lang/IllegalArgumentException) | if maxBufferCapacity not positive |

### SubmissionPublisher

Added in[API level 33](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public SubmissionPublisher (Executor executor, 
                int maxBufferCapacity, 
                BiConsumer<? super Subscriber<? super T>, ? super Throwable> handler)
```

Creates a new SubmissionPublisher using the given Executor for async delivery to subscribers, with the given maximum buffer size for each subscriber, and, if non-null, the given handler invoked when any Subscriber throws an exception in method[onNext](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber#onNext(T)).

<br />

|                                                                                                                                                                                            Parameters                                                                                                                                                                                            ||
|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `executor`          | `Executor`: the executor to use for async delivery, supporting creation of at least one independent thread <br />                                                                                                                                                                                                                                                           |
| `maxBufferCapacity` | `int`: the maximum capacity for each subscriber's buffer (the enforced capacity may be rounded up to the nearest power of two and/or bounded by the largest value supported by this implementation; method[getMaxBufferCapacity()](https://developer.android.com/reference/java/util/concurrent/SubmissionPublisher#getMaxBufferCapacity())returns the actual value) <br /> |
| `handler`           | `BiConsumer`: if non-null, procedure to invoke upon exception thrown in method`onNext` <br />                                                                                                                                                                                                                                                                               |

|                                                                  Throws                                                                   ||
|--------------------------------------------------------------------------------------------------------|-----------------------------------|
| [NullPointerException](https://developer.android.com/reference/java/lang/NullPointerException)         | if executor is null               |
| [IllegalArgumentException](https://developer.android.com/reference/java/lang/IllegalArgumentException) | if maxBufferCapacity not positive |

## Public methods

### close

Added in[API level 33](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public void close ()
```

Unless already closed, issues[onComplete](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber#onComplete())signals to current subscribers, and disallows subsequent attempts to publish. Upon return, this method does*NOT*guarantee that all subscribers have yet completed.

<br />

### closeExceptionally

Added in[API level 33](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public void closeExceptionally (Throwable error)
```

Unless already closed, issues[onError](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber#onError(java.lang.Throwable))signals to current subscribers with the given error, and disallows subsequent attempts to publish. Future subscribers also receive the given error. Upon return, this method does*NOT*guarantee that all subscribers have yet completed.

<br />

|                              Parameters                               ||
|---------|--------------------------------------------------------------|
| `error` | `Throwable`: the`onError`argument sent to subscribers <br /> |

|                                                      Throws                                                      ||
|------------------------------------------------------------------------------------------------|------------------|
| [NullPointerException](https://developer.android.com/reference/java/lang/NullPointerException) | if error is null |

### consume

Added in[API level 33](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public CompletableFuture<Void> consume (Consumer<? super T> consumer)
```

Processes all published items using the given Consumer function. Returns a CompletableFuture that is completed normally when this publisher signals[onComplete](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber#onComplete()), or completed exceptionally upon any error, or an exception is thrown by the Consumer, or the returned CompletableFuture is cancelled, in which case no further items are processed.

<br />

|                               Parameters                                ||
|------------|-------------------------------------------------------------|
| `consumer` | `Consumer`: the function applied to each onNext item <br /> |

|                                                                                                                                                        Returns                                                                                                                                                         ||
|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|
| [CompletableFuture](https://developer.android.com/reference/java/util/concurrent/CompletableFuture)`<`[Void](https://developer.android.com/reference/java/lang/Void)`>` | a CompletableFuture that is completed normally when the publisher signals onComplete, and exceptionally upon any error or cancellation <br /> |

|                                                       Throws                                                        ||
|------------------------------------------------------------------------------------------------|---------------------|
| [NullPointerException](https://developer.android.com/reference/java/lang/NullPointerException) | if consumer is null |

### estimateMaximumLag

Added in[API level 33](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public int estimateMaximumLag ()
```

Returns an estimate of the maximum number of items produced but not yet consumed among all current subscribers.

<br />

|          Returns           ||
|-------|---------------------|
| `int` | the estimate <br /> |

### estimateMinimumDemand

Added in[API level 33](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public long estimateMinimumDemand ()
```

Returns an estimate of the minimum number of items requested (via[request](https://developer.android.com/reference/java/util/concurrent/Flow.Subscription#request(long))) but not yet produced, among all current subscribers.

<br />

|                        Returns                         ||
|--------|------------------------------------------------|
| `long` | the estimate, or zero if no subscribers <br /> |

### getClosedException

Added in[API level 33](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public Throwable getClosedException ()
```

Returns the exception associated with[closeExceptionally](https://developer.android.com/reference/java/util/concurrent/SubmissionPublisher#closeExceptionally(java.lang.Throwable)), or null if not closed or if closed normally.

<br />

|                                                     Returns                                                     ||
|--------------------------------------------------------------------------|---------------------------------------|
| [Throwable](https://developer.android.com/reference/java/lang/Throwable) | the exception, or null if none <br /> |

### getExecutor

Added in[API level 33](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public Executor getExecutor ()
```

Returns the Executor used for asynchronous delivery.

<br />

|                                                                Returns                                                                ||
|-----------------------------------------------------------------------------------|----------------------------------------------------|
| [Executor](https://developer.android.com/reference/java/util/concurrent/Executor) | the Executor used for asynchronous delivery <br /> |

### getMaxBufferCapacity

Added in[API level 33](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public int getMaxBufferCapacity ()
```

Returns the maximum per-subscriber buffer capacity.

<br />

|                         Returns                          ||
|-------|---------------------------------------------------|
| `int` | the maximum per-subscriber buffer capacity <br /> |

### getNumberOfSubscribers

Added in[API level 33](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public int getNumberOfSubscribers ()
```

Returns the number of current subscribers.

<br />

|                     Returns                     ||
|-------|------------------------------------------|
| `int` | the number of current subscribers <br /> |

### getSubscribers

Added in[API level 33](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public List<Subscriber<? super T>> getSubscribers ()
```

Returns a list of current subscribers for monitoring and tracking purposes, not for invoking[Flow.Subscriber](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber)methods on the subscribers.

<br />

|                                                                                                    Returns                                                                                                    ||
|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------|
| [List](https://developer.android.com/reference/java/util/List)`<`[Subscriber](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber)`<? super T>>` | list of current subscribers <br /> |

### hasSubscribers

Added in[API level 33](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public boolean hasSubscribers ()
```

Returns true if this publisher has any subscribers.

<br />

|                           Returns                            ||
|-----------|---------------------------------------------------|
| `boolean` | true if this publisher has any subscribers <br /> |

### isClosed

Added in[API level 33](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public boolean isClosed ()
```

Returns true if this publisher is not accepting submissions.

<br />

|             Returns              ||
|-----------|-----------------------|
| `boolean` | true if closed <br /> |

### isSubscribed

Added in[API level 33](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public boolean isSubscribed (Subscriber<? super T> subscriber)
```

Returns true if the given Subscriber is currently subscribed.

<br />

|                    Parameters                     ||
|--------------|-------------------------------------|
| `subscriber` | `Subscriber`: the subscriber <br /> |

|                    Returns                     ||
|-----------|-------------------------------------|
| `boolean` | true if currently subscribed <br /> |

|                                                        Throws                                                         ||
|------------------------------------------------------------------------------------------------|-----------------------|
| [NullPointerException](https://developer.android.com/reference/java/lang/NullPointerException) | if subscriber is null |

### offer

Added in[API level 33](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public int offer (T item, 
                long timeout, 
                TimeUnit unit, 
                BiPredicate<Subscriber<? super T>, ? super T> onDrop)
```

Publishes the given item, if possible, to each current subscriber by asynchronously invoking its[onNext](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber#onNext(T))method, blocking while resources for any subscription are unavailable, up to the specified timeout or until the caller thread is interrupted, at which point the given handler (if non-null) is invoked, and if it returns true, retried once. (The drop handler may distinguish timeouts from interrupts by checking whether the current thread is interrupted.) Other calls to methods in this class by other threads are blocked while the handler is invoked. Unless recovery is assured, options are usually limited to logging the error and/or issuing an[onError](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber#onError(java.lang.Throwable))signal to the subscriber.

This method returns a status indicator: If negative, it represents the (negative) number of drops (failed attempts to issue the item to a subscriber). Otherwise it is an estimate of the maximum lag (number of items submitted but not yet consumed) among all current subscribers. This value is at least one (accounting for this submitted item) if there are any subscribers, else zero.

If the Executor for this publisher throws a RejectedExecutionException (or any other RuntimeException or Error) when attempting to asynchronously notify subscribers, or the drop handler throws an exception when processing a dropped item, then this exception is rethrown.

<br />

|                                                                                          Parameters                                                                                           ||
|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `item`    | `T`: the (non-null) item to publish <br />                                                                                                                                         |
| `timeout` | `long`: how long to wait for resources for any subscriber before giving up, in units of`unit` <br />                                                                               |
| `unit`    | `TimeUnit`: a`TimeUnit`determining how to interpret the`timeout`parameter <br />                                                                                                   |
| `onDrop`  | `BiPredicate`: if non-null, the handler invoked upon a drop to a subscriber, with arguments of the subscriber and item; if it returns true, an offer is re-attempted (once) <br /> |

|                                             Returns                                             ||
|-------|------------------------------------------------------------------------------------------|
| `int` | if negative, the (negative) number of drops; otherwise an estimate of maximum lag <br /> |

|                                                                    Throws                                                                    ||
|-----------------------------------------------------------------------------------------------------------------------|-----------------------|
| [IllegalStateException](https://developer.android.com/reference/java/lang/IllegalStateException)                      | if closed             |
| [NullPointerException](https://developer.android.com/reference/java/lang/NullPointerException)                        | if item is null       |
| [RejectedExecutionException](https://developer.android.com/reference/java/util/concurrent/RejectedExecutionException) | if thrown by Executor |

### offer

Added in[API level 33](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public int offer (T item, 
                BiPredicate<Subscriber<? super T>, ? super T> onDrop)
```

Publishes the given item, if possible, to each current subscriber by asynchronously invoking its[onNext](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber#onNext(T))method. The item may be dropped by one or more subscribers if resource limits are exceeded, in which case the given handler (if non-null) is invoked, and if it returns true, retried once. Other calls to methods in this class by other threads are blocked while the handler is invoked. Unless recovery is assured, options are usually limited to logging the error and/or issuing an[onError](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber#onError(java.lang.Throwable))signal to the subscriber.

This method returns a status indicator: If negative, it represents the (negative) number of drops (failed attempts to issue the item to a subscriber). Otherwise it is an estimate of the maximum lag (number of items submitted but not yet consumed) among all current subscribers. This value is at least one (accounting for this submitted item) if there are any subscribers, else zero.

If the Executor for this publisher throws a RejectedExecutionException (or any other RuntimeException or Error) when attempting to asynchronously notify subscribers, or the drop handler throws an exception when processing a dropped item, then this exception is rethrown.

<br />

|                                                                                          Parameters                                                                                          ||
|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `item`   | `T`: the (non-null) item to publish <br />                                                                                                                                         |
| `onDrop` | `BiPredicate`: if non-null, the handler invoked upon a drop to a subscriber, with arguments of the subscriber and item; if it returns true, an offer is re-attempted (once) <br /> |

|                                             Returns                                             ||
|-------|------------------------------------------------------------------------------------------|
| `int` | if negative, the (negative) number of drops; otherwise an estimate of maximum lag <br /> |

|                                                                    Throws                                                                    ||
|-----------------------------------------------------------------------------------------------------------------------|-----------------------|
| [IllegalStateException](https://developer.android.com/reference/java/lang/IllegalStateException)                      | if closed             |
| [NullPointerException](https://developer.android.com/reference/java/lang/NullPointerException)                        | if item is null       |
| [RejectedExecutionException](https://developer.android.com/reference/java/util/concurrent/RejectedExecutionException) | if thrown by Executor |

### submit

Added in[API level 33](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public int submit (T item)
```

Publishes the given item to each current subscriber by asynchronously invoking its[onNext](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber#onNext(T))method, blocking uninterruptibly while resources for any subscriber are unavailable. This method returns an estimate of the maximum lag (number of items submitted but not yet consumed) among all current subscribers. This value is at least one (accounting for this submitted item) if there are any subscribers, else zero.

If the Executor for this publisher throws a RejectedExecutionException (or any other RuntimeException or Error) when attempting to asynchronously notify subscribers, then this exception is rethrown, in which case not all subscribers will have been issued this item.

<br />

|                     Parameters                     ||
|--------|--------------------------------------------|
| `item` | `T`: the (non-null) item to publish <br /> |

|                          Returns                          ||
|-------|----------------------------------------------------|
| `int` | the estimated maximum lag among subscribers <br /> |

|                                                                    Throws                                                                    ||
|-----------------------------------------------------------------------------------------------------------------------|-----------------------|
| [IllegalStateException](https://developer.android.com/reference/java/lang/IllegalStateException)                      | if closed             |
| [NullPointerException](https://developer.android.com/reference/java/lang/NullPointerException)                        | if item is null       |
| [RejectedExecutionException](https://developer.android.com/reference/java/util/concurrent/RejectedExecutionException) | if thrown by Executor |

### subscribe

Added in[API level 33](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public void subscribe (Subscriber<? super T> subscriber)
```

Adds the given Subscriber unless already subscribed. If already subscribed, the Subscriber's[onError](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber#onError(java.lang.Throwable))method is invoked on the existing subscription with an[IllegalStateException](https://developer.android.com/reference/java/lang/IllegalStateException). Otherwise, upon success, the Subscriber's[onSubscribe](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber#onSubscribe(java.util.concurrent.Flow.Subscription))method is invoked asynchronously with a new[Flow.Subscription](https://developer.android.com/reference/java/util/concurrent/Flow.Subscription). If[onSubscribe](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber#onSubscribe(java.util.concurrent.Flow.Subscription))throws an exception, the subscription is cancelled. Otherwise, if this SubmissionPublisher was closed exceptionally, then the subscriber's[onError](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber#onError(java.lang.Throwable))method is invoked with the corresponding exception, or if closed without exception, the subscriber's[onComplete](https://developer.android.com/reference/java/util/concurrent/Flow.Subscriber#onComplete())method is invoked. Subscribers may enable receiving items by invoking the[request](https://developer.android.com/reference/java/util/concurrent/Flow.Subscription#request(long))method of the new Subscription, and may unsubscribe by invoking its[cancel](https://developer.android.com/reference/java/util/concurrent/Flow.Subscription#cancel())method.

<br />

|                    Parameters                     ||
|--------------|-------------------------------------|
| `subscriber` | `Subscriber`: the subscriber <br /> |

|                                                        Throws                                                         ||
|------------------------------------------------------------------------------------------------|-----------------------|
| [NullPointerException](https://developer.android.com/reference/java/lang/NullPointerException) | if subscriber is null |