HTTP Examples

The http folder contains examples for the HTTP protocol.

Hello World

An obligatory "Hello World" example for HTTP.

Asynchronous + Aggregated

This example demonstrates asynchronous request processing where the payload body is aggregated into a single object instead of a stream.

  • HelloWorldServer - a server that demonstrates the asynchronous API and responds with a simple Hello World! response body as a text/plain.

  • HelloWorldClient - a client that sends a GET request to the server and receives the response as a single content.

  • HelloWorldUrlClient - a client that sends a GET request to the specified URL in absolute-form and receives the response as a single content.

Asynchronous + Streaming

This example demonstrates asynchronous request processing where the payload body is a stream.

Blocking + Aggregated

This example demonstrates blocking request processing where the payload body is aggregated into a single object. The APIs will block if content is requested but there is no content available.

  • BlockingHelloWorldServer - a server that demonstrates the blocking API and responds with a simple Hello World! response body as a text/plain.

  • BlockingHelloWorldClient - a client that sends a GET request to the server and receives the response payload body as one aggregated object.

  • BlockingHelloWorldUrlClient - a client that sends a GET request to the specified URL in absolute-form and receives the response payload body as one aggregated object.

Blocking + Streaming

This example demonstrates blocking request processing where the payload body is a blocking iterable stream.

Compression

Extends the async "Hello World" example to demonstrate content encoding compression filters. No separate example is needed for the other API variants as the usage of content encoding filters is the same for all API styles.

  • CompressionFilterExampleServer - a server that demonstrates the asynchronous API and responds with a simple Hello World! response body, optionally customized for a specific name for POST requests, as a text/plain.

  • CompressionFilterExampleClient.java - a single-address client that sends a POST request containing a name to the server and receives a response greeting the posted name as a single content.

  • CompressionFilterExampleUrlClient.java - a multi-address client that sends a POST request containing a name to the server and receives a response greeting the posted name as a single content.

Debugging

Extends the async "Hello World" example to demonstrate some useful features available for debugging ServiceTalk applications. You should read and understand the async "Hello World" example first to understand the additions this example adds. No separate example is needed for the other API variants as the usage of the debugging features are the same for all API styles.

Timeout

Extends the async "Hello World" example to demonstrate the use of timeout filters and operators. You should read and understand the async "Hello World" example first to understand the additions this example adds. No separate example is needed for the other API variants as the usage of the timeout features are the same for all API styles.

  • TimeoutServer - the async Hello World! server client enhanced to use timeout capabilities.

  • TimeoutClient.java - the async Hello World! single-address client enhanced to use timeout capabilities.

  • TimeoutUrlClient.java - the async Hello World! multi-address client enhanced to use timeout capabilities.

Serialization: JSON

An example similar to "Hello World" examples, which demonstrates asynchronous-aggregated, asynchronous-streaming, blocking-aggregated, and blocking-streaming client and server with JSON serialization of simple pojo classes.

Client sends a POST request with a JSON payload CreatePojoRequest and expects a response with Content-Type: application/json and PojoResponse as a payload.

All serializers and deserializers defined in SerializerUtils.

Serialization: Protobuf

An example similar to "Hello World" examples, which demonstrates asynchronous-aggregated, asynchronous-streaming, blocking-aggregated, and blocking-streaming client and server with Protobuf serialization of simple proto objects.

Client sends a POST request with a Protobuf payload RequestMessage and expects a response with Content-Type: application/protobuf and ResponseMessage as a payload (message.proto). All serializers and deserializers defined in SerializerUtils.

Serialization: Bytes

An example similar to "Hello World" examples, which demonstrates blocking-aggregated client and server with byte[] serialization.

Client sends a GET request and expects a response that can be deserialized as byte[]. All serializers and deserializers defined in SerializerUtils.

JAX-RS

ServiceTalk provides a JAX-RS implementation that can plugin to ServiceTalk APIs. This example demonstrates how to use these APIs, and how different API variations (e.g. asynchronous/blocking and aggregated/streaming) are exposed.

To use ServiceTalk with Jersey 3.X, replace the following dependencies in the sample:

  • servicetalk-data-jackson-jersey → servicetalk-data-jackson-jersey3-jakarta9 (3.0.X) or servicetalk-data-jackson-jersey3-jakarta10 (3.1.X)

  • servicetalk-data-protobuf-jersey → servicetalk-data-protobuf-jersey3-jakarta9 (3.0.X) or servicetalk-data-protobuf-jersey3-jakarta10 (3.1.X)

  • servicetalk-http-router-jersey → servicetalk-http-router-jersey3-jakarta9 (3.0.X) or servicetalk-http-router-jersey3-jakarta10 (3.1.X)

and change jerseyVersion to jersey3VersionEE9 (3.0.X) or jersey3VersionEE10 (3.1.X)

Hello world

A simple "Hello World" example built using JAX-RS.

  • HelloWorldJaxRsServer - a JAX-RS based hello world server that demonstrates how to write blocking as well as asynchronous resource methods.

  • HelloWorldJaxRsResource - a JAX-RS resource having different methods for blocking and asynchronous interactions.

This example does not have a client yet but one can use curl to send requests like:

curl http://localhost:8080/greetings/hello

More examples of how to use the resource can be found in the HelloWorldJaxRsResource javadocs.

MetaData

This example demonstrates some basic functionality of the HttpMetaData classes:

  • Setting and getting response status.

  • Setting and getting query parameters.

  • Setting, checking, and getting headers.

  • Printing headers without redaction/filtering.

Using the following classes:

This example uses the blocking + aggregated API, as the metadata API is the same across all the HTTP APIs.

Mutual TLS

This example demonstrates how client and server can be configured to do mutual authentication via TLS.

Using the following classes:

  • HttpServerMutualTLS - A server that sets the trust manager and key manager, and requires client authentication.

  • HttpClientMutualTLS - A single-address client that sets the trust manager and key manager.

  • HttpUrlClientMutualTLS - A multi-address client that sets the trust manager and key manager when needed.

This example uses the blocking + aggregated API, as the TLS/SSL configuration API is the same across all the HTTP APIs.

Observer

This example demonstrates the following: - Use of HttpLifecycleObserver to log a summary of each request/response.

Using the following classes:

DefaultLoadBalancer

This example demonstrates how to use the experimental DefaultLoadBalancer:

  • by setting the load balancer to DefaultLoadBalancer for a HTTP client

  • configuring xDS failure detection for that client using default settings

Using the following classes:

DefaultLoadBalancer is currently considered experimental and therefore the API is subject to change.

OpenTracing

This example demonstrates the following:

  • automatically generate and propagate distributed tracing metadata

  • make span IDs available in log statements via MDC

  • publish span IDs via Zipkin’s HTTP API and to a local console logger

Using the following classes:

  • OpenTracingServer - A server that generates/propagates span IDs, makes spans available in logs via MDC, publishes spans via Zipkin’s HTTP API.

  • OpenTracingClient - A client that generates/propagates span IDs, makes spans available in logs via MDC, publishes spans via local console logger.

  • ZipkinServerSimulator - A server that simulates/mocks a Zipkin server, and logs requests to the console.

  • BraveTracingServer - A server that uses Brave OpenTracing implementation.

Redirects

Extends the async "Hello World" example to demonstrate different ways that users can support redirects in ServiceTalk applications. You should read and understand the "Hello World" example first to understand the additions this example adds. No separate example is needed for the other API variants as the usage of the redirect features are the same for all API styles.

  • RedirectingServer - Starts two servers, one of them (HTTP) redirects to another (HTTPS).

  • SingleAddressRedirectClient.java - Async Hello World example that demonstrates how relative redirects can be handled automatically by a single-address client.

  • MultiAddressUrlRedirectClient.java - Async Hello World example that demonstrates how redirects can be handled automatically by a multi-address client. It demonstrates how users can preserve headers and payload body of the original request while redirecting to non-relative locations.

  • ManualRedirectClient.java - Async Hello World example that demonstrates how redirects can be handled manually between multiple single-address clients.

Retries

Extends the async "Hello World" example to demonstrate basic cliest request retry functionality. You should read and understand the async "Hello World" example first to understand the additions this example adds. No separate example is needed for the other API variants as the usage of the debugging features are the same for all API styles.

  • RetryServer - A special "flaky" Hello World server that alternates "509" Gateway Timeout and "200" Success responses for client requests to demonstrate client retry.

  • RetryClient.java - Async Hello World example that demonstrates how retry can be requested for a single-address client.

  • RetryUrlClient.java - Async Hello World example that demonstrates how retry can be requested for a multi-address client.

Traffic Resiliency

Some examples that use the traffic resiliency features.

HTTP/2

These examples demonstrate how users can configure HTTP/2 transport in ServiceTalk.

HTTP/2 with Prior-Knowledge

This example demonstrates how to configure using HTTP/2 transport with Prior-Knowledge for HTTP clients and servers:

HTTP/2 via ALPN for secure connections

For secure TLS connections ALPN extension could be used to negotiate the communication protocol:

  • HttpServerWithAlpn - A server that negotiates HTTP/2 or HTTP/1.1 using ALPN extension for TLS connections.

  • HttpClientWithAlpn - A single-address client that negotiates HTTP/2 or HTTP/1.1 using ALPN extension for TLS connections.

  • HttpUrlClientWithAlpn - A multi-address client that conditionally negotiates HTTP/2 or HTTP/1.1 using ALPN extension for TLS connections.

If HTTP/1.x protocol is configured ServiceTalk always fallbacks to it if the peer does not support ALPN extension.

Your runtime must support ALPN extension for TLS. The recommended way is to use OpenSSL provider and add netty-tcnative artifact to the classpath. If OpenSSL is not available, make sure your JVM version supports ALPN or use another provider that supports it.
These examples use the blocking + aggregated API for demonstration purposes, as the builder API is the same across all the HTTP APIs.

Service Composition

An advanced example which demonstrates a composition of various ServiceTalks services in one application. For more information see Service Composition.

Unix Domain Sockets (UDS)

This example demonstrates how client and server can use unix domain sockets. See the uds example code for more details.

This example uses the blocking + aggregated API, as the UDS configuration API is the same across all the HTTP APIs.

Files

This example demonstrates asynchronous request processing where the response payload body is streamed from a file.

  • FilesServer - a server whose response body is streamed from a file.

  • FilesClient - a client that requests and prints response contents.