Chapter 8. Linking resources

There is no configuration required to be able to inject Atom links into a resource representation, you just have to have this maven artifact in the application's path:

Three things are needed in order to tell RESTEasy to inject Atom links into an entity:

The following example illustrates how to declare everything in order to get the Atom links injected in the book store example:

@Path("/")
@Consumes({"application/xml", "application/json"})
@Produces({"application/xml", "application/json"})
public interface BookStore {

	@AddLinks
	@LinkResource(value = Book.class)
	@GET
	@Path("books")
	public Collection<Book> getBooks();

	@LinkResource
	@POST
	@Path("books")
	public void addBook(Book book);

	@AddLinks
	@LinkResource
	@GET
	@Path("book/{id}")
	public Book getBook(@PathParam("id") String id);

	@LinkResource
	@PUT
	@Path("book/{id}")
	public void updateBook(@PathParam("id") String id, Book book);

	@LinkResource(value = Book.class)
	@DELETE
	@Path("book/{id}")
	public void deleteBook(@PathParam("id") String id);
}

And this is the definition of the Book resource:

@Mapped(namespaceMap = @XmlNsMap(jsonName = "atom", namespace = "http://www.w3.org/2005/Atom"))
@XmlRootElement
@XmlAccessorType(XmlAccessType.NONE)
public class Book {
	@XmlAttribute
	private String author;

	@XmlID
	@XmlAttribute
	private String title;

	@XmlElementRef
	private RESTServiceDiscovery rest;
}

If you do a GET /order/foo, this XML representation will be returned:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<book xmlns:atom="http://www.w3.org/2005/Atom" title="foo" author="bar">
 <atom:link href="http://localhost:8081/books" rel="list"/>
 <atom:link href="http://localhost:8081/books" rel="add"/>
 <atom:link href="http://localhost:8081/book/foo" rel="self"/>
 <atom:link href="http://localhost:8081/book/foo" rel="update"/>
 <atom:link href="http://localhost:8081/book/foo" rel="remove"/>
</book>

And in JSON format:

{
 "book":
 {
  "@title":"foo",
  "@author":"bar",
  "atom.link":
   [
    {"@href":"http://localhost:8081/books","@rel":"list"},
    {"@href":"http://localhost:8081/books","@rel":"add"},
    {"@href":"http://localhost:8081/book/foo","@rel":"self"},
    {"@href":"http://localhost:8081/book/foo","@rel":"update"},
    {"@href":"http://localhost:8081/book/foo","@rel":"remove"}
   ]
 }
}

The RESTServiceDiscovery is a Jakarta XML Binding type which inherits from List. You are free to annotate it in order to customise the Jakarta XML Binding serialisation, or just rely on the default with @XmlElementRef.

This is done by annotating the methods with the @LinkResource annotation. It supports the following optional parameters:

Several @LinkResource annotations can be added on a single method by enclosing them in a @LinkResources annotation. This allows the adding of links to the same method on several resource types. For example the /order/foo/comments operation can belong on the Order resource with the comments relation, and on the Comment resource with the list relation.

When RESTEasy adds links to your resources it needs to insert the right values in the URI template. This is done either automatically by guessing the list of values from the entity, or by specifying the values in the @LinkResource pathParameters parameter.

@XmlRootElement
@XmlAccessorType(XmlAccessType.NONE)
public class Comment {
	@ParentResource
	private Book book;

	@XmlElement
	private String author;

	@XmlID
	@XmlAttribute
	private String id;

	@XmlElementRef
	private RESTServiceDiscovery rest;
}

@Path("/")
@Consumes({"application/xml", "application/json"})
@Produces({"application/xml", "application/json"})
public interface BookStore {

	@AddLinks
	@LinkResources({
		@LinkResource(value = Book.class, rel = "comments"),
		@LinkResource(value = Comment.class)
	})
	@GET
	@Path("book/{id}/comments")
	public Collection<Comment> getComments(@PathParam("id") String bookId);

	@AddLinks
	@LinkResource
	@GET
	@Path("book/{id}/comment/{cid}")
	public Comment getComment(@PathParam("id") String bookId, @PathParam("cid") String commentId);

	@LinkResource
	@POST
	@Path("book/{id}/comments")
	public void addComment(@PathParam("id") String bookId, Comment comment);

	@LinkResource
	@PUT
	@Path("book/{id}/comment/{cid}")
	public void updateComment(@PathParam("id") String bookId, @PathParam("cid") String commentId, Comment comment);

	@LinkResource(Comment.class)
	@DELETE
	@Path("book/{id}/comment/{cid}")
	public void deleteComment(@PathParam("id") String bookId, @PathParam("cid") String commentId);

}

@Path("/")
@Consumes({"application/xml", "application/json"})
@Produces({"application/xml", "application/json"})
public interface BookStore {

	@AddLinks
	@LinkResources({
		@LinkResource(value = Book.class, rel = "comments", pathParameters = "${title}"),
		@LinkResource(value = Comment.class, pathParameters = {"${book.title}", "${id}"})
	})
	@GET
	@Path("book/{id}/comments")
	public Collection<Comment> getComments(@PathParam("id") String bookId);

	@AddLinks
	@LinkResource(pathParameters = {"${book.title}", "${id}"})
	@GET
	@Path("book/{id}/comment/{cid}")
	public Comment getComment(@PathParam("id") String bookId, @PathParam("cid") String commentId);

	@LinkResource(pathParameters = {"${book.title}", "${id}"})
	@POST
	@Path("book/{id}/comments")
	public void addComment(@PathParam("id") String bookId, Comment comment);

	@LinkResource(pathParameters = {"${book.title}", "${id}"})
	@PUT
	@Path("book/{id}/comment/{cid}")
	public void updateComment(@PathParam("id") String bookId, @PathParam("cid") String commentId, Comment comment);

	@LinkResource(Comment.class, pathParameters = {"${book.title}", "${id}"})
	@DELETE
	@Path("book/{id}/comment/{cid}")
	public void deleteComment(@PathParam("id") String bookId, @PathParam("cid") String commentId);

}

The user can restrict which links are injected in the resource based on security restrictions for the client, so that if the current client doesn't have permission to delete a resource he will not be presented with the "delete" link relation.

Security restrictions can either be specified on the @LinkResource annotation, or using RESTEasy and Jakarta Enterprise Beans security annotation @RolesAllowed on the Jakarta RESTful Web Services method.

It has been shown that both the URI template values and the security constraints of @LinkResource use UEL to evaluate expressions. RESTEasy provides a basic UEL context with access only to the entity we are injecting links in, and nothing more.

More variables or functions can be added in this context, by adding a @LinkELProvider annotation on the Jakarta RESTful Web Services method, its class, or its package. This annotation's value should point to a class that implements the ELProvider interface, which wraps the default ELContext in order to add any missing functions.

For example, to support the Seam annotation s:hasPermission(target, permission) in your security constraints, add a package-info.java file like this:

@LinkELProvider(SeamELProvider.class)
package org.jboss.resteasy.links.test;

import org.jboss.resteasy.links.*;

With the following provider implementation:

package org.jboss.resteasy.links.test;

import jakarta.el.ELContext;
import jakarta.el.ELResolver;
import jakarta.el.FunctionMapper;
import jakarta.el.VariableMapper;

import org.jboss.seam.el.SeamFunctionMapper;

import org.jboss.resteasy.links.ELProvider;

public class SeamELProvider implements ELProvider {

	public ELContext getContext(final ELContext ctx) {
		return new ELContext() {

			private SeamFunctionMapper functionMapper;

			@Override
			public ELResolver getELResolver() {
				return ctx.getELResolver();
			}

			@Override
			public FunctionMapper getFunctionMapper() {
				if (functionMapper == null)
					functionMapper = new SeamFunctionMapper(ctx
							.getFunctionMapper());
				return functionMapper;
			}

			@Override
			public VariableMapper getVariableMapper() {
				return ctx.getVariableMapper();
			}
		};
	}

}

And then use it as such:

@Path("/")
@Consumes({"application/xml", "application/json"})
@Produces({"application/xml", "application/json"})
public interface BookStore {

	@AddLinks
	@LinkResources({
		@LinkResource(value = Book.class, rel = "comments", constraint = "${s:hasPermission(this, 'add-comment')}"),
		@LinkResource(value = Comment.class, constraint = "${s:hasPermission(this, 'insert')}")
	})
	@GET
	@Path("book/{id}/comments")
	public Collection<Comment> getComments(@PathParam("id") String bookId);

	@AddLinks
	@LinkResource(constraint = "${s:hasPermission(this, 'read')}")
	@GET
	@Path("book/{id}/comment/{cid}")
	public Comment getComment(@PathParam("id") String bookId, @PathParam("cid") String commentId);

	@LinkResource(constraint = "${s:hasPermission(this, 'insert')}")
	@POST
	@Path("book/{id}/comments")
	public void addComment(@PathParam("id") String bookId, Comment comment);

	@LinkResource(constraint = "${s:hasPermission(this, 'update')}")
	@PUT
	@Path("book/{id}/comment/{cid}")
	public void updateComment(@PathParam("id") String bookId, @PathParam("cid") String commentId, Comment comment);

	@LinkResource(Comment.class, constraint = "${s:hasPermission(this, 'delete')}")
	@DELETE
	@Path("book/{id}/comment/{cid}")
	public void deleteComment(@PathParam("id") String bookId, @PathParam("cid") String commentId);

}

Sometimes it is useful to add resources which are just containers or layers on other resources, for example to represent a collection of Comment with a start index and a certain number of entries, in order to implement paging. Such a collection is not really an entity in the model, but it should obtain the "add" and "list" link relations for the Comment entity.

This is possibly using resource facades. A resource facade is a resource which implements the ResourceFacade<T> interface for the type T, and as such, should receive all links for that type.

Since in most cases the instance of the T type is not directly available in the resource facade, another way is needed to extract its URI template values. This is done by calling the resource facade's pathParameters() method to obtain a map of URI template values by name. This map will be used to fill in the URI template values for any link generated for T, if there are enough values in the map.

Here is an example of such a resource facade for a collection of Comments:

@XmlRootElement
@XmlAccessorType(XmlAccessType.NONE)
public class ScrollableCollection implements ResourceFacade<Comment> {

	private String bookId;
	@XmlAttribute
	private int start;
	@XmlAttribute
	private int totalRecords;
	@XmlElement
	private List<Comment> comments = new ArrayList<Comment>();
	@XmlElementRef
	private RESTServiceDiscovery rest;

	public Class<Comment> facadeFor() {
		return Comment.class;
	}

	public Map<String, ? extends Object> pathParameters() {
		HashMap<String, String> map = new HashMap<String, String>();
		map.put("id", bookId);
		return map;
	}
}

This will produce such an XML collection:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<collection xmlns:atom="http://www.w3.org/2005/Atom" totalRecords="2" start="0">
 <atom.link href="http://localhost:8081/book/foo/comments" rel="add"/>
 <atom.link href="http://localhost:8081/book/foo/comments" rel="list"/>
 <comment xmlid="0">
  <text>great book</text>
  <atom.link href="http://localhost:8081/book/foo/comment/0" rel="self"/>
  <atom.link href="http://localhost:8081/book/foo/comment/0" rel="update"/>
  <atom.link href="http://localhost:8081/book/foo/comment/0" rel="remove"/>
  <atom.link href="http://localhost:8081/book/foo/comments" rel="add"/>
  <atom.link href="http://localhost:8081/book/foo/comments" rel="list"/>
 </comment>
 <comment xmlid="1">
  <text>terrible book</text>
  <atom.link href="http://localhost:8081/book/foo/comment/1" rel="self"/>
  <atom.link href="http://localhost:8081/book/foo/comment/1" rel="update"/>
  <atom.link href="http://localhost:8081/book/foo/comment/1" rel="remove"/>
  <atom.link href="http://localhost:8081/book/foo/comments" rel="add"/>
  <atom.link href="http://localhost:8081/book/foo/comments" rel="list"/>
 </comment>
</collection>