org.apache.xbean.kernel.standard
Class StandardKernel

java.lang.Object
  extended by 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


Copyright © 2005-2009 Apache Software Foundation. All Rights Reserved.