SPHERE.IO JVM SDK

[](the link definitions are at the bottom)

SPHERE.IO is the first Platform-as-a-Service solution for eCommerce.

The JVM SDK enables developers to use Java 8 methods and objects to communicate with 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

• install Java 8
• (since Feb 26, 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.0.0-RC1</version>
</dependency>
<dependency>
  <groupId>com.commercetools.sdk.jvm.core</groupId>
  <artifactId>commercetools-java-client</artifactId>
  <version>1.0.0-RC1</version>
</dependency>

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

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

Modules

• commercetools-java-client: alias for sphere-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

Play/Scala SDK with SBT

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

reactive streams

• since RC1-SNAPSHOT, formerly in sphere-convenience-module
• https://github.com/sphereio/commercetools-jvm-sdk-reactive-streams-addons

JVM SDK Contrib

Useful code from external developers

• https://github.com/sphereio/commercetools-jvm-sdk-contrib

Experimental Add-Ons

• ProductImageUploadCommand from http://dev.sphere.io/http-api-projects-products.html#upload-product-image

see https://github.com/sphereio/sphere-jvm-sdk-experimental-java-add-ons

Short-term roadmap

• https://github.com/sphereio/sphere-jvm-sdk/milestones
• https://waffle.io/sphereio/sphere-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

Stability

1. Experimental features in the API are also experimental features of the SDK.
   • this includes for example
     • cart discounts
     • custom fields
     • discount codes
     • types endpoint/custom fields
     • payments
     • nested product attribute
   • the stable and unstable features can be mixed
     • a cart contains the reference to its discounts
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. getters of draft objects might change since the API allows in upgrades different objects
7. final classes without public constructors can be transformed into an interface

Executing integration tests

1. create a file "integrationtest.properties" inside the project root
2. 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 mvn verify to execute all integration tests
2. use mvn -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 mvn test
4. alternatively use your IDE to execute the tests

[](definitions for the top badges)