org.apache.xbean.kernel.standard
Class StandardKernel

java.lang.Object
  org.apache.xbean.kernel.standard.StandardKernel

All Implemented Interfaces:

Kernel

public class StandardKernel
extends Object
implements Kernel

The standard kernel implementation.

Since:

2.0

Author:

Dain Sundstrom

Constructor Summary

StandardKernel(String kernelName)
Creates a kernel using the specified name.

StandardKernel(String kernelName, ExecutorService serviceExecutor, long timeoutDuration, TimeUnit timeoutUnits)
Creates a kernel using the specified name.

Method Summary

void	addKernelMonitor(KernelMonitor kernelMonitor) Adds a kernel monitor.
void	addServiceMonitor(ServiceMonitor serviceMonitor) Adds a service monitor for all services registered with the kernel.
void	addServiceMonitor(ServiceMonitor serviceMonitor, ServiceName serviceName) Adds a service monitor for a specific service.
void	destroy() Destroys this kernel.
ClassLoader	getClassLoaderFor(ServiceName serviceName) Gets the class loader associated with the specifed service.
String	getKernelName() Gets the unique name of this kernel within the KernelFactory.
Object	getService(Class type) Gets the first running service registered with the kernel that is an instance of the specified type.
Object	getService(ServiceName serviceName) Gets the service registered under the specified name.
List	getServiceFactories(Class type) Gets the all of the service factories registered with the kernel that create an instances of the specified type.
ServiceFactory	getServiceFactory(Class type) Gets the first service factory registered with the kernel that creates an instance of the specified type.
ServiceFactory	getServiceFactory(ServiceName serviceName) Gets the service factory registered under the specified name.
List	getServices(Class type) Gets the all of running service registered with the kernel that are an instances of the specified type.
long	getServiceStartTime(ServiceName serviceName) Gets the time the specified service entered the RUNNING state since the epoch (January 1, 1970, 00:00:00) in milliseconds.
ServiceState	getServiceState(ServiceName serviceName) Gets the ServiceState of the specified service.
boolean	isRegistered(ServiceName serviceName) Determines if there is a service registered under the specified name.
boolean	isRunning() Gets the running status of the kernel.
boolean	isServiceEnabled(ServiceName serviceName) Determines if the service can be instantiated in a kernel.
void	registerService(ServiceName serviceName, ServiceFactory serviceFactory) Registers a service with this kernel.
void	removeKernelMonitor(KernelMonitor kernelMonitor) Removes a kernel monitor.
void	removeServiceMonitor(ServiceMonitor serviceMonitor) Removes a service monitor.
void	setServiceEnabled(ServiceName serviceName, boolean enabled) Sets the enabled status of a service.
void	startService(ServiceName serviceName) Immediately starts the service using the SYNCHRONOUS start strategy.
void	startService(ServiceName serviceName, StartStrategy startStrategy) Immediately starts the service using the specified start strategy.
void	startServiceRecursive(ServiceName serviceName) Immediately starts the service, and if the start ultimately completes successfully, all services owned by the specified service, all services that are owned by those services, and so on, will be started using the startServiceRecursive(ServiceName) method.
void	startServiceRecursive(ServiceName serviceName, StartStrategy startStrategy) Immediately starts the service, and if the start ultimately completes successfully, all services owned by the specified service, all services that are owned by those services, and so on, will be started using the startServiceRecursive(ServiceName, StartStrategy) method.
void	stopService(ServiceName serviceName) Immediately stops the service using the SYNCHRONOUS stop strategy.
void	stopService(ServiceName serviceName, StopStrategy stopStrategy) Immediately stops the service using the specified stop strategy.
void	unregisterService(ServiceName serviceName) Unregisters a service from this kernel.
void	unregisterService(ServiceName serviceName, StopStrategy stopStrategy) Unregisters a service from this kernel.
void	waitForDestruction() Waits for the kernel to be destroyed.

Methods inherited from class java.lang.Object

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

Constructor Detail

StandardKernel

public StandardKernel(String kernelName)

Creates a kernel using the specified name.

Parameters:

kernelName - the unique name of this kernel

StandardKernel

public StandardKernel(String kernelName,
                      ExecutorService serviceExecutor,
                      long timeoutDuration,
                      TimeUnit timeoutUnits)

Creates a kernel using the specified name.

Parameters:

kernelName - the unique name of this kernel

serviceExecutor - the executor to use for asynchronous service operations

timeoutDuration - the maximum duration to wait for a service event to complete

timeoutUnits - the unit of measure for the timeoutDuration

Method Detail

destroy

public void destroy()
             throws KernelErrorsError

Destroys this kernel. This method causes all services to be stopped and unregistered.

Specified by:

destroy in interface Kernel

Throws:

KernelErrorsError

waitForDestruction

public void waitForDestruction()

Waits for the kernel to be destroyed.

Specified by:

waitForDestruction in interface Kernel

isRunning

public boolean isRunning()

Gets the running status of the kernel. Services can not be registered or started on a stopped kernel.

Specified by:

isRunning in interface Kernel

Returns:

true if the kernel is running; false otherwise

getKernelName

public String getKernelName()

Gets the unique name of this kernel within the KernelFactory.

Specified by:

getKernelName in interface Kernel

Returns:

the unique name of this kernel

registerService

public void registerService(ServiceName serviceName,
                            ServiceFactory serviceFactory)
                     throws ServiceAlreadyExistsException,
                            ServiceRegistrationException

Registers a service with this kernel. If the service is restartable, it will enter the server in the STOPPED state. If a service is not restartable, the kernel will assure that all dependencies are satisfied and service will enter the kernel in the RUNNING state. If a dependency for a non-restartable service is not immediately satisfiable, this method will throw a ServiceRegistrationException.

Specified by:

registerService in interface Kernel

Parameters:

serviceName - the unique name of the service in the kernel

serviceFactory - the factory used to create the service

Throws:

ServiceAlreadyExistsException - if service is already registered with the specified name

ServiceRegistrationException - if the service is not restartable and an error occured while starting the service

unregisterService

public void unregisterService(ServiceName serviceName)
                       throws ServiceNotFoundException,
                              ServiceRegistrationException

Unregisters a service from this kernel. The kernel will attempt to stop the service using the SYNCHRONOUS stop strategy, but if it can not stop the service a ServiceRegistrationException will be thrown containing an UnsatisfiedConditionsException.

Specified by:

unregisterService in interface Kernel

Parameters:

serviceName - the unique name of the service in the kernel

Throws:

ServiceNotFoundException - if there is no service registered under the specified name

ServiceRegistrationException - if the service could not be stopped

unregisterService

public void unregisterService(ServiceName serviceName,
                              StopStrategy stopStrategy)
                       throws ServiceNotFoundException,
                              ServiceRegistrationException

Unregisters a service from this kernel. The kernel will attempt to stop the service using the specified stop strategy, but if it can not stop the service a ServiceRegistrationException will be thrown containing either an UnsatisfiedConditionsException or a IllegalServiceStateException.

Specified by:

unregisterService in interface Kernel

Parameters:

serviceName - the unique name of the service in the kernel

stopStrategy - the strategy that determines how unsatisfied conditions are handled

Throws:

ServiceNotFoundException - if there is no service registered under the specified name

ServiceRegistrationException - if the service could not be stopped

isRegistered

public boolean isRegistered(ServiceName serviceName)

Determines if there is a service registered under the specified name.

Specified by:

isRegistered in interface Kernel

Parameters:

serviceName - the unique name of the service

Returns:

true if there is a service registered with the specified name; false otherwise

getServiceState

public ServiceState getServiceState(ServiceName serviceName)
                             throws ServiceNotFoundException

Gets the ServiceState of the specified service. If the service is not restartable, this method will always return RUNNING.

Specified by:

getServiceState in interface Kernel

Parameters:

serviceName - the unique name of the service in the kernel

Returns:

the curren ServiceState of the service

Throws:

ServiceNotFoundException - if there is no service registered under the specified name

getServiceStartTime

public long getServiceStartTime(ServiceName serviceName)
                         throws ServiceNotFoundException

Gets the time the specified service entered the RUNNING state since the epoch (January 1, 1970, 00:00:00) in milliseconds. If the service is in the STOPPED or STARTING states, this method will return 0.

Specified by:

getServiceStartTime in interface Kernel

Parameters:

serviceName - the unique name of the service in the kernel

Returns:

the time the service started in milliseconds since January 1, 1970, 00:00:00

Throws:

ServiceNotFoundException - if there is no service registered under the specified name

startService

public void startService(ServiceName serviceName)
                  throws ServiceNotFoundException,
                         IllegalServiceStateException,
                         UnsatisfiedConditionsException,
                         Exception

Immediately starts the service using the SYNCHRONOUS start strategy. Any exception throw from service constuction is throw directly from this method. If a start condition can not be immediately satisfied, a UnsatisfiedConditionsException will be thrown. If a service already in the RUNNING state, or is not restartable, this method is a noop. If the service is in the STOPPING state an IllegalServiceStateException will be thrown. If the service is disabled, this method will throw an IllegalServiceStateException.

This method has no effect on as service that is not restartable.

Specified by:

startService in interface Kernel

Parameters:

serviceName - the unique name of the service to start

Throws:

ServiceNotFoundException - if there is no service registered under the specified name

IllegalServiceStateException - if the service is restartable and is in the STOPPING state or if the service is disabled

UnsatisfiedConditionsException - if some of the start conditions can not be immediately satisfied

Exception - if service construction threw an Exception

startService

public void startService(ServiceName serviceName,
                         StartStrategy startStrategy)
                  throws ServiceNotFoundException,
                         IllegalServiceStateException,
                         UnsatisfiedConditionsException,
                         Exception

Immediately starts the service using the specified start strategy.

The start strategy determines how any exception thrown from service constuction is handled including throwing the exception directly from this method.

The start strategy determines what to do if a start condition can not be immediately satisfied. Possibilities include throwing an UnsatisfiedConditionsException, blocking, leaving the service in the RUNNING state, or unregistering the service.

If a service already in the RUNNING state, or is not restartable, this method is a noop. If the service is in the STOPPING state an IllegalServiceStateException will be thrown. If the service is disabled, this method will throw an IllegalServiceStateException.

This method has no effect on as service that is not restartable.

Specified by:

startService in interface Kernel

Parameters:

serviceName - the unique name of the service to start

startStrategy - the strategy that determines how unsatisfied conditions and construction exceptions are handled

Throws:

ServiceNotFoundException - if there is no service registered under the specified name

IllegalServiceStateException - if the service is restartable and is in the STOPPING state or if the service is disabled

UnsatisfiedConditionsException - if some of the start conditions can not be immediately satisfied

Exception - if service construction threw an Exception

startServiceRecursive

public void startServiceRecursive(ServiceName serviceName)
                           throws ServiceNotFoundException,
                                  IllegalServiceStateException,
                                  UnsatisfiedConditionsException,
                                  Exception

Immediately starts the service, and if the start ultimately completes successfully, all services owned by the specified service, all services that are owned by those services, and so on, will be started using the startServiceRecursive(ServiceName) method.

Specified by:

startServiceRecursive in interface Kernel

Parameters:

serviceName - the unique name of the service to start recursively

Throws:

ServiceNotFoundException - if there is no service registered under the specified name

IllegalServiceStateException - if the service is restartable and is in the STOPPING state or if the service is disabled

UnsatisfiedConditionsException - if some of the start conditions can not be immediately satisfied

Exception - if service construction threw an Exception

startServiceRecursive

public void startServiceRecursive(ServiceName serviceName,
                                  StartStrategy startStrategy)
                           throws ServiceNotFoundException,
                                  IllegalServiceStateException,
                                  UnsatisfiedConditionsException,
                                  Exception

Immediately starts the service, and if the start ultimately completes successfully, all services owned by the specified service, all services that are owned by those services, and so on, will be started using the startServiceRecursive(ServiceName, StartStrategy) method.

Specified by:

startServiceRecursive in interface Kernel

Parameters:

serviceName - the unique name of the service to start recursively

startStrategy - the strategy that determines how unsatisfied conditions and construction exceptions are handled

Throws:

ServiceNotFoundException - if there is no service registered under the specified name

IllegalServiceStateException - if the service is restartable and is in the STOPPING state or if the service is disabled

UnsatisfiedConditionsException - if some of the start conditions can not be immediately satisfied

Exception - if service construction threw an Exception

stopService

public void stopService(ServiceName serviceName)
                 throws ServiceNotFoundException,
                        UnsatisfiedConditionsException

Immediately stops the service using the SYNCHRONOUS stop strategy. If a stop condition can not be immediately satisfied, an UnsatisfiedConditionsException will be thrown. If a service already in the STOPPED state, this method is a noop.

If the service is not restartable, this method only attempts to satify the stop conditions. This is useful for stopping all dependent services of a non-restartable service before unregistering the service.

Specified by:

stopService in interface Kernel

Parameters:

serviceName - the unique name of the service to stop

Throws:

ServiceNotFoundException - if there is no service registered under the specified name

UnsatisfiedConditionsException

stopService

public void stopService(ServiceName serviceName,
                        StopStrategy stopStrategy)
                 throws ServiceNotFoundException,
                        UnsatisfiedConditionsException

Immediately stops the service using the specified stop strategy. If a stop condition can not be immediately satisfied, an UnsatisfiedConditionsException will be thrown. If a service already in the STOPPED state, this method is a noop.

If the service is not restartable, this method only attempts to satify the stop conditions. This is useful for stopping all dependent services of a non-restartable service before unregistering the service.

Specified by:

stopService in interface Kernel

Parameters:

serviceName - the unique name of the service to stop

stopStrategy - the strategy that determines how unsatisfied conditions are handled

Throws:

ServiceNotFoundException - if there is no service registered under the specified name

UnsatisfiedConditionsException

isServiceEnabled

public boolean isServiceEnabled(ServiceName serviceName)
                         throws ServiceNotFoundException

Determines if the service can be instantiated in a kernel. A disabled restartable service can not be started. This method is equivalent to:

     kernel.getServiceFactory(serviceName).isEnabled();
 

Specified by:

isServiceEnabled in interface Kernel

Parameters:

serviceName - the unique name of the service

Returns:

true if the service factory is enabled; false otherwise

Throws:

ServiceNotFoundException - if there is no service registered under the specified name

setServiceEnabled

public void setServiceEnabled(ServiceName serviceName,
                              boolean enabled)
                       throws ServiceNotFoundException

Sets the enabled status of a service. A disabled restartable service can not be started. This state has no effect on a service that is already started, but if a running service is disabled, it can not be restarted. This method is equivalent to:

     kernel.getServiceFactory(serviceName).setEnabled(enabled);
 

Specified by:

setServiceEnabled in interface Kernel

Parameters:

serviceName - the unique name of the service

enabled - the new enabled state of this factory

Throws:

ServiceNotFoundException - if there is no service registered under the specified name

getService

public Object getService(ServiceName serviceName)
                  throws ServiceNotFoundException,
                         IllegalArgumentException

Gets the service registered under the specified name. If the service is not in the RUNNING, or STARTING state this method will throw an IllegalArgumentException.

Specified by:

getService in interface Kernel

Parameters:

serviceName - the unique name of the service

Returns:

the service associated with the specified name

Throws:

ServiceNotFoundException - if there is no service registered under the specified name

IllegalArgumentException - if the service is not in the RUNNING, or STARTING state

getService

public Object getService(Class type)

Gets the first running service registered with the kernel that is an instance of the specified type. If no running services are instances of the specified type, null is returned.

Specified by:

getService in interface Kernel

Parameters:

type - the of the desired service

Returns:

the first registered service that is an instance of the specified type and is running

getServices

public List getServices(Class type)

Gets the all of running service registered with the kernel that are an instances of the specified type. If no running services are instances of the specified type, an empty list is returned

Specified by:

getServices in interface Kernel

Parameters:

type - the of the desired service

Returns:

the registered services that are instances of the specified type and are running

getServiceFactory

public ServiceFactory getServiceFactory(ServiceName serviceName)
                                 throws ServiceNotFoundException

Gets the service factory registered under the specified name.

Specified by:

getServiceFactory in interface Kernel

Parameters:

serviceName - the unique name of the service

Returns:

the service factory associated with the specified name

Throws:

ServiceNotFoundException - if there is no service registered under the specified name

getServiceFactory

public ServiceFactory getServiceFactory(Class type)

Gets the first service factory registered with the kernel that creates an instance of the specified type. If no service factories create an instance of the specified type, null is returned.

Specified by:

getServiceFactory in interface Kernel

Parameters:

type - the of the desired service

Returns:

the first service factory registered with the kernel that creates an instance of the specified type

getServiceFactories

public List getServiceFactories(Class type)

Gets the all of the service factories registered with the kernel that create an instances of the specified type. If no service factories create an instance of the specified type, an empty list is returned.

Specified by:

getServiceFactories in interface Kernel

Parameters:

type - the of the desired service

Returns:

the registered services that are instances of the specified type and are running

getClassLoaderFor

public ClassLoader getClassLoaderFor(ServiceName serviceName)
                              throws ServiceNotFoundException

Gets the class loader associated with the specifed service.

Specified by:

getClassLoaderFor in interface Kernel

Parameters:

serviceName - the unique name of the service

Returns:

the class loader associated with the specified name

Throws:

ServiceNotFoundException - if there is no service registered under the specified name

addKernelMonitor

public void addKernelMonitor(KernelMonitor kernelMonitor)

Adds a kernel monitor.

Specified by:

addKernelMonitor in interface Kernel

Parameters:

kernelMonitor - the kernel monitor to add

removeKernelMonitor

public void removeKernelMonitor(KernelMonitor kernelMonitor)

Removes a kernel monitor.

Specified by:

removeKernelMonitor in interface Kernel

Parameters:

kernelMonitor - the kernel monitor to remove

addServiceMonitor

public void addServiceMonitor(ServiceMonitor serviceMonitor)

Adds a service monitor for all services registered with the kernel. This method is equivalent to:

     addServiceMonitor(serviceMonitor, null);
 

Note: the order in which service monitors are notified is not specified.

Specified by:

addServiceMonitor in interface Kernel

Parameters:

serviceMonitor - the service monitor to add

addServiceMonitor

public void addServiceMonitor(ServiceMonitor serviceMonitor,
                              ServiceName serviceName)

Adds a service monitor for a specific service.

Note: the order in which service monitors are notified is not specified.

Specified by:

addServiceMonitor in interface Kernel

Parameters:

serviceMonitor - the service monitor to add

serviceName - the unique name of the service to monitor or null to monitor all services

removeServiceMonitor

public void removeServiceMonitor(ServiceMonitor serviceMonitor)

Removes a service monitor.

Specified by:

removeServiceMonitor in interface Kernel

Parameters:

serviceMonitor - the service monitor to remove