org.modeshape.web.jcr.rest
Class JcrResources

java.lang.Object
  extended by org.modeshape.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}/items/{path} accesses the item (node or property) at the path GET, POST, PUT, DELETE
/resources/{repositoryName}/{workspaceName}/query executes the query in the body of the request with a language specified by the content type (application/jcr+xpath, application/jcr+sql, application/jcr+sql2, or application/search) POST

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:


Nested Class Summary
static class JcrResources.InvalidQueryExceptionMapper
           
static class JcrResources.JSONExceptionMapper
           
static class JcrResources.NoSuchRepositoryExceptionMapper
           
static class JcrResources.NotFoundExceptionMapper
           
static class JcrResources.RepositoryExceptionMapper
           
 
Field Summary
protected static String BASE64_ENCODING_SUFFIX
           
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.
protected static UrlEncoder URL_ENCODER
           
 
Constructor Summary
JcrResources()
           
 
Method Summary
 void deleteItem(javax.servlet.http.HttpServletRequest request, String rawRepositoryName, String rawWorkspaceName, String path)
          Deletes the item at path.
 String getItem(javax.servlet.http.HttpServletRequest request, String rawRepositoryName, String rawWorkspaceName, String path, int deprecatedDepth, int depth)
          Handles GET requests for an item in a workspace.
 String getRepositories(javax.servlet.http.HttpServletRequest request)
          Returns the list of JCR repositories available on this server
protected  Session getSession(javax.servlet.http.HttpServletRequest request, String rawRepositoryName, String rawWorkspaceName)
          Returns an active session for the given workspace name in the named repository.
 String getWorkspaces(javax.servlet.http.HttpServletRequest request, String rawRepositoryName)
          Returns the list of workspaces available to this user within the named repository.
protected  String jsonEncodedStringFor(Value value)
          Return the JSON-compatible string representation of the given property value.
 javax.ws.rs.core.Response postItem(javax.servlet.http.HttpServletRequest request, String rawRepositoryName, String rawWorkspaceName, String path, String fullNodeInResponse, String requestContent)
          Adds the content of the request as a node (or subtree of nodes) at the location specified by path.
 String postJcrSearchQuery(javax.servlet.http.HttpServletRequest request, String rawRepositoryName, String rawWorkspaceName, long offset, long limit, javax.ws.rs.core.UriInfo uriInfo, String requestContent)
          Executes the JCR-SQL query contained in the body of the request against the give repository and workspace.
 String postJcrSql2Query(javax.servlet.http.HttpServletRequest request, String rawRepositoryName, String rawWorkspaceName, long offset, long limit, javax.ws.rs.core.UriInfo uriInfo, String requestContent)
          Executes the JCR-SQL2 query contained in the body of the request against the give repository and workspace.
 String postJcrSqlQuery(javax.servlet.http.HttpServletRequest request, String rawRepositoryName, String rawWorkspaceName, long offset, long limit, javax.ws.rs.core.UriInfo uriInfo, String requestContent)
          Executes the JCR-SQL query contained in the body of the request against the give repository and workspace.
 String postXPathQuery(javax.servlet.http.HttpServletRequest request, String rawRepositoryName, String rawWorkspaceName, long offset, long limit, javax.ws.rs.core.UriInfo uriInfo, String requestContent)
          Executes the XPath query contained in the body of the request against the give repository and workspace.
 String putItem(javax.servlet.http.HttpServletRequest request, String rawRepositoryName, String rawWorkspaceName, String path, String requestContent)
          Updates the properties at the path.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

BASE64_ENCODING_SUFFIX

protected static final String BASE64_ENCODING_SUFFIX
See Also:
Constant Field Values

URL_ENCODER

protected static final UrlEncoder URL_ENCODER

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 String getRepositories(@Context
                              javax.servlet.http.HttpServletRequest request)
                       throws org.codehaus.jettison.json.JSONException,
                              RepositoryException
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
Throws:
org.codehaus.jettison.json.JSONException - if there is an error encoding the node
RepositoryException - if any other error occurs

getWorkspaces

public String getWorkspaces(@Context
                            javax.servlet.http.HttpServletRequest request,
                            String rawRepositoryName)
                     throws org.codehaus.jettison.json.JSONException,
                            RepositoryException
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:
org.codehaus.jettison.json.JSONException - if there is an error encoding the node
RepositoryException - if there is any other error accessing the list of available workspaces for the repository

getItem

public String getItem(@Context
                      javax.servlet.http.HttpServletRequest request,
                      String rawRepositoryName,
                      String rawWorkspaceName,
                      String path,
                      int deprecatedDepth,
                      int depth)
               throws org.codehaus.jettison.json.JSONException,
                      org.jboss.resteasy.spi.UnauthorizedException,
                      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
deprecatedDepth - the old depth parameter ("mode:depth"). This version is deprecated and should use the "depth" query parameter instead.
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
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
                                          javax.servlet.http.HttpServletRequest request,
                                          String rawRepositoryName,
                                          String rawWorkspaceName,
                                          String path,
                                          String fullNodeInResponse,
                                          String requestContent)
                                   throws org.jboss.resteasy.spi.NotFoundException,
                                          org.jboss.resteasy.spi.UnauthorizedException,
                                          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
fullNodeInResponse - if fullNodeInResponse == null || Boolean.valueOf(fullNodeInResponse), indicates that a representation of the created node (including all properties and children) should be returned; otherwise, only the path to the new node will be returned
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
RepositoryException - if any other error occurs

deleteItem

public void deleteItem(@Context
                       javax.servlet.http.HttpServletRequest request,
                       String rawRepositoryName,
                       String rawWorkspaceName,
                       String path)
                throws org.jboss.resteasy.spi.NotFoundException,
                       org.jboss.resteasy.spi.UnauthorizedException,
                       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
RepositoryException - if any other error occurs

putItem

public String putItem(@Context
                      javax.servlet.http.HttpServletRequest request,
                      String rawRepositoryName,
                      String rawWorkspaceName,
                      String path,
                      String requestContent)
               throws org.jboss.resteasy.spi.UnauthorizedException,
                      org.codehaus.jettison.json.JSONException,
                      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
RepositoryException - if any other error occurs
IOException - if there is a problem reading the value

postXPathQuery

public String postXPathQuery(@Context
                             javax.servlet.http.HttpServletRequest request,
                             String rawRepositoryName,
                             String rawWorkspaceName,
                             long offset,
                             long limit,
                             @Context
                             javax.ws.rs.core.UriInfo uriInfo,
                             String requestContent)
                      throws InvalidQueryException,
                             RepositoryException,
                             org.codehaus.jettison.json.JSONException
Executes the XPath query contained in the body of the request against the give repository and workspace.

The query results will be JSON-encoded in the response body.

Parameters:
request - the servlet request; may not be null or unauthenticated
rawRepositoryName - the URL-encoded repository name
rawWorkspaceName - the URL-encoded workspace name
offset - the offset to the first row to be returned. If this value is greater than the size of the result set, no records will be returned. If this value is less than 0, results will be returned starting from the first record in the result set.
limit - the maximum number of rows to be returned. If this value is greater than the size of the result set, the entire result set will be returned. If this value is less than zero, the entire result set will be returned. The results are counted from the record specified in the offset parameter.
uriInfo - the information about the URI (from which the other query parameters will be obtained)
requestContent - the query expression
Returns:
the JSON-encoded representation of the query results.
Throws:
org.codehaus.jettison.json.JSONException - if there is an error encoding the node
InvalidQueryException - if the query contained an error, was invalid, or could not be executed
RepositoryException - if any other error occurs

postJcrSqlQuery

public String postJcrSqlQuery(@Context
                              javax.servlet.http.HttpServletRequest request,
                              String rawRepositoryName,
                              String rawWorkspaceName,
                              long offset,
                              long limit,
                              @Context
                              javax.ws.rs.core.UriInfo uriInfo,
                              String requestContent)
                       throws InvalidQueryException,
                              RepositoryException,
                              org.codehaus.jettison.json.JSONException
Executes the JCR-SQL query contained in the body of the request against the give repository and workspace.

The query results will be JSON-encoded in the response body.

Parameters:
request - the servlet request; may not be null or unauthenticated
rawRepositoryName - the URL-encoded repository name
rawWorkspaceName - the URL-encoded workspace name
offset - the offset to the first row to be returned. If this value is greater than the size of the result set, no records will be returned. If this value is less than 0, results will be returned starting from the first record in the result set.
limit - the maximum number of rows to be returned. If this value is greater than the size of the result set, the entire result set will be returned. If this value is less than zero, the entire result set will be returned. The results are counted from the record specified in the offset parameter.
uriInfo - the information about the URI (from which the other query parameters will be obtained)
requestContent - the query expression
Returns:
the JSON-encoded representation of the query results.
Throws:
org.codehaus.jettison.json.JSONException - if there is an error encoding the node
InvalidQueryException - if the query contained an error, was invalid, or could not be executed
RepositoryException - if any other error occurs

postJcrSql2Query

public String postJcrSql2Query(@Context
                               javax.servlet.http.HttpServletRequest request,
                               String rawRepositoryName,
                               String rawWorkspaceName,
                               long offset,
                               long limit,
                               @Context
                               javax.ws.rs.core.UriInfo uriInfo,
                               String requestContent)
                        throws InvalidQueryException,
                               RepositoryException,
                               org.codehaus.jettison.json.JSONException
Executes the JCR-SQL2 query contained in the body of the request against the give repository and workspace.

The query results will be JSON-encoded in the response body.

Parameters:
request - the servlet request; may not be null or unauthenticated
rawRepositoryName - the URL-encoded repository name
rawWorkspaceName - the URL-encoded workspace name
offset - the offset to the first row to be returned. If this value is greater than the size of the result set, no records will be returned. If this value is less than 0, results will be returned starting from the first record in the result set.
limit - the maximum number of rows to be returned. If this value is greater than the size of the result set, the entire result set will be returned. If this value is less than zero, the entire result set will be returned. The results are counted from the record specified in the offset parameter.
uriInfo - the information about the URI (from which the other query parameters will be obtained)
requestContent - the query expression
Returns:
the JSON-encoded representation of the query results.
Throws:
org.codehaus.jettison.json.JSONException - if there is an error encoding the node
InvalidQueryException - if the query contained an error, was invalid, or could not be executed
RepositoryException - if any other error occurs

postJcrSearchQuery

public String postJcrSearchQuery(@Context
                                 javax.servlet.http.HttpServletRequest request,
                                 String rawRepositoryName,
                                 String rawWorkspaceName,
                                 long offset,
                                 long limit,
                                 @Context
                                 javax.ws.rs.core.UriInfo uriInfo,
                                 String requestContent)
                          throws RepositoryException,
                                 org.codehaus.jettison.json.JSONException
Executes the JCR-SQL query contained in the body of the request against the give repository and workspace.

The query results will be JSON-encoded in the response body.

Parameters:
request - the servlet request; may not be null or unauthenticated
rawRepositoryName - the URL-encoded repository name
rawWorkspaceName - the URL-encoded workspace name
offset - the offset to the first row to be returned. If this value is greater than the size of the result set, no records will be returned. If this value is less than 0, results will be returned starting from the first record in the result set.
limit - the maximum number of rows to be returned. If this value is greater than the size of the result set, the entire result set will be returned. If this value is less than zero, the entire result set will be returned. The results are counted from the record specified in the offset parameter.
uriInfo - the information about the URI (from which the other query parameters will be obtained)
requestContent - the query expression
Returns:
the JSON-encoded representation of the query results.
Throws:
org.codehaus.jettison.json.JSONException - if there is an error encoding the node
InvalidQueryException - if the query contained an error, was invalid, or could not be executed
RepositoryException - if any other error occurs

getSession

protected Session getSession(javax.servlet.http.HttpServletRequest request,
                             String rawRepositoryName,
                             String rawWorkspaceName)
                      throws RepositoryException
Returns an active session for the given workspace name in the named repository.

Parameters:
request - the servlet request; may not be null or unauthenticated
rawRepositoryName - the URL-encoded name of the repository in which the session is created
rawWorkspaceName - the URL-encoded name of the workspace to which the session should be connected
Returns:
an active session with the given workspace in the named repository
Throws:
RepositoryException - if any other error occurs

jsonEncodedStringFor

protected String jsonEncodedStringFor(Value value)
                               throws RepositoryException
Return the JSON-compatible string representation of the given property value. If the value is a binary value, then this method returns the Base-64 encoding of that value. Otherwise, it just returns the string representation of the value.

Parameters:
value - the property value; may not be null
Returns:
the string representation of the value
Throws:
RepositoryException - if there is a problem accessing the value


Copyright © 2008-2012 JBoss, a division of Red Hat. All Rights Reserved.