Forem: Guillaume Le Floch

Self-referencing generics, wait, what ?

Guillaume Le Floch — Mon, 20 Nov 2023 21:12:09 +0000

Have you ever seen some declaration of class with a generic type referencing itself ?

public class BaseProject<T extends BaseProject> { ... }

public class FileProject extends BaseProject<FileProject> { ... }

It took me some time to understand the purpose of this. Now that this is clear for me, I decided to write something in order to explain it using a simple example: Builders.

Introduction

Nowadays, library author provides usually builder to ease the usage of their objects.
This allows you to easily create complex objects by chaining methods.

A cache can easily be created like:

Cache<String> cache = Caffeine.newBuilder()
    .expireAfterWrite(1, TimeUnit.MINUTES)
    .maximumSize(100)
    .build();

Crafting a builder can be summed up by creating a class (usually nested) that will expose a method for each property with can set in the object. This builder also exposes a build() method that will call the parent class constructor using data stored in the builder.

How to design a simple builder

Let's say we have the following class:

public class Project {
    private final String name;
    private final File path;
    private final Type type;
    ...
}

Creating a new instance of this class can easily be done by calling a constructor with the required arguments:

var myProject = new Project(name, path, type);

However, it can become complicated when some parameters are optional, we don't want to have all possible constructors declared in our class.
This is where a builder become really handy.

Let's implement it in our Project class:

public static class ProjectBuilder {
    private String name;
    private File path;
    private Type type;

    public Builder name(String name) {
        this.name = name;
        return this;
    }

    public Builder path(File path) {
        this.path = path;
        return this;
    }

    public Builder type(Type type) {            
        this.type = type;
        return this;
    }

    public Project build() {
        return new Project(name, path, type);
    }
}

This builder can be used in the following way:

var myProject = new ProjectBuilder()
           .name("my-project")
           .type(Type.File)
           .build();

Thus, creating a complex object can be as easy as chaining methods based on property we want to set.

What about inheritance

In some case, the class we try to build may extend some classes, and share some property with a super class.
For example, our project could be more specific, instead of having a type property we could have a specific class for each type:

public class BaseProject { 
    protected final String name;
    ...
}
public class FileProject extends BaseProject { 
    private final Path path;
    ...
}
public class UrlProject extends BaseProject { 
    private final URI link;
    ... 
}

Regarding builder, we could decline a specific builder for each subtype, such as:

public class FileProjectBuilder {
    private String name;
    private File path;

    public FilePojectBuilder name(String name) {
        this.name = name;
        return this;
    }

    public FilePojectBuilder path(File path) {
        this.path = path;
        return this;
    }

    public FileProject build() { ... }
}

As we can see with this example, all properties of the BaseProject must be declared in the builder alongside specific properties.

How could we fix that ?

Well, we could use inheritance, such as:

public abstract class BaseProjectBuilder {
    protected String name;

    public BaseProjectBuilder name(String name) {
        this.name = name;
        return this;
    }

    public abstract Project build();
    ...
}

public class FileProjectBuilder extends BaseProjectBuilder {
    private File path;

    public FilePojectBuilder path(File path) {
        this.path = path;
        return this;
    }

    @Override
    public FileProject build() {
        ...
    }
}

public class UrlProject extends BaseProject {
    private URI link;

    public UrlPojectBuilder link(URI link) {
        this.link = link;
        return this;
    }

    @Override
    public UrlProject build() {
        ...
    }
}

With this code, the BaseProjectBuilder takes care of setting BaseProject properties and specific implementations take care of setting specific properties.

var myFileProject = new FileProjectBuilder()
                 .name("my-project")
                 .path(new Files("/src"))
                 .build();

Unfortunately, this does not work ... The type returned by the name() method is a BaseProjectBuilder while the path method is part of the FileProjectBuilder subclass. We just lost the subtype when calling the name() method.

Can we fix that ? Yes, by using self referencing generics.

First we need to update the BaseProjectBuilder class definition in the following way:

public abstract class BaseProjectBuilder<T extends BaseProjectBuilder> { ... }

Then all subclass will be updated to specify a type in there definition:

public class FileProjectBuilder extends BaseProjectBuilder<FileProjectBuilder> {
   ... 
}

public class UrlProjectBuilder extends BaseProjectBuilder<UrlProjectBuilder> {
   ...
}

Thanks to this generic type, we can now implement a self() method in the BaseProjectBuilder class and update the problematic name() method as well:

public abstract class BaseProjectBuilder<T extends BaseProjectBuilder> { 

    ... 

    public T name(String name) {
        this.name = name;
        return self();
    }

    public T self() {
        return (T) this;
    }

}

Now, the name method will return the correct type and the following code can be compile:

var myFileProject = new FileProjectBuilder()
                 .name("my-project")
                 .path(new Files("/src"))
                 .build();

What about Lombok ?

Lombok allows you to easily generate Builder using the @Builder annotation on the class level.

In that specific case we can define a constructor in the subclass and annotate the constructor directly.

Conclusion

Generics are really powerful and can help a lot when it come to handling types. As well as code organisation, we can also find patterns using generics.

Easy HTTP Client with Spring 6.x

Guillaume Le Floch — Mon, 30 Oct 2023 19:55:28 +0000

TLDR;

Spring 6 brings HttpServiceProxyFactory class allowing you to easily generate HTTP client based on interfaces and annotations.

Introduction

Before Spring 6.x, creating an HTTP client consisted of implementing each calls using either the old RestTemplate, the reactive WebClient, or the new RestClient introduced in Spring 6.1.
This leads to a lot of boilerplate code.

Nevertheless, some alternatives exist and aim to ease the development of rest client such as OpenFEIGN or the Eclipse MicroProfile RestClient specification.

In its last major release, Spring introduced the HttpServiceProxyFactory class as well as a new blocking rest client RestClient (in 6.1).

Thanks to this factory, you can declare your client using a simple interface annotated with @HttpExchange annotations (similar to Spring Data Repositories). The factory will then take care of generating an implementation of your interface.

Giving it a try

Let's consider the following beer API (based on Brewery OpenDB)

GET /api/v1/beer 
GET /api/v1/beer/{beerId}
POST /api/v1/beer

In order to create a client, we need to create an interface and specify annotation in order to declare:

Path
HTTP verb
Headers
Cookies
Path and Query parameters

package org.dev.example;

import org.springframework.web.service.annotation.*;

public interface BeerClient {

    @GetExchange("/api/v1/beer")
    public List<Beer> listBeers();

    @GetExchange("/api/v1/beer/{beerId}")
    public Beer getBeer(@PathVariable String beerId);

    @PostExchange("/api/v1/beer")
    public Beer createBeer(@RequestBody Beer beer);
}

It is possible to "simplify" paths using @HttpExchange directly on the interface

package org.dev.example;

import org.springframework.web.service.annotation.*;

@HttpExchange(url = "api/v1/beer", contentType = "application/json")
public interface BeerClient {

    @GetExchange
    public List<Beer> listBeers();

    @GetExchange("/{beerId}")
    public Beer getBeer(@PathVariable String beerId);

    @PostExchange
    public Beer createBeer(@RequestBody Beer beer);
}

Once the interface is created, creating a new client consists of using HttpServiceProxyFactory, setting the http client we would like to use and then creating the client implementation.

public BeerClient buildBeerRestClient(WebClient webClient) {
    HttpServiceProxyFactory clientFactory = HttpServiceProxyFactory.builder(WebClientAdapter.forClient(webClient)).build();
    return clientFactory.createClient(BeerClient.class);
}

This can be integrated in a bean using a simple configuration class:

@Configuration
public class BeerClientConfiguration() {

    @Bean
    public BeerClient buildBeerClient(WebClient.Builder webClientBuilder) {
        WebClient webClient = webClientBuilder.build();
        HttpServiceProxyFactory clientFactory = 
HttpServiceProxyFactory.builder(WebClientAdapter.forClient(webClient)).build();
        return clientFactory.createClient(BeerClient.class);
    }
}

This bean can then be injected as any other bean.

Customizing the WebClient

Usually, in most client, we need to inject some headers, add authentication tokens, set loggers, ...

This can be done directly in the WebClient or RestClient (introduced in Spring 6.1) builders using defaultHeaders(...) method or using filters (interceptors when using RestClient or RestTemplate). For example, you can easily register a filter that add an authentication header based on the currently logged in user.

What about non blocking types ?

Types such as Mono or Flux, can be directly specified as return type in the interface such as

package org.dev.example;

import org.springframework.web.service.annotation.*;
import reactor.core.publisher.*;

@HttpExchange(url = "api/v1/beer", contentType = "application/json")
public interface BeerClient {

    @GetExchange
    public Flux<Beer> listBeers();

    @GetExchange("/{beerId}")
    public Mono<Beer> getBeer(@PathVariable String beerId);

    @PostExchange
    public Mono<Beer> createBeer(@RequestBody Beer beer);
}

The HttpServiceProxyFactory also supports returning ResponseEntity type (which can also be combined with Mono and Flux).

What about testing ?

Testing can be done in different ways:

By overriding the exchangeFunction of the WebClient used by the HttpServiceProxyFactory
If your client is exposed as bean, it can be mocked as any other bean by your favorite mocking library.