Objetos suportados

Tipos suportados

Por padrão, os seguintes tipos de retorno de método são suportados:

  • String

public interface MyApi {
@Path("/customers/{id}") @Get
String getCustomerAsString(@PathParameter String id);
}
  • Tipos primitivos ou wrappers

public interface MyApi {
@Path("/integer") @Get
int integer();
@Path("/boolean") @Get
Boolean boolean();
@Path("/double") @Get
double double();
}
  • byte[]

public interface MyApi {
@Path("/customers/{id}") @Get
byte[] getCustomerAsBytes(@PathParameter String id);
}
  • InputStream

public interface MyApi {
@Path("/customers/{id}") @Get
InputStream getCustomerAsStream(@PathParameter String id);
}
  • Optional

public interface MyApi {
@Path("/customers/{id}") @Get
Optional<Customer> getCustomerById(@PathParameter String id);
}
  • Collection

public interface MyApi {
@Path("/customers") @Get
Collection<Customer> getAllCustomers();
}
  • Stream

public interface MyApi {
@Path("/customers") @Get
Stream<Customer> getAllCustomers();
}
  • Enumeration

public interface MyApi {
@Path("/customers") @Get
Enumeration<Customer> getAllCustomers();
}
  • Iterator

public interface MyApi {
@Path("/customers") @Get
Iterator<Customer> getAllCustomers();
}
  • ListIterator

public interface MyApi {
@Path("/customers") @Get
ListIterator<Customer> getAllCustomers();
}
  • Iterable

public interface MyApi {
@Path("/customers") @Get
Iterable<Customer> getAllCustomers();
}
  • Queue

public interface MyApi {
@Path("/customers") @Get
Queue<Customer> getAllCustomers();
}
  • Callable

Callable é um objeto que representa uma computação qualquer que retorna algum valor. A requisição HTTP será feita de modo lazy, eventualmente em outra thread (o seu código será responsável pela execução do Callable).

public interface MyApi {
@Path("/customers/{id}") @Get
Callable<Customer> getCustomerById(@PathParameter String id);
}
  • Runnable

Runnable é um objeto que representa uma computação qualquer, e não retorna nenhum valor. A requisição HTTP será feita de modo lazy, eventualmente em outra thread (o seu código será responsável pela execução do Runnable).

public interface MyApi {
@Path("/customers") @Post
Runnable createCustomer(@BodyParameter Customer customer);
}
  • EndpointCall<>

Esse objeto representa uma operação HTTP realizada pelo java-restify. O seu código será responsável por invocar o método execute.

import com.github.ljtfreitas.restify.http.client.call.EndpointCall;
public interface MyApi {
@Path("/customers/{id}") @Get
EndpointCall<Customer> getCustomerById(@PathParameter String id);
}
  • Headers

Esse objeto é uma coleção imutável de cabeçalhos. Quando utilizado como retorno de método, irá conter os headers da resposta.

import com.github.ljtfreitas.restify.http.client.message.Headers;
public interface MyApi {
@Path("/customers/{id}") @Head
Headers getCustomerById(@PathParameter String id);
}
  • StatusCode

Esse objeto representa o status HTTP da resposta.

import com.github.ljtfreitas.restify.http.client.message.response.StatusCode;
public interface MyApi {
@Path("/customers") @Post
StatusCode createCustomer(@BodyParameter Customer customer);
}
  • EndpointResponse<>

Esse objeto fornece acesso a todos os dados da resposta (incluindo cabeçalhos e status code). Também fornece acesso ao corpo, já deserializado para um objeto.

import com.github.ljtfreitas.restify.http.client.response.EndpointResponse;
public interface MyApi {
@Path("/customers/{id}") @Get
EndpointResponse<Customer> getCustomerById(@PathParameter String id);
}

Tipos assíncronos

Alguns tipos de retorno farão com que a requisição seja executada da maneira assíncrona automaticamente. De maneira simplificada, a requisição simplesmente será realizada em uma thread separada. O mecanismo é explicado com mais detalhes na documentação sobre requisições assíncronas HTTP.

O java-restify oferece suporte para vários tipos de retorno assíncronos, e os handlers para esses objetos são registrados automaticamente. Para tornar essa configuração explícita:

MyApi myApi = new RestifyProxyBuilder()
.handlers()
.async() // habilita objetos assíncronos (são habilitados por padrão; use apenas caso deseje tornar a utilização explícita)
.target(MyApi.class)
.build();

Os seguintes tipos assíncronos são suportados:

  • Future

public interface MyApi {
@Path("/customers/{id}") @Get
Future<Customer> getCustomerById(@PathParameter String id);
}
  • CompletableFuture

public interface MyApi {
@Path("/customers/{id}") @Get
CompletableFuture<Customer> getCustomerById(@PathParameter String id);
}
  • FutureTask

public interface MyApi {
@Path("/customers/{id}") @Get
FutureTask<Customer> getCustomerById(@PathParameter String id);
}
  • AsyncEndpointCall

Esse objeto é análogo ao EndpointCall, e fornece métodos para execução assíncrona.

import com.github.ljtfreitas.restify.http.client.call.async.AsyncEndpointCall;
public interface MyApi {
@Path("/customers/{id}") @Get
AsyncEndpointCall<Customer> getCustomerById(@PathParameter String id);
}

@CallbackParameter

Ao invés de lidar com o retorno do método, outra possibilidade é utilizar um parâmetro anotado com @CallbackParameter, que represente um callback para a execução assíncrona.

Ao utilizar parâmetros anotados com @CallbackParameter, o retorno do método deve ser void.

import com.github.ljtfreitas.restify.http.contract.CallbackParameter;
import com.github.ljtfreitas.restify.http.client.call.async.EndpointCallSuccessCallback;
import com.github.ljtfreitas.restify.http.client.call.async.EndpointCallFailureCallback;
import com.github.ljtfreitas.restify.http.client.call.async.EndpointCallCallback;
public interface MyApi {
/* callback do tipo java.util.function.BiConsumer:
uma função que recebe o objeto de resposta e a exceção (se houver)
*/
@Path("/customers/{id}") @Get
void getCustomerById(@PathParameter String id, @CallbackParameter BiConsumer<Customer, Throwable> callback);
/* EndpointCallSuccessCallback permite capturar a resposta deserializada como um objeto.
Essa interface possui um único método onSuccess(T response)
*/
@Path("/customers/{id}") @Get
void getCustomerById(@PathParameter String id, @CallbackParameter EndpointCallSuccessCallback<Customer> success);
/* EndpointCallFailureCallback permite capturar a exceção gerada pela requisição HTTP, se ocorrer.
Essa exceção pode ser um problema de I/O ou uma resposta de erro (4xx, 5xx)
Essa interface possui um único método onFailure(Throwable throwable):
*/
@Path("/customers/{id}") @Get
void getCustomerById(@PathParameter String id, @CallbackParameter EndpointCallFailureCallback failure);
/* É possível usar parâmetros dos dois tipos
*/
@Path("/customers/{id}") @Get
void getCustomerById(@PathParameter String id,
@CallbackParameter EndpointCallSuccessCallback<Customer> success,
@CallbackParameter EndpointCallFailureCallback failure);
/* Existe uma terceira interface chamada EndpointCallCallback, que extende EndpointCallSuccessCallback e EndpointCallFailureCallback.
Essa interface também é uma opção caso você precise dos dois callbacks (sucesso e falha)
*/
@Path("/customers/{id}") @Get
void getCustomerById(@PathParameter String id, @CallbackParameter EndpointCallCallback<Customer> callback);
}

Configuração

Os handlers responsáveis pela execução de métodos assíncronos utilizam o mesmo thread pool configurado para requisições assíncronas. A documentação sobre requisições assíncronas fornece mais detalhes de configuração e customizações.