Package de.aristaflow.adept2.base.registry

Class ServiceRegistry

  • All Implemented Interfaces:
    GlobalInvocationResolver, GlobalRegistryServiceProvider, ConfMgrRegistry, ADEPT2Service, AuthenticatingService, LogService, NameResolution, ServiceThreadHandling
    Direct Known Subclasses:
    BootstrapRegistry
    @ConfigurationDescription(properties={@Property(name="Components.GlobalRegistry",isRequired=true,description="a required sub-registry"),,,,,,,,},validator=ConfigurationValidator.class)
public abstract class ServiceRegistry
extends LocalServiceRegistry
implements GlobalInvocationResolver, GlobalRegistryServiceProvider
    A service registry extends the LocalServiceRegistry to support export and publishing of local services as well as accessing remote services.

    A local service is a service which runs in the same JVM and may be accessed directly (aka. embedded) when needed. One distinguishes exported and non-exported local services. While the LocalServiceRegistry supports only non-exported local services, the service registry allows to export a service, that is, a service is exported via one or more URIs (representing different supported communication protocols) and may be accessed via these from outside (or inside) the JVM. An exported service may furthermore be published at a global registry. This global registry acts as a naming service and resolves unique service names to the corresponding service URIs. Such global URIs are resolved right before accessing the corresponding service. The service registry chooses an appropriate URI (chosen by the supported communication protocol) and will create a stub for the service if required. In case the global URI refers to a local service, the service is used directly and no stub will be created.

    The counterpart of exported local services are remote services. Remote services are provided via stubs and therefore transparent for the user. The stubs are created based on a URI of the corresponding service. This may either be configured (called private remote service) or retrieved from the global registry via the service name (called public remote service). The global registry provides multiple URIs from which an appropriate one can be chosen by the supported communication protocol.

    A CommunicationService needs to be provided for every ServiceRegistry. It encapsulates a protocol stack (usually identified by the simple instance name of a CommunicationService ) and stubs and skeletons using this protocol.
    Services can be exported via ADEPT2ServiceExport-instances provided by the CommunicationService configured for the designated service. These service exports support the management of callbacks which are used for asynchronous notifications of clients (in this case the roles of client and server are inverse).

    Services are managed like normal components except that they have a defined lifecycle. Thus, their declaration resembles the declaration of components to a large extent. They have component types (aka. service types or service interfaces), service instances and implementation classes as well as usage relations (c.f. InstanceToInstanceRegistry).
    The instantiation mode for all services is singleton. If something else is specified in the configuration this is logged and ignored. The implementation class is only needed in case of a local service (c.f. ServiceInformation). A local service instance may also have configuration for export services and if so, an additional flag whether the service should be published with all its URIs at the global registry. For this, the configuration keys ExportVia and PublishService are used. The values of the ExportVia is a list of service instances of ADEPT2ServiceExport. These instances are normal services themselves and need to be configured just like other services.
    Remote services are treated a bit differently. They have a component type declaration and in case of a private remote service an additional URI ( ServiceURI ). They also may exported (ExportVia) However, usually exporting a remote service should be avoided (and some communication services even refuse this) since it just creates overhead. Using the global registry allows to contact the peer hosting the actual service instance directly.

    Just like other registries, the service registry is lazy. All services are instantiated, initialised and started as needed. This may include the starting of other services which are required for a requested service. Of course, only local services can be started, remote services are expected to be running.
    The laziness does not apply to exported services. All local services that are exported as well as the required services are started at constructing time of this registry.

    There are a few system services that are expected to be present. This includes all the service instances for service exports that are used to export services with, at least one stub factory service and exactly one global registry which is either an (exported) local service or a private remote service.

    The stub factory is used by this service registry to create stubs for remote services. These have the same interface as the remote service and encapsulate the communication. It is transparent for the client whether to use a local (embedded) or remote service. Stubs differ from local services in not needing to implement ADEPT2Service. This is reflected in the interface of this service registry: local services are subtypes of ADEPT2Service (<T extends ADEPT2Service>) while stubs do not have a predefined type (<T>). Although stubs will be subtypes of ADEPT2Service if the corresponding service interface is a subtype of ADEPT2Service.
    The instantiation mode does not apply to stubs. Services are singletons as well as their corresponding skeletons (otherwise too many network resources, for instance ports, will be used). Stubs in contrast are instantiated as needed.

    This class parses the following properties from its configuration (in init(URI[], URI[])):

    This class parses the following properties from a registry configuration (in the constructor) - besides the properties parsed by super classes:

    • Field Detail

      • GLOB_STUB_PROXY_ANNOT_CACHE_SIZE

        public static final String GLOB_STUB_PROXY_ANNOT_CACHE_SIZE
        Configuration key for the size of the cache for late bound stubs containing whether a specific class has the ProxyAllow, ProxyCallback or ServerSideProxyAllow annotation or implements ServerSideProxy.
        See Also:
        Constant Field Values

      • GLOB_STUB_PROXY_LAZY_METHOD_VALID_TIME

        public static final String GLOB_STUB_PROXY_LAZY_METHOD_VALID_TIME
        Configuration key for the time a return value of a lazy method remains valid.
        See Also:
        Constant Field Values

      • GLOB_STUB_CACHING_REM_IT_INIT_ALIVE_TIME

        public static final String GLOB_STUB_CACHING_REM_IT_INIT_ALIVE_TIME
        Configuration key for the time in milliseconds to keep caching remote iterators retrieved via late bound stubs (using "global" protocol) alive after creating them and before accessing them.
        See Also:
        Constant Field Values

      • GLOB_STUB_CACHING_REM_IT_ALIVE_TIME_EXTENSION

        public static final String GLOB_STUB_CACHING_REM_IT_ALIVE_TIME_EXTENSION
        Configuration key for the time in milliseconds to extend the alive time of caching remote iterators retrieved via late bound stubs (using "global" protocol) after each access.
        See Also:
        Constant Field Values

      • protocolPriority

        protected Map<String,​Integer> protocolPriority
        All supported protocols (the instance names of all known communication services) mapped to the priority of the protocol. This allows to choose the preferred protocol in case a requested service is available via several protocols.

      • globalRegCache

        protected final GlobalRegistryCache globalRegCache
        The cache for the global registry data, that is, service names, global and local URIs.

      • reexportedServices

        protected final Map<String,​ADEPT2Service> reexportedServices
        All remote services that are reexported by this registry. This maps hierarchical service names to the corresponding service. If the service export failed, the service name will be mapped to null to prevent consecutive export failures.

      • clusterName

        protected final String clusterName
        The name of the cluster this registry belongs to.

      • hierInstName

        protected final String hierInstName
        The hierarchical instance name of this service registry. This is twice the configured (simple) instance name.

    • Constructor Detail

      • ServiceRegistry

        protected ServiceRegistry​(UrlConfigurationManager confMgr,
                          org.apache.commons.configuration2.Configuration configuration,
                          Registry registry)
                   throws AbortServiceException
        Constructs a new 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 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.
        AbortServiceException - If the global registry lock cannot be instantiated, an AbortServiceException will be thrown wrapping the actual exception.

      • ServiceRegistry

        protected ServiceRegistry​(UrlConfigurationManager confMgr,
                          org.apache.commons.configuration2.Configuration configuration,
                          Registry registry,
                          SerialisablePair<String,​String> release)
                   throws AbortServiceException
        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 - If a registry is provided, the release will be taken from it. If no registry is provided, the release has to be provided.
        Throws:
        ConfigurationException - If the password cannot be parsed from the configuration, a ConfigurationException will be thrown.
        AbortServiceException - If the global registry lock cannot be instantiated, an AbortServiceException will be thrown wrapping the actual exception.

    • Method Detail

      • readMetaConfiguration

        protected void readMetaConfiguration​(org.apache.commons.configuration2.Configuration registryConfiguration,
                                     String componentType,
                                     String simpleInstanceName)
                              throws ConfigurationException
        Reads the meta information from the registry for the designated service instance, which is: 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 LocalServiceRegistry
        Parameters:
        registryConfiguration - The configuration which contains the (registry) information for the designated instance.
        componentType - 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
        • the designated service type is not configured for this registry,
        • no implementing class name or implementing object is defined in case of a local service,
        • the implementing object is not an ADEPT2Service,
        • the designated implementing class or object is not a subtype of the registered service interface in case of a local service,
        • the configured URI is not a valid service URI ( getServiceURI(String, Configuration)) in case of a private remote service,
        a ConfigurationException will be thrown.

      • initExportServices

        protected void initExportServices​(SessionToken session)
                           throws AbortServiceException
        Starts and exports all local services that need be exported. If these services have dependencies to other local services, the latter are started and exported before. Dependencies to remote services are not considered, they have to be started. This method does not check whether the service is active since it is only called when initialised. Therefore the service is never active when this method is called.
        Parameters:
        session - The session which is used to check for access rights on this method.
        Throws:
        AbortServiceException - If
        • the model factory registry could not be retrieved (needed for the registry wrapper for creating a new local service instance),
        • an exported service is not registered properly,
        • the configuration of the an exported service instance does not provide required configuration values,
        • the creation of an exported service instance fails,
        • the exported services have cyclic dependencies in their required services,
        • the service load graph needs to be build and the build fails due to an improperly configured service,
        • an exception is thrown while starting a (required) service,
        • a (required) service throws an AbortServiceException while initialised or started,
        • the current thread is interrupted while starting an exported (or required) service,
        an AbortServiceException will be thrown.

      • prepareExport

        protected LocalServiceRegistry.ServiceExportInformation prepareExport​(SessionToken session,
                                                                      String serviceName,
                                                                      ADEPT2Service service)
                                                               throws AbortServiceException
        Prepares the export of the designated service by retrieving the communication service for the export and the retrieving corresponding URIs from its service export. If the service is to be published, publishing is prepared by retrieving appropriate service URIs from the global registry.
        Overrides:
        prepareExport in class LocalServiceRegistry
        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 a communication service to be used for exporting is not known, a ConfigurationException will be thrown since the ExportVia-property is wrong.
        AbortServiceException - If the preparation of the service export fails, an AbortServiceException will be thrown.

      • exportService

        protected void exportService​(SessionToken session,
                             String serviceName,
                             ADEPT2Service service,
                             LocalServiceRegistry.ServiceExportInformation serviceExportInformation)
                      throws AbortServiceException
        Exports the designated service (in case of an exported service) using the designated service export objects and the designated URIs. If desired, the service will also be published at the global registry with the corresponding global service URIs. In case of a non-exported service, this method just returns.

        IMPORTANT!

        • This method must only be called once per service!
        • It has to be called from a correctly synchronised context, usually this is the start procedure of the designated service.
        Overrides:
        exportService in class LocalServiceRegistry
        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 and publish.
        serviceExportInformation - The information on the export services and the URIs to use.
        Throws:
        ConfigurationException - If the service type specified by the hierarchical instance name is not registered, a ConfigurationException will be thrown.
        AbortServiceException - If exporting the service fails, an AbortServiceException will be thrown.
        InvalidServiceStateException - If this registry failed to start or is shut down, an InvalidServiceStateException will be thrown.

      • 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. This implementation actually removes the designated service from the global registry and from the service exports. This is needed when shutting down the service.

        Overrides:
        unpublishService in class LocalServiceRegistry
        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.

      • autoStartServices

        protected void autoStartServices()
                          throws AbortServiceException
        Description copied from class: LocalServiceRegistry
        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.
        Overrides:
        autoStartServices in class LocalServiceRegistry
        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
        Returns the designated service which is either a started local service (see LocalServiceRegistry.getService(SessionToken, String, Class)) or a service stub based on URIs (see getService(SessionToken, URI[], Class)). The URIs are either the configured URI for a private remote service or the global or local ones retrieved from the global registry.
        In case of a local service, required services are also started if appropriate.
        This method checks whether the requested service is a startup-required service and declared as such (see LocalServiceRegistry.checkStartupRequiredService(String)).
        Although the designated service name may be completely unknown to this registry a stub will be created if the service is known to the global registry.
        Overrides:
        getService in class LocalServiceRegistry
        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.
        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 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.
        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.

      • getService

        public <T extends ADEPT2Service> T getService​(SessionToken session,
                                              URI[] serviceURIs,
                                              Class<T> serviceType)
                                       throws ServiceNotKnownException
        Retrieves the service described by the URIs which is either a local service (getService(SessionToken, String, Class)) or a stub for a remote service (getServiceStub(SessionToken, URI, Class)). An appropriate URI will be chosen, that is, a URI with a protocol supported by this registry.
        This method checks whether the requested service is a startup-required service and declared as such (see LocalServiceRegistry.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.
        Overrides:
        getService in class LocalServiceRegistry
        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:
        ServiceNotKnownException - If
        • no appropriate communication service is available for the designated URIs,
        • the service is not registered properly,
        • 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.
        NullArgumentException - If one of the parameters is null, a NullArgumentException will be thrown.
        IllegalArgumentException - If
        • the URIs are not valid,
        • the designated service type interface does not conform to the registered type interface or the interface of the stub,
        a IllegalArgumentException will be thrown.

      • getLocallyExportedService

        protected <T extends ADEPT2Service> T getLocallyExportedService​(SessionToken session,
                                                                URI chosenUri,
                                                                URI[] serviceUris,
                                                                Class<T> serviceType)
                                                         throws ServiceNotKnownException
        Gets the locally exported service identified by the designated URI. If the designated URI does not refer to a locally exported service, null will be returned.
        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.
        chosenUri - The (local) URI that is preferred for retrieving the service. Note that this may or may not be part of the serviceUris.
        serviceUris - The URIs with which the service is requested. These are just for logging purpose.
        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). This will be null if the chosen URI does not refer to a service that is locally known, that is, exported by this registry.
        Throws:
        ServiceNotKnownException - If
        • no appropriate communication service is available for the designated URI,
        • the designated URI is not valid,
        • the service does not fulfil the ADEPT2Service -interface appropriately,
        a ServiceNotKnownException will be thrown.

      • init

        public void init​(URI[] localExportedUris,
                 URI[] globalExportedUris)
          throws AbortServiceException
        Checks all component interfaces to implement ADEPT2Service and reading the own configuration. No service is started here yet. 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 LocalServiceRegistry
        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:
        PropertyNotSetException - If a mandatory property is not set, a PropertyNotSetException will be thrown.
        ConfigurationException - If a ConfigurationException will be thrown.
        AbortServiceException - If a ConfigurationException will be thrown.

      • start

        public void start()
           throws AbortServiceException
        Allows threads waiting for the start to proceed and initialises, starts and exports the services to be exported.
        Specified by:
        start in interface ADEPT2Service
        Overrides:
        start in class LocalServiceRegistry
        Throws:
        ConfigurationException - If
        • the exported or required services have cyclic dependencies,
        • one exported service is not registered properly,
        • the creation of a service object fails,
        • the current thread is interrupted while waiting for the exported or required services to start,
        a ConfigurationException will be thrown.
        AbortServiceException - If
        • the model factory registry could not be retrieved (needed for the registry wrapper for creating a new local service instance),
        • an exported service is not registered properly,
        • the creation of an exported service instance fails,
        • the exported services have cyclic dependencies in their required services,
        • the service load graph needs to be build and the build fails due to an improperly configured service,
        • an exception is thrown while starting a (required) service,
        • the URI of a private remote service is no valid URI,
        • a (required) service throws an AbortServiceException while initialised or started,
        • the current thread is interrupted while starting an exported (or required) service,
        an AbortServiceException will be thrown.

      • beforeLocalTermination

        protected void beforeLocalTermination​(boolean emergency,
                                      String hierServName)
        Description copied from class: LocalServiceRegistry
        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.
        Overrides:
        beforeLocalTermination in class LocalServiceRegistry
        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:
        LocalServiceRegistry.beforeLocalTermination(boolean, String)

      • getServiceInformation

        protected ServiceInformation getServiceInformation​(String instanceName)
        Unlike the overridden method, this method returns null instead of a ConfigurationException since it is legal to ask for a service that is not known locally but to the global registry.
        Note that null will also be returned for declared instances that are no services, e. g. plugin instances. However, these are in the map declaredInstances. When iterating all of these entries there may be some non-services!

        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.

        Overrides:
        getServiceInformation in class LocalServiceRegistry
        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).

      • createRegistryWrapper

        protected Registry createRegistryWrapper​(String serviceName,
                                         boolean earlyService,
                                         InstanceToInstanceRegistry mfRegistry,
                                         ModelViewerProvider mvProvider)
        Also provides the cluster name to the created registry wrapper.

        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.

        Overrides:
        createRegistryWrapper in class LocalServiceRegistry
        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.

      • getLocalServiceObject

        protected <T extends ADEPT2Service> T getLocalServiceObject​(SessionToken session,
                                                            String serviceName,
                                                            Class<T> requestedType)
                                                     throws ConfigurationException
        Returns an instance of the designated service if it is local, null otherwise.

        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[]).

        Overrides:
        getLocalServiceObject in class LocalServiceRegistry
        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).

      • globalRegistryChanged

        public GlobalRegistry globalRegistryChanged​(SessionToken session,
                                            URI globRegUri)
                                     throws ServiceNotKnownException
        Changes the URI of the (default instance of the) global registry to the designated URI. This allows for changing it while running. If the (default instance of the) global registry cannot be retrieved with the designated URI, its URI will not be changed and a ServiceNotKnownException will be thrown.
        The global registry and the corresponding cache will be invalidated.

        In case a global registry provider is available, this will be preferred to the designated URI.

        Parameters:
        session - The session which is used to check for access rights on this method.
        globRegUri - The new URI of the global registry.
        Returns:
        The default instance of the global registry with the designated new URI.
        Throws:
        ServiceNotKnownException - If the default instance of the global registry cannot be retrieved with the new URI, a ServiceNotKnownException will be thrown.

      • getInvocationTarget

        public Pair<InvocationTarget,​URI> getInvocationTarget​(URI uri)
        Description copied from interface: GlobalInvocationResolver
        Gets the invocation target for the designated URI. In case of a global URI this will be transformed to the corresponding local URI. The invocation target for the communication service of the local URI will be returned together with the local URI. In case of a local URI, this will be used directly. If the communication service referred communication service is not an invocation communication service or it cannot be retrieved, a ServiceConnectionException will be thrown.
        This method is only used by the global communication stub.
        Specified by:
        getInvocationTarget in interface GlobalInvocationResolver
        Parameters:
        uri - The URI for which to retrieve the concrete communication service.
        Returns:
        The invocation communication service for the designated URI.

      • invalidateGlobalRegistry

        public void invalidateGlobalRegistry()
        Description copied from interface: GlobalInvocationResolver
        Invalidates the global registry in case of communication problems. If a global URI is resolved to a local URI and there are communication problems with this local URI, the local URI is expected to be invalid and the global registry should be renewed.
        Specified by:
        invalidateGlobalRegistry in interface GlobalInvocationResolver

      • getCommunicationService

        protected CommunicationService<?,​?,​?,​?> getCommunicationService​(SessionToken session,
                                                                                  String simpleInstanceName)
                                                                           throws ServiceNotKnownException
        Returns the communication service with the designated instance name. Additionally, it is checked whether the IP-address of the communication service is valid with respect of the licence. If there is no licence manager, the returned service is tracked and checked as soon as the licence manager is available.
        The service will be ignored when checking for used undeclared startup-services.
        Parameters:
        session - The session which is used to check for access rights on this method.
        simpleInstanceName - The simple (non-hierarchical) instance name of the communication service.
        Returns:
        The communication service with the given instance name.
        Throws:
        InvalidServiceStateException - If this registry failed to start or is shut down, an InvalidServiceStateException will be thrown.
        ServiceNotKnownException - If the designated instance name does not specify a known communication service, a ServiceNotKnownException will be thrown.

      • checkServiceURI

        protected void checkServiceURI​(SessionToken session,
                               URI serviceURI)
                        throws ServiceNotKnownException
        Validates whether the designated URI is well-formed and may identify a service instance.
        Overrides:
        checkServiceURI in class LocalServiceRegistry
        Parameters:
        session - A valid session token that authorise this method to access the communication service designated by the given URI for check.
        serviceURI - The 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.

      • prioritiseProtocols

        protected Map<String,​Integer> prioritiseProtocols​(List<String> protocolNames)
        Sets priorities for the designated names as well as the local protocol. This allows to choose the preferred protocol in case a requested service is available via several protocols.
        Parameters:
        protocolNames - The names of the protocols (the instance names of all known communication services) known by this registry.
        Returns:
        A mapping from protocol names to a priority for the corresponding protocol. This is used for choosing a protocol for services being available via several protocols.

      • chooseAppropriateURI

        protected URI chooseAppropriateURI​(URI[] serviceURIs)
        Chooses an appropriate URI for retrieving the service having the designated URIs. The URI is chosen based on the priority of all known protocols.
        Overrides:
        chooseAppropriateURI in class LocalServiceRegistry
        Parameters:
        serviceURIs - A list of service URIs with which a service is exported.
        Returns:
        The URI with the protocol having the protocol with the highest priority or null in case none of the protocols are supported (none specifies a communication service known by this registry.

      • resolveInstanceName

        protected abstract Pair<String,​String> resolveInstanceName​(org.apache.commons.configuration2.Configuration conf)
                                                          throws ConfigurationException
        Gets the cluster and the instance name for this registry from the designated configuration.

        Note that this method is called from the constructor and must not rely on instance fields!

        Parameters:
        conf - The configuration to retrieve the instance name from.
        Returns:
        The cluster and the instance name for this registry from the designated configuration. The cluster name may be null.
        Throws:
        ConfigurationException - If the instance name does not exist in the configuration, a ConfigurationException will be thrown. However, this should never happen if the configuration is validated beforehand.

      • getInstanceNameFromServiceURI

        public 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.

        Overrides:
        getInstanceNameFromServiceURI in class LocalServiceRegistry
        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.
        IllegalArgumentException - If the service URI is invalid for the communication service designated by the given service URI, an IllegalArgumentException will be thrown.