Package org.apache.turbine.services

Contains the Service framework for Turbine.

See:
Description

Interface Summary

Initable	Classes that implement this interface need initialization before they can work.
InitableBroker	Classes that implement this interface can act as a broker for Initable classes.
Service	Services are Initables that have a name, and a set of properties.
ServiceBroker	Classes that implement this interface can act as a broker for Service classes.
ServiceManager	Classes that implement this interface can act as a manager for Service classes.

Class Summary

BaseInitable	This class provides a generic implementation of Initable.
BaseInitableBroker	A generic implementation of InitableBroker.
BaseService	This class is a generic implementation of Service.
BaseServiceBroker	A generic implementation of a ServiceBroker which provides: Maintaining service name to class name mapping, allowing plugable service implementations. Providing Services with a configuration based on system wide configuration mechanism.
BaseUnicastRemoteService	A base implementation of an UnicastRemoteObject as a Turbine Service.
TurbineBaseService	This class provides a Service implementation that Services used in Turbine are required to extend.
TurbineServices	This is a singleton utility class that acts as a Services broker.

Exception Summary

InitializationException	Thrown by Initable class in case of initialization problems.
InstantiationException	Thrown by InitableBroker and ServiceBroker classes to indicate problems with instatiation of requested objects.

Package org.apache.turbine.services Description

Contains the Service framework for Turbine.

Services are singletons that have pluggable implementation and can participate in Turbine startup and shutdown.

What is a service?

• Is a singleton - there is only one instance of it in the system i.e. memory or connections are allocated once only, and the internal state is common to all requesting clients.
• Has pluggable implementation - you can use your own implementation if you need, just change an entry in TurbineResources.properties, and there you go.
• Can access ServletConfig at system startup time to process relative paths and the like.
• Can access RunData on the first Turbine doGet execution to get URL we're running under and the like.
• Can initialize itself (allocate memory, make connctions) just before the client requests it for the first time. Services that are never used by the application will not allocate resources.
• Can execute some action upon system shutdown e.g. close the opened connections.

The life cycle of a Service

A Service (or any other Initable, if we had any) is not supposed to do much in it's constructor. Especialy it should not allocate any costly resources like large memory structures, DB or network connections and the like. It may well happen that the Service is sitting in the config file, but the application does not need it, so allocating all resources at system startup might be a loss.

Early initialization is similar to the constructor. It is used to pass some information that the Service will need in it's future operation. UniqueId Service uses the HttpRequest object from the first Turbine invocation to determine URL this instance is runnign under, to generate instance ID. Early initialization method should process the configuration, store some values, but NOT allocate resources. There is still a chance that the Service will not be used. If the Service is ready to work (i.e. does not need any more objects being sent to it), and does not to allocate any resources during late initialization, the internal state can be changed so that getInit() returns true.

Late initialization happens when the Service is requested by the application for the first time. It should allocate any resources needed and chnge the state so that getInit() returns true. If getInit() returns false after init() is executed, the Service has malfunctioned.

After late initialization, the Service is ready to perform actions on behalf of the application.

When the Service is no longer needed (this usually happens when system is shutting down), the shutdown() method is called. shutdown() should deallocate all resources. If any error conditions occur they are ignored.

Initialization of services outside of the Turbine servlet

In the case where specific Turbine services are desired outside the context of the Turbine servlet, a Turbine JAR file can be used in conjunction with a properly configured TurbineResources.properties file to initialize a specific set of services to use in your application. The following sample code performs such initialization:

String webAppRoot = "/var/httpd/webapps";
String trProps = "/var/httpd/TurbineResources.properties";
try
{
    TurbineConfig cfg = new TurbineConfig(webAppRoot, trProps);
    cfg.init();
}
catch (Exception e)
{
    // If Turine fails to initialize, no logging service will be available.
    String msg = "Failed to initialize Turbine: " + e.getMessage();
    // Write directly to stderr to preserve the full stack trace.
    System.err.println(msg);
    e.printStackTrace();
    throw new Error(msg);
}

$Id: package.html 264148 2005-08-29 14:21:04Z henning $