de.aristaflow.adept2.base.registry

Class AbstractRegistry

java.lang.Object

de.aristaflow.adept2.base.service.AbstractADEPT2Service

de.aristaflow.adept2.base.service.AbstractAuthenticatedService

de.aristaflow.adept2.base.registry.AbstractRegistry

All Implemented Interfaces:

ConfMgrRegistry, ADEPT2Service, AuthenticatingService, LogService, NameResolution, ServiceThreadHandling

Direct Known Subclasses:

PluginRegistry

@ConfigurationDescription(properties={@Property(name="Components.<ComponentTypeName>",documentationOnly=true,description="The value is the name of an interface or class that represents a component type. Such a configuration entry declares a component type having this interface and the designated component type name, e.g. \"Components.C = InterfaceClass1\" declares a component type \"C\" having the interface \"InterfaceClass1\"."),,,,,,})
public abstract class AbstractRegistry
extends AbstractAuthenticatedService
implements ConfMgrRegistry, NameResolution

This class manages interfaces (or super-classes) of component types and instances of components including singletons. New instances are created when requested, configured and returned. To be instantiated by a registry, component implementations need to have a public constructor accepting at least their configuration ( org.apache.commons.configuration2.Configuration).

Classes specified as implementation for a component type may be annotated with a ConfigurationDescription. This description is used to automatically validate actual configurations at creation/request time. This tremendously simplifies the task of manual validation or makes it even unnecessary in some cases. But even manual validation can be performed before any instance of the component is created by the means of a ConfigurationValidator.

Instances of components are declared in the root configuration of this registry configuration: Instances.<ComponentType> = <x>, <y>. The instance names can be used to have instance-specific configurations in the root configuration of this registry: <SimpleName>.<PropertyName> = <PropertyValue>. The simple names are just arbitrary alphanumeric characters. They may not contain any characters that are meaningful when used in a URI. At runtime this name is prepended by the corresponding component type name, creating a hierarchical instance name. Normally, the difference between the simple and the hierarchical instance name can be ignored since the simple name is only used in configuration files and within the registry.
The properties can also be configured for the component type: <ComponentType>.<PropertyName> = <PropertyValue> . These properties are used as default values in case a specific instance does not have a particular property. An exception is the implementing class of a declared component instance. This must always be declared per instance.
If no instances are declared for a component type, the so called "anonymous instance" is implicitly declared. This instance always exists - except its instantiation mode is set to InstantiationMode.OFF. The configuration of the anonymous instance corresponds to the component type and its simple name equals the corresponding type name.

Any declared instance can refuse to be instantiated, instantiated once or multiple times. In case instantiation is set to off, an exception will be thrown when requesting the corresponding component instance. Singleton instances exist only once and are therefore cached internally. If the instantiation mode is not set for a specific instance, the instantiation mode of the corresponding anonymous instance will be used. If this is also not set, singleton will be used.
There are some components that do not allow to configure their instantiation mode. This includes registries which are always singletons and execution environments of which always multiple instances are allowed.

Component instances may be retrieved by providing the name of the instance - unique with respect to the root configuration. If the component instance is to be a singleton and is already instantiated, the existing instance will be returned. When instantiating a component, its constructor is provided at least the configuration ( org.apache.commons.configuration2.Configuration) for the particular instance. The instance has to provide an appropriate constructor! One may also provide additional parameters as well as a class loader.
The instantiation of a component instance is done with a lock to prevent concurrent instantiations. Otherwise it would be possible to retrieve different component instances declared as singleton. The lock implies that the constructor of a component instance must access the registry. This may lead to a deadlock. Component instances need not be instantiated by the registry, they may also be provided by the configuration of the registry. Just provide the corresponding instance for ConfigurationConstants.PROPERTY_REGISTRY_IMPLEMENTATION instead of the classname. Such an injected component instance is checked for its appropriate interfaces. It is per se singleton. It may have an initialisation method . If this method is present and has the appropriate parameters, it will be called when the component instance is requested. That is, the method is called for injected objects instead of the constructor of methods created by the registry (components that provide a class name instead of a component instance). Therefore the initialisation method needs to have the same parameters as the constructor.
The configurations of all injected objects to be initialised by the registry will be validated.

At construction time, the abstract registry reads all interfaces of all managed component types from its configuration. This allows for later checking whether a requested component implementation does fulfil the needs. The corresponding interfaces are declared by: Components.<ComponentType> = <InterfaceOrClass>.
Additionally important information concerning a component instance is also read. This includes the name, the type and the instantiation mode (note: the implementing class of a component has to be specified explicitly). If the instantiation mode is not configured, the configuration of the anonymous instance will be used.

Registries are treated just like ordinary components, except that they are always singleton and there must not be any instances declared. Therefore only the anonymous instance exists - having the name of the type (the anonymous instance). This implies, that each must have its own configuration file to prevent collisions of property names and they must have a public constructor with at least their configuration and the corresponding parent registry. Subclasses of the abstract registry need to provide their configuration to the constructor of this class which handles the management of component interfaces and instance configurations as described above.
Registries are also ADEPT2Services which means they support the normal service lifecycle. This allows to initialise and shut down registries. Therefore the initial registry, called bootstrap-registry, has to support services and is a subclass of LocalServiceRegistry.
One important issue is the difference in the lifecycle. Since registries may be accessed when starting services, they must be fully available after init(URI[], URI[]). Otherwise a may try to start a service which in turn needs to access the same registry but already started. This implies that subclasses notify waiting threads at the beginning of their own AbstractADEPT2Service.start().
When shutting down, every registry can decide on how long it allows access. To prevent access shutdown(boolean) has to be called. After that all access (except by privileged threads) is forbidden.

This class provides access to the initial registry, called bootstrap-registry. The bootstrap-registry extends an abstract registry to include at least configurations for (sub-)registries needed for ADEPT2, which are:

• ADEPT2-registry providing typed access to components used internally,
• model factory registry for typed access to components for creating instances of the ADEPT2-process model, activity model,...
• runtime registry for loading executable components.

This class parses the following properties from a registry configuration (in the constructor):

• Components.<ComponentType> ( ConfigurationConstants.PREFIX_PROPERTY_REGISTRY_TYPES )
• Instances.<ComponentType> ( ConfigurationConstants.PREFIX_PROPERTY_REGISTRY_INSTANCES)
• <InstanceName>.InstantiationMode (including anonymous instance: <ComponentType>.InstantiationMode)
  (ConfigurationConstants.PROPERTY_REGISTRY_INSTANTIATION_MODE)
• <InstanceName>.Implementation
  (ConfigurationConstants.PROPERTY_REGISTRY_IMPLEMENTATION)

Author:

Ulrich Kreher, Kevin Goeser

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	AbstractRegistry.DefaultNameResolution Default implementation for resolving service name and component types.
static class	AbstractRegistry.InstanceInformation InstanceInformation encapsulates the properties from the configuration relevant for a component instance.
static class	AbstractRegistry.InstantiationMode The instantiation modes an instance may have.

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.util.Map<java.lang.String,java.lang.Class<?>>	componentInterfaces Interfaces (and classes) of all components managed by this registry.
protected UrlConfigurationManager	configurationManager The configuration-manager used for this registry.
protected java.util.Map<java.lang.String,AbstractRegistry.InstanceInformation>	declaredInstances All hierarchical instance names (with anonymous instances) declared for the underlying configuration.
static java.lang.String	INIT_INSTANTIATED_OBJECT_METHOD The name of the method that is called to initialise instantiated (injected) objects.
protected NameResolution	nameResolution The implementation for resolving service name and component types.
protected java.util.Map<java.lang.ClassLoader,java.util.Map<java.lang.String,java.lang.Object>>	singletonInstances All singleton instances of all managed components.

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	AbstractRegistry(UrlConfigurationManager confMgr, Configuration configuration, Registry registry) Constructs a new registry by setting the parent registry, the configuration and the initial configuration manager.

Method Summary

Modifier and Type	Method and Description
protected void	checkAndStoreProvidedObject(java.lang.String instanceName, AbstractRegistry.InstanceInformation instInf) Checks whether the designated instance that is provided as object via injection corresponds to its declared component interface and if so, stores it for the classloader of this class in the singleton instances.
protected static Configuration	checkConfiguration(Configuration configuration, java.lang.String instanceName, java.lang.Class<?> implementationClass) Check the configuration description of the implementation class and whether the configuration contains the necessary values.
protected void	checkImplementingClass(java.lang.String instanceName, java.lang.String implementingClassName) Checks whether the implementing class has the right interface.
protected void	checkSupertype(java.lang.String instanceName, java.lang.Class<?> superType, java.lang.Class<?> subType) Checks, if the given subType is an assignable form of superType.
protected <T> T	createInstanceForInterface(java.lang.Class<? extends T> implClass, java.lang.Class<T> compIface, java.lang.Class<?>[] paramTypes, java.lang.Object[] paramValues) Creates an new instance of the designated class having the designated component interface or super class.
protected MethodWrapper	getAppropriateMethod(MethodWrapper[] methods, java.lang.Class<?>[] parameterTypes) Looks for an appropriate method (or constructor) accepting the designated parameter types (or the corresponding supertypes) in the designated class.
protected <T> T	getArbitrarilyNamedObject(java.lang.String instName, Configuration instConf, java.lang.Class<T> componentType, java.lang.ClassLoader classLoader, java.lang.Class<?>[] parameterTypes, java.lang.Object[] parameterValues, AbstractRegistry.InstantiationMode instantiationMode) Gets an arbitrary object for the designated component instance of the requested component type.
java.lang.String	getComponentType(java.lang.String instanceName) Returns the name of the component type of the designated component instance as used in configuration files.
java.lang.String	getFormattedSignature(java.lang.Class<?>[] parameterTypes) Helper method for getting a string describing the parameter types as method signature for use in log messages and exceptions.
java.lang.String	getHierarchicalInstanceName(java.lang.String componentType, java.lang.String simpleName) Returns a hierarchical instance name containing the component type as well as the instance name.
protected AbstractRegistry.InstanceInformation	getInstanceInformation(java.lang.String instanceName) Returns the information (component type, instantiation mode and implementation class) for the designated component instance.
protected AbstractRegistry.InstantiationMode	getInstantiationMode(java.lang.String componentType, java.lang.String simpleInstanceName, Configuration registryConfiguration) Returns the instantiation mode for the designated component instance as specified in the corresponding configuration.
java.lang.Class<?>	getInterfaceForComponentType(java.lang.String componentType) Returns the class object of the corresponding interface / superclass, if the component type is declared.
protected <T> T	getObjectForInstanceName(java.lang.String instanceName, java.lang.Class<T> componentType) Gets an object for the designated instance name of the requested component type and retrieves the instantiation mode from the corresponding configuration.
protected <T> T	getObjectForInstanceName(java.lang.String instanceName, java.lang.Class<T> componentType, java.lang.Class<?>[] addParameterTypes, java.lang.Object[] addParameterValues) Gets an object for the designated instance name of the requested component type and retrieves the instantiation mode from the corresponding configuration.
protected <T> T	getObjectForInstanceName(java.lang.String instanceName, java.lang.Class<T> componentType, java.lang.Class<?>[] addParameterTypes, java.lang.Object[] addParameterValues, AbstractRegistry.InstantiationMode instantiationMode) Gets an object for the designated instance name of the requested component type using the designated instantiation mode from the corresponding configuration.
java.lang.String	getSimpleInstanceName(java.lang.String instanceName) Returns the simple name of the designated component instance as used in configuration files.
void	init(java.net.URI[] localExportedUris, java.net.URI[] globalExportedUris) Initialises a new registry by setting the configuration manager to the ADEPT2-configuration.
protected void	initialiseInstantiatedObject(java.lang.Object instance, java.lang.String compIface, java.lang.Class<?>[] paramTypes, java.lang.Object[] paramValues) Initialises the designated instance having the designated component interface or super class.
protected abstract void	readMetaConfiguration(Configuration registryConfiguration, java.lang.String componentType) Reads the available meta-configuration for components loaded at runtime.
protected void	readMetaConfiguration(Configuration registryConfiguration, java.lang.String componentType, java.lang.String simpleInstanceName) Reads the meta-configuration (implementing class, instantiation mode,...)
protected void	renewConfiguration(Configuration conf) Renews the configuration of this registry by creating a new configuration manager.
void	shutdown(boolean emergency) Signals the shutdown of this registry.

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

_sessionActive, authenticateService, awaitActiveSessions, createChildSession, createSession, getAgent, getSecurityManager, 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, start, 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, start

Field Detail

INIT_INSTANTIATED_OBJECT_METHOD

public static final java.lang.String INIT_INSTANTIATED_OBJECT_METHOD

The name of the method that is called to initialise instantiated (injected) objects.

See Also:

Constant Field Values

nameResolution

protected final NameResolution nameResolution

The implementation for resolving service name and component types.

configurationManager

protected UrlConfigurationManager configurationManager

The configuration-manager used for this registry. Normally this is the global ADEPT2-configuration. It is set in the constructor of this class and recreated when the configuration is renewed. Subclasses will have to set their configuration manager appropriately if required.

componentInterfaces

protected java.util.Map<java.lang.String,java.lang.Class<?>> componentInterfaces

Interfaces (and classes) of all components managed by this registry. Component type names are mapped to the corresponding instance of Class which is the interface or the superclass of the component type.

declaredInstances

protected java.util.Map<java.lang.String,AbstractRegistry.InstanceInformation> declaredInstances

All hierarchical instance names (with anonymous instances) declared for the underlying configuration. It maps (declared) hierarchical instance names to instance information (component type name, instantiation mode and implementing class).
This is synchronised to allow for concurrent retrieval and storing.

singletonInstances

protected java.util.Map<java.lang.ClassLoader,java.util.Map<java.lang.String,java.lang.Object>> singletonInstances

All singleton instances of all managed components. The class loader for the implementation is mapped to the hierarchical instance name and this to the corresponding singleton instance. This mapping is class loader -> (hierarchical) instanceName -> instance.
The mapping contains only instances which are marked as singletons in the corresponding configuration and registries which are always singletons.

Constructor Detail

AbstractRegistry

protected AbstractRegistry(UrlConfigurationManager confMgr,
                           Configuration configuration,
                           Registry registry)
                    throws ConfigurationException

Constructs a new registry by setting the parent registry, the configuration and the initial configuration manager.
This constructor may only be called by subclasses which is ensured by making this class abstract.

Parameters:

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

configuration - The configuration of the created registry instance.

registry - The parent registry of this registry.

Throws:

ConfigurationException - If the password cannot be parsed from the configuration, a ConfigurationException will be thrown.

Method Detail

init

public void init(java.net.URI[] localExportedUris,
                 java.net.URI[] globalExportedUris)
          throws AbortServiceException

Initialises a new registry by setting the configuration manager to the ADEPT2-configuration. The managed component types and the corresponding interfaces (or classes) and information to the component instances (type, instantiation mode and implementing class) are parsed:

• Components.<ComponentType> = <ClassOrInterfaceName>
• Instances.<ComponentType> = <DeclaredInstances>
• <InstanceName>.InstantiationMode
• <InstanceName>.Implementation

This method should be called at the beginning of overriding methods.

Registries must not start or initialise the own managed services while it is initialised itself! The initialised services may access the registry which in turn is not correctly started itself. This is prevented by locks and therefore might cause deadlocks.
To allow registries to initialise and start other services, a registry is considered started after returning from its own init(URI[], URI[]).

Specified by:

init in interface ADEPT2Service

Overrides:

init in class AbstractAuthenticatedService

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.

AbortServiceException - If the registry configuration contains an entry for a managed component but it is not configured properly, a ConfigurationExceptionwill be thrown.

shutdown

public void shutdown(boolean emergency)

Signals the shutdown of this registry. No access except the privileged threads may access this registry afterwards.

This method has to be called at an arbitrary time in the shutdown-procedure of overriding classes.

Specified by:

shutdown in interface ADEPT2Service

Overrides:

shutdown in class AbstractAuthenticatedService

Parameters:

emergency - Whether the shutdown will be an emergency shutdown.

renewConfiguration

protected void renewConfiguration(Configuration conf)
                           throws ConfigurationException

Renews the configuration of this registry by creating a new configuration manager. Afterwards mandatory configuration values are checked, the configured component types are read as well as the instance declarations and information (component type, instantiation mode and implementing class).
This method is called in the initialisation and may therefore not rely on a fully initialised object.

Parameters:

conf - The (new) root configuration for this registry.

Throws:

ConfigurationException - If

• mandatory properties are missing ( PropertyNotSetException),
• the class or interface of a type can not be found,
• the instance is not configured properly (implementing class or object),

a ConfigurationException will be thrown.

readMetaConfiguration

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

Reads the available meta-configuration for components loaded at runtime. This meta-configuration is usually restricted to a classpath where the components and their configuration can be found at runtime. The necessary checks normally done in readMetaConfiguration(Configuration, String, String) has to be done when loading the corresponding components.
This method is called in the initialisation and may therefore not rely on a fully initialised registry.

Parameters:

registryConfiguration - The configuration which contains the (registry) information for runtime instances of the designated component type.

componentType - The type of the component to retrieve the meta-configuration.

Throws:

ConfigurationException - If some of the required information is missing, for instance, the classpath for loading the components at runtime is not specified, a ConfigurationException will be thrown.

readMetaConfiguration

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

Reads the meta-configuration (implementing class, instantiation mode,...) for the designated component instance and stores it in the corresponding maps.
This method is called in the initialisation and may therefore not rely on a fully initialised registry.

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 no implementing class name is defined for the designated instance or the instance is injected as object but it is not declared as singleton or it does not correspond to its declared component type, a ConfigurationException will be thrown.

checkSupertype

protected void checkSupertype(java.lang.String instanceName,
                              java.lang.Class<?> superType,
                              java.lang.Class<?> subType)
                       throws ConfigurationException

Checks, if the given subType is an assignable form of superType. Throws an exception if not.

Parameters:

instanceName - The hierarchical instance name of the component.

superType - The super type (interface or super class).

subType - The sub-type.

Throws:

ConfigurationException - If the subType is not an assignable form of superType, a ConfigurationException will be thrown.

checkConfiguration

protected static Configuration checkConfiguration(Configuration configuration,
                                                  java.lang.String instanceName,
                                                  java.lang.Class<?> implementationClass)
                                           throws ConfigurationException

Check the configuration description of the implementation class and whether the configuration contains the necessary values. In case the designated class is null, this method just returns.

This method is called during the initialisation of the configuration, readMetaConfiguration(Configuration, String, String).

The method is intended to be overridden by subclasses, for bypassing or extending the checks.

Parameters:

configuration - The configuration for the designated instance.

instanceName - The hierarchical instance name.

implementationClass - The implementation class for the designated instance or null.

Returns:

The very same configuration that is provided as parameter. This allows the usage of this method in a call to the super-constructor.

Throws:

ConfigurationException - If the designated configuration does not provide the necessary configuration values for the designated instance of the designated implementation class, a ConfigurationException will be thrown.

checkImplementingClass

protected void checkImplementingClass(java.lang.String instanceName,
                                      java.lang.String implementingClassName)
                               throws ConfigurationException

Checks whether the implementing class has the right interface. For loading the class the class loader of the registry is used. This may differ from the desired class loader for this class (c.f. createInstanceForInterface(Class, Class, Class[], Object[])). The desired class loader may have another class path which prevents the class from being found and checked here. In this case the configuration of the class will not be checked until really loaded by the desired class loader just before creation.

Parameters:

instanceName - The hierarchical instance name.

implementingClassName - The name of the implementing class.

Throws:

ConfigurationException - If the designated component type is not configured for this registry or the designated implementing class is not a subtype of the registered component interface, a ConfigurationException will be thrown.

checkAndStoreProvidedObject

protected void checkAndStoreProvidedObject(java.lang.String instanceName,
                                           AbstractRegistry.InstanceInformation instInf)
                                    throws ConfigurationException

Checks whether the designated instance that is provided as object via injection corresponds to its declared component interface and if so, stores it for the classloader of this class in the singleton instances.

Parameters:

instanceName - The hierarchical instance name of the component.

instInf - The instance information for the instance.

Throws:

ConfigurationException - If the declared component interface does not correspond to the provided (injected) object instance, a ConfigurationException will be thrown.

getInstantiationMode

protected AbstractRegistry.InstantiationMode getInstantiationMode(java.lang.String componentType,
                                                                  java.lang.String simpleInstanceName,
                                                                  Configuration registryConfiguration)

Returns the instantiation mode for the designated component instance as specified in the corresponding configuration. If there is no instantiation mode configured for the designated instance name, the instantiation mode for the anonymous instance of the corresponding component type will be used. If the instantiation for the anonymous instance is neither configured, InstantiationMode.SINGLETON will be returned.
This method is called in the initialisation and may therefore not rely on a fully initialised registry.

Parameters:

componentType - The type of the component to retrieve the meta-configuration.

simpleInstanceName - The simple name of the component instance as declared in the configuration.

registryConfiguration - The configuration which contains the declaration of the instantiation mode.

Returns:

The configured instantiation mode name for the designated component instance or InstantiationMode.SINGLETON.

getHierarchicalInstanceName

public java.lang.String getHierarchicalInstanceName(java.lang.String componentType,
                                                    java.lang.String simpleName)

Description copied from interface: NameResolution

Returns a hierarchical instance name containing the component type as well as the instance name. The returned string resembles, for instance, /ProcessManager/PM1.

Specified by:

getHierarchicalInstanceName in interface NameResolution

Parameters:

componentType - The type of the component to create the hierarchical name for.

simpleName - The simple name of the component instance as defined in the configuration.

Returns:

An instance name containing the component type and the simple component instance name.

getSimpleInstanceName

public java.lang.String getSimpleInstanceName(java.lang.String instanceName)

Description copied from interface: NameResolution

Returns the simple name of the designated component instance as used in configuration files.

Specified by:

getSimpleInstanceName in interface NameResolution

Parameters:

instanceName - The hierarchical name of a component instance.

Returns:

The simple name without the prepending type of the component instance.

getFormattedSignature

public java.lang.String getFormattedSignature(java.lang.Class<?>[] parameterTypes)

Description copied from interface: NameResolution

Helper method for getting a string describing the parameter types as method signature for use in log messages and exceptions.

Specified by:

getFormattedSignature in interface NameResolution

Parameters:

parameterTypes - All the parameter types of a method as instances of Class.

Returns:

A string describing the parameter types as method signature (concatenated and surrounded by parenthesis).

getComponentType

public java.lang.String getComponentType(java.lang.String instanceName)

Description copied from interface: NameResolution

Returns the name of the component type of the designated component instance as used in configuration files.

Specified by:

getComponentType in interface NameResolution

Parameters:

instanceName - The hierarchical name of a component instance.

Returns:

The name of the component type.

getInstanceInformation

protected AbstractRegistry.InstanceInformation getInstanceInformation(java.lang.String instanceName)
                                                               throws ConfigurationException

Returns the information (component type, instantiation mode and implementation class) for the designated component instance. It is also checked, whether the instance is declared and all information is available.

Parameters:

instanceName - The hierarchical name of the component instance for which to retrieve its information.

Returns:

The information for the component instance as a tuple (component type, instantiation mode and implementation class).

Throws:

ConfigurationException - If the designated instance is not configured properly, that is, it is not declared, a ConfigurationException will be thrown.

getObjectForInstanceName

protected <T> T getObjectForInstanceName(java.lang.String instanceName,
                                         java.lang.Class<T> componentType)
                                  throws ConfigurationException

Gets an object for the designated instance name of the requested component type and retrieves the instantiation mode from the corresponding configuration. In case of a singleton instance, an existing object will be returned. The same class loader as for this class will be used.

Type Parameters:

T - The type which the requested object is expected to be of which is either the registered component type or a super type hereof.

Parameters:

instanceName - The hierarchical name of the component instance to retrieve. This may neither be null nor the empty string.

componentType - The type of which the requested object is expected to be. This is either the registered component type interface or a super type hereof.

Returns:

An object for the designated component type with the designated instance name.

Throws:

ConfigurationException - If

• no component interface is registered/configured for the designated component type (componentInterfaces),
• the designated instance is not declared in the corresponding component type configuration (getInstanceInformation(String)),
• the configuration of the instance does not have an entry for the implementation of the instance (getInstanceInformation(String)),
• the implementation class is not a subtype of the configured component interface,
• the implementation class is not found by the class loader of this class,
• the instantiation mode is set to off,
• the configuration of the requested instance does not provide required configuration values,
• the creation of the instance fails (createInstanceForInterface(Class, Class, Class[], Object[])),
• the object instance has been injected into the platform, it has an appropriate initialisation method but this fails to be called,

a ConfigurationException will be thrown.

getObjectForInstanceName

protected <T> T getObjectForInstanceName(java.lang.String instanceName,
                                         java.lang.Class<T> componentType,
                                         java.lang.Class<?>[] addParameterTypes,
                                         java.lang.Object[] addParameterValues)
                                  throws ConfigurationException

Gets an object for the designated instance name of the requested component type and retrieves the instantiation mode from the corresponding configuration. In case of a singleton instance, an existing object will be returned. For instantiating a new object, an appropriate constructor with the designated additional parameters (besides Configuration) will be used. The same class loader as for this class will be used.

Type Parameters:

T - The type which the requested object is expected to be of which is either the registered component type or a super type hereof.

Parameters:

instanceName - The hierarchical name of the component instance to retrieve. This may neither be null nor the empty string.

componentType - The type of which the requested object is expected to be. This is either the registered component type interface or a super type hereof.

addParameterTypes - Additional parameter types (besides Configuration) of the constructor to be used for instantiation. If no additional parameter is to be used, an empty array needs to be provided. This has to correspond to additionalParameterValues.

addParameterValues - Additional parameter (besides the configuration) of the constructor to be used for instantiation. If no additional parameter is to be used, an empty array needs to be provided. This has to correspond to additionalParameterTypes.

Returns:

An object for the designated component type with the designated instance name.

Throws:

ConfigurationException - If

• no component interface is registered/configured for the designated component type (componentInterfaces),
• the designated instance is not declared in the corresponding component type configuration ( getInstanceInformation(String)),
• the configuration of the instance does not have an entry for the implementation of the instance ( getInstanceInformation(String)),
• the implementation class of the requested instance is not a subtype of the configured component interface,
• the implementation class of the requested instance is not found by the class loader of this class,
• the instantiation mode is set to off,
• the configuration of the requested instance does not provide required configuration values,
• the creation of the instance fails ( createInstanceForInterface(Class, Class, Class[], Object[])),
• the object instance has been injected into the platform, it has an appropriate initialisation method but this fails to be called,

a ConfigurationException will be thrown.

getObjectForInstanceName

protected <T> T getObjectForInstanceName(java.lang.String instanceName,
                                         java.lang.Class<T> componentType,
                                         java.lang.Class<?>[] addParameterTypes,
                                         java.lang.Object[] addParameterValues,
                                         AbstractRegistry.InstantiationMode instantiationMode)
                                  throws ConfigurationException

Gets an object for the designated instance name of the requested component type using the designated instantiation mode from the corresponding configuration. In case of a singleton instance, an existing object will be returned. For instantiating a new object, an appropriate constructor with the designated additional parameters (besides Configuration) will be used. The same class loader as for this class will be used.

Type Parameters:

T - The type which the requested object is expected to be of which is either the registered component type or a super type hereof.

Parameters:

instanceName - The hierarchical name of the component instance to retrieve. This may neither be null nor the empty string.

componentType - The type of which the requested object is expected to be. This is either the registered component type interface or a super type hereof.

addParameterTypes - Additional parameter types (besides Configuration) of the constructor to be used for instantiation. If no additional parameter is to be used, an empty array needs to be provided. This has to correspond to additionalParameterValues.

addParameterValues - Additional parameter (besides the configuration) of the constructor to be used for instantiation. If no additional parameter is to be used, an empty array needs to be provided. This has to correspond to additionalParameterTypes.

instantiationMode - Whether the designated component instance may be instantiated never, once or multiple.

Returns:

An object for the designated component type with the designated instance name.

Throws:

ConfigurationException - If

• no component interface is registered/configured for the designated component type (componentInterfaces),
• the designated instance is not declared in the corresponding component type configuration ( getInstanceInformation(String)),
• the configuration of the instance does not have an entry for the implementation of the instance ( getInstanceInformation(String)),
• the implementation class of the requested instance is not a subtype of the configured component interface,
• the implementation class of the requested instance is not found by the class loader of this class,
• the instantiation mode is set to off,
• the configuration of the requested instance does not provide required configuration values,
• the creation of the instance fails ( createInstanceForInterface(Class, Class, Class[], Object[]) ),
• the object instance has been injected into the platform, it has an appropriate initialisation method but this fails to be called,

a ConfigurationException will be thrown.

getArbitrarilyNamedObject

protected <T> T getArbitrarilyNamedObject(java.lang.String instName,
                                          Configuration instConf,
                                          java.lang.Class<T> componentType,
                                          java.lang.ClassLoader classLoader,
                                          java.lang.Class<?>[] parameterTypes,
                                          java.lang.Object[] parameterValues,
                                          AbstractRegistry.InstantiationMode instantiationMode)
                                   throws ConfigurationException

Gets an arbitrary object for the designated component instance of the requested component type. This object does not need to fulfill anything but in turn can not use the registry-framework appropriately (getting a configuration, loading used other components,...).
In case of a singleton instance, an existing object will be returned if it is already loaded by the designated class loader. This also applies to objects that have been provided via injection except that the classloader of this class will be used instead of the provided one. For instantiating a new object, the designated class loader and an appropriate constructor with the designated parameters will be used. In case of an injected object, the corresponding initialisation method will be called once if present. If calling this initialisation method fails, the exception will just be logged and no initialisation will take place.
This method uses a read/write lock based on the instance name when accessing singleton instances and creating instances. It calls createInstanceForInterface(Class, Class, Class[], Object[]) while having the write lock.

Type Parameters:

T - The type which the requested object is expected to be of which is either the registered component type or a super type hereof.

Parameters:

instName - The hierarchical name of the component instance to retrieve. This may neither be null nor the empty string.

instConf - The configuration of the component instance to check for whether all configuration values are present.

componentType - The type of which the requested object is expected to be. This is either the registered component type interface or a super type hereof.

classLoader - The class loader to use for a new instance.

parameterTypes - Parameter types of the constructor to be used for instantiation. This has to correspond to parameterValues.

parameterValues - The parameter of the constructor to be used for instantiation. This has to correspond to parameterTypes.

instantiationMode - Whether the designated component instance may be instantiated never, once or multiple.

Returns:

An object for the designated component type with the designated instance name.

Throws:

ConfigurationException - If

• no component interface is registered/configured for the designated component type (componentInterfaces),
• the designated instance is not declared in the corresponding component type configuration ( getInstanceInformation(String)),
• the configuration of the instance does not have an entry for the implementation of the instance ( getInstanceInformation(String)),
• the implementation class of the requested instance is not a subtype of the configured component interface,
• the implementation class of the requested instance is not found by the class loader of this class,
• the instantiation mode is set to off,
• the configuration of the requested instance does not provide required configuration values,
• the creation of the instance fails ( createInstanceForInterface(Class, Class, Class[], Object[]) ),
• the object instance has been injected into the platform, it has an appropriate initialisation method but this fails to be called,

a ConfigurationException will be thrown.

createInstanceForInterface

protected final <T> T createInstanceForInterface(java.lang.Class<? extends T> implClass,
                                                 java.lang.Class<T> compIface,
                                                 java.lang.Class<?>[] paramTypes,
                                                 java.lang.Object[] paramValues)
                                          throws ConfigurationException

Creates an new instance of the designated class having the designated component interface or super class. If a constructor with the designated parameter types does not exist (or an appropriate one, that is one having compatible supertypes for the parameters), a ConfigurationException will be thrown.
This method is only for registry-internal use since it always instantiates a new object, no matter if there is already an instance of the implementation. Whether or not multiple instantiation is wanted, has to be checked before calling this method.
Make sure to synchronise appropriately before creating singleton instances.

Type Parameters:

T - The requested type of the object - a super type of the registered component type.

Parameters:

implClass - The class which implements or extends the designated interfaces.

compIface - The interface of the component type of the requested instance.

paramTypes - Parameter types for the constructor to be called. This has to correspond to paramValues.

paramValues - Parameter values for the constructor to be called. This has to correspond to paramTypes.

Returns:

A new instance of the implementation, which implements / extends the designated interface.

Throws:

java.lang.AssertionError - If assertions are enabled and the length of the designated parameter type array differs from the designated parameter value array, an AssertionError will be thrown.

ConfigurationException - If

• the constructor of the designated class is not accessible due to security management,
• the designated class or the constructor are not accessible due to language restrictions (visibility, abstract),
• the constructor throws an exception when executed,
• there is no appropriate constructor for the designated parameters,

a ConfigurationException will be thrown, encapsulating the actual exception if appropriate.

initialiseInstantiatedObject

protected final void initialiseInstantiatedObject(java.lang.Object instance,
                                                  java.lang.String compIface,
                                                  java.lang.Class<?>[] paramTypes,
                                                  java.lang.Object[] paramValues)
                                           throws ConfigurationException

Initialises the designated instance having the designated component interface or super class. If the initialisation method with the designated parameter types does not exist (or an appropriate one, that is one having compatible supertypes for the parameters), a ConfigurationException will be thrown.
This method is only for registry-internal use since it always initialises, no matter if the object has already been initialised. This has to be checked before calling this method.
Make sure to synchronise appropriately before initialising to respect singleton behaviour.

Contrary to createInstanceForInterface(Class, Class, Class[], Object[]) this method does not thrown an exception but just logs them. Initialisation is not required (contrary to object construction).

Parameters:

instance - The object instance which to initialise.

compIface - The interface of the component type of the instance.

paramTypes - Parameter types for the initialisation method to be called. This has to correspond to paramValues.

paramValues - Parameter values for the initialisation method to be called. This has to correspond to paramTypes.

Throws:

ConfigurationException - If a method with the right signature (name and parameter types) exists but it fails to be called, an ConfigurationException will be thrown.

java.lang.AssertionError - If assertions are enabled and the length of the designated parameter type array differs from the designated parameter value array, an AssertionError will be thrown.

getInterfaceForComponentType

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

getAppropriateMethod

protected MethodWrapper getAppropriateMethod(MethodWrapper[] methods,
                                             java.lang.Class<?>[] parameterTypes)

Looks for an appropriate method (or constructor) accepting the designated parameter types (or the corresponding supertypes) in the designated class. Overloaded methods are chosen based on the distance of their parameter types (the distance of the methods is the sum of all parameter type distances). If no appropriate method is found, null will be returned.

Parameters:

methods - The methods to get an appropriate method of.

parameterTypes - The types of the method parameters

Returns:

An appropriate method for the designated parameter types or null in case no constructor of the class is appropriate.