Commerce Connector SDK API Details - BloomReach Experience - Open Source CMS

Commerce Connector SDK API Details

This Bloomreach Experience Manager feature requires a standard or premium license. Please contact BloomReach for more information.

Introduction

This page explains how Starter Store Application discovers and accesses CommerceRepository components in a Commerce Connector Module packaged as an HST Addon Module, the common arguments used when invoking CommerceRepository operations, the generic query and filtering specification arguments in search operations, and how to access the current visitor's context in a CommerceRepository implementation with an example. Finally, each specific CommerceRepository interface for each function will be explained in detail.

Module Entrypoint: ConnectorRepositoryProvider

com.bloomreach.commercedxp.api.v2.connector.provider.ConnectorRepositoryProvider is the entry point interface for a Commerce Connector Module. Starter Store Application looks for a component implementing this interface from the module packaged as an HST Addon Module after discovering the module by the configured connnector's module name.

This interface is responsible for providing all the CommerceRepository components explained below through the getter methods such as #getCustomerRepository(), #getCategoryRepository(), #getProductRepository(), etc.. You can create a simple implementation by extending the abstract adapter class, com.bloomreach.commercedxp.api.v2.connector.provider.AbstractConnectorRepositoryProvider, which provides all the getters and setters for the CommerceRepository components.

You should expose a bean implementing this interface through the Spring Assembly included in the module descriptor file of your HST Addon Module package.

Common Concepts

In every CommerceRepository invocation, there are some things in common, playing important roles. In this section, each common concept will be explained.

Common Argument: CommerceConnector

Every operation of a CommerceRepository always accepts the first input argument as a com.bloomreach.commercedxp.starterstore.connectors.CommerceConnector. The CommerceConnector argument allows the CommerceRepository implementation to retrieve the associated CommerceConnector and CommerceConnectorComponent models defined in the Commerce Connector Set Model document. Furthermore, all the properties of those models are resolved at runtime. For example, if the serviceBaseUrl property of a CommerceConnectorComponent is set to "/searches/${storeId}/keywords/form" in the document, then the CommerceConnectorComponent#getServiceBaseUrl(), queried from the CommerceConnector argument, will return a resolved string like "/searches/mystore/keywords/form", based on connector level properties, request attributes or component level parameters, at runtime.

It is up to a specific Commerce Connector Module implementation to decide whether or not to use the CommerceConnector argument, but this is very helpful especially when the Commerce Connector Module wants to externalize the connector specific configurations to communicate with the Commerce Backend Platform, such as simple configurable properties, REST API endpoints, HTTP methods, HTTP query parameters, HTTP request headers, or HTTP request body.

Flexible Query Specification: QuerySpec and FilterSpec

In every search-related API (e.g, CommerceResourceRepository#findAll() and CommerceResourceRepository#findOne()), a QuerySpec argument is passed to each CommerceResourceRepository interface by Starter Store Application, so the CommerceResourceRepository implementation may make queries with proper pagination options, constraints and filtering options.

Basically QuerySpec is a class defining pagination options and query constraints through nested FilterSpec objects. Applications should create a QuerySpec object, optionally with one or more FilterSpec objects, to make a query through a CommerceResourceRepository. Here are some examples:

// Ex-1. Create a simple one with default values.
QuerySpec querySpec1 = new QuerySpec(); // with default pagination setting and no nested filtering.

// Ex-2. Create one with different pagination info.
QuerySpec querySpec2 = new QuerySpec(10, 10); // the result page should start at 11th index up to 10 items at max.

// Ex-3. Create one with a simple filter to search by a specific ID.
FilterSpec filterSpec3 = FilterSpec.create(FilterOperator.EQ, "id", "12345");
QuerySpec querySpec3 = new QuerySpec(filterSpec2); // search an item with id="12345".

// Ex-4. Create one with a complex AND condition.
FilterSpec filterSpec41 = FilterSpec.create(FilterOperator.EQ, "firstName", "John");
FilterSpec filterSpec42 = FilterSpec.create(FilterOperator.GT, "salary", 30000);
FilterSpec filterSpec4 = FilterSpec.and(Arrays.asList(filterSpec41, filterSpec42));
QuerySpec querySpec4 = new QuerySpec(filterSpec4); // search items with firstName="John" and salary > 30000

For more details, see JavaDocs.

It is up to Commerce Connector Module implemenation whether or not to use and how to interpret the given QuerySpec argument. Starter Store Application is simply supposed to provide all the necessary pagination information and query constraints to the Commerce Connector Module for the visitor's best experiences. Therefore, Commerce Connector Module implementations should always make queries based on the given QuerySpec properly.

Visitor Context Awareness: VisitorContext

Depending on Commerce Backend Platform's features, some CommerceRepository operations might need to know the visitor's context information. e.g, whether or not the visitor is already authenticated as a customer, the authenticated customer's e-mail address, customer specific access token against the Commerce Backend Platform, and so on.

For example, in most commerce-enabled experience applications, it would not be appropriate to retrieve someone else's cart data through CartRepository. So, in practice, a CartRepository implementation would want to allow the authenticated customer to retrieve only the customer's own cart data. CommerceRepository implementations in a Commerce Connector Module, therefore, should be able to access the visitor's context.

Commerce Connector SDK provides a solution for this with com.bloomreach.commercedxp.api.v2.connector.visitor.VisitorContext and com.bloomreach.commercedxp.api.v2.connector.visitor.VisitorContextAccess. When it invokes a CommerceRepository, Starter Store Application sets the current VisitorContext based on the current authenticated visitor if available, so that a CommerceRepository implementation is able to access and read the current visitor's context (VisitorContext) in its implementation.

Here is an example code snippet of a CommerceRepository implementation checking the available VisitorContext object:

public class EPCartRepositoryImpl extends AbstractCartRepository {
    // SNIP
    @Override
    public CartModel checkIn(CommerceConnector connector, CartForm resourceForm) throws ConnectorException {
        final VisitorContext visitorContext = VisitorContextAccess.getCurrentVisitorContext();

        // If visitor context is not set, throw an exception, instead of proceeding.
        if (visitorContext == null) {
            throw new ConnectorException("401", "Visitor not authenticated.");
        }

        // SNIP
        final String username = visitorContext.getUsername();
        // You can use the username of the visitorContext in REST API calls on the backend.
        Resource resource = broker.resolve(resourceSpace, serviceBaseUrl, pathVars, exchangeHint);
        return broker.getResourceBeanMapper(resourceSpace).map(resource, EPCart.class);
    }
    // SNIP
}

For more details on the VisitorContext and VisitorContextAccess, see JavaDocs.

How Application Invokes CommerceRepository

In order to invoke a CommerceRepository, Starter Store Application components should retrieve the ConnectorRepositoryProvider of the specific Commerce Connector Module through the ConnectorRepositoryProviderRegistry service component, and retrieve the specific CommerceRepository component through the ConnectorRepositoryProvider like the following example:

public class ProductListComponent extends AbstractStarterStoreComponent {
    // SNIP
    @Override
    public void doBeforeRender(HstRequest request, HstResponse response) throws ConnectorException {
        // Get a decorating CommerceConnector, configurd for the current channel, which resolves variables at runtime.
        final CommerceConnector connector = getDecoratingCommerceConnector(request, response);
        // Get a specific CommerceRepository such as ProductRepository.
        final ProductRepository repo = StarterStoreConnectorUtils.getCommerceRepository(commerceConnector, ProductRepository.class);
        // Invoke the CommerceRepository.
        final QuerySpec querySpec = new QuerySpec();
        final PageResult<ItemModel> beanResult = repo.findAll(commerceConnector, querySpec);
        // You may set the return value to a request attribute, so that the template will be able to display the data.
        request.setAttribute("beanResult", beanResult);
    }
    // SNIP
}

For more details on the VisitorContext and VisitorContextAccess, see JavaDocs.

Repositories

Under the marker CommerceRepository, all the repository interfaces are structured like the following inheritance hierarchy. For a consistent design of CommerceRepository interfaces, each inherits from the parameterized types: CommerceResourceRepository or/and CommerceFormRepository. In this section, each CommerceRepository for a specific function used in commerce-enabled applications are explained in detail.

CommerceResourceRepository interface defines search operations on resources in the Commerce Backend Platform, with template parameters for CommerceModel (M) and identifier (I) types that it can deal with. So, interfaces derived from it realize the types to search specific resources from the backend. For example, CategoryRepository is defined with CategoryModel as CommerceModel type and String as the identifier type; ProductRepository with ItemModel and String type; OrderRepository with OrderModel and String.

CommerceFormRepository interface defines operations making changes on resources or their states in the Commerce Backend Platform, with template parameters for CommerceModel (M), identifier (I) and CommerceForm (F) types that it can deal with. So, interfaces derived from it realize the types to make changes on the specific resources or their states from the backend. For example, OrderRepository is defined with OrderModel as CommerceModel type, String as the identifier type and OrderForm as CommerceForm type; CustomerRepository with CustomerModel, String and CustomerForm; AddressRepository with AddressModel, String and CustomerForm; CartRepository with CartModel, String and CartForm.

CustomerRepository and AddressRepository

CustomerRepository is responsible for a customer's sign-in, sign-out and profile updates, and AddressRepository is responsible for retrieving, creating, updating and deleting a customer's addresses.

[CustomerRepository]

 Operation  Description  Inputs  Output
 save 

 Update the corresponding customer resource in the backend by reading properties from the resourceForm input, and return the updated customer model object.

 CommerceConnector connector, CustomerForm resourceForm  CustomerModel
 create   Sign up a visitor to the Commerce Backend Platform by reading the customer profile data from the resourceForm input, and return the customer model object created by the backend.  CommerceConnector connector, CustomerForm resourceForm  CustomerModel
 delete   Delete a customer.  CommerceConnector connector, String id  CustomerModel
 checkIn   Sign in the customer visitor to the Commerce Backend Platform by reading the customer authentication information from the resourceForm input, and return the customer model object from the backend.  CommerceConnector connector, CustomerForm resourceForm  CustomerModel
 checkOut    Sign out the customer visitor from the Commerce Backend Platform by reading the customer authentication information from the resourceForm input, and return the customer model object from the backend.  CommerceConnector connector, CustomerForm resourceForm  CustomerModel

 findOne

 Search  a single customer resource  item by the given id or querySpec inputs from the Commerce Backend Platform and return it as a CustomerModel, or null if not found.  CommerceConnector connector, String id, QuerySpec querySpec  CustomerModel
 findAll  Search multiple customer resource items by the given querySpec input from the Commerce Backend Platform and return the customer item collection as a paginated result.  CommerceConnector connector, QuerySpec querySpec    PageResult<CustomerModel>
 requestResetCredentials Trigger a credentials reset request (e.g. tokenized request link sent via e-mail/SMS) based on the Customer Form object data.  CommerceConnector connector, CustomerForm resourceForm   CustomerModel

 resetCredentials

Reset the credentials (e.g. customer password) based on the Customer Form object data. The additional info parameter can contain extra value needed by the reset credentials API in the backend.

 CommerceConnector connector, CustomerForm resourceForm
String additionalInfo

 CustomerModel

[AddressRepository]

 Operation  Description  Inputs  Output
 save   Update a specific customer address entry by reading the address entry from the resourceForm input, and return the updated customer model object.  CommerceConnector connector, CustomerForm resourceForm  CustomerModel
 create   Create a specific customer address entry by reading the address entry from the resourceForm input, and return the updated customer model object.  CommerceConnector connector, CustomerForm resourceForm  CustomerModel
 delete   Delete a specific customer address entry by reading the address entry from the resourceForm input, and return the updated customer model object.  CommerceConnector connector, String id  CustomerModel
 checkIn   Not supported, throwing java.lang.UnsupportedOperationException.  CommerceConnector connector, CustomerForm resourceForm  CustomerModel
 checkOut   Not supported, throwing java.lang.UnsupportedOperationException.  CommerceConnector connector, CustomerForm resourceForm  CustomerModel

For more details on the CommerceRepository, and related CommerceModel and CommerceForm interfaces, see JavaDocs.

CategoryRepository 

CategoryRepository is responsible for retrieving product category navigation data.

 Operation  Description  Inputs  Output
 findOne   Search a single category resource item by the given id or querySpec inputs from the Commerce Backend Platform and return it as a CategoryModel, or null if not found.  CommerceConnector connector, String id, QuerySpec querySpec  CategoryModel
 findAll   Search multiple category resource items by the given querySpec input from the Commerce Backend Platform and return the item collection as a paginated result.  CommerceConnector connector, QuerySpec querySpec  PageResult<CategoryModel>

For more details on the CommerceRepository, and related CommerceModel and CommerceForm interfaces, see JavaDocs.

ProductRepository 

ProductRepository is responsible for retrieving product items.

 Operation  Description  Inputs  Output
 findOne   Search a single product item resource by the given id or querySpec inputs from the Commerce Backend Platform and return it as a ItemModel, or null if not found.  CommerceConnector connector, String id, QuerySpec querySpec  ItemModel
 findAll   Search multiple product item resources by the given querySpec input from the Commerce Backend Platform and return the product item collection as a paginated result.  CommerceConnector connector, QuerySpec querySpec  PageResult<ItemModel>
 findAllByCategory   Search the multiple product item resources by the given categoryForm and querySpec input from the Commerce Backend Platform and return the product item collection as a paginated result.  CommerceConnector connector, CategoryForm categoryForm, QuerySpec querySpec  PageResult<ItemModel>

For more details on the CommerceRepository, and related CommerceModel and CommerceForm interfaces, see JavaDocs.

CartRepository 

CartRepository is responsible for creating and updating visitor's cart.

 Operation  Description  Inputs  Output
 save  Update specific cart entries specified in the resourceForm input, and return the updated cart model object.  CommerceConnector connector, CartForm resourceForm  CartModel
 create  Create a cart with the cart entries specified in the resourceForm input, and return the created cart model object.  CommerceConnector connector, CustomerForm resourceForm  CartModel
 delete  Delete the cart.  CommerceConnector connector, String id  CartModel
 checkIn  Retrieve the current visitor's cart from the Commerce Backend Platform.  CommerceConnector connector, CartForm resourceForm  CartModel
 checkOut  Check out the visitor's cart to proceed to place an order from the cart.  CommerceConnector connector, CartForm resourceForm  CartModel

For more details on the CommerceRepository, and related CommerceModel and CommerceForm interfaces, see JavaDocs.

OrderRepository 

OrderRepository is responsible for retrieving customer's order data.

 Operation  Description  Inputs  Output
 findOne   Search a single order item by the given id or querySpec inputs from the Commerce Backend Platform and return it as a OrderModel, or null if not found.  CommerceConnector connector, String id, QuerySpec querySpec  OrderModel
 findAll   Search multiple order items by the given querySpec input from the Commerce Backend Platform and return the order item collection as a paginated result.  CommerceConnector connector, QuerySpec querySpec  PageResult<OrderModel>
 save  Update the shipping addresses if necessary by reading the address entry from the resourceForm input, and return the updated order model object.  CommerceConnector connector, OrderForm resourceForm  OrderModel
 create  Create an order.  CommerceConnector connector, OrderForm resourceForm  OrderModel
 delete  Delete an order.  CommerceConnector connector, String id  OrderModel
 checkIn  Place order on the drafted order.  CommerceConnector connector, OrderForm resourceForm  OrderModel
 checkOut  Not supported, throwing java.lang.UnsupportedOperationException.  CommerceConnector connector, OrderForm resourceForm  OrderModel

For more details on the CommerceRepository, and related CommerceModel and CommerceForm interfaces, see JavaDocs.

Summary

Starter Store Application discovers and invokes a Commerce Connector Module packaged as an HST Addon Module through the entry point bean of type com.bloomreach.commercedxp.api.v2.connector.provider.ConnectorRepositoryProvider, defined in its Spring Assembly. The ConnectorRepositoryProvider is supposed to provide all the necessary CommerceRepository components.

Starter Store Application invokes CommerceRepository operations with common parameters such as CommerceConnector object and QuerySpec object, and it also provides the current visitor's context through VisitorContext and VisitorContextAccess, with which a CommerceRepository implementation may read the visitor specific information or control the invocation access.

For a consistent design of CommerceRepository interfaces, each inherits from the parameterized types: CommerceResourceRepository or/and CommerceFormRepository. A Commerce Connector Module is supposed to implement all the necessary CommerceRepository components so that Starter Store Application can retrieve or update data in the Commerce Backend Platform through the module.

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?