Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. This Developer Center contains the guides for Commerce 6.13.0 through 7.4.1.Visit new site

This version of Elastic Path Commerce is no longer supported or maintained. To upgrade to the latest version, contact your Elastic Path representative.

Learning to use Cortex Java SDK

Learning to use Cortex Java SDK

Cortex Java SDK can consume Cortex resources in client applications that are built with Java.


Cortex Java SDK is available from the Elastic Path Public Maven Repository.

To add Cortex Java SDK to your OSGi project, add the following dependencies to your Maven POM:


Cortex Java SDK is based on the JAX-RS Java API and includes a set of extensions to facilitate development with Cortex. The SDK provides both a straight JAX-RS Client service as well as a user-scoped Cortex client that scopes Cortex calls to a specific user.

JAX-RS Client

The JAX-RS Client can call any REST service, not just Cortex. The client is injected via an OSGi SCR annotation:

@Reference jaxrsClient;

JAX-RS Client Configuration

To configure the JAX-RS client instance, edit its settings through the OSGi admin console. Additionally, you can add and remove ClientConfigurator services through the admin console.

The JAX-RS Client includes the following Client Configurators:
Name Details
apache-connector Configures the JAX-RS client to use the Apache HttpClient Connector. If this configuration is removed, JAX-RS will fall back to using Java's default HttpURLConnection.
jackson Supplies a Jackson ObjectMapper for JAX-RS to use for JSON marshalling.
json-unmarshaller Instructs JAX-RS to utilize Elastic Path's JSON Unmarshaller to map JSON data into data objects.


The Cortex client provides the following:
  • A user-scoped wrapper around the JAX-RS client to facilitate REST calls to Cortex
  • JSON Unmarhsaller types to marshall/unmarshal JSONs
Tip: Storing Client Instances

Client instances should not be stored between requests.

Using Cortex Client in an OSGi Environment

CortexClientFactory provides the Cortex client instance. To obtain an new Cortex client instant, inject the Factory and pass in a MultiValuedMap with the header and the scope (the store code) to the factory.
			@Reference clientFactory;
			MultivaluedMap<String, Object> headers = new MultivaluedHashMap<String, Object>();
			headers.putSingle(HeaderKeys.X_EP_USER_ID_KEY, "customerId");
			headers.putSingle(HeaderKeys.X_EP_USER_ROLES_KEY, "PUBLIC");
			headers.putSingle(HeaderKeys.AUTHORIZATION_KEY, "authToken"); client = clientFactory.create(headers, scope);

Using Cortex Client in an Non-OSGi Environment

To use the Cortex client in a non-OSGi environment, you need to manually instantiate the required beans. The following example shows how to use a Spring application context with the Cortex client.
				<?xml version="1.0" encoding="UTF-8"?>

					<bean id="jacksonObjectMapper" class="com.elasticpath.example.ApplicationObjectMapper" init-method="init"/commerce-legacy/>
					<!-- Note that this is a custom com.fasterxml.jacson.databind.ObjectMapper extension which disables the
					FAIL_ON_UNKNOWN_PROPERTIES on initialization. this.disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES) -->
					<bean id="jsonUnmarshaller" class="com.fasterxml.jackson.contrib.jsonpath.DefaultJsonUnmarshaller"/commerce-legacy/>
					<bean id="zoomModelIntrospector" class=""/commerce-legacy/>
					<bean id="zoomQueryFactory" class=""/commerce-legacy/>
					<bean id="cortexUrlFactoryImpl" class="">
						<constructor-arg ref="zoomModelIntrospector"/commerce-legacy/>
						<constructor-arg ref="zoomQueryFactory"/commerce-legacy/>
					<bean id="jacksonProvider"  class="" >
						<constructor-arg ref="jacksonObjectMapper"/commerce-legacy/>
					<bean id="jsonUnmarshallReaderInterceptor" class="">
						<constructor-arg ref="jsonUnmarshaller"/commerce-legacy/>
				public CortexClientFactory exampleCortexClientFactorySetup(final ApplicationContext context) {
					ClientConfig clientConfig = new ClientConfig();
					clientConfig.register(new WebApplicationExceptionMapper())
							.register(new LoggingFilter(Logger.getLogger(App.class.getName()), true)) // Should be configurable at runtime
							.property(ClientProperties.CONNECT_TIMEOUT, CONNECT_TIMEOUT)  // Should be configurable at runtime
							.property(ClientProperties.READ_TIMEOUT, READ_TIMEOUT); // Should be configurable at runtime
					//Real implementation will want to pass configurable values to this builder.
					HttpClientConfigurator httpClientConfigurator = new HttpClientConfiguratorBuilder().build();
					Client jaxRsClient = ClientBuilder.newClient(clientConfig);
					CortexUrlFactory cortexUrlFactory = (CortexUrlFactory) context.getBean("cortexUrlFactoryImpl");
					//Cortex url should be configurable at runtime.
					return new CortexClientFactoryImpl(cortexUrlFactory, jaxRsClient, "http://localhost:9080/cortex/");

Sending Requests

Once a client is obtained, it can be used to fetch a view:

CartView cart = client.get(CartView.class);

CartView is a custom class with @JsonPath and @JsonProperty annotations.

Constructing URIs

Cortex Java SDK provides four class level annotations to construct Cortex resource URLs:

  • @EntryPointUri: Defines the URI of a Cortex entry point resource.
  • @Zoom: Adds a Zoom query parameter to the request URL.
  • @Path: Used together with @Zoom, @Path specifies the relation/link to follow from the Zoom request.
  • @FollowLocation: Adds a FollowLocation query parameter to the request URL.

Example: Zoom and FollowLocation

A class that models the expected response should be annotated as follows:

public class Cart {}
URLs with Zoom or FollowLocation query parameters can be constructed by calling the createResourceUrlWithQueryParameters method:
baseUrl = "http://localhost:9080/cortex/"
path = "carts/mobee/default"
result = cortexUrlFactory.addQueryParametersToResourceUrl(baseUrl, path, Cart.class)
//result = "http://localhost:9080/cortex/carts/mobee/default?zoom=order&followLocation=true"

Example: Without Query Parameters

URLs without query parameters can be constructed by calling the createResourceUrl method:
baseUrl = "http://localhost:9080/cortex/"
path = "carts/mobee/default"
result = cortexUrlFactory.createResourceUrl(baseUrl, path)
//result = "http://localhost:9080/cortex/carts/mobee/default"

Example: With Entry Point Resource

A class that models the expected response should be annotated as follows:

public class Carts {}
URLs using entry point URIs can be constructed by calling the createResourceUrlFromAnnotations method:
baseUrl = “http://localhost:9080/cortex/”
store = “mobee”
result = cortexUrlFactory.createResourceUrlFromAnnotations(baseUrl, store, Carts.class)
//result = "http://localhost:9080/cortex/carts/mobee/default?zoom=lineitems&followLocation=true" 

Unmarshalling Cortex Responses

Cortex Java SDK unmarshalling is provided by the Elastic Path JSON Unmarshaller, an open source project. This section shows some simple examples of how to use the JSON Unmarshaller. For more complex unmarhalling examples, see the JSON Unmarshaller project page.

Cortex Java SDK provides two annotations to extract data from a Cortex response:

  • @JsonProperty: Extracts a JSON property from a Cortex response.
  • @JsonPath: Uses JSONPath to extract either a single or multiple JSON properties from a Cortex response. This annotation is useful to extract nested JSON properties.
    Tip: JSONPath Expression Tester

    Cortex Studio comes bundled with a JSONPath tester for creating and testing JSONPath expressions.

The examples below parse this response:
  "self": {
    "type": "elasticpath.carts.cart",
    "uri": "/commerce-legacy/carts/mobee/gwu=?zoom=lineitems:element",
    "href": ""
  "total-quantity": 1,
  "_lineitems": [
      "_element": [
          "self": {
            "type": "elasticpath.carts.line-item",
            "uri": "/commerce-legacy/carts/mobee/gwu=/lineitems/gq4=",
            "href": ""
          "links": [
              "rel": "list",
              "type": "elasticpath.collections.links",
              "uri": "/commerce-legacy/carts/mobee/gwu=/lineitems",
              "href": ""
          "quantity": 1
  "links": [
      "rel": "lineitems",
      "rev": "cart",
      "type": "elasticpath.collections.links",
      "uri": "/commerce-legacy/carts/mobee/gwu=/lineitems",
      "href": ""
      "rel": "order",
      "rev": "cart",
      "type": "elasticpath.orders.order",
      "uri": "/commerce-legacy/orders/mobee/hbr=",
      "href": ""
      "rel": "total",
      "rev": "cart",
      "type": "",
      "uri": "/commerce-legacy/totals/carts/mobee/gwu=",
      "href": ""

Example: Extract JSON Property using @JsonProperty

Extract a single, non-nested, JSON property:
public class Cart {)
  private String totalQuantity;

Example: Extract Nested JSON Properties using @JsonPath

Extract nested JSON properties:
public class Cart {
  //Non-nested JSON property
  private int totalQuantity;

  //Nested Property
  private int quantity;

  //Nested Array 
  private List<LineItem> lineItems;