com.github.theholywaffle.teamspeak3.api

Class CommandFuture<V>

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(), isFailed() 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(QueryError) 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()

Method Summary

Modifier and Type	Method and Description
boolean	cancel(boolean mayInterruptIfRunning) Cancelling a CommandFuture will not actually cancel the execution of the command which was sent to the TeamSpeak server.
boolean	fail(QueryError error) Notifies this future that the command has failed.
CommandFuture<V>	forwardFailure(CommandFuture<?> otherFuture) Forwards a failure to another future by calling fail(QueryError) 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	isCancelled()
boolean	isDone()
boolean	isFailed() Returns true if the command failed and threw a TS3CommandFailedException.
boolean	isSuccessful() Returns true if this command completed successfully, i.e. the future wasn't cancelled and the command completed without throwing an exception.
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.
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.
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.
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.
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

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CommandFuture

public CommandFuture()

Method Detail

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.

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

TS3CommandFailedException - 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.

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

TS3CommandFailedException - 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.

Returns:

the server response to the command

Throws:

CancellationException - if the CommandFuture was cancelled before the command completed

TS3CommandFailedException - 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.

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

TS3CommandFailedException - 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>

isFailed

public boolean isFailed()

Returns true if the command failed and threw a TS3CommandFailedException.

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(QueryError error)

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:

error - the error that was returned from the server

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(QueryError) 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

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