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 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.
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.
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.
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
- 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
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.