Class JcrRemotingServlet

  • All Implemented Interfaces:
    Serializable, javax.servlet.Servlet, javax.servlet.ServletConfig, DavConstants
    Direct Known Subclasses:
    DavexServletService, JcrRemotingServlet

    public abstract class JcrRemotingServlet
    extends JCRWebdavServerServlet
    JcrRemotingServlet is an extended version of the JCR Remoting Servlet that provides improved functionality and supports cross workspace copy and cloning.

    Batch Read

    Upon RepositoryService.getItemInfos a JSON object is composed containing the information for the requested node and its child items up to a specified or configuration determined depth.

    Batch read is triggered by adding a '.json' extension to the resource href. Optionally the client may explicitly specify the desired batch read depth by appending '.depth.json' extension. If no json extension is present the GET request is processed by the base servlet.

    The JSON writer applies the following rules:

     - Nodes are represented as JSON objects.
    
     - Each Node has its properties included as JSON key/value pairs.
    
     - Single valued Properties are simple key/value pairs.
    
     - Multi valued Properties are represented as JSON array.
    
     - Each Node has its child nodes included as long a maximal depths is not reached.
     
     - Nodes without any child nodes get a special JSON member named
       ::NodeIteratorSize, whose value is zero.
    
     - If the maximal depth is reached only name, index and unique id of the
       direct child are included (incomplete node info). In order to obtain
       the complete information the client sends another GET with .json extension.
     
    Same name sibling nodes and properties whose type cannot be unambiguously be extracted from the JSON on the client side need some special handling:
     - Node with index > 1, get a JSON key consisting of
       Node.getName() + "[" + Node.getIndex() + "]" 
    
     - Binary Property
       JSON value = length of the JCR value.
       The JCR value must be retrieved separately.
    
     - Name, Path, Reference and Date Property
       The JSON member representing the Property (name, value) is preceded by a
       special member consisting of
       JSON key = ":" + Property.getName()
       JSON value = PropertyType.nameFromValue(Property.getType())
    
     - Multi valued properties with Property.getValues().length == 0 will be
       treated as special property types above (extra property indicating the
       type of the property).
    
     - Double Property
       JSON value must not have any trailing ".0" removed.
     

    Multi Read

    Since Jackrabbit 2.3.6 it is also possible to request multiple subtrees in a single request. This is done by adding one or more ":include" parameters to a batch read request describe above. These extra parameters specify the (relative) paths of all the nodes to be included in the response. The response is a JSON object whose "nodes" property contains all the selected nodes keyed by path. Missing nodes are not included in the response. Each included node is serialized as defined above for batch read.

    Example:

     $ curl 'http://.../parent.json?:path=child1&:path=child2'
     {"nodes":{"/parent/child1":{...},"/parent/child2":{...}}}
     

    Batch Write

    The complete SPI Batch is sent to the server in a single request, currently a POST request containing a custom ":diff" parameter.
    NOTE that this is targeted to be replaced by a PATCH request.

    Diff format

    The diff parameter currently consists of JSON-like key-value pairs with the following special requirements:
       diff       ::= members
       members    ::= pair | pairs
       pair       ::= key " : " value
       pairs      ::= pair line-end pair | pair line-end pairs
       line-end   ::= "\r\n" | "\n" | "\r"
       key        ::= diffchar path
       diffchar   ::= "+" | "^" | "-" | ">"
       path       ::= abspath | relpath
       abspath    ::= * absolute path to an item *
       relpath    ::= * relpath from item at request URI to an item *
       value      ::= value+ | value- | value^ | value>
       value+     ::= * a JSON object *
       value-     ::= ""
       value^     ::= * any JSON value except JSON object *
       value>     ::= path | path "#before" | path "#after" | "#first" | "#last"
     
    In other words:
    • diff consists of one or more key-value pair(s)
    • key must start with a diffchar followed by a rel. or abs. item path
    • diffchar being any of "+", "^", "-" or ">" representing the transient item modifications as follows
         "+" addNode
         "^" setProperty / setValue / removeProperty
         "-" remove Item
         ">" move / reorder Nodes
       
    • key must be separated from the value by a ":" surrounded by whitespace.
    • two pairs must be separated by a line end
    • the format of the value depends on the diffchar
    • for moving around node the value must consist of a abs. or rel. path. in contrast reordering of existing nodes is achieved by appending a trailing order position hint (#first, #last, #before or #after)
    NOTE the following special handling of JCR properties of type Binary, Name, Path, Date and Reference:
    • the JSON value must be missing
    • the POST request is expected to contain extra multipart(s) or request parameter(s) for the property value(s)
    • the content type of the extra parts/params must reflect the property type:"jcr-value/" + PropertyType.nameFromValue(Property.getType).toLowerCase()
    See Also:
    www.json.org for the definition of JSON object and JSON value., Serialized Form