de.aristaflow.adept2.base.registry

Class LocalServiceRegistry

java.lang.Object

de.aristaflow.adept2.base.service.AbstractADEPT2Service

de.aristaflow.adept2.base.service.AbstractAuthenticatedService

de.aristaflow.adept2.base.registry.AbstractRegistry

de.aristaflow.adept2.base.registry.PluginRegistry

de.aristaflow.adept2.base.registry.InstanceToInstanceRegistry

de.aristaflow.adept2.base.registry.LocalServiceRegistry

All Implemented Interfaces:

ConfMgrRegistry, ADEPT2Service, AuthenticatingService, LogService, NameResolution, ServiceThreadHandling

Direct Known Subclasses:

ServiceRegistry

@ConfigurationDescription(properties={@Property(name="MultiThreadedServiceStartPoolSize",type=INT,defaultValue="0",description="The amount of threads that will be used for theconcurrent service start. The value \'0\' means, that the services are started sequentially. For a server at least 20 threads are needed, for a client at least 10 threads are needed."),,,},validator=LocalServiceRegistry.ConfigurationValidator.class)
public abstract class LocalServiceRegistry
extends InstanceToInstanceRegistry

The local service registry extends the InstanceToInstanceRegistry to support service components. Service components fulfil a service interface that supports a whole lifecycle (initialisation, starting, shutting down). Additionally services may be exported, that is, they may be available to other services outside of their own JVM. However, the local service registry only handles local services which are not exported and only have local addresses (URI).
To allow managed registries for exporting services at startup, this registry starts the corresponding configured services when started itself.

The components managed by this registry must implement ADEPT2Service. This is checked when creating a local service registry. Additionally they need to have a public constructor accepting their configuration (org.apache.commons.configuration2.Configuration) as well as a wrapper for this registry (Registry). The constructor should not do much; the initialisation should take place in the corresponding method. It is guaranteed that every service is initialised, started and shutdown exactly once. Additionally, the constructor, ADEPT2Service.init(URI[], URI[]) and ADEPT2Service.start() are called by the same thread.

Services are singletons. This is checked and enforced. Besides these, there are no further issues for services; they behave like normal components as described in the super classes of this LocalServiceRegistry. This also includes the configuration of the services.

Services may require other services for their initialisation and/or execution. Therefore when starting a service, its startup-required services are also started. This applies recursively until a service does not rely on other services. The starting may happen concurrently or sequentially depending on the configuration of this registry. Please note that initialisation, starting and export of a service (including the same with the startup-required services) is performed with a lock based on the session to meet the exactly once-semantic. Since there are no cyclic dependencies there may not be deadlocks.

When shutting down, the services are shut down in the reverse order of their start. This registry will shutdown immediately when starting if one of the auto start services fails to start.

If a critical exception occurs (AbortServiceException when creating, initialising or starting a service while starting this registry, the starting will be aborted and already started services will be shut down. This applies for instance to services required by the registry or autostart services.

This class parses the following (boolean) property from its configuration (in the constructor) - besides the properties parsed by super classes:

• MultiThreadedServiceStartPoolSize ( ConfigurationConstants.SERVICE_MULTI_THREAD_SERVICE_START_POOL_SIZE )
• AutoStartServices ( ConfigurationConstants.SERVICE_AUTOSTART_SERVICES )

Author:

Ulrich Kreher

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	LocalServiceRegistry.ConfigurationValidator Checks the configuration of the ServiceRegistry.
protected static class	LocalServiceRegistry.ServiceExportInformation ServiceExportInformation encapsulates the data which is needed for exporting a service, which is: the services for exporting a service (ADEPT2ServiceExport), the URIs under which the service is exported and which correspond based on the position in the array to the export service, whether the service is to be published at the global registry.
protected class	LocalServiceRegistry.ServiceNameResolution The class used to provide a service load graph with the necessary service data (names of used services and specific service objects.
protected static interface	LocalServiceRegistry.ServiceStarter This interface is used for starting services which requires a start routine (Callable.call()) and the service name (LocalServiceRegistry.ServiceStarter.getServiceName()) for logging purpose.

Nested classes/interfaces inherited from class de.aristaflow.adept2.base.registry.PluginRegistry

PluginRegistry.URLClassloaderPrivilegedAction

Nested classes/interfaces inherited from class de.aristaflow.adept2.base.registry.AbstractRegistry

AbstractRegistry.DefaultNameResolution, AbstractRegistry.InstanceInformation, AbstractRegistry.InstantiationMode

Nested classes/interfaces inherited from class de.aristaflow.adept2.base.service.AbstractADEPT2Service

AbstractADEPT2Service.ActiveSessions

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.Set<java.lang.String>	autoStartServices The names of the services to start when starting this registry.
protected java.util.concurrent.ConcurrentMap<java.lang.String,java.lang.Throwable>	failedServices All services that failed to start, mapping from name to the exception that occurred when starting.
protected boolean	gsmAvailable Whether the global security manager is available now.
protected java.lang.String	nodeName The unique name of the node this registry and the using service belong to.
protected SerialisablePair<java.lang.String,java.lang.String>	release The release of the bootstrap registry.
protected java.util.concurrent.ExecutorService	serviceStarterPool A thread-pool service for starting services concurrently.
protected boolean	shuttingDown Signals when this registry is shutting down and must not start any further service.
protected java.util.Stack<Pair<java.lang.String,ADEPT2Service>>	startedServices All started services (hierarchical service name and service), pushed on the stack in order of their start.
protected java.util.Map<java.lang.String,java.util.concurrent.locks.Lock>	startingLock While starting and while checking for started, a service a write lock is needed.
protected java.lang.ThreadLocal<java.util.Stack<java.lang.String[]>>	startingRequiredServices The names of the startup required services declared by the service which is currently started by the corresponding thread.
protected java.lang.ThreadLocal<java.util.Stack<java.lang.String>>	startingService The hierarchical name of the service which is currently started by the corresponding thread.

Fields inherited from class de.aristaflow.adept2.base.registry.InstanceToInstanceRegistry

usedInstances

Fields inherited from class de.aristaflow.adept2.base.registry.PluginRegistry

declaredPluginTypes, defaultInstances, dynamicPlugins, pluginInstances, runtimePlugins, runtimePluginTypeCLs, singletonPlugins

Fields inherited from class de.aristaflow.adept2.base.registry.AbstractRegistry

componentInterfaces, configurationManager, declaredInstances, INIT_INSTANTIATED_OBJECT_METHOD, nameResolution, singletonInstances

Fields inherited from class de.aristaflow.adept2.base.service.AbstractAuthenticatedService

CFG_EARLY_SERVICEAUTH_ORGPOSID, CFG_EARLY_SERVICEAUTH_ORGPOSNAME, CFG_EARLY_SERVICEAUTH_PASSWORD, CFG_EARLY_SERVICEAUTH_USERNAME, CFG_SERVICEAUTH_ORGPOSID, CFG_SERVICEAUTH_ORGPOSNAME, CFG_SERVICEAUTH_PASSWORD, CFG_SERVICEAUTH_USERNAME

Fields inherited from class de.aristaflow.adept2.base.service.AbstractADEPT2Service

CONF_CSV_LOGGING, configuration, logger, registry, runtimeRequiredServices, startupRequiredServices

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	LocalServiceRegistry(UrlConfigurationManager confMgr, Configuration configuration, Registry registry) Constructs a new local service registry by calling the super constructor.
protected	LocalServiceRegistry(UrlConfigurationManager confMgr, Configuration configuration, Registry registry, SerialisablePair<java.lang.String,java.lang.String> release) Constructs a new service registry by calling the super constructor.

Method Summary

Modifier and Type	Method and Description
protected void	autoStartServices() Prepares the global security manager, authenticates this registry, provides the data sources for the runtime configurations to the configuration manager if appropriate, and starts all services to be automatically started at startup of this registry.
protected void	checkServiceInterface(java.lang.String serviceName, ADEPT2Service service) Checks whether the designated service object does fulfill the ADEPT2Service-interface appropriately.
protected void	checkServiceURI(SessionToken session, java.net.URI serviceURI) Validates whether the designated URI is local, well-formed and may identify a service instance.
protected void	checkServiceUriSyntax(java.net.URI serviceUri) Validates whether the designated URI is well-formed and may identify a service instance.
protected void	checkStartupRequiredService(java.lang.String serviceName) Checks whether the current thread is starting a service right now and whether this service has declared the designated service as a startup-required service type.
protected java.net.URI	chooseAppropriateURI(java.net.URI[] serviceURIs) Chooses an appropriate URI, that is a local URI or null in case no local URI is found.
protected java.net.URI	createLocalServiceURI(java.lang.String instanceName) Creates a local (i.e. not for remote usage) service URI for a given service instance name.
protected javax.management.ObjectName	createMBeanName(java.lang.String serviceName) Creates the name for the designated service to be available as MBean.
protected Registry	createRegistryWrapper(java.lang.String serviceName, boolean earlyService, InstanceToInstanceRegistry mfRegistry, ModelViewerProvider mvProvider) Creates a Registry which is a wrapper for this registry including the service name.
static java.lang.String	determineNodeName(java.util.logging.Logger logger) Determines and returns a unique name for the current platform/cluster node.
protected void	exportService(SessionToken session, java.lang.String serviceName, ADEPT2Service service, LocalServiceRegistry.ServiceExportInformation serviceExportInformation) Exports and publishes the designated service (in case of an exported service) using the designated service export objects and the designated URIs if appropriate.
protected java.lang.String	getAndCheckRequiredService(SessionToken session, java.lang.String usingService, java.lang.String usedServiceTypeName) Gets the name of the used service of the designated type and for the designated using service.
protected <T> T	getConfiguredPlugin(SessionToken session, java.lang.String usingInstanceName, java.lang.Object usingInstance, java.lang.String pluginTypeName, java.lang.Class<T> componentType, java.lang.String pluginInstanceName, java.lang.Class<?>[] additionalParameterTypes, java.lang.Object[] additionalParameterValues) Retrieves the plugin with the designated name of the designated type if it is declared by the using instance or if it is declared and found as runtime plugin.
protected java.util.concurrent.atomic.AtomicLong	getGlobalSequence(java.lang.String seqName) Gets the sequence with the designated name.
protected java.lang.String	getInstanceNameFromServiceURI(java.net.URI serviceURI) Returns the hierarchical instance name from the service URI.
protected AbstractRegistry.InstantiationMode	getInstantiationMode(java.lang.String serviceType, java.lang.String simpleName, Configuration registryConfiguration) Overridden to log non-singleton services.
protected <T extends ADEPT2Service> T	getLocalServiceObject(SessionToken session, java.lang.String serviceName, java.lang.Class<T> requestedType) Returns an instance of the designated service and of the requested type.
protected <T extends AbstractRegistry> T	getRegistry(SessionToken session, java.lang.String registryTypeName, java.lang.Class<T> registryType) Gets a registry (as service and therefore singleton) for the specified type name of the specified type, for instance RuntimeRegistry.
protected SecurityManager	getSecurityManager() Returns a security manager for this registry.
<T extends ADEPT2Service> T	getService(SessionToken session, java.lang.String serviceName, java.lang.Class<T> serviceType) Initialises, starts and exports (not relevant in this registry but in subclasses) the designated local service as well as the services that are startup-required by the designated service.
<T extends ADEPT2Service> T	getService(SessionToken session, java.net.URI[] serviceURIs, java.lang.Class<T> serviceType) Retrieves the service described by the URIs of which one has to be a local one.
protected <T extends ADEPT2Service> T	getServiceForInstance(SessionToken session, java.lang.String usingService, java.lang.String usedServiceTypeName, java.lang.Class<T> usedServiceType) Returns a completely initialised and started service which has been configured to be used by the usingService for the service type usedServiceTypeName and is of (object) type usedServiceType.
protected ServiceInformation	getServiceInformation(java.lang.String instanceName) Returns the information (component type, instantiation mode, implementation class, service URI, export service instances and whether to publish the service) for the designated service instance.
void	init(java.net.URI[] localExportedUris, java.net.URI[] globalExportedUris) Checking all component interfaces to implement ADEPT2Service and reads the own configuration.
protected void	notifyDataSourceToConfMgr(boolean gsmAvailable) Sets the registry in the configuration manager allowing it to access the data source for runtime configurations.
protected LocalServiceRegistry.ServiceExportInformation	prepareExport(SessionToken session, java.lang.String serviceName, ADEPT2Service service) Prepares the export by creating a local URI for initialisation of the service.
protected abstract GlobalSecurityManager	prepareGlobalSecurityManager() Prepares the security manager that is, the global security manager will be retrieved (and started) if necessary.
protected void	readMetaConfiguration(Configuration registryConfiguration, java.lang.String serviceType, java.lang.String simpleInstanceName) Reads the meta information from the registry for the designated service instance, which is: the implementing class or the implementing object for a local service The instantiation mode of a service is always AbstractRegistry.InstantiationMode.SINGLETON If something else is set in the configuration (please note that this property may also - and in this case should - be omitted), a warning message is logged and SINGLETON used instead.
boolean	registryActive() Gets whether this registry is active, that is, it has signalled its start and is not being shut down.
protected void	renewConfiguration(Configuration conf) Renews the configuration of this registry by renewing via the superclass and reading of usage relations.
void	shutdown(boolean emergency) Shut down all started services.
void	start() Starts the services (and the corresponding required services that this registry should start when it is itself started.
protected void	startLocalService(SessionToken session, java.lang.String serviceName, ADEPT2Service service, de.aristaflow.adept2.base.registry.ServiceLoadGraph loadGraph) Initialises, starts and exports (not relevant in this registry but in subclasses) the designated local service as well as the services that are startup-required by the designated service.
protected void	syncExecute(LocalServiceRegistry.ServiceStarter[] startServices) Submits the designated ServiceStarters to an executor service and waits for them to complete.
protected void	terminate(boolean emergency, java.lang.String hierServName) Terminates all started services or until the designated service and signals the shutdown of this registry.
protected void	terminateService(boolean emergency, java.lang.String serviceName, ADEPT2Service service) Terminates the designated service.
protected void	unpublishService(SessionToken session, java.lang.String serviceName, ADEPT2Service service) Removes the designated service from the global registry and from the service exports.

Methods inherited from class de.aristaflow.adept2.base.registry.InstanceToInstanceRegistry

getUsedComponentInstanceNameForInstance, getUsedObjectForInstance

Methods inherited from class de.aristaflow.adept2.base.registry.PluginRegistry

createPluginLoader, getConfiguredPlugin, getConfiguredPlugin, getConfiguredPlugins, prepareRuntimePlugin, readMetaConfiguration

Methods inherited from class de.aristaflow.adept2.base.registry.AbstractRegistry

checkAndStoreProvidedObject, checkConfiguration, checkImplementingClass, checkSupertype, createInstanceForInterface, getAppropriateMethod, getArbitrarilyNamedObject, getComponentType, getFormattedSignature, getHierarchicalInstanceName, getInstanceInformation, getInterfaceForComponentType, getObjectForInstanceName, getObjectForInstanceName, getObjectForInstanceName, getSimpleInstanceName, initialiseInstantiatedObject

Methods inherited from class de.aristaflow.adept2.base.service.AbstractAuthenticatedService

_sessionActive, authenticateService, awaitActiveSessions, createChildSession, createSession, getAgent, getSessionFactory, getStartupRequired, getTopLevelAgent, getUserCredentials, globalSecurityManagerAvailable, isEarlyService, sessionHasCapability

Methods inherited from class de.aristaflow.adept2.base.service.AbstractADEPT2Service

_sessionFinished, activeOrInvalidServiceStateException, changeLogContext, changeLogContext, changeLogContext, consoleLog, csvLoggingEnabled, getClassSpecificJulLogger, getDependencyRegistry, getLocalUris, getLogger, getRelease, getRuntimeRequiredServices, getServiceInstanceName, getStartupRequiredServices, getURIs, isActive, isSessionActive, isShutdown, logMethodEntry, logMethodEntry, logMethodEntry, logMethodExit, logMethodExit, ping, preShutdown, privilegeSession, privilegeThread, revertLogContextChanges, sessionActive, sessionActive, sessionActive, sessionActive, sessionFinished, sessionFinished, signalShutdown, signalStart, unprivilegeThread

Methods inherited from class java.lang.Object

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

Methods inherited from interface de.aristaflow.adept2.base.service.ADEPT2Service

getLocalUris, getRelease, getRuntimeRequiredServices, getServiceInstanceName, getStartupRequiredServices, getURIs, ping, preShutdown

Field Detail

nodeName

protected final java.lang.String nodeName

The unique name of the node this registry and the using service belong to.

autoStartServices

protected final java.util.Set<java.lang.String> autoStartServices

The names of the services to start when starting this registry. These are the simple names until they are exchanged to the hierarchical names when reading the meta configuration of the corresponding service.

startedServices

protected final java.util.Stack<Pair<java.lang.String,ADEPT2Service>> startedServices

All started services (hierarchical service name and service), pushed on the stack in order of their start. The usage of a stack allows to shut down the services in the reverse order.

failedServices

protected final java.util.concurrent.ConcurrentMap<java.lang.String,java.lang.Throwable> failedServices

All services that failed to start, mapping from name to the exception that occurred when starting.

shuttingDown

protected volatile boolean shuttingDown

Signals when this registry is shutting down and must not start any further service. Retrieval of started services is still allowed.

startingLock

protected final transient java.util.Map<java.lang.String,java.util.concurrent.locks.Lock> startingLock

While starting and while checking for started, a service a write lock is needed. This prevents accidentally multiple starting.

serviceStarterPool

protected java.util.concurrent.ExecutorService serviceStarterPool

A thread-pool service for starting services concurrently. Whether the starting of services is single- or multi-threaded is specified in the registry configuration.

startingService

protected final java.lang.ThreadLocal<java.util.Stack<java.lang.String>> startingService

The hierarchical name of the service which is currently started by the corresponding thread. If no service is started by the current thread, this will be null. Initialised here and once for all threads.

startingRequiredServices

protected final java.lang.ThreadLocal<java.util.Stack<java.lang.String[]>> startingRequiredServices

The names of the startup required services declared by the service which is currently started by the corresponding thread. If no service is started by the current thread, this will be null. Initialised here and once for all threads.

release

protected final SerialisablePair<java.lang.String,java.lang.String> release

The release of the bootstrap registry.

gsmAvailable

protected transient boolean gsmAvailable

Whether the global security manager is available now. In the first phases of a boot only a local security manager is available. This will be replaced by the global security manager as soon as possible.

Constructor Detail

LocalServiceRegistry

protected LocalServiceRegistry(UrlConfigurationManager confMgr,
                               Configuration configuration,
                               Registry registry)
                        throws ConfigurationException

Constructs a new local service registry by calling the super constructor. This is the registry-compatible constructor called via reflection by a parent registry.

Parameters:

configuration - The configuration of the created local service registry instance.

confMgr - The initial configuration manager that provides configurations for the loaded component instances.

registry - The parent registry of this registry.

Throws:

ConfigurationException - If the password cannot be parsed from the configuration, a ConfigurationException will be thrown.

LocalServiceRegistry

protected LocalServiceRegistry(UrlConfigurationManager confMgr,
                               Configuration configuration,
                               Registry registry,
                               SerialisablePair<java.lang.String,java.lang.String> release)
                        throws ConfigurationException

Constructs a new service registry by calling the super constructor. This should be called by subclasses when explicitly invoking the constructor. Usually these do not have a registry but then they need to provide the release.

Parameters:

configuration - The configuration of the created service registry instance.

confMgr - The initial configuration manager that provides configurations for the loaded component instances.

registry - The parent registry of this registry. This can be null when invoked by subclasses. But then a release has to be provided.

release - The release of the bootstrap registry.

Throws:

ConfigurationException - If the password cannot be parsed from the configuration, a ConfigurationException will be thrown.

Method Detail

getConfiguredPlugin

protected <T> T getConfiguredPlugin(SessionToken session,
                                    java.lang.String usingInstanceName,
                                    java.lang.Object usingInstance,
                                    java.lang.String pluginTypeName,
                                    java.lang.Class<T> componentType,
                                    java.lang.String pluginInstanceName,
                                    java.lang.Class<?>[] additionalParameterTypes,
                                    java.lang.Object[] additionalParameterValues)
                             throws ConfigurationException

Description copied from class: PluginRegistry

Retrieves the plugin with the designated name of the designated type if it is declared by the using instance or if it is declared and found as runtime plugin. A new plugin instance will be created if the instance is not singleton or it has not been instantiated before. If it is declared as singleton, the singleton behaviour will be relative to the using instance. Therefore if the using instance (name) has not requested the plugin before, it will be instantiated (again).
When instantiating the constructor with the designated additional parameter types (besides Configuration and the class/interface of the using instance) will be called providing the designated additional parameter values (besides its configuration and the using instance).

Overrides:

getConfiguredPlugin in class PluginRegistry

Type Parameters:

T - The type which the used object is expected to be of.

Parameters:

session - The session which is used to check for access rights on this method.

usingInstanceName - The hierarchical name of the using component instance. This may neither be null nor the empty.

usingInstance - The using component instance which is provided in the constructor of the requested plugin to allow for data exchange.

pluginTypeName - The component type of the plugin instance to be retrieved for usage. This may neither be null nor the empty string.

componentType - The type which the used object is expected to be of.

pluginInstanceName - The simple (!) name of the plugin instance to retrieve.

additionalParameterTypes - Additional parameter types (besides Configuration and the class/interface of the using instance) of the constructor to be used for instantiation. If no additional parameter is to be used, an empty array will need to be provided. This has to correspond to additionalParameterValues.

additionalParameterValues - Additional parameter (besides the configuration and the using instance) of the constructor to be used for instantiation. If no additional parameter is to be used, an empty array will need to be provided. This has to correspond to additionalParameterTypes.

Returns:

The instance with the designated name of designated plugin type for which the designated parameters are used when the instance needs to be instantiated.

Throws:

ConfigurationException - If

• the requested plugin type is not declared for the designated instance or its type,
• the requested plugin instance name is not declared in the corresponding component type configuration ( AbstractRegistry.getInstanceInformation(String))
• the configuration of the plugin does not have an entry for the implementation of the plugin instance ( AbstractRegistry.getInstanceInformation(String)),
• no component interface is registered/configured for the designated plugin type (AbstractRegistry.componentInterfaces),
• the designated using instance is not declared in the corresponding component type configuration ( AbstractRegistry.getInstanceInformation(String)),
• the configuration of the requested plugin instance does not provide required configuration values,
• the creation or initialisation of the plugin instance fails,

a ConfigurationException will be thrown.

renewConfiguration

protected void renewConfiguration(Configuration conf)
                           throws ConfigurationException

Description copied from class: InstanceToInstanceRegistry

Renews the configuration of this registry by renewing via the superclass and reading of usage relations.

Overrides:

renewConfiguration in class InstanceToInstanceRegistry

Parameters:

conf - The (new) root configuration for this registry.

Throws:

ConfigurationException - If

• mandatory properties are missing (PropertyNotSetException),
• the class or interface of a type can not be found,
• the instance is not configured properly (implementing class),

a ConfigurationException will be thrown.

readMetaConfiguration

protected void readMetaConfiguration(Configuration registryConfiguration,
                                     java.lang.String serviceType,
                                     java.lang.String simpleInstanceName)
                              throws ConfigurationException

Reads the meta information from the registry for the designated service instance, which is:

• the implementing class or the implementing object for a local service

The instantiation mode of a service is always AbstractRegistry.InstantiationMode.SINGLETON If something else is set in the configuration (please note that this property may also - and in this case should - be omitted), a warning message is logged and SINGLETON used instead.

Overrides:

readMetaConfiguration in class AbstractRegistry

Parameters:

registryConfiguration - The configuration which contains the (registry) information for the designated instance.

serviceType - The type of the component to retrieve the meta-configuration.

simpleInstanceName - The simple name of the component instance as declared in the configuration.

Throws:

ConfigurationException - If

• no implementing class name or implementing object is defined,
• the implementing object is not an ADEPT2Service,
• the designated service type is not configured for this registry,
• the designated implementing class or the implementing object is not a subtype of the registered service interface,

a ConfigurationException will be thrown.

getInstantiationMode

protected AbstractRegistry.InstantiationMode getInstantiationMode(java.lang.String serviceType,
                                                                  java.lang.String simpleName,
                                                                  Configuration registryConfiguration)

Overridden to log non-singleton services. This is usually a wrong configuration.

Overrides:

getInstantiationMode in class AbstractRegistry

Parameters:

serviceType - The type of the component to retrieve the meta-configuration.

simpleName - The simple name of the component instance as declared in the configuration.

registryConfiguration - The configuration which contains the declaration of the instantiation mode.

Returns:

The configured instantiation mode name for the designated component instance or InstantiationMode.SINGLETON.

prepareExport

protected LocalServiceRegistry.ServiceExportInformation prepareExport(SessionToken session,
                                                                      java.lang.String serviceName,
                                                                      ADEPT2Service service)
                                                               throws AbortServiceException

Prepares the export by creating a local URI for initialisation of the service.

Parameters:

session - The session which is used to check for access rights on this method.

serviceName - The name of the service to prepare the export of.

service - The service object to prepare the export of.

Returns:

A ServiceExportInformation-instance containing an empty service export array and a local URI.

Throws:

ConfigurationException - If the service type of the designated service (retrieved from the service name) is not known by this registry, a ConfigurationException will be thrown. This exception will never be thrown by this implementation.

AbortServiceException - If the preparation of the service export fails, an AbortServiceException will be thrown. This exception will never be thrown by this implementation.

InvalidServiceStateException - If this registry failed to start or is shut down, an InvalidServiceStateException will be thrown.

exportService

protected void exportService(SessionToken session,
                             java.lang.String serviceName,
                             ADEPT2Service service,
                             LocalServiceRegistry.ServiceExportInformation serviceExportInformation)
                      throws AbortServiceException

Exports and publishes the designated service (in case of an exported service) using the designated service export objects and the designated URIs if appropriate.

This implementation does nothing and is only for extension in subclasses.

Parameters:

session - The session which is used to check for access rights on this method.

serviceName - The hierarchical instance name of the service.

service - The service object to export.

serviceExportInformation - The information on the export services and the URIs to use.

Throws:

ConfigurationException - If the service type of the designated service (retrieved from the service name) is not known by this registry, a ConfigurationException will be thrown. This exception will never thrown by this implementation.

AbortServiceException - If exporting the service fails, an AbortServiceException will be thrown. This exception will never thrown by this implementation.

unpublishService

protected void unpublishService(SessionToken session,
                                java.lang.String serviceName,
                                ADEPT2Service service)

Removes the designated service from the global registry and from the service exports. This needs to be called before shutting down a service.

This implementation does nothing and is only for extension in subclasses.

Parameters:

session - The session which is used to check for access rights on this method.

serviceName - The hierarchical instance name of the service to remove from the global registry.

service - The service object to remove from the global registry and the service exports.

syncExecute

protected void syncExecute(LocalServiceRegistry.ServiceStarter[] startServices)
                    throws java.util.concurrent.ExecutionException,
                           AbortServiceException

Submits the designated ServiceStarters to an executor service and waits for them to complete. If an exception or an interrupt occurs, all starters will be cancelled (if not already finished) and the exception will be forwarded.

Parameters:

startServices - Callables to start services.

Throws:

java.util.concurrent.ExecutionException - If there is an exception (not an AbortServiceException) while executing a Callable, an ExecutionException will be thrown.

AbortServiceException - If the waiting thread is interrupted, an AbortServiceException will be thrown. If one of the awaited services fails to start with an AbortServiceException (encapsulated in an ExecutionException), this will be forwarded.

startLocalService

protected void startLocalService(SessionToken session,
                                 java.lang.String serviceName,
                                 ADEPT2Service service,
                                 de.aristaflow.adept2.base.registry.ServiceLoadGraph loadGraph)
                          throws AbortServiceException

Initialises, starts and exports (not relevant in this registry but in subclasses) the designated local service as well as the services that are startup-required by the designated service. A service object (declared as singleton) is only initialised and started once. Required services are started within subsessions of the designated session.
The designated service load graph is used for retrieval of the required services. The load graph ignores already started services while ADEPT2Service.getStartupRequiredServices() does not. This is only for better performance.
This method uses a read/write lock based on the instance name when accessing started services and starting instances. The write lock is held while the complete starting of required services, the initialisation, the starting as well as the export of the designated service. This synchronisation allows to start the required services multi-threaded. Whether to use multiple threads is specified in the configuration of this registry.

Parameters:

session - The session which is used to check for access rights on this method.

serviceName - The hierarchical instance name of the service.

service - The service which is to be started.

loadGraph - A graph containing the transitive dependencies of the services. It is used for determining the startup-required services since it does already ignore started services (unlike ADEPT2Service.getStartupRequiredServices()).

Throws:

AbortServiceException - If

• the current thread is interrupted while starting a local service,
• the service load graph needs to be build and the build fails due to an improperly configured service,
• a required service is not registered properly,
• the configuration of a service does not provide required configuration values,
• the creation or the initialisation of a required service object fails,
• the service could not be exported,
• an exception is thrown while starting a required service,
• the service throws an AbortServiceException while initialised or started,
• the service does not fulfill the ADEPT2Service-interface appropriately,

an AbortServiceException will be thrown.

InvalidServiceStateException - If this registry failed to start or is shut down, an InvalidServiceStateException will be thrown.

autoStartServices

protected void autoStartServices()
                          throws AbortServiceException

Prepares the global security manager, authenticates this registry, provides the data sources for the runtime configurations to the configuration manager if appropriate, and starts all services to be automatically started at startup of this registry.

Throws:

AbortServiceException - If there are problems preparing the security manager or starting one of the services to be automatically started, an AbortServiceException will be thrown.

getService

public <T extends ADEPT2Service> T getService(SessionToken session,
                                              java.lang.String serviceName,
                                              java.lang.Class<T> serviceType)
                                       throws ServiceNotKnownException

Initialises, starts and exports (not relevant in this registry but in subclasses) the designated local service as well as the services that are startup-required by the designated service. A service object (declared as singleton) is only initialised and started once so at further retrievals, started service objects will be returned.
This method checks whether the requested service is a startup-required service and declared as such (see checkStartupRequiredService(String)).
In case of retrieval while shutting down the registry, the returned service may already be terminated. But this may also happen when having a direct reference to a service.

Type Parameters:

T - The type which the requested service is expected to be of which is a subtype of ADEPT2Service and either the registered service type or a super type hereof.

Parameters:

session - The session which is used to check for access rights on this method.

serviceName - The hierarchical instance name of the service.

serviceType - The type of which the requested service is expected to be. This is a subtype of ADEPT2Service and either the registered service type interface or a super type hereof.

Returns:

An object for the designated service which is completely initialised, started and exported (if appropriate). The object is never null.

Throws:

ServiceNotKnownException - If

• the service is not registered properly,
• the configuration of the service object does not provide required configuration values,
• the creation of the service object fails,
• the required services have cyclic dependencies,
• the current thread is interrupted while starting a local service,
• the service load graph needs to be build and the build fails due to an improperly configured service,
• a required service is not registered properly,
• the configuration of the service instance does not provide required configuration values,
• the creation of a required service object fails,
• the service could not be exported,
• the service does not fulfill the ADEPT2Service-interface appropriately,
• an exception is thrown while starting a required service,

a ServiceNotKnownException will be thrown. This may encapsulate a ConfigurationException or an AbortServiceException.

InvalidServiceStateException - If this registry failed to start or is shut down, an InvalidServiceStateException will be thrown.

getService

public <T extends ADEPT2Service> T getService(SessionToken session,
                                              java.net.URI[] serviceURIs,
                                              java.lang.Class<T> serviceType)
                                       throws ServiceNotKnownException

Retrieves the service described by the URIs of which one has to be a local one.
This method checks whether the requested service is a startup-required service and declared as such (see checkStartupRequiredService(String)).
Although the designated service name may be completely unknown to this registry a stub will be created if the service has a protocol supported by this registry.

Type Parameters:

T - The type which the requested service is expected to be of. This is a subtype of ADEPT2Service and either the registered service type or a super type hereof.

Parameters:

session - The session which is used to check for access rights on this method.

serviceURIs - The URIs of the service to be retrieved, the array has to contain at least one valid service URI.

serviceType - The type of which the requested service is expected to be.

Returns:

An object for the designated service which is completely initialised, started and exported (if appropriate). The object is never null.

Throws:

NullArgumentException - If one of the parameters is null, a NullArgumentException will be thrown.

ServiceNotKnownException - If

• the service is not registered properly,
• the configuration of the service object does not provide required configuration values,
• the creation of the service object fails,
• the service does not fulfill the ADEPT2Service-interface appropriately,
• the required services have cyclic dependencies,
• the current thread is interrupted while starting a local service,
• the service load graph needs to be build and the build fails due to an improperly configured service,
• a required service is not registered properly,
• the creation of a required service object fails,
• an exception is thrown while starting a required service,

a ServiceNotKnownException will be thrown. This may encapsulate a ConfigurationException or an AbortServiceException.

InvalidServiceStateException - If this registry failed to start or is shut down, an InvalidServiceStateException will be thrown.

java.lang.IllegalArgumentException - If the service URI is invalid, an IllegalArgumentException will be thrown.

getServiceForInstance

protected <T extends ADEPT2Service> T getServiceForInstance(SessionToken session,
                                                            java.lang.String usingService,
                                                            java.lang.String usedServiceTypeName,
                                                            java.lang.Class<T> usedServiceType)
                                                     throws ServiceNotKnownException

Returns a completely initialised and started service which has been configured to be used by the usingService for the service type usedServiceTypeName and is of (object) type usedServiceType.
It will be logged if the requesting service has not declared the requested service type as required.

Type Parameters:

T - The type which the requested service is expected to be of. This is a subtype of ADEPT2Service and either the registered service type or a super type hereof.

Parameters:

session - The session which is used to check for access rights on this method.

usingService - The hierarchical instance name of the using service.

usedServiceTypeName - The name of the type the used component is of. This is the name of the registered service type.

usedServiceType - The (object) type of which the requested service is expected to be.

Returns:

A service object which is configured for the use by the designated service and which is completely initialised, started and exported (if appropriate). The object is never null.

Throws:

InvalidServiceStateException - If this registry failed to start or is shut down, an InvalidServiceStateException will be thrown.

ServiceNotKnownException - If

• the name of the used service instance (or the default service instance) could not be retrieved,
• the requesting service could not be retrieved locally,
• the used service is not registered properly,
• the configuration of the used service object does not provide required configuration values,
• the creation of the used service object fails,
• the used service does not fulfill the ADEPT2Service-interface appropriately,
• the required services have cyclic dependencies,
• the current thread is interrupted while starting a local service,
• the service load graph needs to be build and the build fails due to an improperly configured service,
• a required service is not registered properly,
• the creation of a required service object fails,
• the used service could not be exported,
• an exception is thrown while starting a required service,

a ServiceNotKnownException will be thrown. This may encapsulate a ConfigurationException or an AbortServiceException.

InvalidServiceStateException - If this registry failed to start or is shut down, an InvalidServiceStateException will be thrown.

java.lang.IllegalArgumentException - If a local service is requested and the designated service type interface is not the registered service type interface or a super type hereof, an IllegalArgumentException will be thrown.

See Also:

getAndCheckRequiredService(SessionToken, String, String)

getRegistry

protected <T extends AbstractRegistry> T getRegistry(SessionToken session,
                                                     java.lang.String registryTypeName,
                                                     java.lang.Class<T> registryType)
                                              throws ServiceNotKnownException

Gets a registry (as service and therefore singleton) for the specified type name of the specified type, for instance RuntimeRegistry. The registry will be loaded by the class loader of the/this bootstrap-registry.
Registries are singleton per default and no instances can be declared.

Type Parameters:

T - The type which the requested registry is expected to be of which is either the registered registry type or a super type hereof.

Parameters:

session - The session which is used to check for access rights on this method.

registryTypeName - The (simple) type name of the registry to be retrieved.

registryType - The type of which the requested registry is expected to be. This is either the registered registry type interface or a super type hereof.

Returns:

The registry (singleton) of the designated type.

Throws:

ServiceNotKnownException - If

• the registry is not registered properly,
• the creation of the registry object fails,
• the required services of the registry have cyclic dependencies,
• the current thread is interrupted while starting the registry as a local service,
• the service load graph needs to be build and the build fails due to an improperly configured service,
• a required service for the registry is not registered properly,
• the creation of a required service object fails,
• an exception is thrown while starting a required service,

a ServiceNotKnownException will be thrown. This may encapsulate a ConfigurationException or an AbortServiceException.

InvalidServiceStateException - If this registry failed to start or is shut down, an InvalidServiceStateException will be thrown.

terminateService

protected void terminateService(boolean emergency,
                                java.lang.String serviceName,
                                ADEPT2Service service)

Terminates the designated service.

Parameters:

emergency - Whether it is an emergency shutdown.

serviceName - The hierarchical name of the service which to terminate.

service - The service instance which to terminate.

init

public void init(java.net.URI[] localExportedUris,
                 java.net.URI[] globalExportedUris)
          throws AbortServiceException

Checking all component interfaces to implement ADEPT2Service and reads the own configuration. No service is started here yet, except the local security manager. This is absolutely crucial since the registry needs to be completely initialised (and therefore considered started, see AbstractRegistry.init(URI[], URI[])) before initialising and starting services. These services are allowed to access the registry and expect it be started!

Specified by:

init in interface ADEPT2Service

Overrides:

init in class AbstractRegistry

Parameters:

localExportedUris - The URIs with which this service is exported locally or a local URI or an empty array for internal services.

globalExportedUris - The URIs with which this service is published globally or null in case the service is not published.

Throws:

AbortServiceException - If

• the registry configuration contains an entry for a managed component but the property has no valid value or the specified class can not be found,
• a component interface does not implement ADEPT2Service ( AbstractRegistry.checkSupertype(String, Class, Class)),
• no implementing class name is defined,
• checking the instance configuration for a local service fails (AbstractRegistry.checkConfiguration(Configuration, String, Class)),
• the creation of or the authentication at the local security manager fails,
• creating the local security manager fails,

a ConfigurationException will be thrown.

start

public void start()
           throws AbortServiceException

Starts the services (and the corresponding required services that this registry should start when it is itself started.

Specified by:

start in interface ADEPT2Service

Overrides:

start in class AbstractADEPT2Service

Throws:

AbortServiceException - If preparing the security manager or starting an auto start service fails, the registry will be shut down and an AbortServiceException will be thrown, whereas in case of a wrapped ConfigurationException or AbortServiceException the exceptions will be unwrapped.

shutdown

public void shutdown(boolean emergency)

Shut down all started services.

Specified by:

shutdown in interface ADEPT2Service

Overrides:

shutdown in class AbstractRegistry

Parameters:

emergency - Whether the shutdown will be an emergency shutdown.

terminate

protected void terminate(boolean emergency,
                         java.lang.String hierServName)

Terminates all started services or until the designated service and signals the shutdown of this registry. If a service name is provided all services will be shut down that have been started after the designated service. The shutdown of the registry will not be signalled yet.
Just call this method again afterwards using null as service name.

Parameters:

emergency - Whether it is an emergency shutdown.

hierServName - The hierarchical name of the service until which to shutdown all services started later. If this is null, all services and the registry will be shut down.

getServiceInformation

protected ServiceInformation getServiceInformation(java.lang.String instanceName)
                                            throws ConfigurationException

Returns the information (component type, instantiation mode, implementation class, service URI, export service instances and whether to publish the service) for the designated service instance. This is the same as AbstractRegistry.getInstanceInformation(String) but with the more specific return type ServiceInformation.

Parameters:

instanceName - The hierarchical name of the service instance for which to retrieve its information.

Returns:

The information for the component instance as a tuple (component type, instantiation mode, implementation class, service URI, export service instances and whether to publish the service).

Throws:

ConfigurationException - If the designated instance is not configured properly, that is, it is not declared, a ConfigurationException will be thrown.

prepareGlobalSecurityManager

protected abstract GlobalSecurityManager prepareGlobalSecurityManager()
                                                               throws ServiceNotKnownException

Prepares the security manager that is, the global security manager will be retrieved (and started) if necessary.
This method will be called before (auto) starting any service. Implementations may then prepare a global security manager and provide it appropriately. Before this method has been called, the security manager will authenticate locally. Afterwards it will work with the global security manager.

Returns:

The prepared global security manager to use instead of the local authentication.

Throws:

ServiceNotKnownException - If the security manager could not be retrieved, a ServiceNotKnownException will be thrown. The registry must not continue starting in this case!!

getSecurityManager

protected SecurityManager getSecurityManager()

Returns a security manager for this registry. This works locally until the global security manager has been prepared successfully.

Overrides:

getSecurityManager in class AbstractAuthenticatedService

Returns:

A security manager working only locally for the initial phase of the bootstrapping or offline mode and working with the global security manager as soon as the corresponding service is remotely available.

getGlobalSequence

protected java.util.concurrent.atomic.AtomicLong getGlobalSequence(java.lang.String seqName)

Gets the sequence with the designated name. Sequences with the same name will be shared across the users of this registry. Sequences will be initialised with 1.

Parameters:

seqName - The name of the sequence. This name is arbitrary but should be shared among the services that share the sequence.

Returns:

An atomic long representing the designated sequence.

createRegistryWrapper

protected Registry createRegistryWrapper(java.lang.String serviceName,
                                         boolean earlyService,
                                         InstanceToInstanceRegistry mfRegistry,
                                         ModelViewerProvider mvProvider)

Creates a Registry which is a wrapper for this registry including the service name. It provides convenient access to a registry without the need for the service name and/or session tokens. The created Registry is afterwards provided in the constructor of a service which is currently created.

Parameters:

serviceName - The hierarchical name of the service for which to create a registry wrapper.

earlyService - Whether the service is an early service for which initially only the local security manager is available.

mfRegistry - The model factory registry to be used by the designated registry wrapper.

mvProvider - The provider for model view, that are classes providing type-safe access to plugin data. This is usually the model factory registry.

Returns:

A wrapper for this registry providing convenient access via the Registry -interface.

createLocalServiceURI

protected java.net.URI createLocalServiceURI(java.lang.String instanceName)

Creates a local (i.e. not for remote usage) service URI for a given service instance name.

Parameters:

instanceName - The hierarchical name of the service instance.

Returns:

The local URI for the given service instance.

createMBeanName

protected javax.management.ObjectName createMBeanName(java.lang.String serviceName)
                                               throws javax.management.MalformedObjectNameException

Creates the name for the designated service to be available as MBean.

Parameters:

serviceName - The name of the service which to register as MBean.

Returns:

The name of the MBean which to register for the designated service.

Throws:

javax.management.MalformedObjectNameException - If the designated service name cannot be formatted as a valid MBean name, a MalformedObjectNameException will be thrown.

getLocalServiceObject

protected <T extends ADEPT2Service> T getLocalServiceObject(SessionToken session,
                                                            java.lang.String serviceName,
                                                            java.lang.Class<T> requestedType)
                                                     throws ConfigurationException

Returns an instance of the designated service and of the requested type. The service name has to be known to this registry, otherwise a ConfigurationException will be thrown.
Resembles (and uses) AbstractRegistry.getObjectForInstanceName(String, Class, Class[], Object[]).

Type Parameters:

T - The type which the requested service is expected to be of which is a subtype of ADEPT2Service and either the registered service type or a super type hereof.

Parameters:

session - The session which is used to check for access rights on this method.

serviceName - The hierarchical instance name of the service.

requestedType - The type of which the requested object is expected to be. This is a subtype of ADEPT2Service and either the registered service type interface or a super type hereof.

Returns:

An object for the designated service type with the designated service name. The object is never null.

Throws:

ConfigurationException - If

• the model factory registry could not be retrieved (needed for the registry wrapper),
• the service is not registered properly,
• the configuration of the service instance does not provide required configuration values,
• the creation or the initialisation of the service instance fails,

a ConfigurationException will be thrown (encapsulating an AbortServiceException in case the registry could not be loaded).

InvalidServiceStateException - If this registry failed to start or is shut down, an InvalidServiceStateException will be thrown.

checkStartupRequiredService

protected void checkStartupRequiredService(java.lang.String serviceName)

Checks whether the current thread is starting a service right now and whether this service has declared the designated service as a startup-required service type. If it has not, this will be logged.
This method retrieves the necessary information about the starting service from ThreadLocals set when starting a service.

Parameters:

serviceName - The hierarchical instance name of requested required service.

getAndCheckRequiredService

protected java.lang.String getAndCheckRequiredService(SessionToken session,
                                                      java.lang.String usingService,
                                                      java.lang.String usedServiceTypeName)
                                               throws ConfigurationException

Gets the name of the used service of the designated type and for the designated using service. If the using service is an ADEPT2Service, it will be checked whether the used service is declared as required (startup- as well as runtime-required). If it is not required, a QA-notice will be logged.

Parameters:

session - The session which is used to check for access rights on this method.

usingService - The hierarchical instance name of the using service.

usedServiceTypeName - The name of the type the used service is of. This is the name of the registered service type.

Returns:

The hierarchical name of the configured service instance or the name of the default instance of the used service type to be used by the designated using service instance.

Throws:

ConfigurationException - If

• the name of the used service instance (or the default service instance) could not be retrieved,
• the requesting service could not be retrieved locally,

a ConfigurationException will be thrown.

InvalidServiceStateException - If this registry failed to start or is shut down, an InvalidServiceStateException will be thrown.

checkServiceInterface

protected void checkServiceInterface(java.lang.String serviceName,
                                     ADEPT2Service service)
                              throws ConfigurationException

Checks whether the designated service object does fulfill the ADEPT2Service-interface appropriately. This includes returning arrays that are not null for required services and URIs.

Parameters:

serviceName - The name of the service of which to check the interface.

service - The service object of which to check the interface.

Throws:

ConfigurationException - If the designated service does not fulfill the ADEPT2Service-interface appropriately, a ConfigurationException will be thrown.

checkServiceURI

protected void checkServiceURI(SessionToken session,
                               java.net.URI serviceURI)
                        throws ServiceNotKnownException

Validates whether the designated URI is local, well-formed and may identify a service instance.

Parameters:

session - The session which is used to check for access rights on this method.

serviceURI - The local URI to check for validity.

Throws:

ServiceNotKnownException - If the schema of the designated URI does not specify a known communication service, a ServiceNotKnownException will be thrown. This exception will never thrown by this implementation.

java.lang.IllegalArgumentException - If the service URI is invalid, an IllegalArgumentException will be thrown.

checkServiceUriSyntax

protected void checkServiceUriSyntax(java.net.URI serviceUri)

Validates whether the designated URI is well-formed and may identify a service instance.

Parameters:

serviceUri - The URI to check for validity.

Throws:

java.lang.IllegalArgumentException - If the service URI is invalid, an IllegalArgumentException will be thrown.

chooseAppropriateURI

protected java.net.URI chooseAppropriateURI(java.net.URI[] serviceURIs)

Chooses an appropriate URI, that is a local URI or null in case no local URI is found.

Parameters:

serviceURIs - A list of service URIs with which a service is exported.

Returns:

The first URI of the list which is a local URI or null in case no local URI is found.

getInstanceNameFromServiceURI

protected java.lang.String getInstanceNameFromServiceURI(java.net.URI serviceURI)
                                                  throws ServiceNotKnownException

Returns the hierarchical instance name from the service URI.
Only to be called by the registry or communication framework.

Whenever the instance name needs to be derived from a services URI, this method should be called. This keeps the way, how the instance name is stored in the URI more exchangeable.

Parameters:

serviceURI - The service URI.

Returns:

The hierarchical instance name from the service URI.

Throws:

ServiceNotKnownException - If the schema of the designated URI does not specify a known communication service, a ServiceNotKnownException will be thrown. This exception will never thrown by this implementation.

notifyDataSourceToConfMgr

protected void notifyDataSourceToConfMgr(boolean gsmAvailable)

Sets the registry in the configuration manager allowing it to access the data source for runtime configurations. This is also used to set the session factory (again) after the global security manager has become available.
Note that the data source is needed by the global security manager, so it is available as soon as the global security manager is available.

Parameters:

gsmAvailable - Whether the global security manager has become available. This makes the check for the availability of the data source unnecessary.

registryActive

public boolean registryActive()

Gets whether this registry is active, that is, it has signalled its start and is not being shut down.

Returns:

Whether this registry is active, that is, it has signalled its start and is not being shut down.

determineNodeName

public static java.lang.String determineNodeName(java.util.logging.Logger logger)

Determines and returns a unique name for the current platform/cluster node. This is usually the name of the local host with a trailing random ID. If the host name cannot be determined, a random UUID will be used.

Parameters:

logger - The logger where to log information messages on creating the node name.

Returns:

A unique node name based on the local host name or a random UUID.