org.apache.turbine.services

## Class BaseServiceBroker

- java.lang.Object
- - org.apache.turbine.services.BaseServiceBroker

- All Implemented Interfaces:
    ServiceBroker
  Direct Known Subclasses:
    TurbineServices

      public abstract class BaseServiceBroker
      extends Object
      implements ServiceBroker

  A generic implementation of a `ServiceBroker` which provides:
  - Maintaining service name to class name mapping, allowing pluggable service implementations.
  - Providing `Services` with a configuration based on system wide configuration mechanism.
- Integration of TurbineServiceProviders for looking up non-local services

Version:
  $Id: BaseServiceBroker.java 1706239 2015-10-01 13:18:35Z tv $
Author:
  Kevin Burton, Rafal Krzewski, Daniel Rall, Jason van Zyl, Martin Poeschl, Henning P. Schmiedehausen

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `CLASSNAME_SUFFIX` A `Service` property determining its implementing class name .
    `static String` | `SERVICE_PREFIX` A prefix for `Service` properties in TurbineResource.properties.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `BaseServiceBroker()` Default constructor, protected as to only be usable by subclasses.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `String` | `getApplicationRoot()` Get the application root as set by the parent application.
    `org.apache.commons.configuration.Configuration` | `getConfiguration()` Get the configuration for this service manager.
    `org.apache.commons.configuration.Configuration` | `getConfiguration(String name)` Returns the configuration for the specified service.
    `protected Object` | `getNonLocalService(String name)` Get a non-local service managed by a TurbineServiceProvider.
    `Object` | `getService(String name)` Returns an instance of requested Service.
    `protected Service` | `getServiceInstance(String name)` Retrieves an instance of a Service without triggering late initialization.
    `Iterator<String>` | `getServiceNames()` Returns an Iterator over all known service names.
    `Iterator<String>` | `getServiceNames(String prefix)` Returns an Iterator over all known service names beginning with the provided prefix.
    `Object` | `getServiceObject(String name)` Get an application specific service object.
    `void` | `init()` Initialize this service manager.
    `protected void` | `initMapping()` Creates a mapping between Service names and class names.
    `void` | `initService(String name)` Performs early initialization of specified service.
    `void` | `initServices()` Performs early initialization of all services.
    `void` | `initServices(boolean report)` Performs early initialization of all services.
    `protected boolean` | `isLocalService(String name)` Determines if the requested service is managed by this ServiceBroker.
    `protected boolean` | `isNonLocalService(String name)` Determines if the requested service is managed by an initialized TurbineServiceProvider.
    `boolean` | `isRegistered(String serviceName)` Determines whether a service is registered in the configured `TurbineResources.properties`.
    `void` | `setApplicationRoot(String applicationRoot)` Set the application root.
    `void` | `setConfiguration(org.apache.commons.configuration.Configuration configuration)` Set the configuration object for the services broker.
    `void` | `setServiceObject(String name, Object value)` Set an application specific service object that can be used by application specific services.
    `void` | `shutdownService(String name)` Shuts down a `Service`, releasing resources allocated by an `Service`, and returns it to its initial (uninitialized) state.
    `void` | `shutdownServices()` Shuts down all Turbine services, releasing allocated resources and returning them to their initial (uninitialized) state.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### SERVICE_PREFIX

          public static final String SERVICE_PREFIX

      A prefix for `Service` properties in TurbineResource.properties.
      See Also:
        Constant Field Values

    - #### CLASSNAME_SUFFIX

          public static final String CLASSNAME_SUFFIX

      A `Service` property determining its implementing class name .
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### BaseServiceBroker

          protected BaseServiceBroker()

      Default constructor, protected as to only be usable by subclasses. This constructor does nothing.

  - ### Method Detail

    - #### setConfiguration

          public void setConfiguration(org.apache.commons.configuration.Configuration configuration)

      Set the configuration object for the services broker. This is the configuration that contains information about all services in the care of this service manager.
      Parameters:
        `configuration` - Broker configuration.

    - #### getConfiguration

          public org.apache.commons.configuration.Configuration getConfiguration()

      Get the configuration for this service manager.
      Returns:
        Broker configuration.

    - #### init

          public void init()
                    throws InitializationException

      Initialize this service manager.
      Throws:
        `InitializationException` - if the initialization fails

    - #### setServiceObject

          public void setServiceObject(String name,
                              Object value)

      Set an application specific service object that can be used by application specific services.
      Parameters:
        `name` - name of service object
        `value` - value of service object

    - #### getServiceObject

          public Object getServiceObject(String name)

      Get an application specific service object.
      Parameters:
        `name` - the name of the service object
      Returns:
        Object application specific service object

    - #### initMapping

          protected void initMapping()
                              throws InitializationException

      Creates a mapping between Service names and class names. The mapping is built according to settings present in TurbineResources.properties. The entries should have the following form:

           services.MyService.classname=com.mycompany.MyServiceImpl
           services.MyOtherService.classname=com.mycompany.MyOtherServiceImpl

      Generic ServiceBroker provides no Services.
      Throws:
        `InitializationException` - if a service class could not be found

    - #### isRegistered

          public boolean isRegistered(String serviceName)

      Determines whether a service is registered in the configured `TurbineResources.properties`.
      Specified by:
        `isRegistered` in interface `ServiceBroker`
      Parameters:
        `serviceName` - The name of the service whose existence to check.
      Returns:
        Registration predicate for the desired services.

    - #### getServiceNames

          public Iterator<String> getServiceNames()

      Returns an Iterator over all known service names.
      Returns:
        An Iterator of service names.

    - #### getServiceNames

          public Iterator<String> getServiceNames(String prefix)

      Returns an Iterator over all known service names beginning with the provided prefix.
      Parameters:
        `prefix` - The prefix against which to test.
      Returns:
        An Iterator of service names which match the prefix.

    - #### initService

          public void initService(String name)
                           throws InitializationException

      Performs early initialization of specified service.
      Specified by:
        `initService` in interface `ServiceBroker`
      Parameters:
        `name` - The name of the service (generally the `SERVICE_NAME` constant of the service's interface definition).
      Throws:
        `InitializationException` - Initialization of this service was not successful.

    - #### initServices

          public void initServices()

      Performs early initialization of all services. Failed early initialization of a Service may be non-fatal to the system, thus any exceptions are logged and the initialization process continues.

    - #### initServices

          public void initServices(boolean report)
                            throws InstantiationException,
                                   InitializationException

      Performs early initialization of all services. You can decide to handle failed initializations if you wish, but then after one service fails, the other will not have the chance to initialize.
      Parameters:
        `report` - `true` if you want exceptions thrown.
      Throws:
        `InstantiationException` - if the service could not be instantiated
        `InitializationException` - if the service could not be initialized

    - #### shutdownService

          public void shutdownService(String name)

      Shuts down a `Service`, releasing resources allocated by an `Service`, and returns it to its initial (uninitialized) state.
      Specified by:
        `shutdownService` in interface `ServiceBroker`
      Parameters:
        `name` - The name of the `Service` to be uninitialized.

    - #### shutdownServices

          public void shutdownServices()

      Shuts down all Turbine services, releasing allocated resources and returning them to their initial (uninitialized) state.
      Specified by:
        `shutdownServices` in interface `ServiceBroker`

    - #### getService

          public Object getService(String name)
                            throws InstantiationException

      Returns an instance of requested Service.
      Specified by:
        `getService` in interface `ServiceBroker`
      Parameters:
        `name` - The name of the Service requested.
      Returns:
        An instance of requested Service.
      Throws:
        `InstantiationException` - if the service is unknown or can't be initialized.

    - #### getServiceInstance

          protected Service getServiceInstance(String name)
                                        throws InstantiationException

      Retrieves an instance of a Service without triggering late initialization. Early initialization of a Service can require access to Service properties. The Service must have its name and serviceBroker set by then. Therefore, before calling Initable.initClass(Object), the class must be instantiated with InitableBroker.getInitableInstance(), and Service.setServiceBroker() and Service.setName() must be called. This calls for two - level accessing the Services instances.
      Parameters:
        `name` - The name of the service requested.
      Throws:
        `InstantiationException` - The service is unknown or can't be initialized.

    - #### getConfiguration

          public org.apache.commons.configuration.Configuration getConfiguration(String name)

      Returns the configuration for the specified service.
      Specified by:
        `getConfiguration` in interface `ServiceBroker`
      Parameters:
        `name` - The name of the service.
      Returns:
        Configuration of requested Service.

    - #### setApplicationRoot

          public void setApplicationRoot(String applicationRoot)

      Set the application root.
      Parameters:
        `applicationRoot` - application root

    - #### getApplicationRoot

          public String getApplicationRoot()

      Get the application root as set by the parent application.
      Returns:
        String application root

    - #### isLocalService

          protected boolean isLocalService(String name)

      Determines if the requested service is managed by this ServiceBroker.
      Parameters:
        `name` - The name of the Service requested.
      Returns:
        true if the service is managed by the this ServiceBroker

    - #### isNonLocalService

          protected boolean isNonLocalService(String name)

      Determines if the requested service is managed by an initialized TurbineServiceProvider. We use the service names to lookup the TurbineServiceProvider to ensure that we get a fully inititialized service.
      Parameters:
        `name` - The name of the Service requested.
      Returns:
        true if the service is managed by a TurbineServiceProvider

    - #### getNonLocalService

          protected Object getNonLocalService(String name)
                                       throws InstantiationException

      Get a non-local service managed by a TurbineServiceProvider.
      Parameters:
        `name` - The name of the Service requested.
      Returns:
        the requested service
      Throws:
        `InstantiationException` - the service couldn't be instantiated

Copyright © 2000-2015 The Apache Software Foundation. All Rights Reserved.