Skip to content

mutiny.md

Latest commit

 

History

History
177 lines (132 loc) · 3.27 KB

mutiny.md

File metadata and controls

177 lines (132 loc) · 3.27 KB

Mutiny Client

The MutinyArk client returns Uni<T> from SmallRye Mutiny - ideal for Quarkus and reactive Vert.x applications.

Installation

<dependency>
    <groupId>xyz.juandiii</groupId>
    <artifactId>ark-mutiny</artifactId>
</dependency>
<dependency>
    <groupId>xyz.juandiii</groupId>
    <artifactId>ark-transport-vertx-mutiny</artifactId>
</dependency>

Or use the Quarkus extension which auto-configures everything:

<dependency>
    <groupId>xyz.juandiii</groupId>
    <artifactId>ark-quarkus-jackson</artifactId>
</dependency>

Building the Client

Manual

Vertx vertx = Vertx.vertx();
WebClient webClient = WebClient.create(vertx);

MutinyArk client = MutinyArkClient.builder()
    .serializer(new JacksonClassicSerializer(new ObjectMapper()))
    .transport(new ArkVertxMutinyTransport(webClient))
    .baseUrl("https://api.example.com")
    .build();

With Quarkus Extension

@ApplicationScoped
public class UserService {

    private final MutinyArk client;

    @Inject
    public UserService(MutinyArkClient.Builder builder) {
        this.client = builder
            .baseUrl("https://api.example.com")
            .build();
    }
}

Making Requests

GET

Uni<User> user = client.get("/users/1")
    .accept(MediaType.APPLICATION_JSON)
    .retrieve()
    .body(User.class);

GET with generics

Uni<List<User>> users = client.get("/users")
    .queryParam("page", "1")
    .retrieve()
    .body(new TypeRef<List<User>>() {});

POST

Uni<User> created = client.post("/users")
    .contentType(MediaType.APPLICATION_JSON)
    .body(new User("Juan", "juan@example.com"))
    .retrieve()
    .body(User.class);

DELETE

Uni<ArkResponse<Void>> response = client.delete("/users/1")
    .retrieve()
    .toBodilessEntity();

Full Response

Uni<ArkResponse<User>> response = client.get("/users/1")
    .retrieve()
    .toEntity(User.class);

response.subscribe().with(r -> {
    int status = r.statusCode();
    User body = r.body();
    boolean ok = r.isSuccessful();
});

Multi (streaming from JSON array)

Multi<User> users = client.get("/users")
    .retrieve()
    .bodyAsMulti(User.class);

Deserializes the JSON array response and streams each element as a Multi<T>.

Per-Request Timeout

Uni<User> user = client.get("/slow-endpoint")
    .timeout(Duration.ofSeconds(60))
    .retrieve()
    .body(User.class);

Usage in Quarkus REST

@Path("/users")
public class UserResource {

    @Inject MutinyArk client;

    @GET
    @Path("/{id}")
    public Uni<User> getUser(@PathParam("id") String id) {
        return client.get("/users/" + id)
            .retrieve()
            .body(User.class);
    }
}

Error Handling

See Error Handling for the full exception hierarchy. Errors propagate through the Uni:

client.get("/users/1")
    .retrieve()
    .body(User.class)
    .onFailure(NotFoundException.class).recoverWithItem(User.unknown())
    .onFailure(ServerException.class).retry().atMost(3);

Related