Spring Cloud Square

Quick Start

This quick start walks through using SC LoadBalancer OkHttpClient integration, load-balanced OkHttpClient-based Retrofit clients, and load-balanced WebClient-based Retrofit clients.

OkHttpClient with Spring Cloud LoadBalancer

First, 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-M2</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 the 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

First, 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-M2</version>
    </dependency>
    <dependency>
		<groupId>org.springframework.cloud</groupId>
		<artifactId>spring-cloud-square-okhttp</artifactId>
		<version>0.4.0-M2</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 argument (the annotation can also be used 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 (by 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

First, add the spring-cloud-square-retrofit and spring-boot-starter-webflux starter dependencies to your project:

<dependencies>
    <dependency>
		<groupId>org.springframework.cloud</groupId>
		<artifactId>spring-cloud-square-retrofit</artifactId>
		<version>0.4.0-M2</version>
    </dependency>
    <dependency>
    	<groupId>org.springframework.boot</groupId>
    	<artifactId>spring-boot-starter-webflux</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 (by using serviceId instead of actual host:port):

class AService {

    @Autowired
    HelloClient client;

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

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

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>

OkHttpClient integration with Spring Cloud

This module supplies integration with Square’s [OkHttpClient](https://square.github.io/okhttp/) and [Spring Cloud LoadBalancer](https://github.com/spring-cloud/spring-cloud-commons/spring-cloud-loadbalancer).

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

By supporting OkHttpClient, it enables Square’s [Retrofit](https://square.github.io/retrofit/) to use Spring Cloud LoadBalancer as well.

See [OkHttpLoadBalancerInterceptorTests](https://github.com/spring-cloud-incubator/spring-cloud-square/blob/main/spring-cloud-square-okhttp/src/test/java/org/springframework/cloud/square/okhttp/loadbalancer/OkHttpLoadBalancerInterceptorTests.java) for Spring Cloud LoadBalancer samples.

Spring WebClient

Support was also added for Spring WebClient. This implements an okhttp3.Call.Factory that uses WebClient under the covers. This provides a fully non-blocking shim instead of using okhttp3.

See [WebClientRetrofitTests](https://github.com/spring-cloud-incubator/spring-cloud-square/blob/main/spring-cloud-square-retrofit-webclient/src/test/java/org/springframework/cloud/square/retrofit/webclient/WebClientRetrofitTests.java) for WebClient samples.