Future-based backends
There are several backend implementations which are scala.concurrent.Future
-based. These backends are asynchronous, sending a request is a non-blocking operation and results in a response wrapped in a Future
.
Apart from the ones described below, also the Akka backend is Future
-based.
Class |
Supported stream type |
Websocket support |
---|---|---|
|
n/a |
yes (regular) |
|
|
yes (regular & streaming) |
|
n/a |
yes (regular) |
|
n/a |
n/a |
Using HttpClient
To use, you don’t need any extra dependencies, core
is enough:
"com.softwaremill.sttp.client3" %% "core" % "3.10.1"
You’ll need the following imports:
import sttp.client3.HttpClientFutureBackend
import scala.concurrent.ExecutionContext.Implicits.global
Create the backend using:
val backend = HttpClientFutureBackend()
or, if you’d like to instantiate the HttpClient yourself:
import java.net.http.HttpClient
val client: HttpClient = ???
val backend = HttpClientFutureBackend.usingClient(client)
This backend is based on the built-in java.net.http.HttpClient
available from Java 11 onwards.
Host header override is supported in environments running Java 12 onwards, but it has to be enabled by system property:
-Djdk.httpclient.allowRestrictedHeaders=host
Using OkHttp
To use, add the following dependency to your project:
"com.softwaremill.sttp.client3" %% "okhttp-backend" % "3.10.1"
and some imports:
import sttp.client3.okhttp.OkHttpFutureBackend
import scala.concurrent.ExecutionContext.Implicits.global
Create the backend using:
val backend = OkHttpFutureBackend()
or, if you’d like to instantiate the OkHttpClient yourself:
import okhttp3.OkHttpClient
val okHttpClient: OkHttpClient = ???
val backend = OkHttpFutureBackend.usingClient(okHttpClient)
This backend depends on OkHttp and fully supports HTTP/2.
Using Armeria
To use, add the following dependency to your project:
"com.softwaremill.sttp.client3" %% "armeria-backend" % "3.10.1"
add imports:
import sttp.client3.armeria.future.ArmeriaFutureBackend
create client:
val backend = ArmeriaFutureBackend()
// You can use the default client which reuses the connection pool of ClientFactory.ofDefault()
ArmeriaFutureBackend.usingDefaultClient()
or, if you’d like to instantiate the WebClient yourself::
import com.linecorp.armeria.client.circuitbreaker._
import com.linecorp.armeria.client.WebClient
// Fluently build Armeria WebClient with built-in decorators
val client = WebClient.builder("https://my-service.com")
// Open circuit on 5xx server error status
.decorator(CircuitBreakerClient.newDecorator(CircuitBreaker.ofDefaultName(),
CircuitBreakerRule.onServerErrorStatus()))
.build()
val backend = ArmeriaFutureBackend.usingClient(client)
Note
A WebClient could fail to follow redirects if the WebClient is created with a base URI and a redirect location is a different URI.
This backend is build on top of Armeria and doesn’t support host header override. Armeria’s ClientFactory manages connections and protocol-specific properties. Please visit the official documentation to learn how to configure it.
Streaming
The Akka backend supports streaming using akka-streams.
Other backends don’t support non-blocking streaming.
Websockets
Some of the backends (see above) support regular and streaming websockets.