The e-commerce SDK from commercetools running on the Java virtual machine.
Java Other
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.mvn/wrapper Add maven wrapper (#1484) Jul 26, 2017
commercetools-convenience Set next development version 1.35.0-SNAPSHOT Jul 10, 2018
commercetools-internal-docs Add expansion to shipping method queries (#1801) Aug 16, 2018
commercetools-internal-processors Set next development version 1.35.0-SNAPSHOT Jul 10, 2018
commercetools-java-client-ahc-1_8 Set next development version 1.35.0-SNAPSHOT Jul 10, 2018
commercetools-java-client-ahc-1_9 Set next development version 1.35.0-SNAPSHOT Jul 10, 2018
commercetools-java-client-ahc-2_0 Set next development version 1.35.0-SNAPSHOT Jul 10, 2018
commercetools-java-client-apache-async Set next development version 1.35.0-SNAPSHOT Jul 10, 2018
commercetools-java-client-core Set next development version 1.35.0-SNAPSHOT Jul 10, 2018
commercetools-java-client-internal-test Set next development version 1.35.0-SNAPSHOT Jul 10, 2018
commercetools-java-client Set next development version 1.35.0-SNAPSHOT Jul 10, 2018
commercetools-models Add expansion to shipping method queries (#1801) Aug 16, 2018
commercetools-sdk-base Add setvalidfromanduntil update action to product discount (#1785) Jul 16, 2018
commercetools-test-lib Set next development version 1.35.0-SNAPSHOT Jul 10, 2018
osgi-support Set next development version 1.35.0-SNAPSHOT Jul 10, 2018
sdk-http-ahc-1_8 Set next development version 1.35.0-SNAPSHOT Jul 10, 2018
sdk-http-ahc-1_9 Set next development version 1.35.0-SNAPSHOT Jul 10, 2018
sdk-http-ahc-2_0 Set next development version 1.35.0-SNAPSHOT Jul 10, 2018
sdk-http-apache-async Set next development version 1.35.0-SNAPSHOT Jul 10, 2018
sdk-http Set next development version 1.35.0-SNAPSHOT Jul 10, 2018
src/main/javadoc Add OSGi doc (#1733) Mar 20, 2018
.gitignore Allow properties file for integration test credentials. close #797, c… Dec 3, 2015
.travis.yml Evaluate travis build stages (#1596) Oct 20, 2017
CONTRIBUTING.md fix link Jul 8, 2016
LICENSE.md Update year. Jan 29, 2016
PULL_REQUEST_TEMPLATE.md Improve PR template. Feb 1, 2018
README.md Fix snyk badge wrong reference. Apr 16, 2018
RELEASING.md Update releasing instruction and release notes. Nov 17, 2017
mvnw Add maven wrapper (#1484) Jul 26, 2017
mvnw.cmd Add maven wrapper (#1484) Jul 26, 2017
perform-release.sh Fix or patch release scrript. (#1710) Feb 22, 2018
pom.xml Set next development version 1.35.0-SNAPSHOT Jul 10, 2018
prepare-release.sh Fix or patch release scrript. (#1710) Feb 22, 2018

README.md

commercetools JVM SDK

CT-logo

The JVM SDK enables developers to use Java 8 methods and objects to communicate with the commercetools platform (formerly SPHERE.IO) 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.

Using the SDK

Installation

Java SDK with Maven

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

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

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_8: uses async HTTP client 1.8
  • 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-models: models which do not depend to a client implementation

Java SDK with gradle

repositories {
    mavenCentral()
}

dependencies {
    def jvmSdkVersion = "1.31.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

JVM SDK Contrib

Useful code from external developers

Short-term roadmap

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

OSGi support

  • The JVM SDK is OSGi compatible, the module structure is as follows:
    • Bundle sdk-http responsible for http client features, this bundle has the following fragments
      • Fragment sdk-htt-apache-async which provide an implementation of the http clients.
    • Bundle commercetools-sdk-base that contains the base types used for the sdk models, this bundle has the following fragments
      • commercetools-java-client-core
      • commercetools-java-client-apache-async with the previous fragment, it allow to publish a service describing the http client implementation for our API.
      • commercetools-models contains a description model of the commercetools backend and the different actions that alows interaction with it.
  • A demo test that shows a minimum configuration for use in production in an OSGi setup can be found here: DemoOSGiMinimalConfigTest

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://admin.sphere.io/YOUR_PROJECT_KEY/developers/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 commercetools 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.sphere.io
authUrl=https://auth.sphere.io
  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)