Web Script Runtimes

[resplin]

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)

Table of Contents

• 1 Introduction


• 2 Available Web Script Runtimes
  
  
  
  • 2.1 Servlet Runtime (HTTP Access)
    
    
    
    • 2.1.1 Pre-defined web script URL mappings
    
    
  
  
  • 2.2 JSR-168 Runtime (Portlet Access)
  
  
  • 2.3 JSF Runtime (JSF Component Access)
  
  


• 3 Developing a Web Script Runtime
  
  
  
  • 3.1 Executing a web script
  
  


• 4 Future Runtimes

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)
  
• JSR-168 Runtime (Portlet Access)
  
• JSF Runtime (JSF Component Access)
  

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