Child pages
  • RAAr Design
Skip to end of metadata
Go to start of metadata



RAAr is a library that presents application developers with a local Java library that provides AFS-like API, backed by an Alfresco Web Script-based Java services that marshal/unmarshal calls and direct them to AFS.

RAAr takes care of marshaling/unmarshaling of parameters and handles connection management to multiple-Alfresco instances. Furthermore, RAAr provides more coarse grained calls for better remoting to enhance performance.

Design Overview


Content rich applications will link in process to RAAr and bind against its public interfaces. RAAr's public interfaces are wired to concrete implementations via Spring. The Spring beans implementing the interfaces then communicate with Alfresco over HTTP using GET/POST methods ReSTfully.

Alfresco is extended with WebScripts that fulfill the needs of RAAr and return responses in XML. However, in order to unmarshal the results back to Java objects, a third party library (Castor) is used. Java objects will then be returned back to the caller.

RAAr to Alfresco

  • WebScript call parameters are serialized and passed as strings (Base64) from the client-side due to the limitation of passing parameters for HTTP Method calls.
  • Parameters for uploading content from direct streaming are piggybacked as a query string of HTTP Method and parsed on the server-side.
  • RAAr specifies a request type in HTTP Method header (Header Name: CmaRequestType). Alfresco reads parameters from HTTP query string if the request type is REQUEST_WRITECONTENT.
    • REQUEST_READCONTENT: cma/readContent (for content download. e.g. ContentService.readContent)
    • REQUEST_WRITECONTENT: cma/writeContent (for content upload. e.g. ContentService.writeContent, NodeService.createFile)
    • REQUEST_TEXT: cma/text (for general method calls)
  • WebScripts bypass Alfresco WebScript Authentication. However, all requests are authenticated (except the authenticate request) prior to any method execution.

Alfresco to RAAr

  • Every execution is a transaction, and each transaction is committed prior to sending a response to the client.
  • Known objects such as NodeRef and QName are marshalled and mapped into XML using Castor. Custom mapping handlers are used to map Alfresco Objects.
  • Unknown Serializable objects are serialized into strings (Base64) and their values are mapped to XML.
  • Exceptions from Alfresco are directly serialized into a response stream and de-serialized and propagated by RAAr.
  • Alfresco specifies a response type in HTTP Response header (Header Name: CmaResponseType). RAAr detects the response type and process accordingly.
    • RESPONSE_BINARY: cma/binary (for content download: ConentService.readContent)
    • RESPONSE_ERRROR: cma/error (for serialized Exceptions)
    • RESPONSE_NONE: cma/none (for no response)
    • RESPONSE_XML: cma/response (for general method call responses)
    • RESPONSE_SERVER_ERROR: text/xml (for any error response in xml from the server. Currently the error responses are not unmarshalled)

Design Decisions

Serialization of Parameters

WebScript parameters are serialized and passed as strings (Base64) from the client-side due to the limitation of passing parameters for HTTP Method calls. All parameter objects are required to be Serializable, and performance may have reduced for Serialization and Base64 conversion.

Piggybacking of Parameters

String parameters and file data can be transmitted to the server with a multi-part request, however, there is a need of streaming file data through RAAr directly to the repository. Parameters for writing content are converted into strings and concatenated to a HTTP query string. (a comma is used instead of an equal sign for value assignment since parameter values may contain equal signs from Base64 conversion)


RAAr WebScripts bypass the Alfresco authentication since Alfresco ticket is serialized (and concatenated to a query string for uploading streaming content case) and cannot be recognized by Alfresco. However, RAAr performs authentication on every webscript call prior to any method execution.


Alfresco also provides transaction of WebScript, however, each transaction is committed after the WebScript response is made to the client, which it may result in error when the client makes another request using the !architecture.jpg!response from the previous call and the previous transaction has not committed. In order to overcome this issue, RAAr begins a transaction inside of each WebScript before executing any method and commits the transaction prior to sending a response to the client.

Serialization of Response Values

Known Alfresco data types are mapped into XML using Castor Customized Mapping Handlers. However, unknown data types are serialized and converted to strings by Base64 conversion.

Workflow Service

All data types used for WorkflowService are non-Serializable. Also, since WorkflowDefintion cannot be directly mapped into XML due to a Castor limitation, a mapping helper class is used to temporarily hold values read from XML. Also, all data types that directly or indirectly has a WorkflowDefintion object as a class member are unmarshalled through mapping helper classes.


QNamePatterns are not serializable and cannot be reconstructed from string values. NodeService- getChildAssocs, getParentAssocs, getTargetAssocs and getSourceAssocs can only take QNames for typeQNamePattern and qnamePattern until there is a better resolution.

Multiple Alfresco Instance Support

write up the notion of a ticket with an embedded URI


Interface Requirements Description

The interface should have methods to support the following needed operations:

  1. Creating and manipulating files and folders
  2. Accessing and modifying nodes meta-data
  3. Querying the repository using Lucene
  4. Creating, querying, and modifying permissions
  5. Creating, querying, and modifying authorities
  6. Uploading documents and check-in/check-out
  7. Start, signal, and cancel workflow on packages
  8. Classification API

See Javadocs for actual interface definitions.

WebScripts in Java


package org.alfresco.web.scripts;


import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

public class JavaWebScript extends AbstractWebScript implements WebScript {
    protected static final Log logger = LogFactory.getLog(JavaWebScript.class);

    public void execute(WebScriptRequest req, WebScriptResponse res) throws IOExceptio {
        WebScriptServletResponse wssr = (WebScriptServletResponse)res;
        wssr.getHttpServletResponse().addHeader("TEST, "test");

  • No labels