Web Script Runtimes

From AlfrescoWiki

Jump to: navigation, search

Back to HTTP API.


NOTE:
This document describes features to be found in Alfresco v2.1 onwards.


Contents

[edit] 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 (i.e. a unit of work) and its environment (i.e. the host within which the unit of work is executed) known as a Web Script Runtime.

New runtimes may be plugged-in allowing Web Scripts to be re-used & re-hosted in a number of different applications.

[edit] Available Web Script Runtimes

Today, the following Web Script Runtimes are available:

[edit] 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>

[edit] 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

[edit] 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>
  </supports

  <portlet-info>
    <title>Portlet Title</title>
    <short-title>Portlet Short Title</short-title</short-title>
  </portlet-info>
</portlet>

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

[edit] JSF Runtime (JSF Component Access)

The JSF Runtime maps a JSF component to a Web Script.

It's configured as follows within a JSP: 

<%@ taglib uri="/WEB-INF/repo.tld" prefix="r" %>

...

<r:webScript scriptUrl="/wcservice/<web script url>" />

The following parameters are available:

scriptUrl 
the url of the Web Script

Authentication is handled by the Alfresco Web Client.

[edit] 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.

[edit] 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 e.g. for a servlet, the HttpServletRequest and HttpServletResponse.

A new Web Script Runtime must be instantiated for each invocation (where the context changes) e.g. for each servlet request.

[edit] Future Runtimes

JSP Runtime 
allow access via JSP - converts any Web Script into a JSP Tag
Retrieved from "http://wiki.alfresco.com/wiki/Web_Script_Runtimes"