Package de.aristaflow.adept2.base.registry

Class 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=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:

    • Field Detail

      • nodeName

        protected final String nodeName
        The unique name of the node this registry and the using service belong to.

      • autoStartServices

        protected final Set<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 Stack<Pair<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 ConcurrentMap<String,​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 Map<String,​Lock> startingLock
        While starting and while checking for started, a service a write lock is needed. This prevents accidentally multiple starting.

      • serviceStartLocker

        protected final transient ObjectCounting<String> serviceStartLocker
        A count for the threads currently waiting to start or starting a service. This allows to remove the service start locks from startingLock properly.

      • serviceStarterPool

        protected 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 ThreadLocal<Stack<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 ThreadLocal<Stack<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.

      • 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,
                               org.apache.commons.configuration2.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,
                               org.apache.commons.configuration2.Configuration configuration,
                               Registry registry,
                               SerialisablePair<String,​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,
                                    String usingInstanceName,
                                    Object usingInstance,
                                    String pluginTypeName,
                                    Class<T> componentType,
                                    String pluginInstanceName,
                                    Class<?>[] additionalParameterTypes,
                                    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 a ConfigurationException will be thrown.

      • renewConfiguration

        protected void renewConfiguration​(org.apache.commons.configuration2.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​(org.apache.commons.configuration2.Configuration registryConfiguration,
                                     String serviceType,
                                     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​(String serviceType,
                                                                  String simpleName,
                                                                  org.apache.commons.configuration2.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,
                                                                      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 hierarchical 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,
                             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,
                                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 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:
        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,
                                 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,
                                              String serviceName,
                                              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,
                                              URI[] serviceURIs,
                                              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.
        IllegalArgumentException - If the service URI is invalid, an IllegalArgumentException will be thrown.

      • getServiceForInstance

        protected <T extends ADEPT2Service> T getServiceForInstance​(SessionToken session,
                                                            String usingService,
                                                            String usedServiceTypeName,
                                                            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.
        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,
                                                     String registryTypeName,
                                                     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,
                                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​(URI[] localExportedUris,
                 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 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 PluginRegistry
        Parameters:
        emergency - Whether the shutdown will be an emergency shutdown.

      • terminate

        protected void terminate​(boolean emergency,
                         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.

      • beforeLocalTermination

        protected void beforeLocalTermination​(boolean emergency,
                                      String hierServName)
        This method is called after this registry has prepared its shutdown procedure but before the local services are terminated. It allows subclasses to handle termination stuff.
        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.
        See Also:
        beforeLocalTermination(boolean, String)

      • getServiceInformation

        protected ServiceInformation getServiceInformation​(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 AtomicLong getGlobalSequence​(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​(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 URI createLocalServiceURI​(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 ObjectName createMBeanName​(String serviceName)
                              throws 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:
        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,
                                                            String serviceName,
                                                            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​(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 String getAndCheckRequiredService​(SessionToken session,
                                            String usingService,
                                            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​(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,
                               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.
        IllegalArgumentException - If the service URI is invalid, an IllegalArgumentException will be thrown.

      • checkServiceUriSyntax

        protected void checkServiceUriSyntax​(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:
        IllegalArgumentException - If the service URI is invalid, an IllegalArgumentException will be thrown.

      • chooseAppropriateURI

        protected URI chooseAppropriateURI​(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 String getInstanceNameFromServiceURI​(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 String determineNodeName​(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.