Adding Links to Your Resource
Adding Links to Your Resource
This tutorial assumes you have created the terms and conditions resource in Writing Your First Resource.
The goal of this tutorial is to add a new link between resources. You will enhance the terms and conditions resource you created in Writing Your First Resource by linking it from the orders resource. After completing this tutorial, you will be able to view the terms and conditions resource by following a link on the orders resource.
Linking from Orders to Terms and Conditions
{ "self": { "type": "elasticpath.orders.order", "uri": "/commerce-legacy/orders/{scope}/{order-id}", "href": "http://localhost/cortex/orders/mobee/<an-order-id>", "max-age": 0 }, "links": [ ... { "rel":"terms", "type":"elasticpath.terms.terms-and-conditions", "uri":"/commerce-legacy/terms/id=", "href":"http://localhost:9080/cortex/termswithlink/id=" }, ... ] }A client application can follow the link with rel terms to retrieve the terms and conditions for an order.
Creating the Terms Link Handler
Use ResourceStateLinkHandlers to attach links to a specific resource representation. To attach our terms link to an Order representation, we will develop a ResourceStateLinkHandler that targets an OrderEntity.
- Open the terms-and-conditions-resource you created in Writing Your First Resource in your IDE
- Create the com.elasticpath.rest.example.links package under src/main/java
- Create the OrdersToTermsLinkHandler class in the
com.elasticpath.example.links package
The OrdersToTermsLinkHandler implements the ResourceStateLinkHandler interface. The type parameter for ResourceStateLinkHandlers is used to infer the entity types we want to attach links to. For our tutorial, we target the OrderEntity so our links will appear on the order.
- Open the terms-and-conditions-resource's pom.xml and
add a dependency to the ep-resource-orders-api. This dependency will add the
OrderEntity to the classpath of your resource.
<dependency> <groupId>com.elasticpath.rest.definitions</groupId> <artifactId>ep-resource-orders-api</artifactId> <version>1.10.100.20140827092242</version> </dependency>
- Implement the getLinks method in
OrdersToTermsLinkHandler
GetLinks returns all the links we want to attach to a target. For our tutorial, we return one link to our terms resource
src/main/resources/templates/rest-tutorials/terms-and-conditions-links/src/main/java/com/elasticpath/example/links/OrdersToTermsLinkHandler.java import static com.elasticpath.rest.definition.terms.TermsMediaTypes.TERMS_AND_CONDITIONS; import static java.util.Arrays.asList; import javax.inject.Named; import javax.inject.Singleton; import com.elasticpath.rest.definition.orders.OrderEntity; import com.elasticpath.rest.resource.dispatch.linker.ResourceStateLinkHandler; import com.elasticpath.rest.schema.ResourceLink; import com.elasticpath.rest.schema.ResourceLinkFactory; import com.elasticpath.rest.schema.ResourceState; /** * Handles attaching links to terms on orders. */ @Singleton @Named("ordersToTermsLinkHandler") public class OrdersToTermsLinkHandler implements ResourceStateLinkHandler<OrderEntity> { /** * Attaches links to an order. * * @param resourceState the order resource to attach a link to * @return a link to the terms resource */ @Override public Iterable<ResourceLink> getLinks(final ResourceState<OrderEntity> resourceState) { return asList( ResourceLinkFactory.createNoRev( "/commerce-legacy/terms/id=", TERMS_AND_CONDITIONS.id(), "terms" ) ); } }
- Export the LinkHandler we just created in the
terms-blueprint.xml
src/main/resources/templates/rest-tutorials/terms-and-conditions-links/src/main/resources/OSGI-INF/blueprint/terms-blueprint.xml <service ref="ordersToTermsLinkHandler" auto-export="interfaces"/commerce-legacy/> <service ref="termsResourceOperator" auto-export="interfaces"/commerce-legacy/> </blueprint>
- Run the following command to build the terms and conditions resource JAR
file:
mvn clean install
Verify that the build was successful.
Testing the Terms Link
At this point you've created all the necessary components for linking the terms and conditions resource to an order resource.
- Open a command line and navigate to the directory containing your Cortex web application.
- Run the following command to start the Cortex web
application:
mvn tomcat7:run-war
Using Cortex Studio:
- Navigate to your default cart: GET /carts/mobee/default
- Follow the order link
- Ensure that there is a link to terms on your order
- Follow the terms link and ensure that the terms and conditions are succesfully displayed
Congratulations, you just linked a resource to another resource. By following the same steps, you can now create resources that provide additional services to your client applications.