Creating Your First Helix Resource
This document outlines the overall process of developing a resource in the Helix programming model, as well as the tools available for working with resources. It is intended as an overview of the process. For more in depth information on developing a specific type of resource, see the following resources:
- Tutorials - In the
ep-commerce-examples
directory for this version, select theexamples
branch. To find tutorials for creating or extending a Helix resource, search forcreate Helix
orextend Helix
. - Helix Pattern Catalog - This repository contains a series of self-contained Helix examples that illustrate some of the core resource design patterns.
Helix Programming Model Workflow
The Helix programming model workflow consists of three parts:
- Defining your resource API in XML
- Implementing the prototypes in Java
- Implementing repositories
The extensions/cortex
module includes an example
resource which can serve as a starting point.
Defining and Generating API
To define the API of your new resource, do the following:
- Define your resources, their relationships, and more in XML
- Use Maven to generate Java Interfaces for resource identifiers, prototypes and the relationships between them
Creating API Project
Create the API project in the cortex/resources-api
directory. Refer to extensions/cortex/resources-api/example-api
as a starting point. Like example-api
, your project should have a pom.xml
and an api.xml
file. These are used to generate the interfaces under the target directory.
Parent the pom.xml file with the resources-api-parent artifact ID:
<parent>
<groupId>com.elasticpath.extensions.rest.definitions</groupId>
<artifactId>resources-api-parent</artifactId>
<version>0-SNAPSHOT</version>
</parent>
Include the api-generator-maven-plugin
artifact ID in pom.xml
as well:
<plugin>
<groupId>com.elasticpath.rest.definitions</groupId>
<artifactId>api-generator-maven-plugin</artifactId>
</plugin>
The api.xml
file should be located at src/main/resources/META-INF/rest-definitions/api.xml
.
Defining API
Define your API in api.xml
using the API definition language. Here you model the REST endpoints and the relationships between them by defining the family names, resources, forms, entities, and relationships.
For detailed information, see API Definition.
Generating API
Use Maven to generate the API itself. The generated API consists of .java source and .class files as well as interfaces to implement.
To generate the API, run the following Maven command:
mvn clean install
This generates the following:
Class files in
target/com/elasticpath/rest/definitions/
and.java
source files for reference intarget/generated-sources/api-generator/com/elasticpath/rest/definitions/
Resource interfaces which extend
EntityResourceDefinition
Resource interfaces specify the operations to be implemented by the prototype classes.
Relationship interfaces which extend
RelationshipDefinition
These Relationship interfaces specify the LinkTo interface, which the prototype classes will implement.
An entity interface which extends
ResourceEntity
, as well as anIdentifier
interface which extendsResourceIdentifier
The prototype classes inject these in as fields in order to access the Entity and Identifier properties
Creating Resource Prototype Bundle
Resource prototypes are Java classes which implement the resources defined by the API definition. They perform particular operations by instantiating and routing logic for CRUD (Create Read Update Delete) and other API operations, including submit
, info
and linkto
. For more information see Resource Prototypes.
Resource Prototype Project
The prototype projects must be in the cortex/helix-resources
directory. Refer to extensions/cortex/helix-resources/example
as a starting point.
The Helix resource prototype project must include a Maven pom.xml
file, and the necessary code for Marking Your Bundle as a Prototype Bundle. It also must have a Maven dependency on the Helix resource API created in the resource-api
folder.
The Prototype project should have 4 packages:
permissions
, which contains thePermissionParameterStrategy
classprototype
, which contains the operation prototypes forEntityResourceDefinition
as defined in the APIrelationship
, which contains the classes implementing theRelationshipDefinition
interfaces from the APIwiring
, which contains theServiceWiring
class
Implementing Prototype
Prototype classes need to implement the interfaces generated from resource-api
.
For more information on implementing prototypes, see Resource Prototypes.
For more information on configuring prototypes, their permissions, and more see Configuring Prototypes.
Adding a Helix Repository
Helix repositories are responsible for interacting with Commerce Engine. Repositories translate between commerce domain objects and API representations, abstracting the complexity of Commerce Engine’s databases and business logic from the API layer.
Repositories typically implement either one of the interfaces in the com.elasticpath.repository
package, and one or more of their methods. A resource may have multiple repositories implemented. For more information in implementing repositories, see Resource Repositories.
Running Helix Prototype
Deploying Resources
Update the pom.xml file for the Cortex webapp module with the setting for the new resource.
Go to the
cortex/ext-cortex-webapp/
module and open thepom.xml
file.In the resource-api and resource-prototype artifacts, complete the following:
- Add the dependencies to each artifact
- Set the scope to provided for each artifact, as in the following example:
<dependency> <groupId>...</groupId> <artifactId>...</artifactId> <version>...</version> <scope>provided</scope> </dependency>
In the maven-dependency-plugin >
<!-- Helix Resources
section, add thegroupId
for the new modules.
note
Perform this step if you use a different groupId. The following default groupIds for the extension resources already exist:
com.elasticpath.extensions.rest.repositories
com.elasticpath.extensions.rest.resource
Starting Cortex Webapp
The Cortex webapp consists of three applications:
- Cortex Server
- Cortex Studio
- Apache Felix Web Console
These allow you to test your resource configurations, examine the JSON responses, and troubleshoot resource loading errors.
To launch the Cortex webapp, navigate to the /cortex/ext-cortex-webapp/
directory. Then, run the following command:
mvn clean tomcat8:run-war
This cleans out the existing target directory, starts up a tomcat9 server, and deploys the Cortex Server, Studio, and Felix webapps to the following locations:
- Cortex Server deploys to
http://localhost:9080/cortex
- Cortex Studio deploys to
http://localhost:9080/studio
- The Felix Console deploys to
http://localhost:9080/cortex/system/console/bundles
Debugging Cortex
There are numerous reasons why Cortex may fail to start up. This section can help you address and debug start up issues.
Starting Cortex Webapp in Debug mode
To debug prototype code, start up the Cortex webapp in debug mode and attach your debugger to the running process.
To start the webapp in debug mode, run mvnDebug
instead of mvn
from the command line while in the webapp folder:
mvnDebug tomcat8:run-war
When you start the Cortex webapp in debug mode, the console output provides a listening port. You can use this port to attach IntelliJ IDEA’s remote debugging to Cortex.
Attaching IDEA Remote Debugging to Cortex WebApp
Once the Cortex webapp is running in debug mode, attach your IDE’s remote debugger to the listening port:
JMX Console
In order to access Cortex with a JMX console, update your system’s environment variables and add the following:
MAVEN_JMX=-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=6969 -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management .jmxremote.authenticate=false
Module Validation
The verification phase of the Maven life cycle validates resources, APIs and prototypes. Maven validates the api.xml
file in your resource’s API as well as prototype identifiers and entities to ensure that the resources they point to exist. Errors can occur when maven finds an invalid identifier in your XML.
If you see errors similar to the following, you may need to check your module’s validation.
Apache Felix Web Console
The Apache Felix Web Console allows developers to interact with installed bundles. There are number of subsections specific to Cortex resources that can help you understand any errors you might be receiving. For more information, see Apache Felix Web Console.