Web Script Runtimes

Document created by resplin Employee on Jun 6, 2015
Version 1Show Document
  • View in full screen mode

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

Attachments

    Outcomes