public final class GettingStarted extends Base
The commercetools Composable Commerce client communicates asynchronously with the API via HTTPS and it takes care about authentication.
The client uses Java objects to formulate an HTTP request, performs the request and maps the JSON response into a Java object. The resulting Java object is not directly accessible as object, but it is embedded in a Future/Promise for asynchronous programming. Since the client is thread-safe you need only one client to perform multiple requests in parallel.
There are different client flavors for different future implementations:
| Client | Future implementation |
|---|---|
SphereClient (default) | java.util.concurrent.CompletionStage |
| SphereScalaClient | scala.concurrent.Future |
| SpherePlayJavaClient | play.libs.F.Promise (deprecated in Play 2.5.x) |
Follow the instructions at Getting Started to create a CTP project and to retrieve the API credentials needed for the following sections.
Simple instantiation:
import io.sphere.sdk.client.SphereClient;
import io.sphere.sdk.client.SphereClientFactory;
public class JavaClientInstantiationExample { public void instantiate() { final SphereClientFactory factory = SphereClientFactory.of(); final SphereClient client = factory.createClient( "jvm-sdk-dev-1", //replace with your project key "ELqF0rykXD2fyS8s-IhIPKfQ", //replace with your client id "222222222222222222222222222222226"); //replace with your client secret } }See the test code.
Simple instantiation with blocking client:
import io.sphere.sdk.client.BlockingSphereClient;
import io.sphere.sdk.client.SphereClient;
import io.sphere.sdk.client.SphereClientFactory;
import java.util.concurrent.TimeUnit;
public class BlockingJavaClientInstantiationExample { public void instantiate() { try (final BlockingSphereClient sphereClient = createSphereClient()) { //do blocking requests here } } private BlockingSphereClient createSphereClient() { final SphereClientFactory factory = SphereClientFactory.of(); final SphereClient asyncSphereClient = factory.createClient( "jvm-sdk-dev-1", //replace with your project key "ELqF0rykXD2fyS8s-IhIPKfQ", //replace with your client id "222222222222222222222222222222226"); //replace with your client secret return BlockingSphereClient.of(asyncSphereClient, 20, TimeUnit.SECONDS); } }See the test code.
For projects in the USA you should specify in addition to the previous parameters the auth and api urls:
import io.sphere.sdk.client.SphereClient;
import io.sphere.sdk.client.SphereClientFactory;
public class JavaClientInstantiationExampleInUSA { public void instantiate() { final SphereClientFactory factory = SphereClientFactory.of(); final SphereClient client = factory.createClient( "jvm-sdk-dev-1", //replace with your project key "ELqF0rykXD2fyS8s-IhIPKfQ", //replace with your client id "222222222222222222222222222222226", "https://auth.us-central1.gcp.commercetools.com/", "https://api.us-central1.gcp.commercetools.com" ); } }See the test code.
Spring example
import io.sphere.sdk.client.BlockingSphereClient;
import io.sphere.sdk.client.SphereClient;
import io.sphere.sdk.client.SphereClientConfig;
import io.sphere.sdk.client.SphereClientFactory;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import java.io.IOException;
import java.util.concurrent.TimeUnit;
@Configuration
public class CommercetoolsConfig {
@Bean(destroyMethod = "close")
public BlockingSphereClient sphereClient(
@Value("${ctp.projectKey}") final String projectKey,
@Value("${ctp.clientId}") final String clientId,
@Value("${ctp.clientSecret}") final String clientSecret,
@Value("${ctp.authUrl}") final String authUrl,
@Value("${ctp.apiUrl}") final String apiUrl
) throws IOException {
final SphereClientConfig config = SphereClientConfig.of(projectKey, clientId, clientSecret, authUrl, apiUrl);
final SphereClient asyncClient = SphereClientFactory.of().createClient(config);
return BlockingSphereClient.of(asyncClient, 20, TimeUnit.SECONDS);
}
}
Spring Batch example
import io.sphere.sdk.client.BlockingSphereClient;
import io.sphere.sdk.client.SphereClient;
import io.sphere.sdk.client.SphereClientConfig;
import io.sphere.sdk.client.SphereClientFactory;
import org.springframework.batch.core.configuration.annotation.JobScope;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import java.io.IOException;
import java.util.concurrent.TimeUnit;
@Configuration
public class CommercetoolsClientConfiguration {
@Bean(destroyMethod = "close")
@JobScope
public BlockingSphereClient sphereClient(
@Value("#{jobParameters['ctp.projectKey']}") final String projectKey,
@Value("#{jobParameters['ctp.clientId']}") final String clientId,
@Value("#{jobParameters['ctp.clientSecret']}") final String clientSecret,
@Value("#{jobParameters['ctp.authUrl']}") final String authUrl,
@Value("#{jobParameters['ctp.apiUrl']}") final String apiUrl
) throws IOException {
final SphereClientConfig config = SphereClientConfig.of(projectKey, clientId, clientSecret, authUrl, apiUrl);
final SphereClient asyncClient = SphereClientFactory.of().createClient(config);
return BlockingSphereClient.of(asyncClient, 20, TimeUnit.SECONDS);
}
}
A client works on the abstraction level of one HTTP request for one project. With one client you can start multiple requests in parallel, it is thread-safe.
The client method SphereClient.execute(io.sphere.sdk.client.SphereRequest) takes a SphereRequest as parameter.
You can create a SphereRequest yourself or use the predefined ones listed on SphereResources.
Example:
CompletionStage<PagedQueryResult<TaxCategory>> future = client.execute(TaxCategoryQuery.of().byName("de19"));See the test code.
SphereClient.close() to release them.
Tuning the client (blocking requests, timeouts, rate limiting, automatic error handling)Writing unit tests with the client