com.google.api.gax.httpjson

Class HttpJsonClientCall<RequestT,ResponseT>

java.lang.Object

com.google.api.gax.httpjson.HttpJsonClientCall<RequestT,ResponseT>

Type Parameters:

RequestT - type of message sent to the server

ResponseT - type of message received one or more times from the server

@BetaApi
public abstract class HttpJsonClientCall<RequestT,ResponseT>
extends Object

An instance of a call to a remote method. A call will send zero or more request messages to the server and receive zero or more response messages back.

Instances are created by a HttpJsonChannel and used by stubs to invoke their remote behavior.

start(com.google.api.gax.httpjson.HttpJsonClientCall.Listener<ResponseT>, com.google.api.gax.httpjson.HttpJsonMetadata) must be called prior to calling any other methods, with the exception of cancel(java.lang.String, java.lang.Throwable). Whereas cancel(java.lang.String, java.lang.Throwable) must not be followed by any other methods, but can be called more than once, while only the first one has effect.

Methods are potentially blocking but are designed to execute quickly. The implementations of this class are expected to be thread-safe.

There is a race between cancel(java.lang.String, java.lang.Throwable) and the completion/failure of the RPC in other ways. If cancel(java.lang.String, java.lang.Throwable) won the race, Listener.onClose() is called with statusCode corresponding to CANCELLED. Otherwise, Listener.onClose() is called with whatever status the RPC was finished. We ensure that at most one is called.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	HttpJsonClientCall.Listener<T> Callbacks for receiving metadata, response messages and completion status from the server.

Constructor Summary

Constructors

Constructor and Description
HttpJsonClientCall()

Method Summary

Modifier and Type	Method and Description
abstract void	cancel(String message, Throwable cause) Prevent any further processing for this HttpJsonClientCall.
abstract void	halfClose() Close the call for request message sending.
abstract void	request(int numMessages) Requests up to the given number of messages from the call to be delivered to HttpJsonClientCall.Listener.onMessage(Object).
abstract void	sendMessage(RequestT message) Send a request message to the server.
abstract void	start(HttpJsonClientCall.Listener<ResponseT> responseListener, HttpJsonMetadata requestHeaders) Start a call, using responseListener for processing response messages.

Methods inherited from class java.lang.Object

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

Constructor Detail

HttpJsonClientCall

public HttpJsonClientCall()

Method Detail

start

public abstract void start(HttpJsonClientCall.Listener<ResponseT> responseListener,
                           HttpJsonMetadata requestHeaders)

Start a call, using responseListener for processing response messages.

It must be called prior to any other method on this class, except for cancel(java.lang.String, java.lang.Throwable) which may be called at any time.

Parameters:

responseListener - receives response messages

requestHeaders - which can contain extra call metadata, e.g. authentication credentials.

request

public abstract void request(int numMessages)

Requests up to the given number of messages from the call to be delivered to HttpJsonClientCall.Listener.onMessage(Object). No additional messages will be delivered.

Message delivery is guaranteed to be sequential in the order received. In addition, the listener methods will not be accessed concurrently. While it is not guaranteed that the same thread will always be used, it is guaranteed that only a single thread will access the listener at a time.

If called multiple times, the number of messages able to delivered will be the sum of the calls.

This method is safe to call from multiple threads without external synchronization.

Parameters:

numMessages - the requested number of messages to be delivered to the listener. Must be non-negative.

cancel

public abstract void cancel(@Nullable
                            String message,
                            @Nullable
                            Throwable cause)

Prevent any further processing for this HttpJsonClientCall. No further messages may be sent or will be received. The server is not informed of cancellations. Cancellation is permitted even if previously halfClose()d. Cancelling an already cancel()ed ClientCall has no effect.

No other methods on this class can be called after this method has been called.

Parameters:

message - if not null, will appear as the description of the CANCELLED status

cause - if not null, will appear as the cause of the CANCELLED status

halfClose

public abstract void halfClose()

Close the call for request message sending. Incoming response messages are unaffected. This should be called when no more messages will be sent from the client.

sendMessage

public abstract void sendMessage(RequestT message)

Send a request message to the server. May be called zero or more times but for unary and server streaming calls it must be called not more than once.

Parameters:

message - message to be sent to the server.