@ConfigurationDescription(properties={@Property(name="Instances.<ComponentTypeName>",documentationOnly=true,description="The PluginRegistry extends the semantic of the comma-separated list as follows:\nThe first declared instance is the default instacne of the corresponding component type.\nIf the list is empty, an implicit (default) instance will exist having the same name as the component type, e. g. \"C.C\". This is called the anonymous instance.\nOne element of the list but not the first one can be \"*\". This enablesdynamic and runtime instances for this component type. Dynamic plugins are declared by separate configuration files being somewhere in the classpath ofthis PluginRegistry. The name of the configuration files are the name of the corresponding component/plugin type. The configurations contain the same information as a plugin configuration read by this PluginRegistry. "),,,},validator=PluginRegistry.ConfigurationValidator.class) public abstract class PluginRegistry extends AbstractRegistry
AbstractRegistry does not allow to be directly
accessed, this class supports the retrieval of specific component instances
as well as default component instances. For this the component instance using
a plugin declares a component type as plugin type. At runtime it may request
the default instance or a specific instance of the plugin type. For instance,
a worklist manager is declared as follows: Components.WorklistManager = de.aristaflow.adept2.core.worklistmanager.WorklistManager Instances.WorklistManager = WL1, WL2 WL1.PluginTypes = DelegationHandling WL2.PluginTypes = EscalationHandling PluginRegistry that the used
implementation for the worklist manager instance WL1 may use
instances for the handling of delegation, while WL2 is able to
use external escalation handling. The corresponding types have to be declared
explicitly:
Components.DelegationHandling = de.aristaflow.adept2.core.worklistmanager.DelegationHandling Instances.DelegationHandling = DH1, DH2, DH3 Components.EscalationHandling = de.aristaflow.adept2.core.worklistmanager.EscalationHandling WL1 may request a
component instance for delegation handling. The name of the component
instance may be arbitrary, for instance, it is retrieved from a worklist item
which requires special delegation handling. DelegationHandling needs a public
constructor with org.apache.commons.configuration2.Configuration
and the implementation class (or an appropriate superclass or interface) of
WL1. Accordingly, EscalationHandling needs
Configuration and the implementation class (or an appropriate
superclass or interface) for WL2 in the public constructor. All
communication between plugins and the using components, for instance
initialisation and shutting down of used plugins, is under the responsibility
of the using components.
To simplify the configuration of usage relations, every component type has a
default instance. This is either the first declared instance from the
configuration file (Instances.<ComponentType>) or the anonymous
instance in case no instance is declared at all. In the example,
WL1, DH1 and the anonymous instance
EscalationHandling are default instances. This allows a
component to retrieve a plugin without knowing its name: If a worklist item
has no specific delegation handling defined, it asks for the default instance
and retrieves DH1.
The plugin type can be configured for all instances of the using type by
configuring it: WorklistManager.PluginTypes = EscalationHandling
. This configuration is used, in case no specific plugin type for the using
instance is found.
If a plugin is declared as singleton, the singleton behaviour will be relative to the using instance. That is, a using instance will always get the very same plugin instance. However, a new plugin instance will be created if a different using instance requests a plugin instance with the same type and the same name.
Besides the pre-configured plugin instances, plugin instances can also be retrieved dynamically or at runtime. This is enabled by declaring the special instance "*" as instance. This instance must not be default instance, that is, it must not be the first in the list of instances.
Components.DelegationHandling = de.aristaflow.adept2.core.worklistmanager.DelegationHandling Instances.DelegationHandling = DH1, DH2, DH3, * DelegationHandling.PluginClassPath = ${arflow:arflow.libdir}/plugins ConfigurationConstants.CONFIG_FILE_EXTENSION
)). All found configurations are parsed for declarations of plugin instance
implementations (plugin instance name prepended by
".Implementation" (
ConfigurationConstants.PROPERTY_REGISTRY_IMPLEMENTATION)). All
corresponding entries in the configuration file will be considered as
declared plugin instances. This configuration file will also be used as
configuration for the plugin instances it declares.
Additionally, the plugin registry allows for plugin instances determined at
runtime. If a plugin instance is requested at runtime but neither declared
statically nor found dynamically when initialising the registry and its type
has a plugin classpath ("PluginClassPath",
ConfigurationConstants.PROPERTY_REGISTRY_CLASSPATH), this classpath
will be searched for the requested plugin instance. This can be a normal
classpath, for instance jar-files, directories or arbitrary URLs (as long as
the corresponding protocol handler is installed). This classpath needs to
contain an entry with the name of the requested plugin. This can either be a
jar-file, a file, a subdirectory (containing several libraries), or a
configuration file having the plugin instance name prepended by
".properties" (ConfigurationConstants.CONFIG_FILE_EXTENSION
).
Depending on the found data, the (separate) classpath for the plugin instance
will be created. In case of a jar-file as base classpath entry, a directory
with the name of the requested plugin instance will be added to the plugin
instance classpath. In case of a file as base classpath entry it is first
checked whether this file or directory exists. If this is a file, it will be
added directly to the plugin instance classpath. If this is a directory, a
jar-file with the name of the plugin instance is appended. If this file
exists, it will be added to the plugin instance classpath. Afterwards a
directory having the name of the plugin instance is appended. If this exists,
it is added to the plugin instance classpath as well as all its direct
subdirectories and its jar-files (not transitively). All base classpaths with
other URL-protocols are added to the plugin instance classpath without
modification. This results in the implicit classpath for the plugin instance.
If the plugin type classpath contains a plugin instance (meta) configuration
file, this can contain an explicit classpath for a plugin instance as well as
the other information necessary to find the plugin instance. This includes
the implementation class, the instantiation mode and the explicit classpath (
ConfigurationConstants.PROPERTY_REGISTRY_CLASSPATH) of the plugin
instance.
A runtime plugin needs to have/may have its own configuration file in its
classpath (which is the extended plugin type classpath, see above). The
configuration has to be a PropertiesConfiguration. In case of an
implicit classpath this file has to exist somewhere in the plugin instance
classpath and it has to have the name of the plugin type prepended by
".properties" (ConfigurationConstants.CONFIG_FILE_EXTENSION
), for instance "ActivityTypeCheck.properties". It must provide at
least the implementation class of the plugin instance. Optionally it may have
an instantiation mode. Both of these configuration entries need to be
prefixed with the plugin instance name!
In case of an explicit classpath there needs to be a
PropertiesConfiguration in the plugin type classpath providing at
least the implementation class, the explicit classpath and optionally the
instantiation mode. They also have to be prefixed with the plugin instance
name! This (meta) configuration needs to have the name of the plugin instance
prepended by ".properties", for instance
"pluginName.properties".
With implicit classpaths there may be arbitrary additional entries in the one
configuration file; the whole configuration will be provided to the plugin
instance in its constructor (see above). With explicit classpaths there may
be an additional PropertiesConfiguration besides the meta
configuration named by the corresponding plugin type, for instance
"ActivityTypeCheck.properties" in the explicitly set plugin
instance classpath. This configuration may provide arbitrary additional
entries. With explicit classpaths only this configuration will be provided in
the constructor (excluding the meta configuration values). It will be empty
if the configuration file is not in the classpath of the plugin instance.
DelegationHandling4.Implementation = de.aristaflow.adept2.ext.MyDelegationHandling # Singleton-behaviour; this need not be set explicitly DelegationHandling4.InstantiationMode = Singleton # Arbitrary configuration values for DelegationHandling4 Database = jdbc: ... DelegateTo = Agent(id=4711)
DelegationHandling4.Implementation = de.aristaflow.adept2.ext.MyDelegationHandling
DelegationHandling4.ClassPath = ${arflow:arflow.libdir}/../MyDelegationHandling
# Singleton-behaviour; this need not be set explicitly
DelegationHandling4.InstantiationMode = Singleton
# Arbitrary configuration values for DelegationHandling4 Database = jdbc: ... DelegateTo = Agent(id=4711)
This class parses the following properties from the registry configuration - besides the properties parsed by super classes:
ConfigurationConstants.PROPERTY_REGISTRY_PLUGIN_TYPES)ConfigurationConstants.PROPERTY_REGISTRY_PLUGIN_CLASSPATH)ConfigurationConstants.PROPERTY_REGISTRY_IMPLEMENTATION)ConfigurationConstants.PROPERTY_REGISTRY_CLASSPATH)| Modifier and Type | Class and Description |
|---|---|
static class |
PluginRegistry.ConfigurationValidator
Checks that all declared plugin instances are configured properly, that is
they have an implementation class and runtime plugins have a plugin
classpath.
|
protected class |
PluginRegistry.URLClassloaderPrivilegedAction
A simple implementation of a privileged action that returns a normal
URLClassLoader classloader with the provided URLs as classpath. |
AbstractRegistry.DefaultNameResolution, AbstractRegistry.InstanceInformation, AbstractRegistry.InstantiationModeAbstractADEPT2Service.ActiveSessions| Modifier and Type | Field and Description |
|---|---|
protected java.util.Map<java.lang.String,java.util.Set<java.lang.String>> |
declaredPluginTypes
The declared plugin types.
|
protected java.util.Map<java.lang.String,java.lang.String> |
defaultInstances
The default instance per component type.
|
protected java.util.Map<java.lang.String,Configuration> |
dynamicPlugins
Map from hierarchical plugin instance name to the corresponding plugin
instance configuration.
|
protected java.util.Map<java.lang.String,java.util.Set<java.lang.String>> |
pluginInstances
Map from plugin type, to the set of configured plugin instances (simple
names).
|
protected java.util.Map<java.lang.String,Pair<java.lang.ClassLoader,Configuration>> |
runtimePlugins
Map from hierarchical plugin instance names to the classloader and the
configuration of the plugin instance.
|
protected java.util.Map<java.lang.String,java.net.URLClassLoader> |
runtimePluginTypeCLs
Map from plugin types having declared runtime loading (one plugin instance
is named "*") to the class loaders having the classpath set to
the declared plugin path for loading runtime plugins.
|
protected java.util.Map<java.lang.String,java.util.Map<java.lang.String,java.lang.Object>> |
singletonPlugins
All plugins are singletons relative to the using/requesting component.
|
componentInterfaces, configurationManager, declaredInstances, INIT_INSTANTIATED_OBJECT_METHOD, nameResolution, singletonInstancesCFG_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_USERNAMECONF_CSV_LOGGING, configuration, logger, registry, runtimeRequiredServices, startupRequiredServices| Modifier | Constructor and Description |
|---|---|
protected |
PluginRegistry(UrlConfigurationManager confMgr,
Configuration configuration,
Registry registry)
Constructs a new registry supporting plugins, that is components extending
an existing component.
|
| Modifier and Type | Method and Description |
|---|---|
protected java.net.URLClassLoader |
createPluginLoader(java.lang.String pluginInstanceName,
java.net.URL[] classpaths)
Creates a new classloader for the designated plugin instance having the
appropriate classpaths.
|
protected <T> T |
getConfiguredPlugin(SessionToken session,
java.lang.String usingInstanceName,
java.lang.Object usingInstance,
java.lang.String pluginTypeName,
java.lang.Class<T> componentType)
Retrieves the default instance of the designated plugin type.
|
protected <T> T |
getConfiguredPlugin(SessionToken session,
java.lang.String usingInstanceName,
java.lang.Object usingInstance,
java.lang.String pluginTypeName,
java.lang.Class<T> componentType,
java.lang.String pluginInstanceName)
Retrieves the plugin with the designated name of the designated type if it
is declared by the using instance or if it is declared and found as runtime
plugin.
|
protected <T> T |
getConfiguredPlugin(SessionToken session,
java.lang.String usingInstanceName,
java.lang.Object usingInstance,
java.lang.String pluginTypeName,
java.lang.Class<T> componentType,
java.lang.String pluginInstanceName,
java.lang.Class<?>[] additionalParameterTypes,
java.lang.Object[] additionalParameterValues)
Retrieves the plugin with the designated name of the designated type if it
is declared by the using instance or if it is declared and found as runtime
plugin.
|
protected <T> java.util.Map<java.lang.String,T> |
getConfiguredPlugins(SessionToken session,
java.lang.String usingInstanceName,
java.lang.Object usingInstance,
java.lang.String pluginTypeName,
java.lang.Class<T> componentType)
Retrieves all plugin instances (pre-configured and dynamic) of the
designated plugin type.
|
protected void |
prepareRuntimePlugin(java.lang.String typeName,
java.lang.String instanceName)
Prepares the designated runtime plugin, that is, the meta configuration
providing the implementation class and an optional classpath is loaded, the
instance information is set appropriately, the classloader for the plugin
instance is created and the normal configuration is loaded.
|
protected void |
readMetaConfiguration(Configuration registryConfiguration,
java.lang.String componentType)
Reads the available meta-configuration for components loaded at runtime.
|
protected void |
renewConfiguration(Configuration conf)
Renews the configuration of this registry by renewing via the superclass
and reading of default instances as well as declared plugin types.
|
checkAndStoreProvidedObject, checkConfiguration, checkImplementingClass, checkSupertype, createInstanceForInterface, getAppropriateMethod, getArbitrarilyNamedObject, getComponentType, getFormattedSignature, getHierarchicalInstanceName, getInstanceInformation, getInstantiationMode, getInterfaceForComponentType, getObjectForInstanceName, getObjectForInstanceName, getObjectForInstanceName, getSimpleInstanceName, init, initialiseInstantiatedObject, readMetaConfiguration, shutdown_sessionActive, authenticateService, awaitActiveSessions, createChildSession, createSession, getAgent, getSecurityManager, getSessionFactory, getStartupRequired, getTopLevelAgent, getUserCredentials, globalSecurityManagerAvailable, isEarlyService, sessionHasCapability_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, unprivilegeThreadclone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitgetLocalUris, getRelease, getRuntimeRequiredServices, getServiceInstanceName, getStartupRequiredServices, getURIs, ping, preShutdown, startprotected java.util.Map<java.lang.String,java.lang.String> defaultInstances
Maps from the component type to the hierarchical name of the default instance.
protected java.util.Map<java.lang.String,java.util.Set<java.lang.String>> declaredPluginTypes
protected java.util.Map<java.lang.String,java.util.Set<java.lang.String>> pluginInstances
protected java.util.Map<java.lang.String,Configuration> dynamicPlugins
protected java.util.Map<java.lang.String,java.net.URLClassLoader> runtimePluginTypeCLs
protected java.util.Map<java.lang.String,Pair<java.lang.ClassLoader,Configuration>> runtimePlugins
protected java.util.Map<java.lang.String,java.util.Map<java.lang.String,java.lang.Object>> singletonPlugins
protected PluginRegistry(UrlConfigurationManager confMgr, Configuration configuration, Registry registry) throws ConfigurationException
AbstractRegistry which sets the registry configuration and
the configuration manager.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.ConfigurationException - If the password cannot be parsed from the
configuration, a ConfigurationException will be
thrown.protected void renewConfiguration(Configuration conf) throws ConfigurationException
renewConfiguration in class AbstractRegistryconf - The (new) root configuration for this registry.ConfigurationException - If a plugin type is declared but the type is
not known by this registry, a ConfigurationException
will be thrown.protected void readMetaConfiguration(Configuration registryConfiguration, java.lang.String componentType) throws ConfigurationException
AbstractRegistryAbstractRegistry.readMetaConfiguration(Configuration, String, String) has to be
done when loading the corresponding components. readMetaConfiguration in class AbstractRegistryregistryConfiguration - 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.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.protected <T> T getConfiguredPlugin(SessionToken session, java.lang.String usingInstanceName, java.lang.Object usingInstance, java.lang.String pluginTypeName, java.lang.Class<T> componentType, java.lang.String pluginInstanceName) throws ConfigurationException
T - The type which the used object is expected to be of.session - The session which is used to check for access rights on this
method.usingInstanceName - The hierarchical name of the using component
instance. This may neither be null nor the empty.usingInstance - The using component instance which is provided in the
constructor of the requested plugin to allow for data exchange.pluginTypeName - The component type of the plugin instance to be
retrieved for usage. This may neither be null nor the empty
string.componentType - The type which the used object is expected to be of.pluginInstanceName - The simple (!) name of the plugin instance to
retrieve.InvalidServiceStateException - If
this registry failed to start or is shut down, an
InvalidServiceStateException will be thrown.ConfigurationException - If
AbstractRegistry.getInstanceInformation(String))
AbstractRegistry.componentInterfaces), AbstractRegistry.getInstanceInformation(String)),
ConfigurationException will be thrown.protected <T> T getConfiguredPlugin(SessionToken session, java.lang.String usingInstanceName, java.lang.Object usingInstance, java.lang.String pluginTypeName, java.lang.Class<T> componentType) throws ConfigurationException
T - The type which the used object is expected to be of.session - The session which is used to check for access rights on this
method.usingInstanceName - The hierarchical name of the using component
instance. This may neither be null nor the empty string.usingInstance - The using component instance which is provided in the
constructor of the requested plugin to allow for data exchange.pluginTypeName - The component type of the plugin instance to be
retrieved for usage. This may neither be null nor the empty
string.componentType - The type which the used object is expected to be of.
retrieve.InvalidServiceStateException - If
this registry failed to start or is shut down, an
InvalidServiceStateException will be thrown.ConfigurationException - If
AbstractRegistry.componentInterfaces), AbstractRegistry.getInstanceInformation(String)),
ConfigurationException will be thrown.protected <T> java.util.Map<java.lang.String,T> getConfiguredPlugins(SessionToken session, java.lang.String usingInstanceName, java.lang.Object usingInstance, java.lang.String pluginTypeName, java.lang.Class<T> componentType) throws ConfigurationException
T - The plugin type of the requested instances.session - The session which is used to check for access rights on this
method.usingInstanceName - The hierarchical name of the using component
instance. This may neither be null nor the empty.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.componentType - The type of the requested plugin.InvalidServiceStateException - If
this registry failed to start or is shut down, an
InvalidServiceStateException will be thrown.ConfigurationException - If
AbstractRegistry.componentInterfaces),AbstractRegistry.getInstanceInformation(String)),ConfigurationException will be thrown.protected <T> T getConfiguredPlugin(SessionToken session, java.lang.String usingInstanceName, java.lang.Object usingInstance, java.lang.String pluginTypeName, java.lang.Class<T> componentType, java.lang.String pluginInstanceName, java.lang.Class<?>[] additionalParameterTypes, java.lang.Object[] additionalParameterValues) throws ConfigurationException
Configuration and the class/interface of the
using instance) will be called providing the designated additional
parameter values (besides its configuration and the using instance).T - The type which the used object is expected to be of.session - The session which is used to check for access rights on this
method.usingInstanceName - The hierarchical name of the using component
instance. This may neither be null nor the empty.usingInstance - The using component instance which is provided in the
constructor of the requested plugin to allow for data exchange.pluginTypeName - The component type of the plugin instance to be
retrieved for usage. This may neither be null nor the empty
string.componentType - The type which the used object is expected to be of.pluginInstanceName - The simple (!) name of the plugin instance to
retrieve.additionalParameterTypes - Additional parameter types (besides
Configuration and the class/interface of the using
instance) of the constructor to be used for instantiation. If no
additional parameter is to be used, an empty array will need to be
provided. This has to correspond to
additionalParameterValues.additionalParameterValues - Additional parameter (besides the
configuration and the using instance) of the constructor to be
used for instantiation. If no additional parameter is to be used,
an empty array will need to be provided. This has to correspond to
additionalParameterTypes.InvalidServiceStateException - If
this registry failed to start or is shut down, an
InvalidServiceStateException will be thrown.ConfigurationException - If
AbstractRegistry.getInstanceInformation(String))AbstractRegistry.getInstanceInformation(String)),AbstractRegistry.componentInterfaces),AbstractRegistry.getInstanceInformation(String)),ConfigurationException will be thrown.protected void prepareRuntimePlugin(java.lang.String typeName,
java.lang.String instanceName)
throws ConfigurationException
typeName - The component type of the plugin instance to be retrieved
for usage. This may neither be null nor the empty string.instanceName - The simple (!) name of the plugin instance to retrieve.ConfigurationException - If
ConfigurationException will be thrown.protected java.net.URLClassLoader createPluginLoader(java.lang.String pluginInstanceName,
java.net.URL[] classpaths)
For instance, instName and
[file:/C:/Program%20Files/Java/jre1.5.0_07/lib/,
jar:file:/var/lib/security/local_policy.jar!/,
http://aristaflow.de/adept2.jar] is converted to
pluginInstanceName - The simple name of the requested plugin. This
name will be appended to the jar and file classpaths as directory
and as name of a jar file if appropriate.classpaths - The classpaths that are declared for the corresponding
plugin type of the designated plugin instance. This may be null.