Commerce Connector SDK API Details

Info: This feature in Bloomreach Content requires a standard or premium license. Contact Bloomreach for details.

Overview

This page describes how the Bloomreach Commerce Accelerator Application discovers and interacts with CommerceRepository components provided by a Commerce Connector Module packaged as an HST Addon Module. It covers the common arguments used in CommerceRepository operations, the query and filtering specifications for search operations, and how to access the current visitor's context within a CommerceRepository implementation. The documentation also details each specific CommerceRepository interface.

Module Entrypoint: ConnectorRepositoryProvider

The entry point for a Commerce Connector Module is the com.bloomreach.commercedxp.api.v2.connector.provider.ConnectorRepositoryProvider interface. The Bloomreach Commerce Accelerator Application locates an implementation of this interface in the module, which must be packaged as an HST Addon Module and referenced by the configured connector's module name.

This interface provides access to all CommerceRepository components through getter methods such as getCustomerRepository(), getCategoryRepository(), and getProductRepository(). To simplify implementation, extend the abstract adapter class com.bloomreach.commercedxp.api.v2.connector.provider.AbstractConnectorRepositoryProvider, which supplies the necessary getters and setters for these components.

Expose a bean implementing this interface in the Spring Assembly defined in your HST Addon Module package descriptor.

Common Concepts

All CommerceRepository operations share several key concepts. This section explains each.

Common Argument: CommerceConnector

Every CommerceRepository operation receives a com.bloomreach.commercedxp.starterstore.connectors.CommerceConnector as its first argument. This argument enables the implementation to access the associated CommerceConnector and CommerceConnectorComponent models defined in the Commerce Connector Set Model. All model properties are resolved at runtime. For example, if the serviceBaseUrl property is set to "/searches/${storeId}/keywords/form", then CommerceConnectorComponent#getServiceBaseUrl() returns a resolved value such as "/searches/mystore/keywords/form" based on connector properties, request attributes, or component parameters.

Using the CommerceConnector argument is optional for connector module implementations, but it is recommended for externalizing connector-specific configuration such as REST API endpoints, HTTP methods, query parameters, headers, or request bodies.

Flexible Query Specification: QuerySpec and FilterSpec

Search-related APIs (such as CommerceResourceRepository#findAll() and CommerceResourceRepository#findOne()) accept a QuerySpec argument. The Bloomreach Commerce Accelerator Application passes this argument to each CommerceResourceRepository interface, allowing implementations to apply pagination, constraints, and filtering.

QuerySpec defines pagination options and query constraints, which can include nested FilterSpec objects. Applications create a QuerySpec—optionally with one or more FilterSpec instances—to query a CommerceResourceRepository. Examples:

// Example 1: Create a QuerySpec with default values.
QuerySpec querySpec1 = new QuerySpec(); // Default pagination, no filters.

// Example 2: Create a QuerySpec with custom pagination.
QuerySpec querySpec2 = new QuerySpec(10, 10); // Start at index 11, return up to 10 items.

// Example 3: Create a QuerySpec with a filter for a specific ID.
FilterSpec filterSpec3 = FilterSpec.create(FilterOperator.EQ, "id", "12345");
QuerySpec querySpec3 = new QuerySpec(filterSpec2); // Search for item with id="12345".

// Example 4: Create a QuerySpec with an 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 for firstName="John" and salary > 30000

Refer to the JavaDocs for additional details.

Connector module implementations determine whether and how to use the provided QuerySpec. The Bloomreach Commerce Accelerator Application supplies all necessary pagination and query constraints for optimal visitor experience. Connector modules should process queries according to the given QuerySpec.

Visitor Context Awareness: VisitorContext

Some CommerceRepository operations require visitor context, such as authentication status, customer email, or access tokens for the Commerce Backend Platform.

For example, a CartRepository should restrict access so that a visitor can only retrieve their own cart data. To support this, the Commerce Connector SDK provides com.bloomreach.commercedxp.api.v2.connector.visitor.VisitorContext and com.bloomreach.commercedxp.api.v2.connector.visitor.VisitorContextAccess.

When invoking a CommerceRepository, the Bloomreach Commerce Accelerator Application sets the current VisitorContext based on the authenticated visitor. The CommerceRepository implementation can then access the visitor's context as needed.

Example: Checking the current VisitorContext in a CommerceRepository implementation.

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

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

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

See the JavaDocs for more information on VisitorContext and VisitorContextAccess.

How the Application Invokes CommerceRepository

To invoke a CommerceRepository, application components retrieve the ConnectorRepositoryProvider for the specific Commerce Connector Module using the ConnectorRepositoryProviderRegistry service. They then obtain the required CommerceRepository component from the provider. Example:

public class ProductListComponent extends AbstractStarterStoreComponent {
    // SNIP
    @Override
    public void doBeforeRender(HstRequest request, HstResponse response) throws ConnectorException {
        // Retrieve a CommerceConnector configured for the current channel.
        final CommerceConnector connector = getDecoratingCommerceConnector(request, response);
        // Obtain 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);
        // Set the result as a request attribute for template rendering.
        request.setAttribute("beanResult", beanResult);
    }
    // SNIP
}

Refer to the JavaDocs for more details on VisitorContext and VisitorContextAccess.

Repositories

All repository interfaces extend from the base CommerceRepository marker interface. The hierarchy is structured for consistency: each interface extends either CommerceResourceRepository or CommerceFormRepository (or both), with type parameters for models, identifiers, and forms. This section describes each repository interface used in commerce-enabled applications.

Commerce repository interface hierarchy for resource and form repositories

Diagram: This UML-style diagram shows the interface hierarchy. The top-level CommerceRepository branches into CommerceResourceRepository (for search operations like findOne and findAll) and CommerceFormRepository (for form operations such as save, create, delete, checkIn, and checkOut). Generic type parameters represent models, identifiers, and forms. Specialized interfaces—such as CategoryRepository, ItemRepository, OrderRepository, CustomerRepository, AddressRepository, and CartRepository—inherit from these base interfaces with their specific type parameters.

CommerceResourceRepository defines search operations for resources in the Commerce Backend Platform, parameterized by CommerceModel (M) and identifier (I) types. For example:
- CategoryRepository: CategoryModel (model), String (identifier)
- ProductRepository: ItemModel (model), String (identifier)
- OrderRepository: OrderModel (model), String (identifier)
CommerceFormRepository defines operations that modify resources or their states, parameterized by CommerceModel (M), identifier (I), and CommerceForm (F) types. For example:
- OrderRepository: OrderModel (model), String (identifier), OrderForm (form)
- CustomerRepository: CustomerModel, String, CustomerForm
- AddressRepository: AddressModel, String, CustomerForm
- CartRepository: CartModel, String, CartForm

CustomerRepository and AddressRepository

CustomerRepository manages customer sign-in, sign-out, and profile updates.
AddressRepository manages retrieval, creation, update, and deletion of customer addresses.

CustomerRepository

Operation	Description	Inputs	Output
`save`	Update a customer resource using properties from the `resourceForm` input. Returns the updated customer model.	`CommerceConnector connector, CustomerForm resourceForm`	`CustomerModel`
`create`	Register a new customer using profile data from the `resourceForm` input. Returns the created customer model.	`CommerceConnector connector, CustomerForm resourceForm`	`CustomerModel`
`delete`	Delete a customer.	`CommerceConnector connector, String id`	`CustomerModel`
`checkIn`	Sign in a customer using authentication information from the `resourceForm` input. Returns the customer model.	`CommerceConnector connector, CustomerForm resourceForm`	`CustomerModel`
`checkOut`	Sign out a customer using authentication information from the `resourceForm` input. Returns the customer model.	`CommerceConnector connector, CustomerForm resourceForm`	`CustomerModel`
`findOne`	Retrieve a customer by `id` or `querySpec`. Returns a `CustomerModel` or `null` if not found.	`CommerceConnector connector, String id, QuerySpec querySpec`	`CustomerModel`
`findAll`	Retrieve multiple customers using `querySpec`. Returns a paginated result.	`CommerceConnector connector, QuerySpec querySpec`	`PageResult<CustomerModel>`
`requestResetCredentials`	Initiate a credentials reset (e.g., send a reset link) using data from the `resourceForm`.	`CommerceConnector connector, CustomerForm resourceForm`	`CustomerModel`
`resetCredentials`	Reset credentials (e.g., password) using data from the `resourceForm` and optional additional information.	`CommerceConnector connector, CustomerForm resourceForm, String additionalInfo`	`CustomerModel`

AddressRepository

Operation	Description	Inputs	Output
`save`	Update a customer address using the `resourceForm` input. Returns the updated customer model.	`CommerceConnector connector, CustomerForm resourceForm`	`CustomerModel`
`create`	Create a customer address using the `resourceForm` input. Returns the updated customer model.	`CommerceConnector connector, CustomerForm resourceForm`	`CustomerModel`
`delete`	Delete a customer address using the `resourceForm` input. Returns the updated customer model.	`CommerceConnector connector, String id`	`CustomerModel`
`checkIn`	Not supported. Throws `java.lang.UnsupportedOperationException`.	`CommerceConnector connector, CustomerForm resourceForm`	`CustomerModel`
`checkOut`	Not supported. Throws `java.lang.UnsupportedOperationException`.	`CommerceConnector connector, CustomerForm resourceForm`	`CustomerModel`

See the JavaDocs for further details on CommerceRepository, CommerceModel, and CommerceForm interfaces.

CategoryRepository

CategoryRepository provides access to product category navigation data.

Operation	Description	Inputs	Output
`findOne`	Retrieve a category by `id` or `querySpec`. Returns a `CategoryModel` or `null` if not found.	`CommerceConnector connector, String id, QuerySpec querySpec`	`CategoryModel`
`findAll`	Retrieve multiple categories using `querySpec`. Returns a paginated result.	`CommerceConnector connector, QuerySpec querySpec`	`PageResult<CategoryModel>`

See the JavaDocs for more information.

ProductRepository

ProductRepository provides access to product items.

Operation	Description	Inputs	Output
`findOne`	Retrieve a product by `id` or `querySpec`. Returns an `ItemModel` or `null` if not found.	`CommerceConnector connector, String id, QuerySpec querySpec`	`ItemModel`
`findAll`	Retrieve multiple products using `querySpec`. Returns a paginated result.	`CommerceConnector connector, QuerySpec querySpec`	`PageResult<ItemModel>`
`findAllByCategory`	Retrieve products by `categoryForm` and `querySpec`. Returns a paginated result.	`CommerceConnector connector, CategoryForm categoryForm, QuerySpec querySpec`	`PageResult<ItemModel>`

Refer to the JavaDocs for additional details.

CartRepository

CartRepository manages creation and updates to the visitor's cart.

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

See the JavaDocs for more information.

OrderRepository

OrderRepository provides access to customer order data.

Operation	Description	Inputs	Output
`findOne`	Retrieve an order by `id` or `querySpec`. Returns an `OrderModel` or `null` if not found.	`CommerceConnector connector, String id, QuerySpec querySpec`	`OrderModel`
`findAll`	Retrieve multiple orders using `querySpec`. Returns a paginated result.	`CommerceConnector connector, QuerySpec querySpec`	`PageResult<OrderModel>`
`save`	Update shipping addresses or other order data using the `resourceForm`. Returns the updated order model.	`CommerceConnector connector, OrderForm resourceForm`	`OrderModel`
`create`	Create a new order.	`CommerceConnector connector, OrderForm resourceForm`	`OrderModel`
`delete`	Delete an order.	`CommerceConnector connector, String id`	`OrderModel`
`checkIn`	Place an order based on a draft.	`CommerceConnector connector, OrderForm resourceForm`	`OrderModel`
`checkOut`	Not supported. Throws `java.lang.UnsupportedOperationException`.	`CommerceConnector connector, OrderForm resourceForm`	`OrderModel`

Refer to the JavaDocs for further details.

Summary

The Bloomreach Commerce Accelerator Application discovers and interacts with a Commerce Connector Module packaged as an HST Addon Module by using a bean of type com.bloomreach.commercedxp.api.v2.connector.provider.ConnectorRepositoryProvider defined in the module's Spring Assembly. This provider supplies all required CommerceRepository components.

The application invokes CommerceRepository operations with common parameters such as a CommerceConnector and a QuerySpec. It also makes the current visitor's context available through VisitorContext and VisitorContextAccess, allowing implementations to access visitor-specific information or control access as needed.

Each CommerceRepository interface extends either CommerceResourceRepository or CommerceFormRepository (or both) with appropriate type parameters. A Commerce Connector Module must implement the necessary CommerceRepository components so that the Bloomreach Commerce Accelerator Application can retrieve or update data in the Commerce Backend Platform through the connector module.