org.jboss.dna.web.jcr.rest
Class JcrResources

java.lang.Object
  org.jboss.dna.web.jcr.rest.JcrResources

@Immutable
public class JcrResources
extends Object

RESTEasy handler to provide the JCR resources at the URIs below. Please note that these URIs assume a context of /resources for the web application.

URI Pattern	Description	Supported Methods
/resources	returns a list of accessible repositories	GET
/resources/{repositoryName}	returns a list of accessible workspaces within that repository	GET
/resources/{repositoryName}/{workspaceName}	returns a list of operations within the workspace	GET
/resources/{repositoryName}/{workspaceName}/item/{path}	accesses the item (node or property) at the path	ALL

Binary data

There are several ways to transfer binary property values, but all involve encoding the binary value into ASCII characters using a Base64 notation and denoting this by adding annotating the property name with a suffix defining the type of encoding. Currently, only "base64" encoding is supported.

For example, if the "jcr:data" property contains a single binary value of "propertyValue", then the JSON object representing that property will be:

   "jcr:data/base64/" : "cHJvcGVydHlWYWx1ZQ=="
 

Likewise, if the "jcr:data" property contains two binary values each being "propertyValue", then the JSON object representing that property will be:

   "jcr:data/base64/" : [ "cHJvcGVydHlWYWx1ZQ==", "cHJvcGVydHlWYWx1ZQ==" ]
 

Note that JCR 1.0.1 does not allow property names to and with a '/' character (among others), while JCR 2.0 does not allow property names to contain an unescaped or unencoded '/' character. Therefore, the "/{encoding}/" suffix can never appear in a valid JCR property name, and will always identify an encoded property.

Here are the details:

• Getting a node with GET /resources/{repositoryName}/item/{pathToNode} obtains the JSON object representing the node, and each property is represented as a nested JSON object where the name is the property name and the value(s) are represented as either a single string value or an array of string values. If the property has a binary value, then the property name is appended with "/base64/" and the string representation of each value is encoded in Base64.
• Getting a property with GET /resources/{repositoryName}/item/{pathToProperty} allows only the value(s) for the one property to be included in the response. If any of the values is a binary value, then all of the values will be encoded in Base64.
• Setting a property with PUT /resources/{repositoryName}/item/{pathToProperty} allows setting the property to a single value, and only that value needs to be included in the body of the request. If the value is binary, the value must be encoded by the client and the "Content-Transfer-Encoding" header must be set to "base64" (case does not matter). When the request is received, the value is decoded before the property value is updated on the node.
• Creating a node with POST /resources/{repositoryName}/item/{pathToNode} requires a request that is structured in the same way as the response from getting a node: the resulting JSON object represents the node, with nested JSON objects for the properties and children. If any property of the new node has a binary value, then the name of the property must be appended with "/base64/" and the string representation of each value are to be encoded in Base64.
• Updating a node with PUT /resources/{repositoryName}/item/{pathToNode} requires a request that is structured in the same way as the response from getting or posting a node: the resulting JSON object represents the node, with nested JSON objects for the properties and children. If any property of the new node has a binary value, then the name of the property must be appended with "/base64/" and the string representation of each value are to be encoded in Base64.

Nested Class Summary

static class	JcrResources.JSONExceptionMapper
static class	JcrResources.NotFoundExceptionMapper
static class	JcrResources.RepositoryExceptionMapper

Field Summary

static String	EMPTY_REPOSITORY_NAME Name to be used when the repository name is empty string as "//" is not a valid path.
static String	EMPTY_WORKSPACE_NAME Name to be used when the workspace name is empty string as "//" is not a valid path.

Constructor Summary

JcrResources()

Method Summary

void	deleteItem(HttpServletRequest request, String rawRepositoryName, String rawWorkspaceName, String path) Deletes the item at path.
String	getItem(HttpServletRequest request, String rawRepositoryName, String rawWorkspaceName, String path, int depth) Handles GET requests for an item in a workspace.
Map<String,RepositoryEntry>	getRepositories(HttpServletRequest request) Returns the list of JCR repositories available on this server
Map<String,WorkspaceEntry>	getWorkspaces(HttpServletRequest request, String rawRepositoryName) Returns the list of workspaces available to this user within the named repository.
javax.ws.rs.core.Response	postItem(HttpServletRequest request, String rawRepositoryName, String rawWorkspaceName, String path, String requestContent) Adds the content of the request as a node (or subtree of nodes) at the location specified by path.
String	putItem(HttpServletRequest request, String rawRepositoryName, String rawWorkspaceName, String path, String requestContent) Updates the properties at the path.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

EMPTY_REPOSITORY_NAME

public static final String EMPTY_REPOSITORY_NAME

Name to be used when the repository name is empty string as "//" is not a valid path.

See Also:

Constant Field Values

EMPTY_WORKSPACE_NAME

public static final String EMPTY_WORKSPACE_NAME

Name to be used when the workspace name is empty string as "//" is not a valid path.

See Also:

Constant Field Values

Constructor Detail

JcrResources

public JcrResources()

Method Detail

getRepositories

public Map<String,RepositoryEntry> getRepositories(@Context
                                                   HttpServletRequest request)

Returns the list of JCR repositories available on this server

Parameters:

request - the servlet request; may not be null

Returns:

the list of JCR repositories available on this server

getWorkspaces

public Map<String,WorkspaceEntry> getWorkspaces(@Context
                                                HttpServletRequest request,
                                                String rawRepositoryName)
                                         throws javax.jcr.RepositoryException,
                                                IOException

Returns the list of workspaces available to this user within the named repository.

Parameters:

rawRepositoryName - the name of the repository; may not be null

request - the servlet request; may not be null

Returns:

the list of workspaces available to this user within the named repository.

Throws:

IOException - if the given repository name does not map to any repositories and there is an error writing the error code to the response.

javax.jcr.RepositoryException - if there is any other error accessing the list of available workspaces for the repository

getItem

public String getItem(@Context
                      HttpServletRequest request,
                      String rawRepositoryName,
                      String rawWorkspaceName,
                      String path,
                      int depth)
               throws org.codehaus.jettison.json.JSONException,
                      org.jboss.resteasy.spi.UnauthorizedException,
                      javax.jcr.RepositoryException

Handles GET requests for an item in a workspace.

Parameters:

request - the servlet request; may not be null or unauthenticated

rawRepositoryName - the URL-encoded repository name

rawWorkspaceName - the URL-encoded workspace name

path - the path to the item

depth - the depth of the node graph that should be returned if path refers to a node. @{code 0} means return the requested node only. A negative value indicates that the full subgraph under the node should be returned. This parameter defaults to 0 and is ignored if path refers to a property.

Returns:

the JSON-encoded version of the item (and, if the item is a node, its subgraph, depending on the value of depth)

Throws:

org.jboss.resteasy.spi.NotFoundException - if the named repository does not exists, the named workspace does not exist, or the user does not have access to the named workspace

org.codehaus.jettison.json.JSONException - if there is an error encoding the node

org.jboss.resteasy.spi.UnauthorizedException - if the given login information is invalid

javax.jcr.RepositoryException - if any other error occurs

See Also:

EMPTY_REPOSITORY_NAME, EMPTY_WORKSPACE_NAME, Session.getItem(String)

postItem

public javax.ws.rs.core.Response postItem(@Context
                                          HttpServletRequest request,
                                          String rawRepositoryName,
                                          String rawWorkspaceName,
                                          String path,
                                          String requestContent)
                                   throws org.jboss.resteasy.spi.NotFoundException,
                                          org.jboss.resteasy.spi.UnauthorizedException,
                                          javax.jcr.RepositoryException,
                                          org.codehaus.jettison.json.JSONException

Adds the content of the request as a node (or subtree of nodes) at the location specified by path.

The primary type and mixin type(s) may optionally be specified through the jcr:primaryType and jcr:mixinTypes properties.

Parameters:

request - the servlet request; may not be null or unauthenticated

rawRepositoryName - the URL-encoded repository name

rawWorkspaceName - the URL-encoded workspace name

path - the path to the item

requestContent - the JSON-encoded representation of the node or nodes to be added

Returns:

the JSON-encoded representation of the node or nodes that were added. This will differ from requestContent in that auto-created and protected properties (e.g., jcr:uuid) will be populated.

Throws:

org.jboss.resteasy.spi.NotFoundException - if the parent of the item to be added does not exist

org.jboss.resteasy.spi.UnauthorizedException - if the user does not have the access required to create the node at this path

org.codehaus.jettison.json.JSONException - if there is an error encoding the node

javax.jcr.RepositoryException - if any other error occurs

deleteItem

public void deleteItem(@Context
                       HttpServletRequest request,
                       String rawRepositoryName,
                       String rawWorkspaceName,
                       String path)
                throws org.jboss.resteasy.spi.NotFoundException,
                       org.jboss.resteasy.spi.UnauthorizedException,
                       javax.jcr.RepositoryException

Deletes the item at path.

Parameters:

request - the servlet request; may not be null or unauthenticated

rawRepositoryName - the URL-encoded repository name

rawWorkspaceName - the URL-encoded workspace name

path - the path to the item

Throws:

org.jboss.resteasy.spi.NotFoundException - if no item exists at path

org.jboss.resteasy.spi.UnauthorizedException - if the user does not have the access required to delete the item at this path

javax.jcr.RepositoryException - if any other error occurs

putItem

public String putItem(@Context
                      HttpServletRequest request,
                      String rawRepositoryName,
                      String rawWorkspaceName,
                      String path,
                      String requestContent)
               throws org.jboss.resteasy.spi.UnauthorizedException,
                      org.codehaus.jettison.json.JSONException,
                      javax.jcr.RepositoryException,
                      IOException

Updates the properties at the path.

If path points to a property, this method expects the request content to be either a JSON array or a JSON string. The array or string will become the values or value of the property. If path points to a node, this method expects the request content to be a JSON object. The keys of the objects correspond to property names that will be set and the values for the keys correspond to the values that will be set on the properties.

Parameters:

request - the servlet request; may not be null or unauthenticated

rawRepositoryName - the URL-encoded repository name

rawWorkspaceName - the URL-encoded workspace name

path - the path to the item

requestContent - the JSON-encoded representation of the values and, possibly, properties to be set

Returns:

the JSON-encoded representation of the node on which the property or properties were set.

Throws:

org.jboss.resteasy.spi.NotFoundException - if the parent of the item to be added does not exist

org.jboss.resteasy.spi.UnauthorizedException - if the user does not have the access required to create the node at this path

org.codehaus.jettison.json.JSONException - if there is an error encoding the node

javax.jcr.RepositoryException - if any other error occurs

IOException - if there is a problem reading the value