Documentation

Java SDK Overview

Integrate applications running on the Java Virtual Machine (JVM) with Composable Commerce

About the Java SDK

The Java SDK (also referred to as the Java v2 SDK) enables developers to use Java 8 methods and objects to communicate with the Composable Commerce APIs rather than using plain HTTP calls and untyped JSON node objects.

Users gain type-safety, encapsulation, IDE autocompletion, and an internal domain-specific language to discover and formulate valid requests.

It supports multiple languages that run on the JVM, including:

  • Java
  • Scala
  • Groovy
  • Clojure
  • Kotlin

Java 8 features

The Java SDK uses various Java 8 language constructs and classes, including:

As a result of Java 8 dependencies, the Java SDK is unsuitable for Android development as it does not (yet) support Java 8 on its virtual machine.

Good defaults for equals() and hashCode()

The SDK's model implementation classes provide default implementations for these methods using reflection.

Client interfaces

The HTTP client abstract itself is a functional interface and can be replaced with test doubles.

Model factory methods

Each model has a factory method ::of() to create a new empty instance. The method ::builder() returns a new builder instance.

Javadoc

The full Javadoc reference can be found here.

Get the source on GitHub

The Java SDK is fully open source and is available on GitHub.

License

The Java SDK is provided under the Apache License.

Release notes

The release notes for the Java SDK can be found on GitHub.

Best practices and error handling

  • Ensure the Java SDK is up to date.
  • Read the documentation carefully to correctly and properly implement or integrate the SDK.
  • Report issues as soon as they are noticed or spotted at the GitHub repository.
  • If you encounter an issue that is urgent or critical for your business, create a support request at the commercetools support portal.
  • Provide as many details as possible with your issue reports, including the SDK version, the specific error message, any log or stack traces, and the code snippet that causes the issue.

A complete list of best practices can be found on GitHub

Exceptions

The Java SDK uses exceptions from the Java Development Kit (such as IllegalArgumentException) and provides its own exceptions which inherit from BaseException.

Problems concerning the ApiHttpClient throw a ApiHttpException.

JSON serializing and deserializing problems throw JsonException.

ApiHttpException is a base exception for all error responses (HTTP status code >= 400).

ApiClientException expresses errors which can be recovered by the client side (HTTP status code >= 400 and < 500). ApiServerException is for server errors.

Errors

If a command cannot be performed due to unfulfilled preconditions, one error response with multiple errors can be returned (for more information, see HTTP API Errors). The Java SDK then adds a BadRequestException into a CompletionStage.

Custom HttpExceptionFactory

Responses with a status code of 400 (or higher) are treated as errors and raise exceptions. These exceptions are created by the DefaultHttpExceptionFactory. In case you want to override the handling you have to implement this interface and override the default methods if necessary.

public class HttpExceptionFactoryTest {


    static class CustomExceptionFactory implements HttpExceptionFactory {
        @Override
        public ApiHttpException create(ApiHttpRequest request, ApiHttpResponse<byte[]> response) {
            return new ApiHttpException(response.getStatusCode(), request.getSecuredBody(), response.getHeaders(),
                "something bad happened", response, request);
        }


        @Override
        public ResponseSerializer getResponseSerializer() {
            return ResponseSerializer.of();
        }
    }


    @Test
    public void customFactory() {


        ProjectApiRoot client = ApiRootBuilder.of()
                .defaultClient(ServiceRegion.GCP_EUROPE_WEST1.getApiUrl())
                .withHttpExceptionFactory(CustomExceptionFactory::new)
                .build("my-project-key");


        assertThatExceptionOfType(ApiHttpException.class).isThrownBy(() -> client.get().executeBlocking())
                .withMessageStartingWith("detailMessage: something bad happened");


    }
}

Logging

Internal logging used by the commercetools client itself uses a SLF4J logger named commercetools.

Log information

The default logger middleware logs the following information per level.

Error

When an ApiHttpException occurs, the HTTP method, URI, and response status code are logged. For any other exception, the cause and exception are logged.

Information

By default any response by the API is logged with the HTTP method, URI, and response status code. If a deprecated header was submitted in the response, an information entry with the deprecation notice is logged.

The log level for these events can be configured when instantiating the InternalLoggerMiddleware.

Debug

The request and the response object are logged as a string representation including headers and body. Sensitive data like auth tokens and passwords are redacted.

Trace

The request and response are logged with a pretty-printed output. Sensitive data like auth tokens and passwords are redacted.

Logger hierarchy

The loggers form a hierarchy separated by a period. The root logger is commercetools.

The child loggers of commercetools are the endpoints. For example commercetools.categories for Categories and commercetools.product-types for Product Types.

The grandchild loggers refer to the action. commercetools.categories.request refers to performing requests per HTTPS to commercetools for Categories, commercetools.categories.response refers to the responses.

The logger makes use of different log levels, so for example commercetools.categories.response logs the HTTP response on debug level:

 [OkHttp https://api.europe-west1.gcp.commercetools.com/...] DEBUG commercetools.categories.response - io.vrap.rmf.base.client.ApiHttpResponse@33e37acd[statusCode=200,headers=...,textInterpretedBody={"limit":20,"offset":0,"count":4,"total":4,"results":[{"id":"ca7f64dc-ab41-4e7f-b65b-bfc25bf01111","version":1,"createdAt":"2021-01-06T09:21:55.445Z","lastModifiedAt":"2021-01-06T09:21:55.445Z","key":"random-key-15aab6ee-9a48-4fdc-a8c3-8ff9ff390d60","name":{"key-6bc3cc62-1995-43f4":"value-random-string-c3ff7f1a-6371-4c0c-a3b9-5060eca08b8a"},"slug":{"key-6bc3cc62-1995-43f4":"value-random-string-c3ff7f1a-6371-4c0c-a3b9-5060eca08b8a"},"description":{"key-6bc3cc62-1995-43f4":"value-random-string-c3ff7f1a-6371-4c0c-a3b9-5060eca08b8a"},"ancestors":[],"orderHint":"random-string-a99e6941-3225-4766-923a-4a654652532f","externalId":"random-id-100b3851-29b4-47c1-aef3-860b4cd28f54"}]}]

Additionally, commercetools.categories.response logs the formatted HTTP response on trace level:

[OkHttp https://api.europe-west1.gcp.commercetools.com/...] TRACE commercetools.categories.response - 200
 {
   "limit" : 20,
   "offset" : 0,
   "count" : 4,
   "total" : 4,
   "results" : [ {
     "id" : "bcb15128-b69e-47b6-81c4-1ea5f9a63b83",
     "version" : 1,
     "lastMessageSequenceNumber" : 1,
     "createdAt" : "2021-01-06T09:21:50.485Z",
     "lastModifiedAt" : "2021-01-06T09:21:50.485Z",
     "createdBy" : {
       "clientId" : "h-QvaF3NpsjPBWeXa6TUOnq0",
       "isPlatformClient" : false
     },
     "key" : "random-key-f45535f5-1111-4bfb-98ac-164234ac2c73",
     "name" : {
       "key-b7d87008-9526-47b3-8b80" : "value-random-string-baf1a1ae-3726-4573-bec5-2c53c7d1114a"
     },
     "slug" : {
       "key-b7d87008-9526-47b3-8b80" : "value-random-string-baf1a1ae-3726-4573-bec5-2c53c7d1114a"
     },
     "description" : {
       "key-b7d87008-9526-47b3-8b80" : "value-random-string-baf1a1ae-3726-4573-bec5-2c53c7d1114a"
     },
     "ancestors" : [ ],
     "orderHint" : "random-string-6b88f299-d4ca-491a-9d7c-3463e718c8d2",
     "externalId" : "random-id-b98a5ab4-5413-40b3-8119-eb5ac2b5afbb",
     "metaTitle" : {
       "key-b7d87008-9526-47b3-8b80" : "value-random-string-baf1a1ae-3726-4573-bec5-2c53c7d1114a"
     },
     "metaKeywords" : {
       "key-b7d87008-9526-47b3-8b80" : "value-random-string-baf1a1ae-3726-4573-bec5-2c53c7d1114a"
     },
     "metaDescription" : {
       "key-b7d87008-9526-47b3-8b80" : "value-random-string-baf1a1ae-3726-4573-bec5-2c53c7d1114a"
     }
   }, {
   ...
   } ]
 }

commercetools.products.responses.queries only logs HTTP GET requests and commercetools.products.responses.commands only logs HTTP POST/DELETE requests.

[pool-1-thread-1] DEBUG commercetools.products.request.commands - io.vrap.rmf.base.client.ApiHttpRequest@1d2c6948[method=POST,uri="https://api.europe-west1.gcp.commercetools.com/test-php-dev-integration-1/products",headers=[...],textInterpretedBody={"productType":{"id":"cda39953-23af-4e85-abb0-5b89517ec5f2","typeId":"product-type"},"name":{"random-string-b66de021-d2fa-4262-8837-94a6992a8cdc":"random-string-da28a010-e66b-49d4-a18b-f1bfc145d2f6"},...}]
 [pool-1-thread-1] DEBUG commercetools.products.request.queries - io.vrap.rmf.base.client.ApiHttpRequest@53667fdb[method=GET,uri="https://api.europe-west1.gcp.commercetools.com/test-php-dev-integration-1/products/ef745227-b115-4132-ba2c-4e46db80df79",headers=[...],textInterpretedBody=empty body]