Turbine Services Creation

Adding your own services to Turbine is an easy task. Simply make your class extend org.apache.turbine.services.TurbineBaseService. This is necessary so that the Turbine Service Broker can start up your service.

To make it known to the Turbine itself, you must configure it in the TurbineResources.properties like this:

services.MyServiceName.classname = full.class.name.of.your.service

and you're set, Turbine will now initialize the service if it is requested by an application. Please be aware that your service is not initialized right at Startup. This is called lazy init. If you need your Service to start up right away, you must add another property to the TurbineResources.properties:

services.MyServiceName.earlyInit = true

If you look at the examples of the simple services like db/TurbinePoolBrokerService or servlet/TurbineServletService you'll get on speed pretty fast.

In a Nutshell

• You must not try to provide a constructor with parameters, best is not to provide any constructor at all, because nothing should be done at construction time (You'll get the default constructor which is fine for us).
• Your Service will be instantiated exactly once. So it must be threadsafe and must not use class global variables for session-dependent information.
• You should provide an init() method which is called when your service is requested for the first time (or at startup if you set earlyInit = true) and should initialize your service dependent code. There is lots of confusion of how this init() method should look like because Turbine used different methods of Service initialization. Beginning with Turbine 2.2, you should only use the parameterless variant:

public void init() throws InitializationException
{
}

• You must call setInit(true) if your service initializes correctly. Otherwise no user of your service can request it. Right after this, your service might be queried and used by other sessions, so you should not call setInit() prematurely.
• You might provide a shutdown() method which is called when Turbine shuts down. You can clean up your internal data in this method. You should call setInit(false) as the last thing in shutdown().

Style

It is good style, that if you build the FooService, to provide your.package.FooService.java with an Interface definition of your service which extends org.apache.turbine.services.Service It should contain a constant SERVICE_NAME with the Turbine visible name of your service like this:

package your.package;

import org.apache.turbine.services.Service;

public interface FooService extends Service
{
    /**
     * The service identifier
     */
    public String SERVICE_NAME = "FooService";

    [...]

}

your.package.TurbineFooService.java which extends the org.apache.turbine.services.TurbineBaseService class and implements your.package.FooService and provides the actual code:

package your.package;

import org.apache.turbine.services.TurbineBaseService;

public class TurbineFooService
    extends TurbineBaseService
    implements FooService
{
    /**
     * Service logic here
     */
    [...]

}

your.package.TurbineFoo.java which contains static facade methods for your service along the following lines:

import org.apache.turbine.services.TurbineServices;

public class TurbineFoo
{
    protected static FooService getService()
    {
        return (FooService) TurbineServices
            .getInstance().getService(FooService.SERVICE_NAME);
    }

    [...]

    public static void fooMethod1()
    {
        getService().fooMethod1();
    }

    public static int fooMethod2(int bar)
    {
        return getService().fooMethod2(bar);
    }

    [...]

}

to give users of your service the ability to simply write:

TurbineFoo.fooMethod1();

in their code and not to care about which actual Implementation of FooService is running.

init() and shutdown() applies to Turbine 2.1/2.2 This might change with the lifecycle interfaces in a later release.