Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.modeshape.web.jcr.rest
Class JcrResources

    java.lang.Object
      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:

- 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.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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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