CommandFuture (TeamSpeak 3 Java API 1.1.0 API)

java.lang.Object
- com.github.theholywaffle.teamspeak3.api.CommandFuture<V>

Type Parameters:
V - the type of the value

All Implemented Interfaces:

Future<V>
```
public class CommandFuture<V>
extends Object
implements Future<V>
```
Represents the result of an asynchronous execution of a query command.
Basically, this class is a container for a server response which will arrive at some time in the future. It also accounts for the possibility that a command might fail and that a future might be cancelled by a user.
A CommandFuture can therefore have 4 different states:
- Waiting - No response from the server has arrived yet
- Cancelled - A user cancelled this future before a response from the server could arrive
- Failed - The server received the command but responded with an error message
- Succeeded - The server successfully processed the command and sent back a result
You can check the state of the future using the methods isDone(), isSuccessful(), hasFailed() and isCancelled().
A CommandFuture's value can be retrieved by calling get() or get(long, TimeUnit), which block the current thread until the server response arrives. The method with a timeout should be preferred as there's no guarantee that a proper response (or an error message) will ever arrive, e.g. in case of a permanent disconnect. There are also variations of these methods which ignore thread interrupts, getUninterruptibly() and getUninterruptibly(long, TimeUnit).
Note that these methods all wait for the response to arrive and thereby revert to synchronous execution. If you want to handle the server response asynchronously, you need to register success and failure listeners. These listeners will be called in a separate thread once a response arrives.
Each CommandFuture can only ever have one CommandFuture.SuccessListener and one CommandFuture.FailureListener registered. All TS3ApiAsync methods are guaranteed to return a CommandFuture with no listeners registered.
To set the value of a CommandFuture, the set(Object) method is used; to notify it of a failure, fail(TS3Exception) is used. You usually shouldn't call these methods yourself, however. That's the job of the API.
CommandFutures are thread-safe. All state-changing methods are synchronized.
See Also:
TS3ApiAsync

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static interface`	`CommandFuture.FailureListener` A listener which will be notified if the `CommandFuture` failed.
`static interface`	`CommandFuture.SuccessListener<V>` A listener which will be notified if the `CommandFuture` succeeded.

Constructor Summary

Constructors
Constructor and Description

CommandFuture()

Constructors
Constructor and Description
`CommandFuture()`

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`await()` Waits indefinitely until the command completes.
`void`	`await(long timeout, TimeUnit unit)` Waits for at most the given time until the command completes.
`void`	`awaitUninterruptibly()` Waits indefinitely until the command completes.
`void`	`awaitUninterruptibly(long timeout, TimeUnit unit)` Waits for at most the given time until the command completes.
`boolean`	`cancel(boolean mayInterruptIfRunning)`
`boolean`	`fail(TS3Exception exception)` Notifies this future that the command has failed.
`CommandFuture<V>`	`forwardFailure(CommandFuture<?> otherFuture)` Forwards a failure to another future by calling `fail(TS3Exception)` on that future with the error that caused this future to fail.
`void`	`forwardResult(CommandFuture<V> otherFuture)` Forwards both a success as well as a failure to another `CommandFuture`.
`CommandFuture<V>`	`forwardSuccess(CommandFuture<? super V> otherFuture)` Forwards a success to another future by calling `set(Object)` on that future with the value this future was set to.
`V`	`get()` Waits indefinitely until the command completes and returns the result of the command.
`V`	`get(long timeout, TimeUnit unit)` Waits for at most the given time until the command completes and returns the result of the command.
`V`	`getUninterruptibly()` Waits indefinitely until the command completes and returns the result of the command.
`V`	`getUninterruptibly(long timeout, TimeUnit unit)` Waits for at most the given time until the command completes and returns the result of the command.
`boolean`	`hasFailed()` Returns `true` if the command failed and threw a `TS3Exception`.
`static <V> CommandFuture<V>`	`immediate(V value)` Returns a new `CommandFuture` that already has a value set.
`boolean`	`isCancelled()`
`boolean`	`isDone()`
`boolean`	`isSuccessful()` Returns `true` if this command completed successfully, i.e.
`static <F> CommandFuture<List<F>>`	`ofAll(Collection<CommandFuture<F>> futures)` Combines a collection of `CommandFuture`s into a single future, which will succeed if all futures succeed and fail as soon as one future fails.
`static <F> CommandFuture<List<F>>`	`ofAll(CommandFuture<F>... futures)` Combines multiple `CommandFuture`s into a single future, which will succeed if all futures succeed and fail as soon as one future fails.
`static <F> CommandFuture<F>`	`ofAny(Collection<CommandFuture<F>> futures)` Combines a collection of `CommandFuture`s into a single future, which will succeed as soon as one of the futures succeeds and fail if all futures fail.
`static <F> CommandFuture<F>`	`ofAny(CommandFuture<F>... futures)` Combines multiple `CommandFuture`s into a single future, which will succeed if any of the futures succeeds and fail if all of the futures fail.
`CommandFuture<V>`	`onFailure(CommandFuture.FailureListener listener)` Sets a `CommandFuture.FailureListener` which will be notified when this future fails because of a error returned by the TeamSpeak server.
`CommandFuture<V>`	`onSuccess(CommandFuture.SuccessListener<? super V> listener)` Sets a `CommandFuture.SuccessListener` which will be notified when this future succeeded and a value has been set.
`boolean`	`set(V value)` Sets the value of this future.

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

- Constructor Detail
  - CommandFuture
```
public CommandFuture()
```
- Method Detail
  - await
```
public void await()
           throws InterruptedException
```
    Waits indefinitely until the command completes.
    If the thread is interrupted while waiting for the command to complete, this method will throw an InterruptedException and the thread's interrupt flag will be cleared.
    Please note that this method is blocking and thus negates the advantage of the asynchronous nature of this class. Consider using onSuccess(SuccessListener) and onFailure(FailureListener) instead.
    
    Throws:
    
    InterruptedException - if the method is interrupted by calling Thread.interrupt(). The interrupt flag will be cleared
  - await
```
public void await(long timeout,
         TimeUnit unit)
           throws InterruptedException,
                  TimeoutException
```
    Waits for at most the given time until the command completes.
    If the thread is interrupted while waiting for the command to complete, this method will throw an InterruptedException and the thread's interrupt flag will be cleared.
    Please note that this method is blocking and thus negates the advantage of the asynchronous nature of this class. Consider using onSuccess(SuccessListener) and onFailure(FailureListener) instead.
    
    Parameters:
    timeout - the maximum amount of the given time unit to wait
    unit - the time unit of the timeout argument
    
    Throws:
    
    InterruptedException - if the method is interrupted by calling Thread.interrupt(). The interrupt flag will be cleared
    
    TimeoutException - if the given time elapsed without the command completing
  - awaitUninterruptibly
```
public void awaitUninterruptibly()
```
    Waits indefinitely until the command completes.
    If the thread is interrupted while waiting for the command to complete, the interrupt is simply ignored and no InterruptedException is thrown.
    Please note that this method is blocking and thus negates the advantage of the asynchronous nature of this class. Consider using onSuccess(SuccessListener) and onFailure(FailureListener) instead.
  - awaitUninterruptibly
```
public void awaitUninterruptibly(long timeout,
                        TimeUnit unit)
                          throws TimeoutException
```
    Waits for at most the given time until the command completes.
    If the thread is interrupted while waiting for the command to complete, the interrupt is simply ignored and no InterruptedException is thrown.
    Please note that this method is blocking and thus negates the advantage of the asynchronous nature of this class. Consider using onSuccess(SuccessListener) and onFailure(FailureListener) instead.
    
    Parameters:
    timeout - the maximum amount of the given time unit to wait
    unit - the time unit of the timeout argument
    
    Throws:
    
    TimeoutException - if the given time elapsed without the command completing
  - get
```
public V get()
      throws InterruptedException
```
    Waits indefinitely until the command completes and returns the result of the command.
    If the thread is interrupted while waiting for the command to complete, this method will throw an InterruptedException and the thread's interrupt flag will be cleared.
    Please note that this method is blocking and thus negates the advantage of the asynchronous nature of this class. Consider using onSuccess(SuccessListener) and onFailure(FailureListener) instead.
    
    Specified by:
    
    get in interface Future<V>
    
    Returns:
    the server response to the command
    
    Throws:
    
    InterruptedException - if the method is interrupted by calling Thread.interrupt(). The interrupt flag will be cleared
    
    CancellationException - if the CommandFuture was cancelled before the command completed
    
    TS3Exception - if the command fails
  - get
```
public V get(long timeout,
    TimeUnit unit)
      throws InterruptedException,
             TimeoutException
```
    Waits for at most the given time until the command completes and returns the result of the command.
    If the thread is interrupted while waiting for the command to complete, this method will throw an InterruptedException and the thread's interrupt flag will be cleared.
    Please note that this method is blocking and thus negates the advantage of the asynchronous nature of this class. Consider using onSuccess(SuccessListener) and onFailure(FailureListener) instead.
    
    Specified by:
    
    get in interface Future<V>
    
    Parameters:
    timeout - the maximum amount of the given time unit to wait
    unit - the time unit of the timeout argument
    
    Returns:
    the server response to the command
    
    Throws:
    
    InterruptedException - if the method is interrupted by calling Thread.interrupt(). The interrupt flag will be cleared
    
    TimeoutException - if the given time elapsed without the command completing
    
    CancellationException - if the CommandFuture was cancelled before the command completed
    
    TS3Exception - if the command fails
  - getUninterruptibly
```
public V getUninterruptibly()
```
    Waits indefinitely until the command completes and returns the result of the command.
    If the thread is interrupted while waiting for the command to complete, the interrupt is simply ignored and no InterruptedException is thrown.
    Please note that this method is blocking and thus negates the advantage of the asynchronous nature of this class. Consider using onSuccess(SuccessListener) and onFailure(FailureListener) instead.
    
    Returns:
    the server response to the command
    
    Throws:
    
    CancellationException - if the CommandFuture was cancelled before the command completed
    
    TS3Exception - if the command fails
  - getUninterruptibly
```
public V getUninterruptibly(long timeout,
                   TimeUnit unit)
                     throws TimeoutException
```
    Waits for at most the given time until the command completes and returns the result of the command.
    If the thread is interrupted while waiting for the command to complete, the interrupt is simply ignored and no InterruptedException is thrown.
    Please note that this method is blocking and thus negates the advantage of the asynchronous nature of this class. Consider using onSuccess(SuccessListener) and onFailure(FailureListener) instead.
    
    Parameters:
    timeout - the maximum amount of the given time unit to wait
    unit - the time unit of the timeout argument
    
    Returns:
    the server response to the command
    
    Throws:
    
    TimeoutException - if the given time elapsed without the command completing
    
    CancellationException - if the CommandFuture was cancelled before the command completed
    
    TS3Exception - if the command fails
  - isDone
```
public boolean isDone()
```
    Specified by:
    
    isDone in interface Future<V>
  - isSuccessful
```
public boolean isSuccessful()
```
    Returns true if this command completed successfully, i.e. the future wasn't cancelled and the command completed without throwing an exception.
    
    Returns:
    true if the command completed successfully
  - isCancelled
```
public boolean isCancelled()
```
    Specified by:
    
    isCancelled in interface Future<V>
  - hasFailed
```
public boolean hasFailed()
```
    Returns true if the command failed and threw a TS3Exception.
    
    Returns:
    true if the command failed
  - set
```
public boolean set(V value)
```
    Sets the value of this future. This will mark the future as successful.
    Furthermore, this will run the CommandFuture.SuccessListener, if one is registered. All exceptions thrown from the body of the SuccessListener are caught so no exceptions can leak into user code.
    Note that a future's value can only be set once. Subsequent calls to this method will be ignored.
    
    Parameters:
    value - the value to set this future to
    
    Returns:
    true if the command was marked as successful
  - fail
```
public boolean fail(TS3Exception exception)
```
    Notifies this future that the command has failed.
    Furthermore, this will run the CommandFuture.FailureListener, if one is registered. All exceptions thrown from the body of the FailureListener are caught so no exceptions can leak into user code.
    Note that a future can only fail once. Subsequent calls to this method will be ignored.
    
    Parameters:
    exception - the exception that occurred while executing this command
    
    Returns:
    true if the command was marked as failed
  - cancel
```
public boolean cancel(boolean mayInterruptIfRunning)
```
    Cancelling a CommandFuture will not actually cancel the execution of the command which was sent to the TeamSpeak server.
    It will, however, prevent the CommandFuture.SuccessListener and the CommandFuture.FailureListener from firing, provided a response from the server has not yet arrived.
    
    Specified by:
    
    cancel in interface Future<V>
  - onSuccess
```
public CommandFuture<V> onSuccess(CommandFuture.SuccessListener<? super V> listener)
```
    Sets a CommandFuture.SuccessListener which will be notified when this future succeeded and a value has been set.
    If this future has already succeeded, this method will immediately call the listener method, which will be executed synchronously.
    
    Parameters:
    listener - the listener to notify of a success
    
    Returns:
    this object for chaining
  - onFailure
```
public CommandFuture<V> onFailure(CommandFuture.FailureListener listener)
```
    Sets a CommandFuture.FailureListener which will be notified when this future fails because of a error returned by the TeamSpeak server.
    If this future has already failed, this method will immediately call the listener method, which will be executed synchronously.
    
    Parameters:
    listener - the listener to notify of a failure
    
    Returns:
    this object for chaining
  - forwardSuccess
```
public CommandFuture<V> forwardSuccess(CommandFuture<? super V> otherFuture)
```
    Forwards a success to another future by calling set(Object) on that future with the value this future was set to.
    This will register a CommandFuture.SuccessListener, meaning that you will not be able to register another SuccessListener.
    
    Parameters:
    otherFuture - the future to forward a success to
    
    Returns:
    this object for chaining
  - forwardFailure
```
public CommandFuture<V> forwardFailure(CommandFuture<?> otherFuture)
```
    Forwards a failure to another future by calling fail(TS3Exception) on that future with the error that caused this future to fail.
    This will register a CommandFuture.FailureListener, meaning that you will not be able to register another FailureListener.
    
    Parameters:
    otherFuture - the future to forward a failure to
    
    Returns:
    this object for chaining
  - forwardResult
```
public void forwardResult(CommandFuture<V> otherFuture)
```
    Forwards both a success as well as a failure to another CommandFuture. This method just calls both forwardSuccess(CommandFuture) and forwardFailure(CommandFuture).
    This will set both a CommandFuture.SuccessListener as well as a CommandFuture.FailureListener, so no other listeners can be registered.
    
    Parameters:
    otherFuture - the future which should be notified about
  - immediate
```
public static <V> CommandFuture<V> immediate(V value)
```
    Returns a new CommandFuture that already has a value set.
    
    Type Parameters:
    V - the dynamic type of the value, will usually be inferred
    Parameters:
    value - the default value for the new CommandFuture
    
    Returns:
    a new CommandFuture with a default value
  - ofAll
```
@SafeVarargs
public static <F> CommandFuture<List<F>> ofAll(CommandFuture<F>... futures)
```
    Combines multiple CommandFutures into a single future, which will succeed if all futures succeed and fail as soon as one future fails.
    
    Type Parameters:
    F - the common return type of the futures
    Parameters:
    futures - the futures to combine
    
    Returns:
    a future which succeeds if all supplied futures succeed
  - ofAll
```
public static <F> CommandFuture<List<F>> ofAll(Collection<CommandFuture<F>> futures)
```
    Combines a collection of CommandFutures into a single future, which will succeed if all futures succeed and fail as soon as one future fails.
    
    Type Parameters:
    F - the common return type of the futures
    Parameters:
    futures - the futures to combine
    
    Returns:
    a future which succeeds if all supplied futures succeed
  - ofAny
```
@SafeVarargs
public static <F> CommandFuture<F> ofAny(CommandFuture<F>... futures)
```
    Combines multiple CommandFutures into a single future, which will succeed if any of the futures succeeds and fail if all of the futures fail.
    
    Type Parameters:
    F - the common return type of the futures
    Parameters:
    futures - the futures to combine
    
    Returns:
    a future which succeeds if one of the supplied futures succeeds
  - ofAny
```
public static <F> CommandFuture<F> ofAny(Collection<CommandFuture<F>> futures)
```
    Combines a collection of CommandFutures into a single future, which will succeed as soon as one of the futures succeeds and fail if all futures fail.
    
    Type Parameters:
    F - the common return type of the futures
    Parameters:
    futures - the futures to combine
    
    Returns:
    a future which succeeds if one of the supplied futures succeeds

Class CommandFuture<V>

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

CommandFuture

Method Detail

await

await

awaitUninterruptibly

awaitUninterruptibly

get

get

getUninterruptibly

getUninterruptibly

isDone

isSuccessful

isCancelled

hasFailed

set

fail

cancel

onSuccess

onFailure

forwardSuccess

forwardFailure

forwardResult

immediate

ofAll

ofAll

ofAny

ofAny