How to write an engine lifecycle extension

See also:

An engine lifecycle extension is another JSPWiki extension point, that allows custom components be aware of Engine's initialization and shutdown, without having to deep dive on Engine's internals.

Examples of EngineLifecycleExtension's use cases:

  • Appending a plugin's classpath to jspwiki.plugin.searchPath, so it can be used as a drop-in, without further configuration.
  • Providing default parameters for a custom extension.
  • Setting up that expensive singleton, or disposing resources, without having to use or register a WikiEventListener.

As such, Engine lifecycle extensions are usually bundled with another custom component (plugin, filter, etc.). If it is needed to bundle the extension on a separate jar, see the starting point for developing custom components to create a maven project holding the extension.

As a concrete example, the markdown module uses an EngineLifecycleExtension to set up all the required properties if jspwiki.syntax=markdown is provided on the jspwiki[-custom].properties file.

warning Engine lifecycle extensions' execution order isn't guaranteed, so they should not rely on it, nor try to overwrite other components configuration. Their scope should circunscribe to themselves or to the custom component they are bundled with.

Code#

Engine Lifecycle Extensions are implemented as SPIs.

Coding an engine lifecycle extension is pretty straightforward, just needs two things:

  • An EngineLifecycleExtension class that implements the org.apache.wiki.api.engine.EngineLifecycleExtension interface. All methods on that interface are provided with a default, do-nothing implementation, so specific EngineLifecycleExtensions only have to provide implementations for the methods they're really interested in:
    • void onInit( final Properties properties ): Called before Engine initialization, after the wiki properties have been sought out.
    • void onStart( final Engine e, final Properties properties ): Called after Engine initialization.
    • void onShutdown( final Engine e, final Properties properties ): Called before Engine shutdown.
  • A META-INF/services/org.apache.wiki.api.engine.EngineLifecycleExtension file which contains the fully qualified class name of the EngineLifecycleExtension implementation.

and that's it!

Unit testing#

See JSPWikiPublicAPI#Testing

Package #

Deploy#

As engine lifecycle extensions are coded as SPIs, JSPWiki is automatically aware about the engine lifecycles extensions present, so there is no need of any further configuration.

Category.Documentation