##### General Information

- Overview
- Features
- Specification
- Getting Started
- Howto Build Turbine
- Changes

##### Documentation

- Services
- Howtos
  - Action Events Howto
  - Annotations Howto
  - Configuration Howto
  - Extend User Howto
  - Hibernate OM Howto
  - Intake Howto
  - JSP Howto
  - Migrating from 2.1 to 2.2
  - Migrating from 2.2 to 2.3
  - Migrating from 2.3 to 4.0
  - Pull Model Howto
  - Python Howto
  - Security Howto
  - Services Howto
  - URL rewriting Howto
  - Velocity Context Howto
  - Velocity Site Howto
  - VelocityOnlyLayout Howto
- Wiki
- JavaDocs

##### Development

- Proposals
- How To Help
- Todo

##### Project Documentation

- Project Information
- Project Reports

##### Apache

- Apache Website
- License
- How the ASF works
- Sponsorship
- Thanks
- Security

## 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.

### 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`.