Lookup

When the client application makes a GET request to a resource, the resource uses a lookup to retrieve the data. Lookups use a strategy pattern and a transformer to call down into the Integration layer to perform the read/GET operation. To understand how this works, the following example assumes the Cortex API client application made a GET request to the profiles resource in order to retrieve the logged in client's profile.

In the example, ProfileLookupImpl.java instantiates a ProfileLookupStrategy and a ProfileTransformer. Then the getProfile(String scope, final String profileId) method uses the ProfileTransformer to create a profile DTO with the profileID that the client is trying to GET. Then the ProfileLookupStrategy.find(profileDto) method passes the profile DTO down into the integration layer to retrieve the profile. Once the operation completes, we check if the read was successful using the profileResult.isFailure() method. If the read is successful, the ProfileTransformer converts the profileDTO into a profile representation and then surfaces that back up to the Kernel for processing.

@Singleton
@Named("profileLookup")
public final class ProfileLookupImpl implements ProfileLookup {
	private final ProfileLookupStrategy profileLookupStrategy;
	private final ProfileTransformer profileTransformer;

	/**
	 * Default constructor.
	 *
	 * @param profileLookupStrategy the lookup strategy.
	 * @param profileTransformer the representation transformer.
	 */
	@Inject
	ProfileLookupImpl(
			@Named("profileLookupStrategy")
			final ProfileLookupStrategy  profileLookupStrategy,
			@Named("profileTransformer")
			final ProfileTransformer profileTransformer) {
		this.profileLookupStrategy = profileLookupStrategy;
		this.profileTransformer = profileTransformer;
	}

	@Override
	public ExecutionResult<ProfileRepresentation> getProfile(final String scope, final String profileId) {
		final ExecutionResult<ProfileRepresentation> result;
		ProfileDto profileDto = profileTransformer.transformToDto(scope, profileId, null);
		ExecutionResult<ProfileDto> profileResult = profileLookupStrategy.find(profileDto);
		if (profileResult.isFailure()) {
			result = ExecutionResultFactory.createErrorFromExecutionResult(profileResult);
		} else {
			ProfileRepresentation profileRepresentation = profileTransformer.transformToRepresentation(scope, profileResult.getData());
			result = ExecutionResultFactory.createReadOK(profileRepresentation);
		}
		return result;
	}
}

Writer

When a client application makes a PUT, POST, or DELETE request to a resource, the resource's writer is used to perform the operation. Writers use a strategy pattern to call down into the Integration layer to perform the create, update, or delete operation. To understand how this works, the following example assumes the Cortex API client application made a PUT request to the profiles resource to update the logged in client's profile.

In the example, ProfileWriter instantiates a ProfileWriterStrategy and a ProfileTransformer. Then the ProfileWriter.update(String profileId, ProfileRepresentation profile) method receives the ProfileRepresentation and the profileId. In this case, the ProfileRepresentation is the updated profile that we want to write to the Commerce Engine and the profileId is the ID of the profile we want to update. Continuing with the code flow, we see that ProfileRepresentation is converted into a ProfileMutator and the profileID is set to it. Then the ProfileTransformer converts the ProfileMutator into a ProfileDTO (for why we convert this into a DTO, see Why Use Transformers and DTOs?). The ProfileWriterStrategy then calls down to the Integration layer with the ProfileDTO to update. The Intergration layer writes the ProfileDTO to the Commerce Engine and the result is returned as an ExecutionResult, which then surfaces back up to the Kernel for processing.

@Named("profileWriter")
public final class ProfileWriterImpl  implements ProfileWriter {
	private final ProfileWriterStrategy profileWriterStrategy;
	private final ProfileTransformer profileTransformer;

	/**
	 * The default constructor.
	 *
	 * @param profileWriterStrategy the writer strategy.
	 * @param profileTransformer the transformer.
	 */
	@Inject
	ProfileWriterImpl(
			@Named("profileWriterStrategy")
			final ProfileWriterStrategy profileWriterStrategy,
			@Named("profileTransformer")
			final ProfileTransformer profileTransformer) {
		this.profileWriterStrategy = profileWriterStrategy;
		this.profileTransformer = profileTransformer;
	}

	@Override
	public ExecutionResult<Void> update(final String profileId, final ProfileRepresentation profile) {
		final ExecutionResult<Void> result;
		ProfileMutator profileMutator = ProfileMutator.create(profile);
		profileMutator.setProfileId(profileId);
		ProfileDto profileDto = profileTransformer.transformToDto(profileMutator.getRepresentation());
		ExecutionResult<Void> profileUpdateResult = profileWriterStrategy.update(profileDto);
		if (profileUpdateResult.isSuccessful()) {
			result = ExecutionResultFactory.createUpdateOK();
		} else {
			result = ExecutionResultFactory.createErrorFromExecutionResult(profileUpdateResult);
		}
		return result;
	}
}

Basically, because it simplifies programming. Breaking up the resource's responsibilities into separate classes makes it easier to code.

You'll notice the lookups and writers use strategies. The strategy's interface is defined in the Rest Resource layer, while its implementation is defined in the Integration layer. This provides loose coupling between the Rest Resource layer and the Integration layer. With this setup, the resource defines what it needs through the strategy and then how that information is retrieved is defined in the Integration layer. This way the code in the Integration layer can be changed without having to refactor the resource in the Rest Resource layer.

Transformer

When the request originates from the Kernel, transformers are used to convert the representation into a DTO. When the request's response comes back from the Integration layer, the transformer converts the DTO into a representation. The ProfileTransformer shown below is a good example of a simple transformer. Usually, transformers have these basic methods:

• transformToDto(ProfileRepresentation representation)Receives the representation as a parameter, converts it into a DTO, and then returns the DTO. http://sitedocs.elasticpath.com/JavaDocs/rest-resources/1.9.0/com/elasticpath/rest/resource/profiles/transform/ProfileTransformer.html
• transformToRepresentation(ProfileDto profileDto)Receives the DTO as a parameter, creates a profile mutator, takes the DTOs values and sets them to the profile mutator, then returns a profile representation.

 @Named("profileTransformer")
public class ProfileTransformer {
	/**
	 * transforms a profile entity to a representation.
	 *
	 * @param profileDto the profile entity.
	 * @return the profile representation.
	 */
	public ProfileRepresentation transformToRepresentation(final ProfileDto profileDto) {
		ProfileMutator profileMutator = ProfileMutator.create();
		String encodedProfileId = Base32Util.encode(profileDto.getUserGuid());
		profileMutator
			.setScope(profileDto.getScope())
			.setProfileId(encodedProfileId)
			.setFirstName(profileDto.getFirstName())
			.setLastName(profileDto.getLastName());
		return profileMutator.getRepresentation();
	}
	/**
	 * Transforms a profile representation into a profile DTO.
	 *
	 * @param representation the profile representation.
	 * @return the profile DTO.
	 */
	public ProfileDto transformToDto(final ProfileRepresentation representation) {
		ProfileDto profileDto = ResourceTypeFactory.createResourceEntity(ProfileDto.class);
		String profileId = representation.getProfileId();
		if (profileId != null) {
			profileId = Base32Util.decode(profileId);
		}
		profileDto.setFirstName(representation.getFirstName())
			.setLastName(representation.getLastName())
			.setPassword(representation.getPassword())
			.setScope(representation.getScope())
			.setUserGuid(profileId);
		return profileDto;
	}
	/**
	 * Creates a profileDto with the given fields, and decodes the profile ID.
	 *
	 * @param scope the scope.
	 * @param profileId the profile ID.
	 * @param username the username.
	 * @return the profile DTO.
	 */
	public ProfileDto transformToDto(final String scope, final String profileId, final String username) {
		ProfileDto profileDto = ResourceTypeFactory.createResourceEntity(ProfileDto.class);
		String decodedProfileId = Base32Util.decode(profileId);
		profileDto.setUserGuid(decodedProfileId)
			.setScope(scope)
			.setUsername(username);
		return profileDto;
	}
}

Mutator

Mutators modify and create representations (for why we use mutators to do this, see Why use Transformers, Mutators, and DTOs?). From the ProfileMutator example below, we can see that the mutator extends the RepresentationMutator class and is typed to the ProfileRepresentation. The mutator has a number of set methods to define the representation's values.

public final class ProfileMutator extends RepresentationMutator<ProfileRepresentation> {

	/**
	 * Creates a new instance of ProfileMutator. This also creates the Profile representation inside.
	 *
	 * @return the new ProfileMutator
	 */
	public static ProfileMutator create() {
		return create(ResourceTypeFactory.createRepresentation(ProfileRepresentation.class));
	}
	/**
	 * Creates a new instance of ProfileMutator for a provided representation.
	 * @param profileRepresentation the profile Representation.
	 * @return the new ProfileMutator
	 */
	public static ProfileMutator create(final ProfileRepresentation profileRepresentation) {
		return new ProfileMutator(profileRepresentation);
	}
	private ProfileMutator(final ProfileRepresentation representation) {
		super(representation);
	}
	/**
	 * @param firstName the given name to set
	 * @return This ProfileMutator instance
	 */
	public ProfileMutator setFirstName(final String firstName) {
		set(ProfileRepresentation.GIVEN_NAME, firstName);
		return this;
	}
	/**
	 * @param lastName the family name to set
	 * @return This ProfileMutator instance
	 */
	public ProfileMutator setLastName(final String lastName) {
		set(ProfileRepresentation.FAMILY_NAME, lastName);
		return this;
	}
	/**
	 *
	 * @param password the password to set.
	 * @return This ProfileMutator instance.
	 */
	public ProfileMutator setPassword(final String password) {
		set(ProfileRepresentation.PASSWORD, password);
		return this;
	}
	/**
	 * @param profileId the profile ID to set
	 * @return This ProfileMutator instance
	 */
   public ProfileMutator setProfileId(final String profileId) {
	   set("profileId", profileId);
	   return this;
   }
	/**
	 * @param scope the scope
	 * @return This ProfileMutator instance
	 */
	@Internal
   public  ProfileMutator setScope(final String scope) {
		set("scope", scope);
		return this;
	}
}

Why use Transformers, Mutators, and DTOs?

The Integration layer is designed so other backend systems—systems other than the Elastic Path Commerce Engine—can integrate with Cortex API. Most backend systems, including ours, don't understand representations. However, pretty much all backend systems, including ours, understand DTOs. Therefore, the Integration layer communicates with backend systems using DTOs. The layers above the Integration layer communicate using representations. Transformers and mutators convert DTOs to representations and representations to DTOs, so that Cortex API can communicate with different backend systems, not just Elastic Path's.

Representations are immutable, which means their state can't change once they are created (by state we mean the representation's values). Representations are designed this way because, as a coding practice, using immutable objects leads to simple and reliable code, thread-safety, and restrict accidental changes to the representation's state. Because representations can't be changed directly, mutators are used to modify them at the Rest Resource layer. By having to code a mutator to change a representation, the chances of a developer accidentally making changes to a representation is reduced.