Obsolete Pages{{Obsolete}}
The official documentation is at: http://docs.alfresco.com
Web Scripts
Back to RESTful API.
NOTE:
This document describes features to be found in Alfresco v2.1. (Newer versions: v3)
Introduction
Although web scripts are accessible via HTTP, their URL addressability means they can actually be hosted in a number of different environments (and therefore accessed via a protocol appropriate to the environment).
The web script architecture clearly separates the notion of a web script (that is, a unit of work) and its environment (that is, the host within which the unit of work is executed), which is known as a Web Script Runtime.
New runtimes may be plugged-in allowing web scripts to be re-used and re-hosted in a number of different applications.
Available Web Script Runtimes
Today, the following Web Script Runtimes are available:
Servlet Runtime (HTTP Access)
The Servlet Runtime maps HTTP requests to web scripts.
It's configured just as any other servlet in web.xml:
<servlet>
<servlet-name>WebScriptServlet</servlet-name>
<servlet-class>org.alfresco.web.scripts.WebScriptServlet</servlet-class>
<init-param>
<param-name>authenticator</param-name>
<param-value>webscripts.authenticator.basic</param-value>
</init-param>
</servlet>
The following initialization parameters are supported:
- authenticator : the web script Authenticator as specified by its unique id
Multiple web script servlets may be configured, allowing multiple url mappings where each mapping may use a different authenticator.
<servlet-mapping>
<servlet-name>WebScriptServlet</servlet-name>
<url-pattern>/service/*</url-pattern>
</servlet-mapping>
Pre-defined web script URL mappings
- /alfresco/service or /alfresco/s : mapped to HTTP Basic Authenticator
- /alfresco/wcservice or /alfresco/wcs : mapped to Web Client Authenticator
- /alfresco/168service or /alfresco/168s : mapped to JSR-68 Authenticator
JSR-168 Runtime (Portlet Access)
The JSR-168 Runtime maps a portlet to a web script.
A JSR-168 proxy portlet class is provided which may be configured as follows:
<portlet>
<description>A Portlet</description>
<portlet-name>Portlet Name</portlet-name>
<portlet-class>org.alfresco.web.scripts.portlet.WebScriptPortlet</portlet-class>
<init-param>
<param-name>authenticator</param-name>
<param-value>webscripts.authenticator.jsr168.webclient</param-value>
</init-param>
<init-param>
<name>scriptUrl</name>
<value>/alfresco/service/portlet/aportlet</value>
</init-param>
<supports>
<mime-type>text/html</mime-type>
<portlet-mode>VIEW</portlet-mode>
<portlet-info>
<title>Portlet Title</title>
<short-title>Portlet Short Title</short-title>
</portlet-info>
</portlet>
Note: For versions beyond 3.3 the WebScriptPortlet class has been moved to Spring. Instead use:
<portlet-class>org.springframework.extensions.webscripts.portlet.WebScriptPortlet</portlet-class>
The following initialization parameters are supported:
- authenticator (optional) : the web script Authenticator as specified by its unique id. If not specified, the default JSR-168 authenticator (webscripts.authenticator.jsr168) is used.
- scriptUrl : the url to the web script
JSF Runtime (JSF Component Access)
The JSF Runtime maps a JSF component to a web script.
It's configured as follows within a JSP:
<web script url>' />
The following parameters are available:
- scriptUrl : the url of the web script
Authentication is handled by the Alfresco Web Client.
Developing a Web Script Runtime
A Web Script Runtime is implemented by deriving a Java class from:
org.alfresco.web.scripts.WebScriptRuntime
This is an abstract class requiring the following methods to be implemented:
/**
* Get the web script method e.g. get, post
*
* @return web script method
*/
protected abstract String getScriptMethod();
/**
* Get the web script Url
*
* @return web script url
*/
protected abstract String getScriptUrl();
/**
* Create a web script request
*
* @param match web script matching the script method and url
* @return web script request
*/
protected abstract WebScriptRequest createRequest(WebScriptMatch match);
/**
* Create a web script response
*
* @return web script response
*/
protected abstract WebScriptResponse createResponse();
/**
* Authenticate web script execution
*
* @param required required level of authentication
* @param isGuest is the request accessed as Guest
*
* @return true if authorised, false otherwise
*/
protected abstract boolean authenticate(RequiredAuthentication required, boolean isGuest);
Implementations of:
org.alfresco.web.scripts.WebScriptRequest
org.alfresco.web.scripts.WebScriptResponse
are also required as they are instantiated by createRequest and createResponse respectively. The helper class:
org.alfresco.web.scripts.WebScriptURLRequest
provides a skeleton implementation of WebScriptRequest given a URL string.
Executing a web script
The following pattern is used to execute a web script via a Web Script Runtime:
WebScriptRuntime runtime = new CustomWebScriptRuntime(...);
runtime.executeScript();
Runtime context is passed in via the constructor, for example, for a servlet, the HttpServletRequest and HttpServletResponse.
A new Web Script Runtime must be instantiated for each invocation (where the context changes), for example, for each servlet request.
Future Runtimes
- JSP Runtime : allow access via JSP - converts any web script into a JSP Tag
