| /** |
| * |
| * Copyright 2005 the original author or authors. |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| package org.gbean.kernel; |
| |
| import java.util.List; |
| |
| /** |
| * This iterface defines the API for managing and monitoring service life-cycle. A kernel can be constructed with the |
| * following code: |
| * <p><blockquote><pre> |
| * Kernel kernel = KernelFactory.newInstance().createKernel(name); |
| * </pre></blockquote> |
| * Services can be registered, unregistered, started and |
| * stopped. The lifecycle model is loosly based on the J2ee Management Specification (JSR 77). All lifecycle |
| * transitions are broadcasted via a ServiceMonitor. |
| * <p/> |
| * Each kernel must have a name that is unique with in the KernelFactory (there should only be one KernelFactory per |
| * VM but class loader tricks can result in several KernelFactory) |
| * <p/> |
| * This class is loosely based on the J2ee management MEJB and JMX MBeanServer interfaces. |
| * |
| * @author Dain Sundstrom |
| * @version $Id$ |
| * @since 1.0 |
| */ |
| public interface Kernel { |
| /** |
| * Destroys this kernel. This method causes all services to be stopped and unregistered. |
| */ |
| void destroy(); |
| |
| /** |
| * Gets the running status of the kernel. Services can not be registered or started on a stopped kernel. |
| * |
| * @return true if the kernel is running; false otherwise |
| */ |
| boolean isRunning(); |
| |
| /** |
| * Gets the unique name of this kernel within the KernelFactory. |
| * |
| * @return the unique name of this kernel |
| */ |
| String getKernelName(); |
| |
| /** |
| * 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. |
| * |
| * @param serviceName the unique name of the service in the kernel |
| * @param serviceFactory the factory used to create the service |
| * @param classLoader the class loader to use for this service |
| * @throws ServiceAlreadyExistsException if service is already registered with the specified name |
| * @throws ServiceRegistrationException if the service is not restartable and an error occured while starting the service |
| */ |
| void registerService(ServiceName serviceName, ServiceFactory serviceFactory, ClassLoader classLoader) throws ServiceAlreadyExistsException, 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. |
| * |
| * @param serviceName the unique name of the service in the kernel |
| * @throws ServiceNotFoundException if there is no service registered under the specified name |
| * @throws ServiceRegistrationException if the service could not be stopped |
| */ |
| void unregisterService(ServiceName serviceName) 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. |
| * |
| * @param serviceName the unique name of the service in the kernel |
| * @param stopStrategy the strategy that determines how unsatisfied conditions are handled |
| * @throws ServiceNotFoundException if there is no service registered under the specified name |
| * @throws ServiceRegistrationException if the service could not be stopped |
| */ |
| void unregisterService(ServiceName serviceName, StopStrategy stopStrategy) throws ServiceNotFoundException, ServiceRegistrationException; |
| |
| /** |
| * Determines if there is a service registered under the specified name. |
| * |
| * @param serviceName the unique name of the service |
| * @return true if there is a service registered with the specified name; false otherwise |
| */ |
| boolean isRegistered(ServiceName serviceName); |
| |
| /** |
| * Gets the ServiceState of the specified service. If the service is not restartable, this method will |
| * always return RUNNING. |
| * |
| * @param serviceName the unique name of the service in the kernel |
| * @return the curren ServiceState of the service |
| * @throws ServiceNotFoundException if there is no service registered under the specified name |
| */ |
| ServiceState getServiceState(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. |
| * |
| * @param serviceName the unique name of the service in the kernel |
| * @return 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 |
| */ |
| long getServiceStartTime(ServiceName serviceName) throws ServiceNotFoundException; |
| |
| /** |
| * 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. |
| * <p/> |
| * This method has no effect on as service that is not restartable. |
| * |
| * @param serviceName the unique name of the service to start |
| * @throws ServiceNotFoundException if there is no service registered under the specified name |
| * @throws IllegalServiceStateException if the service is restartable and is in the STOPPING state or if the |
| * service is disabled |
| * @throws UnsatisfiedConditionsException if some of the start conditions can not be immediately satisfied |
| * @throws Exception if service construction threw an Exception |
| */ |
| void startService(ServiceName serviceName) throws ServiceNotFoundException, IllegalServiceStateException, UnsatisfiedConditionsException, Exception; |
| |
| /** |
| * Immediately starts the service using the specified start strategy. |
| * <p/> |
| * The start strategy determines how any exception thrown from service constuction is handled including throwing |
| * the exception directly from this method. |
| * <p/> |
| * 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. |
| * <p/> |
| * 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. |
| * <p/> |
| * This method has no effect on as service that is not restartable. |
| * |
| * @param serviceName the unique name of the service to start |
| * @param 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 |
| * @throws IllegalServiceStateException if the service is restartable and is in the STOPPING state or if the |
| * service is disabled |
| * @throws UnsatisfiedConditionsException if some of the start conditions can not be immediately satisfied |
| * @throws Exception if service construction threw an Exception |
| */ |
| void startService(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) method. |
| * |
| * @param serviceName the unique name of the service to start recursively |
| * @throws ServiceNotFoundException if there is no service registered under the specified name |
| * @throws IllegalServiceStateException if the service is restartable and is in the STOPPING state or if the |
| * service is disabled |
| * @throws UnsatisfiedConditionsException if some of the start conditions can not be immediately satisfied |
| * @throws Exception if service construction threw an Exception |
| */ |
| 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, StartStrategy) method. |
| * |
| * @param serviceName the unique name of the service to start recursively |
| * @param 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 |
| * @throws IllegalServiceStateException if the service is restartable and is in the STOPPING state or if the |
| * service is disabled |
| * @throws UnsatisfiedConditionsException if some of the start conditions can not be immediately satisfied |
| * @throws Exception if service construction threw an Exception |
| */ |
| void startServiceRecursive(ServiceName serviceName, StartStrategy startStrategy) throws ServiceNotFoundException, IllegalServiceStateException, UnsatisfiedConditionsException, Exception; |
| |
| /** |
| * 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. |
| * <p/> |
| * 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. |
| * |
| * @param serviceName the unique name of the service to stop |
| * @throws ServiceNotFoundException if there is no service registered under the specified name |
| */ |
| void stopService(ServiceName serviceName) 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. |
| * <p/> |
| * 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. |
| * |
| * @param serviceName the unique name of the service to stop |
| * @param stopStrategy the strategy that determines how unsatisfied conditions are handled |
| * @throws ServiceNotFoundException if there is no service registered under the specified name |
| */ |
| void stopService(ServiceName serviceName, StopStrategy stopStrategy) throws ServiceNotFoundException, UnsatisfiedConditionsException; |
| |
| /** |
| * Determines if the service can be instantiated in a kernel. A disabled restartable service can not be |
| * started. This method is equivalent to: |
| * <p><blockquote><pre> |
| * kernel.getServiceFactory(serviceName).isEnabled(); |
| * </pre></blockquote> |
| * <p/> |
| * |
| * @param serviceName the unique name of the service |
| * @return true if the service factory is enabled; false otherwise |
| * @throws ServiceNotFoundException if there is no service registered under the specified name |
| */ |
| boolean isServiceEnabled(ServiceName serviceName) 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: |
| * <p><blockquote><pre> |
| * kernel.getServiceFactory(serviceName).setEnabled(enabled); |
| * </pre></blockquote> |
| * <p/> |
| * |
| * @param serviceName the unique name of the service |
| * @param enabled the new enabled state of this factory |
| * @throws ServiceNotFoundException if there is no service registered under the specified name |
| */ |
| void setServiceEnabled(ServiceName serviceName, boolean enabled) throws ServiceNotFoundException; |
| |
| /** |
| * 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. |
| * |
| * @param serviceName the unique name of the service |
| * @return the service associated with the specified name |
| * @throws ServiceNotFoundException if there is no service registered under the specified name |
| * @throws IllegalArgumentException if the service is not in the RUNNING, or STARTING state |
| */ |
| Object getService(ServiceName serviceName) throws ServiceNotFoundException, IllegalArgumentException; |
| |
| /** |
| * 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. |
| * |
| * @param type the of the desired service |
| * @return the first registered service that is an instance of the specified type and is running |
| */ |
| Object getService(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 |
| * |
| * @param type the of the desired service |
| * @return the registered services that are instances of the specified type and are running |
| */ |
| List getServices(Class type); |
| |
| /** |
| * Gets the service factory registered under the specified name. |
| * |
| * @param serviceName the unique name of the service |
| * @return the service factory associated with the specified name |
| * @throws ServiceNotFoundException if there is no service registered under the specified name |
| */ |
| ServiceFactory getServiceFactory(ServiceName serviceName) throws ServiceNotFoundException; |
| |
| /** |
| * 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. |
| * |
| * @param type the of the desired service |
| * @return the first service factory registered with the kernel that creates an instance of the specified type |
| */ |
| ServiceFactory getServiceFactory(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. |
| * |
| * @param type the of the desired service |
| * @return the registered services that are instances of the specified type and are running |
| */ |
| List getServiceFactories(Class type); |
| |
| /** |
| * Gets the class loader associated with the specifed service. |
| * |
| * @param serviceName the unique name of the service |
| * @return the class loader associated with the specified name |
| * @throws ServiceNotFoundException if there is no service registered under the specified name |
| */ |
| ClassLoader getClassLoaderFor(ServiceName serviceName) throws ServiceNotFoundException; |
| |
| /** |
| * Adds a kernel monitor. |
| * |
| * @param kernelMonitor the kernel monitor to add |
| */ |
| void addKernelMonitor(KernelMonitor kernelMonitor); |
| |
| /** |
| * Removes a kernel monitor. |
| * |
| * @param kernelMonitor the kernel monitor to remove |
| */ |
| void removeKernelMonitor(KernelMonitor kernelMonitor); |
| |
| /** |
| * Adds a service monitor for all services registered with the kernel. This method is equivalent to: |
| * <p><blockquote><pre> |
| * addServiceMonitor(serviceMonitor, null); |
| * </pre></blockquote> |
| * <p/> |
| * Note: the order in which service monitors are notified is not specified. |
| * |
| * @param serviceMonitor the service monitor to add |
| */ |
| void addServiceMonitor(ServiceMonitor serviceMonitor); |
| |
| /** |
| * Adds a service monitor for a specific service. |
| * <p/> |
| * Note: the order in which service monitors are notified is not specified. |
| * |
| * @param serviceMonitor the service monitor to add |
| * @param serviceName the unique name of the service to monitor or null to monitor all services |
| */ |
| void addServiceMonitor(ServiceMonitor serviceMonitor, ServiceName serviceName); |
| |
| /** |
| * Removes a service monitor. |
| * |
| * @param serviceMonitor the service monitor to remove |
| */ |
| void removeServiceMonitor(ServiceMonitor serviceMonitor); |
| } |