New Plugin Manager

Revised: 31 August, 2005 LarryStone

...

There is only one implementation class for the plugin. It is
indicated in the configuration.
For examples, see
EvolutionToServiceLocatorProposal.
This type of plugin chooses an implementation of a service, for
the entire system, at configuration time.
Your application just fetches the
plugin for that interface and gets the configured-in choice.
See the #PluginManager Class #getSinglePlugingetSinglePlugin() method.

2. Sequence Plugins

You need a sequence or series of plugins, to implement a mechanism
like StackableAuthenticationMethods or a pipeline, where each plugin
is called in order to contribute its implementation of a process to the whole.
The Plugin Manager supports this by letting you configure a sequence
of plugins for a given interface. See the
#PluginManager Class #getPluginSequencegetPluginSequence() method for details.

3. Named Plugins

Use a named plugin
when the application has to choose one plugin implementation out of
many available ones.
Each implementation
is bound to one or more names (symbolic identifiers) in the
configuration.

...

Think of plugin names as a controlled vocabulary – for a given
plugin interface, there is a set of names for which plugins can be
found. The designer of a Named Plugin interface is responsible for
deciding what the name means and how to derive it; for example, names
of metadata crosswalk plugins may describe the target metadata format.
See the #PluginManager Class #getNamedPlugingetNamedPlugin() method and the
#PluginManager Class #getPluginNamesgetPluginNames() method
for more details.

...

A sequence plugin is returned as an array of `Objects` since it
is actually an ordered list of plugins.
See the methods
#PluginManager Class #getSinglePlugingetSinglePlugin(), #getPluginSequencegetPluginSequence(), #getNamedPlugingetNamedPlugin()

Lifecycle Management

When `PluginManager` fulfills a request for a plugin, it checks whether
the implementation class is reusable; if so, it creates one
instance of that class and returns it for every subsequent request for
that interface and name. If it is not reusable, a new instance is always
created.

...

The `PluginManager` can list all the names of the
Named Plugins which implement an interface.
You may need this, for example, to implement a menu in a user interface
that presents a choice among all possible plugins.
See the method
#PluginManager Class #getPluginNamesgetPluginNames().
Note that it only returns the plugin name, so if you need a
more sophisticated or meaningful "label" (i.e. a key into the I18N
message catalog) then you should add a method to the plugin itself to
return that.

...

Returns an instance of a plugin that implements the interface intface
and is bound to a name matching name. If there is no matching
plugin, it returns `null`. The names are matched by `String.equals()`.
See the `plugin.named` and
`plugin.selfnamed` configuration keys for configuration details.

...

A named plugin implementation must `extend` this class if it
wants to supply its own Plugin Name(s). See
#SelfSelf-Named Plugins for why this is sometimes necessary.

...