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

## Introduction

This document describes the basic steps needed to migrate an application written for Turbine 2.3 to Turbine 4.0.

Migrating from Turbine 2.3 to Turbine 4.0 is mostly a task of moving from the old service format to the new one. One of the biggest purposes with Turbine 4 was to decouple the different services and move them to Fulcrum. Many of the released components of Fulcrum correspond to a previous Turbine service that is no longer bundled with the Turbine core.

The services has been converted to Avalon components and do not implement the Service interface any more. Turbine still handles services that do implement the Service interface though so no rewrite is necessary if you have written services of your own. The new services can also be accessed in pretty much the same way as the old ones, as long as the AvalonComponentService is properly configured.

## Accessing the new services

What needs to be done to access the decoupled services can be summarised in 4 steps:

- Make sure the AvalonComponentService is properly configured
- Add the services you need to your project dependency and to roleConfiguration.xml
- Access the Fulcrum services with class name instead of service name
- Remove any reference to the static facade classes and access the interfaces directly

### Make sure the AvalonComponentService is properly configured

The AvalonComponentService allows you to retrieve the new services via the old TurbineServices interface. Make sure that the AvalonComponentService is added in your TurbineResources.properties and that you use TurbineYaafiComponentService as the implementing class.

    services.AvalonComponentService.classname=org.apache.turbine.services.avaloncomponent.TurbineYaafiComponentService
    services.AvalonComponentService.earlyInit=true

The service must be the first service in TurbineResources.properties and it must be initialized early. Also make sure that Fulcrum YAAFI is added to your project dependency.

### Add the services you need to your project dependency and to roleConfiguration.xml

Many services that were previously included in Turbine has been converted to Avalon components and moved to Fulcrum. You only need to add the ones used in your project as a dependency. Each service has its own documentation and it is described on their project page how you can configure them, but common for all is that they need to be added to your roleConfiguration.xml file. Adding a service to roleConfiguration.xml is equivalent to adding a Turbine service to TurbineResources.properties.

### Access the Fulcrum services with class name instead of service name

As you may have noticed in the documentation for the Fulcrum components, the name for the different services is the full class name. Therefore the input parameter in the getService method of TurbineServices needs to be the full class name of the service. Usually this is stored in a static field called ROLE. Ex:

    ParseService parserService = (ParserService)TurbineServices.getInstance().getService(ParserService.ROLE);

### Remove any reference to the static facade classes and access the interfaces directly

The new services do not have a static facade class like the old ones (org.apache.turbine.services.localization.Localization for LocalizationService, org.apache.turbine.services.cache.TurbineGlobalCache for GlobalCacheService etc). If you have used these facade classes, you now need to access the service directly via the interface instead. How to access the classes is described in the previous section.