We are happy to announce that we have released the first publicly available milestone version of the Spring Cloud Square incubator project. The project provides Spring Cloud LoadBalancer integration for OkHttpClient and Retrofit, as well as non-blocking WebClient-backed Retrofit clients. Retrofit is a declarative HTTP client from Square.

You can find more information on how to get started with the project below. You can also check the project repository and project documentation .

OkHttpClient Spring Cloud LoadBalancer Integration

An application interceptor is added to the OkHttpClient created by auto-configuration. It resolves the scheme, host, and port from Spring Cloud LoadBalancer and rewrites the URL.

To use SC LoadBalancer to resolve and select instances to send requests to, add the spring-cloud-square-okhttp dependency to your project:

<dependency>
		<groupId>org.springframework.cloud</groupId>
		<artifactId>spring-cloud-square-okhttp</artifactId>
		<version>0.4.0-M1</version>
</dependency>

Then create a @LoadBalanced-annotated OkHttpClient.Builder bean:

@Configuration
class OkHttpClientConfig{
@Bean
@LoadBalanced
public OkHttpClient.Builder okHttpClientBuilder() {
    return new OkHttpClient.Builder();
    }
}

Now you can use the serviceId or virtual hostname rather than an actual host:port in your requests. SC LoadBalancer resolves it by selecting one of available service instances.

Request request = new Request.Builder()
                        .url("http://serviceId/hello").build();
Response response = builder.build().newCall(request).execute();

Retrofit with OkHttpClient and Spring Cloud LoadBalancer

We also use load-balanced OkHttpClient instances to run Retrofit calls.

To use Retrofit with Spring Cloud LoadBalancer-backed OkHttpClient, add the spring-cloud-square-retrofit and spring-cloud-square-okhttp dependencies to your project:

<dependencies>
    <dependency>
		<groupId>org.springframework.cloud</groupId>
		<artifactId>spring-cloud-square-retrofit</artifactId>
		<version>0.4.0-M1</version>
    </dependency>
    <dependency>
		<groupId>org.springframework.cloud</groupId>
		<artifactId>spring-cloud-square-okhttp</artifactId>
		<version>0.4.0-M1</version>
    </dependency>
</dependencies>

Use the @EnableRetrofitClients annotation to let us automatically instantiate and inject Retrofit clients for you. Then create a @LoadBalanced-annotated OkHttpClient.Builder bean to be used under the hood:

@Configuration
@EnableRetrofitClients
class OkHttpClientConfig {

@Bean
@LoadBalanced
public OkHttpClient.Builder okHttpClientBuilder() {
    return new OkHttpClient.Builder();
    }
}

Create a Retrofit client and annotate it with @RetrofitClient, passing the serviceId of your service as an argument (you can also use the annotation to pass a custom configuration that contains user-crated interceptors for the Retrofit client):

@RetrofitClient("serviceId")
interface HelloClient {
	@GET("/")
	Call<String> hello();
}

Make sure to use Retrofit method annotations, such as @GET("/"). You can now inject the Retrofit client and use it to run load-balanced calls (using serviceId instead of actual host:port):

class AService {

    @Autowired
    HelloClient client;

	public String hello() throws IOException {
		return client.hello().execute().body();
	}
}

We created a full sample for load-balanced-OkHttpClient-based Retrofit clients.

Retrofit with WebClient and Spring Cloud LoadBalancer

We also use adapters to provide WebClient support for Retrofit.

To use Retrofit with a Spring Cloud LoadBalancer-backed WebClient, add the spring-cloud-square-retrofit and spring-boot-starter-webflux starter dependencies to your project:

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-webflux</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.cloud</groupId>
	<artifactId>spring-cloud-square-retrofit-webclient</artifactId>
	<version>0.4.0-M1</version>
    </dependency>
    <dependency>
        <groupId>org.springframework.cloud</groupId>
	<artifactId>spring-cloud-starter-loadbalancer</artifactId>
    </dependency>
</dependencies>

Use the @EnableRetrofitClients annotation to let us automatically instantiate and inject Retrofit clients for you. Then create a @LoadBalanced-annotated WebClient.Builder bean to be used under the hood:

@Configuration
@EnableRetrofitClients
class OkHttpClientConfig {

@Bean
@LoadBalanced
public WebClient.Builder webClientBuilder() {
    return WebClient.builder();
    }
}

Create a Retrofit client and annotate it with @RetrofitClient, passing the serviceId of your service as argument:

@RetrofitClient("serviceId")
interface HelloClient {
	@GET("/")
	Mono<String> hello();
}

Make sure to use Retrofit method annotations, such as @GET("/"). You can now inject the Retrofit client and use it to run load-balanced calls (using serviceId instead of actual host:port):

class AService {

    @Autowired
    HelloClient client;

	public Mono<String> hello() throws IOException {
		return client.hello();
	}
}

We created a full sample for load-balanced-WebClient-based Retrofit clients.

NOTE:

As the currently available release is a milestone, you need to add the Spring Milestone repository link to your projects for all the examples presented in this blog entry:

<repositories>
    <repository>
        <id>spring-milestones</id>
        <url>https://repo.spring.io/milestone</url>
    </repository>
</repositories>

We recommend using dependency management for other Spring Cloud dependencies:

<dependencyManagement>
		<dependencies>
			<dependency>
				<groupId>org.springframework.cloud</groupId>
				<artifactId>spring-cloud-dependencies</artifactId>
				<version>${spring-cloud.version}</version>
				<type>pom</type>
				<scope>import</scope>
			</dependency>
		</dependencies>
</dependencyManagement>