commercetools / commercetools-jvm-sdk

The e-commerce SDK from commercetools running on the Java virtual machine.

commercetools JVM SDK

⚠️ **This commercetools JVM SDK is in its Maintenance Support mode currently, and is planned to be deprecated, please note the following dates.

Active Support	Maintenance Support	End of Life
28th February, 2022	31st December 2023.	1st January 2024.

We recommend to use our Java SDK V2, and you can migrate to the new version using our migration guideline.

The JVM SDK enables developers to use Java 8 methods and objects to communicate with the Composable Commerce API rather than using plain HTTP calls. Users gain type-safety, encapsulation, IDE auto completion and an internal domain specific language to discover and formulate valid requests.

JDK compatibility

Tested with JDKs: Oracle 1.8.0_221, OpenJDK 1.8.0_221 and Amazon Corretto 8.222.10.1.

Using the SDK

• install Java 8
• (since May 19, 2016 new link) Javadoc, there you find also code snippets and insights
  • Getting Started
  • Release Notes
  • Contributing

Installation

Java SDK with Maven

<dependency>
  <groupId>com.commercetools.sdk.jvm.core</groupId>
  <artifactId>commercetools-models</artifactId>
  <version>1.61.0</version>
</dependency>
<dependency>
  <groupId>com.commercetools.sdk.jvm.core</groupId>
  <artifactId>commercetools-java-client</artifactId>
  <version>1.61.0</version>
</dependency>

<!-- experimental -->
<dependency>
  <groupId>com.commercetools.sdk.jvm.core</groupId>
  <artifactId>commercetools-convenience</artifactId>
  <version>1.61.0</version>
</dependency>

• https://search.maven.org/#artifactdetails%7Ccom.commercetools.sdk.jvm.core%7Ccommercetools-models%7C1.61.0%7Cjar
• https://search.maven.org/#artifactdetails%7Ccom.commercetools.sdk.jvm.core%7Ccommercetools-java-client%7C1.61.0%7Cjar
• https://search.maven.org/#artifactdetails%7Ccom.commercetools.sdk.jvm.core%7Ccommercetools-convenience%7C1.61.0%7Cjar

Modules

• commercetools-java-client: alias for commercetools-java-client-ahc-2_0
• commercetools-java-client-apache-async: uses Apache HTTP client
• commercetools-java-client-ahc-1_9: uses async HTTP client 1.9 (AHC 1.9 is incompatible to AHC 1.8)
• commercetools-java-client-ahc-2_0: uses async HTTP client 2.0 (do not mix it with the other AHC modules)
• commercetools-java-client-ahc-2_5: uses async HTTP client 2.5 (AHC 2.5 is incompatible to AHC 2.0)
• commercetools-java-client-ahc-2_12: uses async HTTP client 2.12
• commercetools-models: models which do not depend to a client implementation

Java SDK with gradle

repositories {
    mavenCentral()
}

dependencies {
    def jvmSdkVersion = "1.61.0"
    compile "com.commercetools.sdk.jvm.core:commercetools-models:$jvmSdkVersion"
    compile "com.commercetools.sdk.jvm.core:commercetools-java-client:$jvmSdkVersion"
    compile "com.commercetools.sdk.jvm.core:commercetools-convenience:$jvmSdkVersion"
}

Play/Scala SDK with SBT

see https://github.com/commercetools/commercetools-jvm-sdk-scala-add-ons

reactive streams

• https://github.com/commercetools/commercetools-jvm-sdk-reactive-streams-add-ons

JVM SDK Contrib

Useful code from external developers

• https://github.com/commercetools/commercetools-jvm-sdk-contrib
• contains also ProductImageUploadCommand from https://docs.commercetools.com/http-api-projects-products.html#upload-a-product-image

Short-term roadmap

• https://github.com/commercetools/commercetools-jvm-sdk/milestones
• https://waffle.io/commercetools/commercetools-jvm-sdk

Open Source Examples

• Sunrise Java - a shop using Play Framework 2.x with Handlebars.java as template engine, Google Guice for DI
• Donut - single product subscription shop example with Play Framework 2.x and Twirl (Plays default) as template engine
• commercetools Spring MVC archetype - template integrating the SDK with Spring DI and Spring MVC and showing just some products, thymeleaf template engine
• Reproducer Example - a demo which shows how to reproduce errors

Stability

1. Experimental features in the API are also experimental features of the SDK.
   • this includes for example
     • payments
     • nested product attributes
2. The dependencies will only be updated in the next major version to improve stability. Of course, if bugs in libraries occur, we may need to update.
3. JVM SDK test dependencies and build tools can be updated because they don't affect the production code.
4. The JVM SDK has an abstract HTTP client layer so old or new http client versions can be used.
5. order import is experimental
6. the search methods with lambda parameters are beta ProductProjectionSearch.ofCurrent().withQueryFilters(m -> m.categories().id().containsAll(categoryIds1))
7. getters of draft objects might change since new HTTP API features can introduce polymorphism
8. final classes without public constructors can be transformed into an interface

Executing integration tests

1. create a NEW API client in the Admin Center (https://mc.commercetools.com/YOUR_PROJECT_KEY/settings/developer/api-clients) with all available permissions (at the time of writing it is manage_payments manage_my_profile manage_orders view_products view_customers view_payments view_types manage_my_orders manage_types manage_customers manage_products view_orders manage_project), the by default created client has just manage_project
2. in the Admin Center in the "DANGER ZONE" activate the checkbox "ENABLE MESSAGES" within the "Messages Settings"
3. set "de", "de-AT", "en" as languages in the Admin Center
4. set at least one country in the Admin Center
5. create a file "integrationtest.properties" inside the project root
6. fill it with the credentials of a new empty Project which is for testing;

projectKey=YOUR project key without quotes
clientId=YOUR client id without quotes
clientSecret=YOUR client secret without quotes
apiUrl=https://api.europe-west1.gcp.commercetools.com
authUrl=https://auth.europe-west1.gcp.commercetools.com

1. use ./mvnw verify to execute all integration tests
2. use ./mvnw -Dit.test=*Product* -DfailIfNoTests=false verify to execute all integration test classes which have "Product" in the class name
3. for running the unit tests use ./mvnw test
4. alternatively use your IDE to execute the tests
5. for some IDEs like IntelliJ IDEA you need to add the Javac flag "-parameters", then also rebuild the whole project to apply the change

[](definitions for the top badges)

commercetools-jvm-sdk's Issues

Show/document example client usage with Spring DI

Keep reference expansion information for commands

Model model = client.execute(query);
Mode updatedModel = client.execute(new ModelUpdate(model, actions));

• if model have some references expanded, the same references should be expanded in updatedModel
• if the client updates a model just using id and version, no references will be expanded
• Versioned needs be extended by a default method which contains a list of strings, which elements should be expanded, the command base classes should handle this

Provide extended javadoc

Would be nice to have javadoc for each class with more detailed informations like:

• What it can do with it and why do i need that
• Description for all available methods
• Implementation examples

Something like that:
http://commons.apache.org/proper/commons-lang/javadocs/api-3.1/org/apache/commons/lang3/concurrent/BasicThreadFactory.html

Add Action annotation for checking customer is logged in

see https://github.com/commercetools/sphere-snowflake/blob/master/app/controllers/actions/Authorization.java

provide abstract class, since URL and messages need be settable

Refactorings and code quality things

• check if all Impl classes (even client) can be package local if a builder is present

Reference expansion with type-safe API

Review query API usage

http://sphereio.github.io/sphere-jvm-sdk/javadoc/1.0.0-SNAPSHOT/io/sphere/sdk/queries/package-summary.html#package.description

Move static methods of Categories into Category

Add helpers for prev/next like functionality (products)

@schleichardt it would be good to provide some helpers like

• hasPrev()
• hasNext()
• prev()
• next()
  which will calculate what would be the prev / next product based on the products list (PagedQueryResult) I pass to those helpers.

Do you know what I mean?

Enhance predicate API

e.g. not predicates

Document how to run single test with IntelliJ IDEA

Format detailed log as markdown

• add cwd as log field

Implement product types

• check all attributes are present: http://dev.sphere.io/http-api-projects-productTypes.html#attribute-type

Log response on failed commands

• only responses for queries seem to be logged

pure Java JARs should not contain Scala binary version

Make http connection timeout configurable

• timeout for single request configurable??

Class Hierarchy: every concrete class should inherit from Base or another class except Object

Move AttributeDefinition::findByName to ProductType as default method

sphere-play-sdk should have the same organization as the other artefacts

Provide type reference via default method in interface

Example:

• method: protected com.fasterxml.jackson.core.type.TypeReference typeReference()
• requests: ProductTypeCreateCommand, ProductTypeDeleteCommand, ProductUpdateCommand, fetch product type via ID
• remove TypeReference as static method or from Impl classes
• request class implement XyzRequest, which has as default method the type reference and baseEndpointWithoutId()
• => XyzCreateCommand, XyzDeleteCommand, XyzUpdateCommand, XyzFetch will have one to two methosd fewer to implement

Add helper to generate unique orderNumbers/customerNumbers

In order to avoid duplicates in order numbers (or customer numbers), it would be nice to get a helper that generates a project-wide unique number.

Consider to replace Wrapper with Supplier

Improve PagedQueryResult

• isFirst()
• isLast()

Products package documentation

Migrate to Java 8

❤️❤️❤️

• migrate to Optional from Java 8, see zapodot/jackson-databind-java-optional#1
• remove Guava types from generics, return types and parameters
• use https://github.com/FasterXML/jackson-module-parameter-names
• use new interfaces like AutoCloseable
• use Java 8 new Future classes instead of Guava
• Java 8 function classes (ResultMapper)

Move PagedQueryResult to queries module

create bundle artefacts

• Java bundle: sbt module which contains all model modules and the Java client
• Scala bundle: sbt module which contains Java bundle and Scala client
• Play Java bundle: sbt module which contains Scala bundle, Play Java client and Play helper/utility classes

Create manual how to create new aggregate

• SBT
• update dependency graph
• model as interface
• Impl class in package scope
• CreateCommand
• DeleteCommand
• Query/Predicate/Sorting API
• examples in Javadoc
• Impl test base class
• query test base class
• Builder
• link styleguide from sunrise

Rename: XyzDeleteCommand to XyzDeleteByIdCommand

Define milestones in GitHub and adjust version to 1.0.0-M1-SNAPSHOT

Recover from timeouts/check behaviour

WARNING: An exception was thrown by TimerTask.
java.lang.NullPointerException
    at com.ning.http.client.providers.netty.timeout.TimeoutsHolder.cancel(TimeoutsHolder.java:31)
    at com.ning.http.client.providers.netty.timeout.RequestTimeoutTimerTask.run(RequestTimeoutTimerTask.java:34)
    at org.jboss.netty.util.HashedWheelTimer$HashedWheelTimeout.expire(HashedWheelTimer.java:546)
    at org.jboss.netty.util.HashedWheelTimer$Worker.notifyExpiredTimeouts(HashedWheelTimer.java:446)
    at org.jboss.netty.util.HashedWheelTimer$Worker.run(HashedWheelTimer.java:395)
    at java.lang.Thread.run(Thread.java:744)
11:54:08.561 [Sphere-ClientCredentials-refresh-1] ERROR sphere - [oauth] Failed to refresh access token.
java.util.concurrent.ExecutionException: java.net.ConnectException: connection timed out: auth-v1.sphere.io/5.79.36.225:443 to https://auth-v1.sphere.io/oauth/token?grant_type=client_credentials&scope=manage_project%3Ajvm-sdk-integration-tests-1
    at com.google.common.util.concurrent.AbstractFuture$Sync.getValue(AbstractFuture.java:299) ~[guava-17.0.jar:na]
    at com.google.common.util.concurrent.AbstractFuture$Sync.get(AbstractFuture.java:286) ~[guava-17.0.jar:na]
    at com.google.common.util.concurrent.AbstractFuture.get(AbstractFuture.java:116) ~[guava-17.0.jar:na]
    at io.sphere.sdk.client.SphereClientCredentials.lambda$beginRefresh$3(SphereClientCredentials.java:113) ~[classes/:na]
    at io.sphere.sdk.client.SphereClientCredentials$$Lambda$30/62281031.run(Unknown Source) [classes/:na]
    at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1142) [na:1.8.0]
    at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:617) [na:1.8.0]
    at java.lang.Thread.run(Thread.java:744) [na:1.8.0]
Caused by: java.net.ConnectException: connection timed out: auth-v1.sphere.io/5.79.36.225:443 to https://auth-v1.sphere.io/oauth/token?grant_type=client_credentials&scope=manage_project%3Ajvm-sdk-integration-tests-1
    at com.ning.http.client.providers.netty.NettyConnectListener.operationComplete(NettyConnectListener.java:103) ~[async-http-client-1.8.7.jar:na]
    at org.jboss.netty.channel.DefaultChannelFuture.notifyListener(DefaultChannelFuture.java:427) ~[netty-3.9.0.Final.jar:na]
    at org.jboss.netty.channel.DefaultChannelFuture.notifyListeners(DefaultChannelFuture.java:418) ~[netty-3.9.0.Final.jar:na]
    at org.jboss.netty.channel.DefaultChannelFuture.setFailure(DefaultChannelFuture.java:380) ~[netty-3.9.0.Final.jar:na]
    at org.jboss.netty.channel.socket.nio.NioClientBoss.processConnectTimeout(NioClientBoss.java:140) ~[netty-3.9.0.Final.jar:na]
    at org.jboss.netty.channel.socket.nio.NioClientBoss.process(NioClientBoss.java:83) ~[netty-3.9.0.Final.jar:na]
    at org.jboss.netty.channel.socket.nio.AbstractNioSelector.run(AbstractNioSelector.java:318) ~[netty-3.9.0.Final.jar:na]
    at org.jboss.netty.channel.socket.nio.NioClientBoss.run(NioClientBoss.java:42) ~[netty-3.9.0.Final.jar:na]
    at org.jboss.netty.util.ThreadRenamingRunnable.run(ThreadRenamingRunnable.java:108) ~[netty-3.9.0.Final.jar:na]
    at org.jboss.netty.util.internal.DeadLockProofWorker$1.run(DeadLockProofWorker.java:42) ~[netty-3.9.0.Final.jar:na]
    ... 3 common frames omitted
Caused by: org.jboss.netty.channel.ConnectTimeoutException: connection timed out: auth-v1.sphere.io/5.79.36.225:443
    at org.jboss.netty.channel.socket.nio.NioClientBoss.processConnectTimeout(NioClientBoss.java:137) ~[netty-3.9.0.Final.jar:na]
    at org.jboss.netty.channel.socket.nio.NioClientBoss.process(NioClientBoss.java:83) ~[netty-3.9.0.Final.jar:na]
    at org.jboss.netty.channel.socket.nio.AbstractNioSelector.run(AbstractNioSelector.java:318) ~[netty-3.9.0.Final.jar:na]
    at org.jboss.netty.channel.socket.nio.NioClientBoss.run(NioClientBoss.java:42) ~[netty-3.9.0.Final.jar:na]
    ... 3 common frames omitted

Refactor Log class to take Object as parameter and call internally toString

Review client API usage

http://sphereio.github.io/sphere-jvm-sdk/javadoc/1.0.0-SNAPSHOT/io/sphere/sdk/client/package-summary.html#package.description

Log with call by name parameters (Java client + Play utils)

• gain performance by only executing the block on an adequate log level

import io.sphere.sdk.utils.Log;

Log.trace(() -> bigObject.toString));

internally implemented as

if(isTraceEnabled()){
    Log.trace(argument.get());
}

• Use Supplier<Object>

Create demo actor which can load multiple paged results

Review product types

Hajo:

• can you have a look at this sentence:
  "The by ProductTypeCreateCommand required NewProductType can be created by instantiation or by subclassing:"
• btw: "suggested retail price" -> "recommended retailer price" - short rrp

Type-safe deserialization of product attributes

• check for existence of attribute (maybe use product type)
• keep it compatible with product projections

Show it test results in console

Add documentation guidelines

• api call related stuff in package documentation but not unit test suggestions
• an model Interface should always have a link to it's builder

Consider making model impl classes package private

PagedQueryResult use long or int?

Add CustomerGroup class in own module (required by products)

Add Channel class in own module (required by products)

Endpoint specific logging

It would be nice to set trace logging for example just for product types.

Categories module is not aggregated.

Check also for other projects not in root module aggregated.

catch exceptions in client and add debug data

• for example failed: java.util.concurrent.ExecutionException: java.lang.RuntimeException: com.fasterxml.jackson.databind.JsonMappingException:xJ was not handled

Show/document example client usage with Google Guice

link to sunrise

Migrate to Play 2.3.1

Improve query example for product types

• http://sphereio.github.io/sphere-jvm-sdk/javadoc/master/io/sphere/sdk/producttypes/package-summary.html#query-product-types
• optional and promises make it harder to understand

Fix PagedQueryResult tests

• offset is not the page, but it is the number of skipped items (like products)
• fix specifications
• fix documentation in SDK
• fix documentation in website