View Javadoc

1   package org.tinyjee.maven.dim.spi;
2   
3   import org.apache.velocity.app.VelocityEngine;
4   import org.apache.velocity.context.Context;
5   import org.apache.velocity.tools.config.EasyFactoryConfiguration;
6   import org.tinyjee.maven.dim.spi.backport.ServiceLoader;
7   
8   import java.util.Map;
9   
10  /**
11   * {@link VelocityConfigurator} defines an interface that may be implemented and registered via service loading
12   * to customize the configuration of the velocity template engine and context before the templates are rendered.
13   * <p/>
14   * <b>Implementation</b>:<code><pre>
15   * package my.package;
16   * public class MyVelocityConfigurator implements VelocityConfigurator {
17   *      public void configureEngine(VelocityEngine engine) {
18   *          engine.setProperty(VM_PERM_INLINE_LOCAL, true);
19   *          ...
20   *      }
21   *      ...
22   * }
23   * </pre></code>
24   * <p/>
25   * <b>Register the implementation using service loading</b>:<ul>
26   * <li>
27   * Create the following file:<code><pre>
28   * META-INF/services/
29   *    org.tinyjee.maven.dim.spi.VelocityConfigurator
30   * </pre></code></li>
31   * <li>Add the fully qualified class name of your implementation to the file "org.tinyjee.maven.dim.spi.VelocityConfigurator":<code><pre>
32   * my.package.MyVelocityConfigurator
33   * </pre></code></li>
34   * </ul>
35   *
36   * @version 1.1
37   * @since 1.1
38   * @author Juergen_Kellerer, 2011-10-14
39   */
40  public interface VelocityConfigurator {
41  
42  	/**
43  	 * Is an iterable over all configurators within the classpath.
44  	 */
45  	Iterable<VelocityConfigurator> CONFIGURATORS = ServiceLoader.load(VelocityConfigurator.class);
46  
47  	/**
48  	 * Is called after applying default settings but before the engine is initialized.
49  	 *
50  	 * @param engine an uninitialized engine that may be configured.
51  	 */
52  	void configureEngine(VelocityEngine engine);
53  
54  	/**
55  	 * Is called when configuring velocity tools using {@link EasyFactoryConfiguration}.
56  	 *
57  	 * @param toolsConfiguration the instance to use for configuring tools.
58  	 */
59  	void configureTools(EasyFactoryConfiguration toolsConfiguration);
60  
61  	/**
62  	 * Is called right before a template is executed.
63  	 *
64  	 * @param requestParameters the macro request parameters as they would also be seen by the template.
65  	 * @param templateContext   the pre-configured template context.
66  	 */
67  	void configureContext(Map<String, Object> requestParameters, Context templateContext);
68  }