de.aristaflow.adept2.base.registry

Class ServiceRegistry

java.lang.Object

de.aristaflow.adept2.base.service.AbstractADEPT2Service

de.aristaflow.adept2.base.service.AbstractAuthenticatedService

de.aristaflow.adept2.base.registry.AbstractRegistry

de.aristaflow.adept2.base.registry.PluginRegistry

de.aristaflow.adept2.base.registry.InstanceToInstanceRegistry

de.aristaflow.adept2.base.registry.LocalServiceRegistry

de.aristaflow.adept2.base.registry.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=ServiceRegistry.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 just have a component type declaration and in case of a private remote service an additional URI ( ServiceURI ). No further configuration is needed and parsed. This disallows the (local) exporting of remote services which does not make sense since the services are already exported.

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

• Instances.CommunicationService ( BaseConstants.COMPONENT_TYPE_COMMUNICATION_SERVICE )

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

• <InstanceName>.ExportVia ( ConfigurationConstants.SERVICE_EXPORT_VIA )
• <InstanceName>.PublishService ( ConfigurationConstants.SERVICE_PUBLISH_SERVICE )
• <InstanceName>.ServiceURI ( ConfigurationConstants.PROPERTY_REGISTRY_SERVICE_URI )

Author:

Ulrich Kreher

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ServiceRegistry.ConfigurationValidator Checks the configuration of the ServiceRegistry.

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

LocalServiceRegistry.ServiceExportInformation, LocalServiceRegistry.ServiceNameResolution, LocalServiceRegistry.ServiceStarter

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

PluginRegistry.URLClassloaderPrivilegedAction

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

AbstractRegistry.DefaultNameResolution, AbstractRegistry.InstanceInformation, AbstractRegistry.InstantiationMode

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

AbstractADEPT2Service.ActiveSessions

Field Summary

Fields

Modifier and Type	Field and Description
protected java.lang.String	clusterName The name of the cluster this registry belongs to.
protected GlobalRegistryCache	globalRegCache The cache for the global registry data, that is, service names, global and local URIs.
protected java.lang.String	hierInstName The hierarchical instance name of this service registry.
protected java.util.Map<java.lang.String,java.lang.Integer>	protocolPriority All supported protocols (the instance names of all known communication services) mapped to the priority of the protocol.

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

autoStartServices, failedServices, gsmAvailable, nodeName, release, serviceStarterPool, shuttingDown, startedServices, startingLock, startingRequiredServices, startingService

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

usedInstances

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

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

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

componentInterfaces, configurationManager, declaredInstances, INIT_INSTANTIATED_OBJECT_METHOD, nameResolution, singletonInstances

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

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

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

CONF_CSV_LOGGING, configuration, logger, registry, runtimeRequiredServices, startupRequiredServices

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
protected void	autoStartServices() Prepares the global security manager, authenticates this registry, provides the data sources for the runtime configurations to the configuration manager if appropriate, and starts all services to be automatically started at startup of this registry.
protected void	checkServiceURI(SessionToken session, java.net.URI serviceURI) Validates whether the designated URI is well-formed and may identify a service instance.
protected java.net.URI	chooseAppropriateURI(java.net.URI[] serviceURIs) Chooses an appropriate URI for retrieving the service having the designated URIs.
protected javax.management.ObjectName	createMBeanName(java.lang.String serviceName) Creates the name for the designated service to be available as MBean.
protected Registry	createRegistryWrapper(java.lang.String serviceName, boolean earlyService, InstanceToInstanceRegistry mfRegistry, ModelViewerProvider mvProvider) Also provides the cluster name to the created registry wrapper.
protected void	exportService(SessionToken session, java.lang.String serviceName, ADEPT2Service service, LocalServiceRegistry.ServiceExportInformation serviceExportInformation) Exports the designated service (in case of an exported service) using the designated service export objects and the designated URIs.
protected CommunicationService<?,?,?,?>	getCommunicationService(SessionToken session, java.lang.String simpleInstanceName) Returns the communication service with the designated instance name.
GlobalRegistry	getGlobalRegistry(SessionToken session) Returns a reference to (the default instance of) the global registry.
java.lang.String	getInstanceNameFromServiceURI(java.net.URI serviceURI) Returns the hierarchical instance name from the service URI.
Pair<InvocationTarget,java.net.URI>	getInvocationTarget(java.net.URI uri) Gets the invocation target for the designated URI.
protected <T extends ADEPT2Service> T	getLocallyExportedService(SessionToken session, java.net.URI chosenUri, java.net.URI[] serviceUris, java.lang.Class<T> serviceType) Gets the locally exported service identified by the designated URI.
protected <T extends ADEPT2Service> T	getLocalServiceObject(SessionToken session, java.lang.String serviceName, java.lang.Class<T> requestedType) Returns an instance of the designated service if it is local, null otherwise.
<T extends ADEPT2Service> T	getService(SessionToken session, java.lang.String serviceName, java.lang.Class<T> serviceType) 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)).
<T extends ADEPT2Service> T	getService(SessionToken session, java.net.URI[] serviceURIs, java.lang.Class<T> serviceType) 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)).
protected ServiceInformation	getServiceInformation(java.lang.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.
GlobalRegistry	globalRegistryChanged(SessionToken session, java.net.URI globRegUri) Changes the URI of the (default instance of the) global registry to the designated URI.
void	init(java.net.URI[] localExportedUris, java.net.URI[] globalExportedUris) Checks all component interfaces to implement ADEPT2Service and reading the own configuration.
protected void	initExportServices(SessionToken session) Starts and exports all local services that need be exported.
void	invalidateGlobalRegistry() Invalidates the global registry in case of communication problems.
protected LocalServiceRegistry.ServiceExportInformation	prepareExport(SessionToken session, java.lang.String serviceName, ADEPT2Service service) Prepares the export of the designated service by retrieving the communication service for the export and the retrieving corresponding URIs from its service export.
protected java.util.Map<java.lang.String,java.lang.Integer>	prioritiseProtocols(java.util.List<java.lang.String> protocolNames) Sets priorities for the designated names as well as the local protocol.
protected void	readMetaConfiguration(Configuration registryConfiguration, java.lang.String componentType, java.lang.String simpleInstanceName) Reads the meta information from the registry for the designated service instance, which is: the implementing class or the implementing object for a local service service instances for exporting for a local service publish service flag for an exported local service service URI for a private remote 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.
protected abstract Pair<java.lang.String,java.lang.String>	resolveInstanceName(Configuration conf) Gets the cluster and the instance name for this registry from the designated configuration.
void	start() Allows threads waiting for the start to proceed and initialises, starts and exports the services to be exported.
protected void	unpublishService(SessionToken session, java.lang.String serviceName, ADEPT2Service service) Removes the designated service from the global registry and from the service exports.

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

checkServiceInterface, checkServiceUriSyntax, checkStartupRequiredService, createLocalServiceURI, determineNodeName, getAndCheckRequiredService, getConfiguredPlugin, getGlobalSequence, getInstantiationMode, getRegistry, getSecurityManager, getServiceForInstance, notifyDataSourceToConfMgr, prepareGlobalSecurityManager, registryActive, renewConfiguration, shutdown, startLocalService, syncExecute, terminate, terminateService

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

getUsedComponentInstanceNameForInstance, getUsedObjectForInstance

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

createPluginLoader, getConfiguredPlugin, getConfiguredPlugin, getConfiguredPlugins, prepareRuntimePlugin, readMetaConfiguration

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

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

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

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

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

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

Methods inherited from class java.lang.Object

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

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

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

Field Detail

protocolPriority

protected java.util.Map<java.lang.String,java.lang.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.

clusterName

protected final java.lang.String clusterName

The name of the cluster this registry belongs to.

hierInstName

protected final java.lang.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,
                          Configuration configuration,
                          Registry registry)
                   throws ConfigurationException

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.

ServiceRegistry

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

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

Parameters:

configuration - The configuration of the created service registry instance.

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

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

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

Method Detail

readMetaConfiguration

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

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

• the implementing class or the implementing object for a local service
• service instances for exporting for a local service
• publish service flag for an exported local service
• service URI for a private remote 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 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,
                                                                      java.lang.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 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,
                             java.lang.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,
                                java.lang.String serviceName,
                                ADEPT2Service service)

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

This implementation does nothing and is only for extension in subclasses. 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,
                                              java.lang.String serviceName,
                                              java.lang.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.

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

getService

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

Retrieves the service described by the URIs 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.

java.lang.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,
                                                                java.net.URI chosenUri,
                                                                java.net.URI[] serviceUris,
                                                                java.lang.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. never null.

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(java.net.URI[] localExportedUris,
                 java.net.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

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

a ConfigurationException will be thrown.

AbortServiceException - If

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

a ConfigurationException will be thrown.

start

public void start()
           throws AbortServiceException

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.

getServiceInformation

protected ServiceInformation getServiceInformation(java.lang.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(java.lang.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.

createMBeanName

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

Description copied from class: LocalServiceRegistry

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

Overrides:

createMBeanName in class LocalServiceRegistry

Parameters:

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

Returns:

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

Throws:

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

getLocalServiceObject

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

Returns an instance of the designated service 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).

getGlobalRegistry

public GlobalRegistry getGlobalRegistry(SessionToken session)
                                 throws ServiceNotKnownException

Returns a reference to (the default instance of) the global registry. It will be ignored when checking for used undeclared startup-services.
This uses adaptAndGetGlobalRegistry(SessionToken, URI) so in case of an available global registry provider, the global registry may change.

Specified by:

getGlobalRegistry in interface GlobalRegistryServiceProvider

Parameters:

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

Returns:

The global registry which provides access to public services.

Throws:

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

ServiceNotKnownException - If the global registry cannot be retrieved, an ServiceNotKnownException will be thrown.

globalRegistryChanged

public GlobalRegistry globalRegistryChanged(SessionToken session,
                                            java.net.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,java.net.URI> getInvocationTarget(java.net.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,
                                                                java.lang.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,
                               java.net.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.

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

prioritiseProtocols

protected java.util.Map<java.lang.String,java.lang.Integer> prioritiseProtocols(java.util.List<java.lang.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 java.net.URI chooseAppropriateURI(java.net.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<java.lang.String,java.lang.String> resolveInstanceName(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 java.lang.String getInstanceNameFromServiceURI(java.net.URI serviceURI)
                                               throws ServiceNotKnownException

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

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

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.

java.lang.IllegalArgumentException - If the service URI is invalid for the communication service designated by the given service URI, an IllegalArgumentException will be thrown.