com.pcloud.networking.api

Interface Call<T>

Type Parameters:

T - the type of the returned result

All Superinterfaces:

java.lang.Cloneable

public interface Call<T>
extends java.lang.Cloneable

An abstraction over a RPC call to pCloud's API servers.

A Call object resemebles a future request to execute a method having the following properties:

• Allows for asynchronous execution by the enqueue(Callback) method with a Callback object.
• Allows for synchronous execution on the same thread by calling the execute() method.
• Can be executed only once, state can be checked via the isExecuted() property.
• Once created, a Call instance can be cloned via the clone() method and executed again.
• Executed calls can be cancelled via the cancel() method. It is safe to call cancel() multiple times.
• Running calls that are being cancelled will result in an IOException being thrown or reported via Callback.onFailure(Call, IOException).

Method Summary

Modifier and Type	Method and Description
void	cancel() Cancel this call.
Call<T>	clone()
void	enqueue(Callback<T> callback) Asynchronously send the request and notify callback of its response or if an error occurred talking to the server, creating the request, or processing the response.
T	enqueueAndWait() Sends a request on another thread but blocks the calling thread until the operation is complete or an exception is thrown.
T	enqueueAndWait(long timeout, java.util.concurrent.TimeUnit timeUnit) Sends a request on another thread but blocks the calling thread for at most the amount of time specified in the arguments.
T	execute() Synchronously send the request and return its response.
boolean	isCancelled()
boolean	isExecuted() Returns true if this call has been either executed or enqueued.
java.lang.String	methodName() The API method name to be executed.

Method Detail

methodName

java.lang.String methodName()

The API method name to be executed.

Returns:

the non-null method name

execute

T execute()
   throws java.io.IOException

Synchronously send the request and return its response.

Returns:

the result of the call

Throws:

java.io.IOException - if a problem occurred talking to the server.

enqueue

void enqueue(Callback<T> callback)

Asynchronously send the request and notify callback of its response or if an error occurred talking to the server, creating the request, or processing the response.

Parameters:

callback - a non-null object that will be notified when a result is available or an error occurs.

Throws:

java.lang.IllegalArgumentException - on a null callback argument.

enqueueAndWait

T enqueueAndWait()
          throws java.io.IOException,
                 java.lang.InterruptedException

Sends a request on another thread but blocks the calling thread until the operation is complete or an exception is thrown.

Returns:

The result of the network request

Throws:

java.io.IOException - on failed IO operations

java.lang.InterruptedException - If the waiting thread is interrupted

enqueueAndWait

T enqueueAndWait(long timeout,
                 java.util.concurrent.TimeUnit timeUnit)
          throws java.io.IOException,
                 java.lang.InterruptedException,
                 java.util.concurrent.TimeoutException

Sends a request on another thread but blocks the calling thread for at most the amount of time specified in the arguments.

Note you are not guaranteed to receive the result after the specified time is up. After the time is up you will receive the result of the request if available or a TimeoutException if the request is not yet completed.

Parameters:

timeout - The maximum amount of time before an attempt to gather the result of the request.

timeUnit - The units in which you specified the time argument.

Returns:

The result of the request if available

Throws:

java.io.IOException - on failed IO operations

java.lang.InterruptedException - if the waiting thread is interrupted

java.util.concurrent.TimeoutException - if the time is up and the request is not yet completed

isExecuted

boolean isExecuted()

Returns true if this call has been either executed or enqueued. It is an error to execute or enqueue a call more than once.

Returns:

true if this call has been executed, false otherwise

cancel

void cancel()

Cancel this call. An attempt will be made to cancel in-flight calls, and if the call has not yet been executed it never will be.

isCancelled

boolean isCancelled()

Returns:

true if this call has been cancelled, false otherwise

clone

Call<T> clone()

Returns:

a new, identical call to this one which can be enqueued or executed again.