Apache Turbine – Annotations Howto

Annotations

Turbine provides a number of annotations to inject dependencies into your actions, screens and layouts. All Assemblers that is, all modules of type Action, Screen, Layout, Page, Navigation and ScheduledJob as well as all Valves in the pipeline support the injection of services, configurations and loaders. This relieves you from the burden of looking them up at runtime and thus simplifies and accelerates the code.

@TurbineService

The annotation can only be used with a field. A declared field in a class annotated with @TurbineService gets injected an instance of this service at the time the instance of the class is created. The field should have the type of the service interface like in the following two examples:

// Explicit service name
@TurbineService( "RunDataService" )
private RunDataService runDataService;

// Implicit SERVICE_NAME or ROLE
@TurbineService
private FactoryService factory;

This is the equivalent of

runDataService = (RunDataService) TurbineServices
    .getInstance().getService("RunDataService");

factory = (FactoryService) TurbineServices
    .getInstance().getService(FactoryService.ROLE);

As you an see, the annotation supports an optional parameter, the name of the service in the Turbine service repository. If this parameter is not present, the annotation processor will look for the field SERVICE_NAME and then ROLE in the type class of the field to retrieve the service name. If none of them can be found, the fully qualified class name of the service interface is used to look up the service.
If the service instance cannot be found, the annotation processor will throw an exception.

@TurbineConfiguration

The annotation can only be used with a field. If a declared field of the type Configuration is annotated with @TurbineConfiguration, Turbine will inject an instance of the Turbine configuration object at the time the instance of the class is created.

// Injected configuration instance
@TurbineConfiguration
private Configuration config;

// Injected configuration subset instance
@TurbineConfiguration( "action" )
private Configuration actionConfig;

This is the equivalent of

config = Turbine.getConfiguration();

actionConfig = Turbine.getConfiguration().subset("action");

The annotation supports an optional parameter, the prefix of the configuration subset to retrieve.
If other fields having simple types are annotated with @TurbineConfiguration, Turbine will inject the corresponding configuration value. In this case, the annotation parameter defines the configuration key and is required. Strings, Lists and most simple types are supported. The value will only be set if the key is found in the configuration, so that the field can be initialized with a default value.

// Injected configuration value
@TurbineConfiguration( "module.cache" )
private boolean moduleCache = true;

@TurbineConfiguration( "template.homepage" )
private String templateHomepage;

This is the equivalent of

moduleCache = Turbine.getConfiguration().getBoolean("module.cache", true);
templateHomepage = Turbine.getConfiguration().getString("template.homepage");

@TurbineLoader

The annotation can only be used with a field. A declared field in a class annotated with @TurbineLoader gets injected an instance of the specified Loader at the time the instance of the class is created. The field should have the type of the loader.

// Injected loader instance
@TurbineLoader( Action.class )
private ActionLoader actionLoader;

This is the equivalent of

actionLoader = TurbineAssemblerBroker.getLoader(Action.class);

The annotation parameter is required and defines the type of module that is to be loaded.

@TurbineActionEvent

The annotation can only be used with a method. A method in a class annotated with @TurbineActionEvent is associated to a named action event. The annotation parameter is required and defines the name of the event. See the Action Events Howto for usage and examples.

@TurbineTool

The annotation can only be used with a field. A declared field in a class annotated with @TurbineTool gets injected an instance of the specified ApplicationTool at the time the instance of the class is created. The field should have the type of the tool.

// Injected loader instance
@TurbineTool( TemplateLink.class )
private TemplateLink templateLink;

Normally a tool needs an context (request, global, user). You have to set the context by calling the tool.init(Object object) method. E.g. in action methods you have access to request and session context objects. The annotation parameter is required and defines the type of the tool.

Performance Considerations

It is important to note that the processing of the annotations at the time the module class is instantiated takes some time. It is therefore strongly recommended to re-use the module instances in a production environment by setting the configuration parameter module.cache to true in TurbineResources.properties.