de.aristaflow.adept2.base.globalregistry

Interface GlobalRegistry

All Superinterfaces:

ADEPT2Service

public interface GlobalRegistry
extends ADEPT2Service

Global registry for querying PMS-wide service instances.

Overview

The global registry is responsible for keeping track of the service instances of the ADEPT2 core components which are accessible through the network, and with which communication techniques they may be contacted.

Note: The orchestration of the services in the sense "which service uses which other service instance" is not part of the global registry. The local registries are responsible for this kind of orchestration.

The following image provides an overview of the role of the services, the local registries and the global registry.

Communication with the Global Registry

Whenever a service, e.g. an execution manager, requires another service, e.g. a data manager, it queries the local Registry. The local registry knows which instance of the data manager shall be used by the calling execution manager. In case it is a local service instance, it will be returned immediately. In case it is a remote service instance, the local registry queries the global registry for the location and communication techniques of the remote service. This information is used by the local registry to locally create a stub and return it to the calling service, i.e. the execution manager in the example.
The following image provides an outline of the whole process:

Service URIs and object URIs

Service URIs are used for specifying the type, the instance, the location and the communication technique of a service.
Example: simple-rmi://main.example.com:43005/ProcessManager/PM1 describes that the ProcessManager instance named PM1 can be reached using simple-rmi on the host main.example.com at the port 43005.
For further information see ADEPT2ServiceExport.

TODO will reject all URIs with local as scheme.

Object URIs are used across the system for identifying an object including the service where it belongs to. The service type and the service name are part of the object URI - e.g. template://ProcessManager/PM1/3 identifies the process template with ID 3, which is stored in the ProcessManager with the name PM1.
In the global registry, object URIs can be used for resolving the service's URIs providing the object's URI to LocalServiceRegistry.getService(SessionToken, URI[], Class).

Service Registration

The global registry does not statically keep all known services. Instead, the local registries need to register the services they provide to the public at the global registry. In case a service becomes unavailable, the local registry has to deregister it from the global registry.

Service Life Cycle, Persistence, Pings

The global registry has a minimal persistence of the list of known services. This allows for maintenance restarts of the global registry without the need of a re-registration of the services by the local registries.
During startup, the stored URIs will be used to "ping" the services, for proving their availability.
TODO further docs / requirements...

Future Work

TODO also keep track of "who" queried the process instances?

TODO block a shutdown of a service and inform other services which used the service?

TODO global registry as service monitor and service event monitor?

TODO global registry as central point of authority concerning service requests?

TODO above will require local services to have a public interface for maintenance calls. => preliminary LocalServiceRegistry

TODO configuration management interface?

TODO URIs for objects, URLs for services?

TODO use hierarchical instance names?

Author:

Kevin Goeser, Ulrich Kreher

Method Summary

Modifier and Type	Method and Description
java.util.Map<java.lang.String,java.util.Map<java.lang.String,Pair<java.util.List<java.net.URI>,java.util.List<java.net.URI>>>>	getAllServices() Gets the global and local URIs of all published services currently managed by the global registry.
java.util.Map<java.lang.String,Pair<java.util.List<java.net.URI>,java.util.List<java.net.URI>>>	getAllServices(java.lang.String serviceType) Gets the global and local URIs of all published service instances of the designated service type currently managed by the global registry.
GlobalServiceExport	getGlobalServiceExport() Gets the global service export interface, that allows arbitrary services, to be exported via a corresponding callback object.
java.util.List<java.net.URI>	getGlobalServiceUris(java.lang.String clusterName, java.lang.String serviceType, java.lang.String serviceName) Gets the global URIs with which the designated service instance is published.
java.util.List<java.net.URI>	getGlobalServiceUris(java.lang.String clusterName, java.net.URI entityUri) Gets the global URIs of the service, which is referenced in the given object URI.
java.util.List<java.net.URI>	getLocalServiceUris(java.lang.String clusterName, java.lang.String serviceType, java.lang.String serviceName) Gets the local URIs with which the designated service instance is published at this global registry.
java.util.List<java.net.URI>	getLocalServiceUris(java.lang.String clusterName, java.net.URI entityUri) Gets the local URIs of the service, which is referenced in the given object URI.
java.util.List<java.net.URI>	getLocalServiceUris(java.lang.String clusterName, java.net.URI[] globalServiceUris) Gets the local service URI of a service having the designated global URIs.
void	invalidate(SessionToken session, java.lang.String clusterName, java.lang.String serviceType, java.lang.String serviceName) Informs the global registry that the designated service is not reachable any more.
void	invalidate(SessionToken session, java.lang.String clusterName, java.net.URI[] globalServiceUris) Informs the global registry that the designated service is not reachable any more.
java.util.List<java.net.URI>	prepareServicePublishing(SessionToken session, java.lang.String clusterName, java.lang.String serviceType, java.lang.String serviceName, java.util.List<java.net.URI> localServiceUris) Prepares the specified service for being published.
void	publishService(SessionToken session, java.lang.String serviceType, java.lang.String serviceName, java.util.List<java.net.URI> globalServiceUris) Publishes the designated service with the designated global URIs and registers the designated local URIs for it.
boolean	unpublishService(SessionToken session, java.lang.String clusterName, java.lang.String serviceType, java.lang.String serviceName, java.util.List<java.net.URI> globalServiceUris) Unpublishes the designated service with the designated global URIs.

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

getLocalUris, getRelease, getRuntimeRequiredServices, getServiceInstanceName, getStartupRequiredServices, getURIs, init, ping, preShutdown, shutdown, start

Method Detail

getGlobalServiceUris

java.util.List<java.net.URI> getGlobalServiceUris(java.lang.String clusterName,
                                                  java.lang.String serviceType,
                                                  java.lang.String serviceName)
                                           throws ServiceNotKnownException

Gets the global URIs with which the designated service instance is published.

Parameters:

clusterName - The name of the cluster of the requested service.

serviceType - The type of the service of which to get the global URIs.

serviceName - The simple instance name of the service of which to get the global URIs.

Returns:

The global URIs for the designated published service. If the service is only prepared yet, an empty list will be returned.

Throws:

ServiceNotKnownException - If the designated service is not known by this global registry, a ServiceNotKnownException will be thrown. If the provided cluster name is different from the cluster name of this registry, a WrongClusterException will be thrown.

getLocalServiceUris

java.util.List<java.net.URI> getLocalServiceUris(java.lang.String clusterName,
                                                 java.lang.String serviceType,
                                                 java.lang.String serviceName)
                                          throws ServiceNotKnownException

Gets the local URIs with which the designated service instance is published at this global registry. These URIs are the ones with which the service is locally exported, so they refer to a specific protocol and server.

Parameters:

clusterName - The name of the cluster of the requested service.

serviceType - The type of the service of which to get the local URIs.

serviceName - The simple instance name of the service of which to get the local URIs.

Returns:

The local URIs for the designated published service. If the service is only prepared yet, an empty list will be returned.

Throws:

ServiceNotKnownException - If the designated service is not known by this global registry, a ServiceNotKnownException will be thrown. If the provided cluster name is different from the cluster name of this registry, a WrongClusterException will be thrown.

getGlobalServiceUris

java.util.List<java.net.URI> getGlobalServiceUris(java.lang.String clusterName,
                                                  java.net.URI entityUri)
                                           throws ServiceNotKnownException

Gets the global URIs of the service, which is referenced in the given object URI.

Parameters:

clusterName - The name of the cluster of the requested entity.

entityUri - The URI of an entity.

Returns:

The global URIs for the published service referenced by the designated entity. If the service is not known, null will be returned. If the service is only prepared yet, an empty list will be returned.

Throws:

ServiceNotKnownException - If the service the entity URI refers to is not known by this global registry, a ServiceNotKnownException will be thrown. If the provided cluster name is different from the cluster name of this registry, a WrongClusterException will be thrown.

java.lang.IllegalArgumentException - If the entityURI is not a valid object URI.

getLocalServiceUris

java.util.List<java.net.URI> getLocalServiceUris(java.lang.String clusterName,
                                                 java.net.URI entityUri)
                                          throws ServiceNotKnownException

Gets the local URIs of the service, which is referenced in the given object URI. These URIs are the ones with which the service is locally exported, so they refer to a specific protocol and server.

Parameters:

clusterName - The name of the cluster of the requested entity.

entityUri - The URI of an entity.

Returns:

The global URIs for the published service referenced by the designated entity. If the service is not known, null will be returned. If the service is only prepared yet, an empty list will be returned.

Throws:

ServiceNotKnownException - If the service the entity URI refers to is not known by this global registry, a ServiceNotKnownException will be thrown. If the provided cluster name is different from the cluster name of this registry, a WrongClusterException will be thrown.

java.lang.IllegalArgumentException - If the entityUri is not a valid object URI.

getAllServices

java.util.Map<java.lang.String,java.util.Map<java.lang.String,Pair<java.util.List<java.net.URI>,java.util.List<java.net.URI>>>> getAllServices()

Gets the global and local URIs of all published services currently managed by the global registry.

Returns:

A map of all known services, indexed by service type, simple service name mapping to the corresponding global and local URIs. If no service is known, an empty map will be returned.

getAllServices

java.util.Map<java.lang.String,Pair<java.util.List<java.net.URI>,java.util.List<java.net.URI>>> getAllServices(java.lang.String serviceType)

Gets the global and local URIs of all published service instances of the designated service type currently managed by the global registry.

Parameters:

serviceType - The type of the service for which to get all instances and their global and local URIs.

Returns:

A map of all known services, indexed by simple service name mapping to the corresponding global and local URIs. If the designated service type is unknown, an empty map will be returned.

getLocalServiceUris

java.util.List<java.net.URI> getLocalServiceUris(java.lang.String clusterName,
                                                 java.net.URI[] globalServiceUris)
                                          throws ServiceNotKnownException

Gets the local service URI of a service having the designated global URIs. The service may more global than the designated ones, but there must not be an unknown URI or one of a different service.

Parameters:

clusterName - The name of the cluster of the requested service.

globalServiceUris - The global URIs of a specific service.

Returns:

A list of local service URIs of the specified service.

Throws:

ServiceNotKnownException - If one of the designated URIs is unknown or not all URIs refer to the same service, a ServiceNotKnownException will be thrown. If the provided cluster name is different from the cluster name of this registry, a WrongClusterException will be thrown.

prepareServicePublishing

java.util.List<java.net.URI> prepareServicePublishing(SessionToken session,
                                                      java.lang.String clusterName,
                                                      java.lang.String serviceType,
                                                      java.lang.String serviceName,
                                                      java.util.List<java.net.URI> localServiceUris)
                                               throws WrongClusterException

Prepares the specified service for being published. This creates globally unique URIs for the service. Afterwards the service can be published and is then available via the URIs.
The returned URIs are reserved for the service until unpublished. If starting the service fails, just unpublish it, so the URIs can be reused.

Parameters:

session - The session which is used to identify the publishing service. Only the publishing service may publish an unpublish the service.

clusterName - The name of the cluster in which to publish the service.

serviceType - The type of the service for which to prepare its publishing.

serviceName - The simple instance name of the service for which to prepare its publishing.

localServiceUris - The local service URIs the service is exported locally and can be reached with.

Returns:

The global URIs for the published service. These have to be used when actually publishing the service afterwards.

Throws:

WrongClusterException - If the provided cluster name is different from the cluster name of this registry, a WrongClusterException will be thrown.

java.lang.IllegalArgumentException - If there is already a service with the designated name or there are problems retrieving the required information from the designated session token, an IllegalArgumentException will be thrown.

publishService

void publishService(SessionToken session,
                    java.lang.String serviceType,
                    java.lang.String serviceName,
                    java.util.List<java.net.URI> globalServiceUris)
             throws ServiceNotKnownException

Publishes the designated service with the designated global URIs and registers the designated local URIs for it. This has to be prepared appropriately. Only the service that prepared the service publishing (identified by the designated session token) may call this method. The designated URIs have to be the ones from preparing the service publishing.

Parameters:

session - The session which is used to identify the publishing service. This has to be the same service that prepared publishing.

serviceType - The type of the service for which to prepare its publishing.

serviceName - The simple instance name of the service for which to prepare its publishing.

globalServiceUris - The global service URI with which the service publishing has been prepared.

Throws:

ServiceNotKnownException - If the service has not been prepared for publishing, a ServiceNotKnownException will be thrown.

java.lang.IllegalArgumentException - If

• the service URIs do not match the ones returned when preparing,
• there are problems retrieving the required information from the designated session token or
• the designated session token does not refer to the service preparing the publishing,

an IllegalArgumentException will be thrown.

unpublishService

boolean unpublishService(SessionToken session,
                         java.lang.String clusterName,
                         java.lang.String serviceType,
                         java.lang.String serviceName,
                         java.util.List<java.net.URI> globalServiceUris)
                  throws ServiceNotKnownException

Unpublishes the designated service with the designated global URIs. The service has to be prepared and published appropriately. Only the service that prepared and published the service (identified by the designated session token) may call this method. The designated URIs have to be the ones from preparing the service publishing.

Parameters:

session - The session which is used to identify the publishing service. This has to be the same service that prepared publishing.

clusterName - The name of the cluster in which to unpublish the service.

serviceType - The type of the service for which to prepare its publishing.

serviceName - The simple instance name of the service for which to prepare its publishing.

globalServiceUris - The global service URI with which the service publishing has been prepared.

Returns:

Whether the designated service was published before and has been successfully unpublished. If the service is unknown or has not been published, false will be returned.

Throws:

ServiceNotKnownException - If the service has not been prepared for publishing, a ServiceNotKnownException will be thrown. If the provided cluster name is different from the cluster name of this registry, a WrongClusterException will be thrown.

java.lang.IllegalArgumentException - If

• the service URIs do not match the ones returned when preparing,
• there are problems retrieving the required information from the designated session token or
• the designated session token does not refer to the service preparing the publishing,

an IllegalArgumentException will be thrown.

invalidate

void invalidate(SessionToken session,
                java.lang.String clusterName,
                java.net.URI[] globalServiceUris)
         throws WrongClusterException

Informs the global registry that the designated service is not reachable any more. The global registry should verify this asynchronously and remove the service if appropriate.
Implementations should check the designated session token for whether they are currently already invalidating with this to prevent loops.

Parameters:

session - The session token with which to check for access rights and recursive calls of this method.

clusterName - The name of the cluster in which to invalidate the service.

globalServiceUris - The global URIs of the invalid service.

Throws:

WrongClusterException - If the provided cluster name is different from the cluster name of this registry, a WrongClusterException will be thrown.

invalidate

void invalidate(SessionToken session,
                java.lang.String clusterName,
                java.lang.String serviceType,
                java.lang.String serviceName)
         throws WrongClusterException

Informs the global registry that the designated service is not reachable any more. The global registry should verify this asynchronously and remove the service if appropriate.
Implementations should check the designated session token for whether they are currently already invalidating with this to prevent loops.

Parameters:

session - The session token with which to check for access rights and recursive calls of this method.

clusterName - The name of the cluster in which to invalidate the service.

serviceType - The type of the service which to invalidate.

serviceName - The simple instance name of the service which to invalidate.

Throws:

WrongClusterException - If the provided cluster name is different from the cluster name of this registry, a WrongClusterException will be thrown.

getGlobalServiceExport

GlobalServiceExport getGlobalServiceExport()

Gets the global service export interface, that allows arbitrary services, to be exported via a corresponding callback object. This enables services on machines disallowed to accept incoming connections to be globally available.

Returns:

The interface that exports arbitrary services and thus makes them globally available even if the corresponding server machines are not allowed to accept incoming connections.