This article covers a Bloomreach Experience Manager version 13. There's an updated version available that covers our most recent release.

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 Bloomreach Accelerator: B2C Commerce 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. Bloomreach Accelerator: B2C Commerce 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 Bloomreach Accelerator: B2C Commerce 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. Bloomreach Accelerator: B2C Commerce 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, Bloomreach Accelerator: B2C Commerce 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, Bloomreach Accelerator: B2C Commerce 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.