Extensibility Module Deployment

[ddraper]

Introduction

Having covered the basics of the new extensibility features that are currently available in the latest Alfresco Community source and will be available in Alfresco Enterprise 4.0 this module will focus in greater detail on module structure and their deployment.

Background

If you've been working through the previous tutorials you might have noticed that when deploying your modules (via http://localhost:8080/share/page/modules/deploy - if you're using the defaults) some additional options are displayed to the right of the screen when clicking on a module. This is the module deployment configuration and it provides the opportunity to override the default configuration of an extension.

Even if a Module is deployed the function it provides may not be applicable to every request. Therefore a Module can be configured to use an 'evaluator' that determines whether or not it should be used which is invoked on each request.

A deployed module will always be evaluated on every request.  A developer can optionally provide default Evaluator configuration but if it is omitted then Spring Surf will automatically apply the default application Evaluator (as defined in the Spring application context). By default Spring Surf defines a default application Evaluator that always results in the module being applied to each request. When you deploy any module you have the option of keeping the default Evaluator (which will either be the application default or will be have been explicitly defined in the configuration) or selecting your own.

Module Evaluators are just Spring beans like Sub-Component Evaluators and technically a single bean can be both a Module and Sub-Component Evaluator providing it implements both the 'org.springframework.extensions.surf.extensibility.ExtensionModuleEvaluator' and 'org.springframework.extensions.surf.extensibility.SubComponentEvaluator' interfaces.  However, a Module Evaluator takes precedence over a Sub-Component Evaluator in the sense that it will be evaluated first, and if the evaluation fails then the Sub-Components in the module will not even get the opportunity to be evaluated. Essentially though they are intended to perform the same function, i.e. compare data in the current request with against a set of configured parameters to see if the request meets the evaluation criteria.

The default Module Evaluator is configured in the Spring application context with the id 'default.extensibility.evaluator' that maps to the Class 'org.springframework.extensions.surf.extensibility.impl.ApproveAllModulesEvaluator' which (as its name suggests) will always evaluate to true. Another Evaluator available 'out of the box' has the bean id 'config.approval.evaluator'.  If you select this as the Evaluator when deploying a Module you will see that it asks for a single property with the key 'apply' which determines whether or not the Module gets applied (e.g. if you set the value as 'true' then the Module will always be applied, if you set it to anything else then the Module will never be applied).

Tutorial

Try this out with one of the previously created modules. It is not necessary to restart the server - simply browse to the module deployment WebScript UI, select the 'config.approval.evaluator' and set the 'apply' property to 'false' and when you refresh the previously affected Alfresco Share page you will see that the module is no longer be applied (NOTE: You must click the 'update' button to apply the change to the  module and then click the 'Apply Changes' button to persist your  changes).

To achieve the same objective through configuration update the module configuration to contain the following (NOTE: only a fragment of the module config is shown - see the earlier blogs for the complete configuration):

<module>
    <id>Blog Module (New Content)</id>
    <evaluator type='config.approval.evaluator'>
        <params>
            <apply>false</apply>
        </params>
    </evaluator>

There are only a limited number of 'out-of-the-box' Evaluators available so it is likely that you may want to create your own. This process is very similar to creating a Sub-Component evaluator. First create the following Java class:

package blog.demo;
import java.util.Map;
import org.springframework.extensions.surf.RequestContext;
import org.springframework.extensions.surf.extensibility.ExtensionModuleEvaluator;
public class BlogModuleEvaluator implements ExtensionModuleEvaluator
{
    public static final String USER_PROP = 'user';
    public boolean applyModule(RequestContext context, Map<String, String> evaluationProperties)
    {
        String currUser = context.getUser().getId();
        String targetUser = evaluationProperties.get(USER_PROP);
        return (targetUser != null && targetUser.equals(currUser));
    }
    public String[] getRequiredProperties()
    {
        return new String[] { USER_PROP};
    }
}

Add the following line to your 'spring-surf-extensibility-context.xml' file:

<bean id='blog.module.evaluator' class='blog.demo.BlogModuleEvaluator'/>

Re-build and deploy your extension JAR and when you refresh the module deployment page after re-starting the web server you should be able to select your new module. Notice that the String array returned from the 'getRequiredProperties' method is used by the UI to provide a default set of properties to supply. These properties are currently not automatically validated in anyway so it's up to the Evaluator developer to check that all the data they require has been provided.

The custom Module Evaluator we've created will only apply the module for the user specified in the deployment configuration, so if you set the 'user' property to be 'admin' and then log onto Alfresco Share as 'admin' you will not see the title bar on the User Dashboard page (see example screenshots).