bootique-jersey

Provides Jersey JAX-RS server and client integration with Bootique. This provides the necessary API to create REST services and consume someone else's REST services.

Jersey Server

Integrates JAX-RS server as a servlet in Bootique. See usage example bootique-rest-demo. A few quick tips:

Jakarta vs JavaEE: Bootique 3.x supports both the legacy JavaEE and the newer Jakarta versions of Jersey. Each Bootique Jersey module is shipped in two flavors (with and without -jakarta in the name). The examples below a based on the newer Jakarta modules. But It is your choice which one to use. The API of both is identical (except for the import package).

Add Jersey server capabilities to your Bootique app:

<dependency>
	<groupId>io.bootique.jersey</groupId>
	<artifactId>bootique-jersey-jakarta</artifactId>
</dependency>

Publish individual endpoints:

public void configure(Binder binder) {
    JerseyModule.extend(binder)
        .addResource(MyApi1.class)
        .addResource(MyApi2.class);
}

Add JSON serialization capabilities:

<dependency>
	<groupId>io.bootique.jersey</groupId>
	<artifactId>bootique-jersey-jakarta-jackson</artifactId>
</dependency>

Exclude null properties from JSON responses:

public void configure(Binder binder) {
    JerseyJacksonModule.extend(binder).skipNullProperties();
}

Enable debug output of the application resources:

log:
  loggers:
    io.bootique.jersey:
      level: debug # or "trace" for even more detailed output

Jersey Client

Integrates JAX-RS-based HTTP client in Bootique with support for various types of server authentication (BASIC, OAuth2, etc.). Allows to configure multiple client runtime parameters, as well as define server URL endpoints. Implementation is built on top of Jersey and Grizzly connector.

Basic Client Usage

Add the client module to your Bootique app:

<dependency>
	<groupId>io.bootique.jersey</groupId>
	<artifactId>bootique-jersey-jakarta-client</artifactId>
</dependency>

Or if you need clients with health checks and metrics:

<dependency>
	<groupId>io.bootique.jersey</groupId>
	<artifactId>bootique-jersey-jakarta-client-instrumented</artifactId>
</dependency>

Inject HttpClientFactory and create client instances:

@Inject
private HttpClientFactory clientFactory;

public void doSomething() {

    Client client = clientFactory.newClient();
    Response response = client
        .target("https://example.org")
        .request()
        .get();
}

Optionally, configure client parameters:

jerseyclient:
  followRedirects: true
  readTimeoutMs: 2000
  connectTimeoutMs: 2000
  asyncThreadPoolSize: 10

URL Targets

In the example above we injected HttpClientFactory (that produced instances of JAX RS Client), and hardcoded the endpoint URL in Java. Instead you can map multiple URLs in the .yml, assigning each URL a symbolic name and optionally providing URL-specific runtime parameters:

jerseyclient:
  targets:
    google:
      url: "https://google.com"
    bootique:
      url: "https://bootique.io"
      followRedirects: false

Now you can inject HttpTargets and acquire instances of WebTarget by name:

@Inject
private HttpTargets targets;

public void doSomething() {

    Response response = targets.newTarget("bootique").request().get();
}

This not only reduces the amount of code, but more importantly allows to manage your URLs (and their runtime parameters) via configuration. E.g. you might use a different URL between test and production environments without changing the code.

Using BASIC Authentication

If your server endpoint requires BASIC authentication, you can associate your Clients and WebTargets with a named auth configuration. One or more named configurations are setup like this:

jerseyclient:
  auth:
    myauth:
      type: basic
      username: myuser
      password: mypassword

When creating a client in the Java code you can reference auth name ("myauth"):

@Inject
private HttpClientFactory clientFactory;

public void doSomething() {

    Client client = clientFactory.newBuilder().auth("myauth").build();
    Response response = client
        .target("https://example.org")
        .request()
        .get();
}

Or you can associate a target with it:

jerseyclient:
  ...
  targets:
    secret:
      url: "https://example.org"
      auth: myauth

Using OAuth2 Authentication

OAuth2 authentication is very similar to BASIC. In fact they are no different on the Java end. In YAML the type should be "oauth2", and an extra "tokenUrl" property is required. Here is an example auth for a Twitter client:

jerseyclient:
  auth:
    twitter:
      type: oauth2
      tokenUrl: https://api.twitter.com/oauth2/token
      username: sdfjkdferefxfkdsf
      password: Efcdsfdsflkurecdsfj

bootique / bootique-jersey