de.aristaflow.adept2.base.service

Interface ServiceAccess

All Superinterfaces:

ModelViewerProvider, NameResolution

All Known Subinterfaces:

ADEPT2ClientService, Registry

All Known Implementing Classes:

MultiplexingClientService, RegistryWrapper

public interface ServiceAccess
extends ModelViewerProvider, NameResolution

This interface provides components and services initialised and started by the registry framework with access to other services and components.

Author:

Ulrich Kreher

Method Summary

Modifier and Type	Method and Description
<T> T	getConfiguredPlugin(SessionToken session, java.lang.Object usingInstance, java.lang.String pluginTypeName, java.lang.Class<T> pluginType) Retrieves the default plugin of the designated type which is configured for the designated (using) instance.
<T> T	getConfiguredPlugin(SessionToken session, java.lang.Object usingInstance, java.lang.String pluginTypeName, java.lang.Class<T> pluginType, java.lang.String pluginInstanceName) Retrieves the plugin having the designated type and instance name as well as type and which is configured for the designated (using) instance.
<T> java.util.Map<java.lang.String,T>	getConfiguredPlugins(SessionToken session, java.lang.Object usingInstance, java.lang.String pluginTypeName, java.lang.Class<T> pluginType) Retrieves all plugin instances (pre-configured and dynamic) of the designated plugin type.
java.lang.Class<?>	getInterfaceForComponentType(java.lang.String componentType) Returns the class object of the corresponding interface / superclass, if the component type is declared.
<T> T	getModelFactory(java.lang.String modelFactoryName, java.lang.Class<T> modelFactoryType) Gets the designated model factory registry.
<T extends ADEPT2Service> T	getService(SessionToken session, java.lang.String serviceName, java.lang.Class<T> serviceType) Returns the designated service which is either a local service or a service stub that is retrieved from the global registry if the service is not known to this registry but to the global registry.
<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 stub that is retrieved from the global registry if the service is not known to this registry but to the global registry.
<T extends ADEPT2Service> T	getServiceOfType(SessionToken session, java.lang.String serviceTypeName, java.lang.Class<T> serviceType) Returns the service instance of the designated service type which is configured for usage by this (the requesting) service instance.

Methods inherited from interface de.aristaflow.adept2.model.common.ModelViewerProvider

getModelViewerClass

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

getComponentType, getFormattedSignature, getHierarchicalInstanceName, getSimpleInstanceName

Method Detail

getInterfaceForComponentType

java.lang.Class<?> getInterfaceForComponentType(java.lang.String componentType)
                                         throws ConfigurationException

Returns the class object of the corresponding interface / superclass, if the component type is declared. If not, the method throws a ConfigurationException. This method must not to be called by clients; it is only for the registry and the communication framework.

Parameters:

componentType - The name of the component type of which to retrieve the configured interface.

Returns:

The class object of the corresponding interface / superclass.

Throws:

ConfigurationException - If the designated component type is not configured for this registry, a ConfigurationException will be thrown.

getModelFactory

<T> T getModelFactory(java.lang.String modelFactoryName,
                      java.lang.Class<T> modelFactoryType)
               throws ServiceNotKnownException

Gets the designated model factory registry.

Type Parameters:

T - The type of the requested model factory registry.

Parameters:

modelFactoryName - The name of the requested model factory. Use the names declared in ModelRegistryConstants. No other model factory registries need to exist.

modelFactoryType - The type of the requested model factory registry.

Returns:

The requested model factory registry. The object is never null.

Throws:

ServiceNotKnownException - If

• the requested model factory registry is not configured properly,
• the requested model factory registry cannot be created,

a ServiceNotKnownException wrapping a ConfigurationException will be thrown.

getServiceOfType

<T extends ADEPT2Service> T getServiceOfType(SessionToken session,
                                             java.lang.String serviceTypeName,
                                             java.lang.Class<T> serviceType)
                                      throws ServiceNotKnownException

Returns the service instance of the designated service type which is configured for usage by this (the requesting) service instance. If no special service instance is configured for usage, the default instance of the requested service type 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.

serviceTypeName - The type name of the requested service. Refer to ComponentTypes and BaseConstants for valid predefined service type names. Other service type names are also valid if the corresponding services are configured appropriately. ADEPT2Service and the interface configured for the service type or a super type hereof.

serviceType - The type of the requested service. This is a subtype of ADEPT2Service and the interface configured for the service type or a super type hereof.

Returns:

The requested service (or a service stub). The object is never null.

Throws:

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

ServiceNotKnownException - If

• the service is not configured properly,
• the service cannot be created or started,
• a required service is not configured properly or cannot be started,
• the creation of a required service object fails,
• the service does not fulfil the ADEPT2Service -interface appropriately,
• an exception is thrown while creating or starting a required service,

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

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

java.lang.IllegalArgumentException - If the designated service type interface does not conform to the interface configured for the service type, an IllegalArgumentException will be thrown.

getConfiguredPlugin

<T> T getConfiguredPlugin(SessionToken session,
                          java.lang.Object usingInstance,
                          java.lang.String pluginTypeName,
                          java.lang.Class<T> pluginType)
                   throws ServiceNotKnownException

Retrieves the default plugin of the designated type which is configured for the designated (using) instance. This is the same as getConfiguredPlugin(SessionToken, Object, String, Class, String) except that the default plugin instance is used, that is the first configured one. Therefore this will not be a runtime plugin.

Type Parameters:

T - The type of the requested plugin.

Parameters:

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

usingInstance - The instance which is using the plugin and which is provided in to the plugin when creating it. This allows the plugin to access the instance it extends.

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

pluginType - The type of the requested plugin.

Returns:

The requested plugin instance. The object is never null.

Throws:

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

ServiceNotKnownException - If

• the plugin type is not configured for the designated object,
• the plugin is not configured properly,
• the creation or the initialisation of the plugin instance fails,

a ServiceNotKnownException wrapping a ConfigurationException will be thrown.

getConfiguredPlugins

<T> java.util.Map<java.lang.String,T> getConfiguredPlugins(SessionToken session,
                                                           java.lang.Object usingInstance,
                                                           java.lang.String pluginTypeName,
                                                           java.lang.Class<T> pluginType)
                                                    throws ServiceNotKnownException

Retrieves all plugin instances (pre-configured and dynamic) of the designated plugin type. A new plugin instance will be created if an instance is not singleton or it has not been instantiated before.

Type Parameters:

T - The plugin type of the requested instances.

Parameters:

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

usingInstance - The instance which is using the plugins and which is provided to the plugins when creating them. This allows the plugins to access the instance it extends.

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

pluginType - The type of the requested plugin.

Returns:

The requested plugin instances, indexed by their instance id. This map may be empty.

Throws:

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

ServiceNotKnownException - If

• the plugin type is not configured for the designated object,
• the creation of a plugin instances fails,

a ServiceNotKnownException wrapping a ConfigurationException will be thrown.

ServiceNotKnownException - If

• the configuration of a plugin instance does not provide required configuration values,
• a plugin is not configured properly,
• the creation or the initialisation of a plugin instance fails,

a ServiceNotKnownException will be thrown.

getConfiguredPlugin

<T> T getConfiguredPlugin(SessionToken session,
                          java.lang.Object usingInstance,
                          java.lang.String pluginTypeName,
                          java.lang.Class<T> pluginType,
                          java.lang.String pluginInstanceName)
                   throws ServiceNotKnownException

Retrieves the plugin having the designated type and instance name as well as type and which is configured for the designated (using) instance. The designated using instance need to support plugins of the requested type. The plugin may be configured in the server/client configuration or it may be a runtime plugin that is found (together with its configuration) when requested. A new plugin instance will be created if the instance is not singleton or it has not been instantiated before.

Type Parameters:

T - The type of the requested plugin.

Parameters:

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

usingInstance - The instance which is using the plugin and which is provided in to the plugin when creating it. This allows the plugin to access the instance it extends.

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

pluginType - The type of the requested plugin.

pluginInstanceName - The simple name of the plugin instance to retrieve. This is either configured in the server/client configuration or in a configuration found at runtime.

Returns:

The requested plugin instance. The object is never null.

Throws:

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

ServiceNotKnownException - If

• the plugin type is not configured for the designated object,
• the plugin is not configured properly,
• the plugin is to be used as a runtime plugin but the designated object does not allow for runtime plugins,
• the plugin is to be used as a runtime plugin but it is not found,
• the creation or the initialisation of the plugin instance fails,

a ServiceNotKnownException wrapping a ConfigurationException will be thrown.

getService

<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 local service or a service stub that is retrieved from the global registry if the service is not known to this registry but to the global registry.

Type Parameters:

T - The type of the requested service. This is a subtype of ADEPT2Service and either interface configured for the 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 the requested service. This is a subtype of ADEPT2Service and the interface configured for the service type or a super type hereof.

Returns:

The requested service (or a service stub). The object is never null.

Throws:

ServiceNotKnownException - If

• the service is not configured properly,
• the service cannot be created or started,
• a required service is not configured properly or cannot be started,
• the creation of a required service object fails,
• the service does not fulfill the ADEPT2Service -interface appropriately,
• an exception is thrown while creating or starting a required service,

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

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

java.lang.IllegalArgumentException - If the designated service type interface does not conform to the interface configured for the service type, an IllegalArgumentException will be thrown.

getService

<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 stub that is retrieved from the global registry if the service is not known to this registry but to the global registry. An appropriate URI will be chosen, that is, a URI with a protocol supported by this registry.

Type Parameters:

T - The type of the requested service. This is a subtype of ADEPT2Service and either interface configured for the 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 the requested service. This is a subtype of ADEPT2Service and the interface configured for the service type or a super type hereof.

Returns:

The requested service (or a service stub). The object is never null.

Throws:

ServiceNotKnownException - If

• no appropriate communication service is available for the designated URIs,
• the service is not configured properly,
• the service cannot be created or started,
• a required service is not configured properly or cannot be started,
• the creation of a required service object fails,
• the service does not fulfill the ADEPT2Service -interface appropriately,
• an exception is thrown while creating or 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 interface configured for the service type,

an IllegalArgumentException will be thrown.