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:
Learn how to set up and use the Java SDK with our get started guide.
Migrate from the v1 SDK
Learn how to migrate to the Java v2 SDK by following our migration guide.
The full Javadoc reference can be found here.
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.
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.
Use helper methods to perform repetitive tasks in the Java SDK. You can find a complete list of helper methods including example usage in the Javadoc.
Get the source on GitHub
The Java SDK is fully open source and is available on GitHub.
The Java SDK is provided under the Apache License.
The release notes for the Java SDK can be found on GitHub.
Best practices and error handling
A complete list of best practices can be found on GitHub
You can find integration tests for each endpoint here. These tests also provide code examples for creating, querying, updating, and deleting resources within your Composable Commerce Project.
JSON serializing and deserializing problems throw JsonException.
ApiHttpException is a base exception for all error responses (HTTP status code >= 400).
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.
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.
Internal logging used by the commercetools client itself uses a SLF4J logger named
The default logger middleware logs the following information per level.
When an ApiHttpException occurs, the HTTP method, URI, and response status code are logged. For any other exception, the cause and exception are logged.
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.
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.
The request and response are logged with a pretty-printed output. Sensitive data like auth tokens and passwords are redacted.
The loggers form a hierarchy separated by a period. The root logger is
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:
commercetools.categories.response logs the formatted HTTP response on trace level:
commercetools.products.responses.queries only logs HTTP GET requests and
commercetools.products.responses.commands only logs HTTP POST/DELETE requests.