Cortex API communicates with the Core Domain Layer to read and write data to the database and to initiate e-commerce operations in the Commerce Engine. The Core Domain Layer uses heavyweight domain objects to communicate with the various parts of the Commerce Engine, but Cortex API uses light-weight objects called representations to communicate with client applications. In order for Cortex API to communicate with the Core Domain layer, the API's representations need to be converted into domain objects. The same goes for when the Core Domain Layer needs to communicate with Cortex API, the domain objects need to be converted into representations.

DTOs, a lightweight design pattern for transferring data, are used to convert representations to domain objects and domain objects to representations. The example below shows how a shopping cart domain objects is converted into a cart DTO, which Cortex API can then turn into a representation that can be surfaced back to the client application.

Elastic Path core Shopping Cart domain objects contain a lot more information than just a container for line items. This additional luggage is undesired in Cortex API context, especially when it is not used. This just adds to the data footprint of the information being passed back and forth, and DTO's help concentrate on just the information we need to display to the end user. In this example, core Shopping Cart information is assembled into Cortex API DTOs. The CartDto interface defines accessor methods for total quantity and cart guid.

public interface CartDto extends ResourceEntity {

	CartDto setTotalQuantity(int totalQuantity);

	int getTotalQuantity();

	CartDto setCartGuid(String cartGuid);

	String getCartGuid();
}

The cart DTO is constructed through the CartDomainTransformer, which takes in a core ShoppingCart core domain object, creates a CartDto and populates it with values that display cart level data.

...
protected CartDto internalTransformToEntity(final ShoppingCart cart, final Locale locale) {
	CartDto cartDto = ResourceTypeFactory.createResourceEntity(CartDto.class)
			.setCartGuid(cart.getGuid())
			.setTotalQuantity(cart.getNumItems());
	return cartDto;
}

Similarly, the line items of a cart can be transformed by a LineItemDomainTransformer to LineItemDtos to get a full picture of the cart contents for display.

...
protected LineItemDto internalTransformToEntity(final LineItem lineItem, final Locale locale) {
		LineItemDto lineItemDto = ResourceTypeFactory.createResourceEntity(LineItemDto.class)
				.setCartCorrelationId(lineItem.getCartId())
				.setItemCorrelationId(lineItem.getItemId())
				.setLineItemCorrelationId(lineItem.getShoppingItem().getGuid())
				.setQuantity(lineItem.getShoppingItem().getQuantity());
		return lineItemDto;
	}
...

The CartLookupStrategy, LineItemLookupStrategy and LineItemWriterStrategy offer a number of methods for working with the core domain cart. For instance the CartLookupStrategyImpl getCart method, gets a shopping cart from core then converts it to a CartDto using the above transformer.

...
public ExecutionResult<CartDto> getCart(final String cartId, final Subject subject) {
	final ExecutionResult<CartDto> result;
	CustomerSession customerSession = customerSessionRepository.findOrCreateCustomerSession(subject);
	ExecutionResult<ShoppingCart> cartResult = shoppingCartRepository.getShoppingCart(customerSession, cartId);
	if (cartResult.isFailure()) {
		result = ExecutionResultFactory.createErrorFromExecutionResult(cartResult);
	} else {
		ShoppingCart cart = cartResult.getData();
		CartDto cartDto = cartDomainTransformer.transformToEntity(cart);
		result = ExecutionResultFactory.createReadOK(cartDto);
	}
	return result;
}
...

The repository instances, customerSessionRepository and shoppingCartRepository, are wrappers around core services that relate with core domain objects, usually manipulating Cortex API objects sent in as applicable to use within a core domain object context, then returning replies in a Cortex API ExcecutionResult. These core object results are then usually either used for additional calls, or assembled into Cortex API DTOs. In this case, the end result is a CartDto which is returned and used further within Cortex API process.