Working with Mixed Models

The Helix programming model for Cortex API introduces a new way of creating resources and new repositories that simplifies the process of working with Cortex. This guide is intended to address some common scenarios you might encounter when working with Helix and legacy resources and repositories, and how to navigate those situations.

Interacting with Legacy Resources from Helix Resources

In many cases, Helix resources can link to legacy resources without having to modify the legacy resource.

The <from/> and <to/> elements in your Helix resource’s API definition can be used to build relationships with legacy resources without having to extend or modify the legacy resources themselves. For more information, see Resource Relationships.

<relationship>
    <name>item-to-wishlist-form</name>
    <description>Link from items.item to a form used to add that item to a wishlist</description>
    <rel>addtowishlistform</rel>
    <from>items.item</from>
    <to>add-item-to-wishlist-form</to>
</relationship>

The above would be defined in the wishlist resource to add a link on the items.item resource to the add-item-to-wishlist-form.

Repositories

Creating New Repository

Whenever possible, when you create a new Helix resource, you should also create a Helix repository to interact with the resource.

For an example, see the Tutorials repository. In the repository, expand the ep-commerce-examples directory for this version, and select the examples branch. To find tutorials for creating or extending a Helix resource, search for create Helix or extend Helix.

Extending Existing Repository

In many cases, new resources created in the Helix programming model will need to interact with existing legacy repositories.

The recommended practice is to create a Helix repository and extend the legacy resource from the Helix repository. Then, delegate any functionality that requires request-scoped caching to the legacy repository’s methods. This provides you with a consistent interface to program against, while still taking advantage of request-scoped caching.

For an example of this in practice, consider the findOne method in ProfileEntityRepositoryImpl, the Helix programming model implementation of the Profile resource:

public Single<ProfileEntity> findOne(final ProfileIdentifier profileIdentifier) {
    String profileId = profileIdentifier.getProfileId().getValue().toString();
    return customerRepository.findCustomerByGuid(profileId).toSingle()
    .map(this::convertCustomerToProfileEntity);
}

MediaType Classes

By default, the generated MediaType class prefixes the type (self.type) with "elasticpath". Helix programming model entities use a different prefix.

As a workaround, specify the <entity-type/>:

<entity>
    <name>item</name>
    <description><![CDATA[Defines the item type.]]></description>
    <property>
        <name>item-id</name>
        <description><![CDATA[The item identifier.]]></description>
        <internal/>
        <string/>
    </property>
    <entity-type>items.item</entity-type>
</entity>

note

MediaType is a deprecated feature and should be avoided when possible.

Injecting URI-parts

The URI-parts of legacy resources are somewhat inconsistent in format. Most are base-32 encoded String objects, but some are plain String objects, some are a <Map> with only one entry, some are a <Map> with multiple entries, and some are other types like Integer. In some instances, you may need to transform the URI into a consistent format to help with using @Inject to inject these URI-parts.

To properly inject these URI-parts, register a custom URI-part transformer in the Helix prototype, then use this transfomer to convert the decoded String to <Map<String, String>>.

To do this, declare a service with a property of the URI-part you want to transform. The URI-part type pattern in the Helix Pattern Library provides an example of this:

@Component(service = IdentifierTransformer.class, property = "uri-part=cars.car-id")
public class CarIdTransformer extends PlainStringTransformer {

}

If you are uncertain what a particular URI’s retun type is, use the URIPart Transformers tool in the Apache Felix console, located at http://[server]:[port]/cortex/system/console/UriPartTransformers. This lists out all the URI-parts loaded and their return type.