Documentation

Java SDK middleware

Elevate, May 20-22-2025, Miami Beach, Florida

ErrorMiddleware

ErrorMiddleware reacts to erroneous HTTP responses. It is always the first middleware in HandlerStack. The default implementation converts responses with a status code of 400 or higher to exceptions. To create the exceptions, ErrorMiddleware uses an HttpExceptionFactory.
return next
  .apply(request)
  .thenApply(response -> {
    if (response.getStatusCode() >= 400) {
      throw exceptionFactory.create(request, response);
    }
    return response;
  });

OAuthMiddleware

OAuthMiddleware authenticates a request against the Composable Commerce APIs. The default implementation adds an auth header to the request instance. If a token is expired, it will try to reauthenticate automatically. The Java SDK calls OAuthHandler to retrieve an AuthenticationToken.
return failsafeExecutor.getStageAsync(() -> {
    if (request.getHeaders().getFirst(ApiHttpHeaders.AUTHORIZATION) != null) {
      return next.apply(request);
    }
    AuthenticationToken token = authHandler.getToken();
    return next.apply(
      request.addHeader(
        ApiHttpHeaders.AUTHORIZATION,
        OAuthHandler.authHeader(token)
      )
    );
  });

PolicyMiddleware

PolicyMiddleware and PolicyBuilder allow the combination of different policies for failing requests (for example, retrying).

When retrying, the middleware uses an exponential backoff strategy which increases the wait time before each retry to avoid overwhelming the API. Jitter is also added to reduce the possibility of parallel requests.

ProjectApiRoot apiRoot = ApiRootBuilder
  .of()
  .defaultClient(
    ClientCredentials
      .of()
      .withClientId("clientId")
      .withClientSecret("clientSecret")
      .build(),
    ServiceRegion.GCP_EUROPE_WEST1
  )
  .withPolicies(policyBuilder ->
    policyBuilder.withRetry(retry ->
      retry
        .maxRetries(3)
        .statusCodes(
          Arrays.asList(
            HttpStatusCode.SERVICE_UNAVAILABLE_503,
            HttpStatusCode.INTERNAL_SERVER_ERROR_500
          )
        )
    )
  )
  .build("my-project-key");
PolicyMiddleware uses the library failsafe.

UserAgentMiddleware

The UserAgentMiddleware adds a user agent header to every request. By default it submits the following data:
  • SDK version
  • JVM runtime version
  • Operating system name and version
String runtimeVersion = SystemUtils.JAVA_RUNTIME_VERSION;
String osName = SystemUtils.OS_NAME;
String osArch = SystemUtils.OS_ARCH;
String sdkVersion = BuildInfo.VERSION;
return (
  userAgent +
  sdkVersion +
  " " +
  " Java/" +
  runtimeVersion +
  " (" +
  osName +
  "; " +
  osArch +
  ")"
);

AcceptGZipMiddleware

The AcceptGZipMiddleware adds an Accept-Encoding: gzip header, to enable compressing the response to reduce the data transport time.

InternalLoggerMiddleware

The InternalLoggerMiddleware logs every request sent using the Java SDK. Depending on the configured logging level, the default implementation logs the request and the response.

The info level logs the request method, URL, and response status. At the debug level, it logs the request and response instances. With trace level, it pretty-prints the request body and response. InternalLoggerMiddleware redacts sensitive data, such as passwords and tokens, before logging.