Package org.processmining.framework.plugin

Interface PluginManager

All Known Implementing Classes:

PluginManagerImpl

public interface PluginManager

The plugin manager manages plugins. It loads plugins from URLs and provides access to them through search methods.

Author:

bfvdonge

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	PluginManager.PluginManagerListener	This interface describes an error listener for the plugin manager.

Field Summary

Fields

Modifier and Type	Field	Description
static java.lang.String	CLASS_EXTENSION	Constant to denote the file extension for class files.
static java.lang.String	FILE_PROTOCOL	Constant to denote the file protocol to be used in URLs provided to this plugin manager.
static java.lang.String	JAR_EXTENSION	Constant to denote the file extension for jar files.
static java.lang.String	MCR_EXTENSION	Constant to denote the file extension for macro files.

Method Summary

Modifier and Type	Method	Description
void	addListener(PluginManager.PluginManagerListener listener)	Adds a listener to the plugin manager.
java.util.Set<Pair<java.lang.Integer,PluginParameterBinding>>	find(java.lang.Class<? extends java.lang.annotation.Annotation> annotation, java.lang.Class<?>[] resultTypes, java.lang.Class<? extends PluginContext> contextType, boolean totalMatch, boolean orderedParameters, boolean mustBeUserVisible, java.lang.Class<?>... parameters)	This method retuns a collection of Pairs of Integer and PluginParameterBinding objects, such that:
java.util.Set<Pair<java.lang.Integer,PluginParameterBinding>>	find(java.lang.Class<? extends java.lang.annotation.Annotation> annotation, java.lang.Class<?> resultType, java.lang.Class<? extends PluginContext> contextType, boolean totalMatch, boolean orderedParameters, boolean mustBeUserVisible, java.lang.Class<?>... args)	This method retuns a collection of Pairs of Integer and PluginParameterBinding objects, such that:
java.util.SortedSet<PluginDescriptor>	getAllPlugins()	Returns all plugin descriptors
java.util.SortedSet<PluginDescriptor>	getAllPlugins(boolean mustBeVisible)	Returns all plugin descriptors known to the plugin manager.
java.util.Set<java.lang.Class<?>>	getKnownClassesAnnotatedWith(java.lang.Class<? extends java.lang.annotation.Annotation> annotationType)	Returns all known classes annotated with a certain annotationType.
java.util.Set<java.lang.Class<?>>	getKnownObjectTypes()	Returns the set of types that is known to the plugin manager.
PluginDescriptor	getPlugin(java.lang.String id)	Returns a PluginDescriptor of which the toString() of its id equals the given id.
PluginDescriptor	getPlugin(PluginDescriptorID id)	Returns a PluginDescriptor with the given id.
java.util.Set<PluginParameterBinding>	getPluginsAcceptingAtLeast(java.lang.Class<? extends PluginContext> contextType, boolean mustBeUserVisible, java.lang.Class<?>... parameters)	Returns PluginParameterBindings, which can be invoked in the given context on the given parameter types.
java.util.Set<PluginParameterBinding>	getPluginsAcceptingInAnyOrder(java.lang.Class<? extends PluginContext> contextType, boolean mustBeUserVisible, java.lang.Class<?>... parameters)	Returns executable PluginParameterBindings, which can be invoked in the given context on the given parameter types.
java.util.Set<PluginParameterBinding>	getPluginsAcceptingOrdered(java.lang.Class<? extends PluginContext> contextType, boolean mustBeUserVisible, java.lang.Class<?>... parameters)	Returns executable PluginParameterBindings, which can be invoked in the given context on the given parameter types.
java.util.Set<Pair<java.lang.Integer,PluginDescriptor>>	getPluginsResultingIn(java.lang.Class<? extends java.lang.Object> resultType, java.lang.Class<? extends PluginContext> contextType, boolean mustBeUserVisible)	Find the plugins resulting in the given type.
boolean	isParameterAssignable(java.lang.Class<?> instanceType, java.lang.Class<?> requestedType)	Returns true if the instance type can be cast to the requested type, or if the requested type is an array and the instance type can be cast to the component type of the requested type.
void	register(java.net.URL url, PackageDescriptor pack)	registers a URL to this plugin manager.
void	register(java.net.URL url, PackageDescriptor pack, java.lang.ClassLoader loader)	registers a URL to this plugin manager.
void	removeListener(PluginManager.PluginManagerListener listener)	Removes the listener from the plugin manager.

Field Detail

CLASS_EXTENSION

static final java.lang.String CLASS_EXTENSION

Constant to denote the file extension for class files.

See Also:

Constant Field Values

MCR_EXTENSION

static final java.lang.String MCR_EXTENSION

Constant to denote the file extension for macro files.

See Also:

Constant Field Values

JAR_EXTENSION

static final java.lang.String JAR_EXTENSION

Constant to denote the file extension for jar files.

See Also:

Constant Field Values

FILE_PROTOCOL

static final java.lang.String FILE_PROTOCOL

Constant to denote the file protocol to be used in URLs provided to this plugin manager.

See Also:

Constant Field Values

Method Detail

addListener

void addListener(PluginManager.PluginManagerListener listener)

Adds a listener to the plugin manager.

Parameters:

listener - the listener to add.

removeListener

void removeListener(PluginManager.PluginManagerListener listener)

Removes the listener from the plugin manager.

Parameters:

listener - the listener to remove.

register

void register(java.net.URL url,
              PackageDescriptor pack)

registers a URL to this plugin manager. If the URL uses the FILE_PROTOCOl protocol and denotes a directory, then this folder is recursively scanned for files with the CLASS_EXTENSION extension. Otherwise, the URL is assumed to point to a jar file, of which the classes are scanned. Each class file is scanned for classes and/or methods annotated with the Plugin annotation. If a class is annotated with this annotation, then its methods are scanned for the PluginVariant annotation. For each plugin found, a PluginDescriptor object is instantiated. These plugin descriptors can later be used to invoke plugins.

Parameters:

url - The URL to register

pack - The package that corresponds to the URL

register

void register(java.net.URL url,
              PackageDescriptor pack,
              java.lang.ClassLoader loader)

registers a URL to this plugin manager. If the URL uses the FILE_PROTOCOl protocol and denotes a directory, then this folder is recursively scanned for files with the CLASS_EXTENSION extension. Otherwise, the URL is assumed to point to a jar file, of which the classes are scanned. Each class file is scanned for classes and/or methods annotated with the Plugin annotation. If a class is annotated with this annotation, then its methods are scanned for the PluginVariant annotation. For each plugin found, a PluginDescriptor object is instantiated. These plugin descriptors can later be used to invoke plugins.

Parameters:

url - The URL to register

pack - The package that corresponds to the URL

loader - The class loader used to load the jar files.

find

java.util.Set<Pair<java.lang.Integer,PluginParameterBinding>> find(java.lang.Class<? extends java.lang.annotation.Annotation> annotation,
                                                                         java.lang.Class<?> resultType,
                                                                         java.lang.Class<? extends PluginContext> contextType,
                                                                         boolean totalMatch,
                                                                         boolean orderedParameters,
                                                                         boolean mustBeUserVisible,
                                                                         java.lang.Class<?>... args)

This method retuns a collection of Pairs of Integer and PluginParameterBinding objects, such that:

The method belonging to the plugin in the pluginParameterBinding carries the given annotation. If no specific annotation is required, the method should be called with Plugin.class. Note that the annotation required has to be on the same level as the Plugin annotation, i.e. either on a method or a class

When invoked, the PluginParameterBinding returns an array of objects, of which the object at the index given by the integer in the pair is of the required result type, i.e. resultType.isAssignableFrom(p.getPlugin().getReturnTypes()[i]) If no specific return type is required, use Object.class for this parameter.

The PluginParameterBinding can be executed in a PluginContext of the given type.

If totalMatch is true, then the PluginParameterBinding binds all parameters of the plugin with all arguments. Otherwise, the PluginParameterBinding only requires a subset of the given arguments and is therefore not directly executable on the given set of arguments.

If orderedParameters is true, then the PluginParameterBinding binds the given arguments in the given order, i.e. no arguments are reordered.

If mustBeUserVisible is true, then the plugin must have the isUserVisible flag set to true.

The PluginParameterBinding can be executed on arguments of the given types. The list of arguments can be empty, in which case no arguments are required to invoke the PluginParameterBinding. Note that only types of arguments are required, not the values. For checking whether arguments can be assigned to parameters of the Plugin, the isParameterAssignable method is used. Any ProMFutures should be unwrapped.

Parameters:

annotation - The annotation that should be present on the plugin (use Plugin.class if none is required).

resultType - The required result type (use Object.class if no specific type is required).

contextType - The context type in which this plugin should be executable. Note that this type should be the contextType of the context from which the find is called, or a supertype thereof.

totalMatch - Whether or not all arguments should be used to execute this plugin.

orderedParameters - Whether or not the arguments are given in the right order.

mustBeUserVisible - Whether or not all returned plugins should be user visible.

args - The types of the arguments provided to the plugin. Can be empty.

Returns:

A collection of pluginparameterbindings. They are executable if totalMatch is true.

find

java.util.Set<Pair<java.lang.Integer,PluginParameterBinding>> find(java.lang.Class<? extends java.lang.annotation.Annotation> annotation,
                                                                         java.lang.Class<?>[] resultTypes,
                                                                         java.lang.Class<? extends PluginContext> contextType,
                                                                         boolean totalMatch,
                                                                         boolean orderedParameters,
                                                                         boolean mustBeUserVisible,
                                                                         java.lang.Class<?>... parameters)

This method retuns a collection of Pairs of Integer and PluginParameterBinding objects, such that:

The method belonging to the plugin in the pluginParameterBinding carries the given annotation. If no specific annotation is required, the method should be called with Plugin.class. Note that the annotation required has to be on the same level as the Plugin annotation, i.e. either on a method or a class

When invoked, the PluginParameterBinding returns an array of objects, of which the object at the index given by the integer in the pair is of the required result type as specified in the input list, i.e. for all i resultTypes[i].isAssignableFrom(p.getPlugin().getReturnTypes()[i]) If no specific return type is required, use the other find method.

The PluginParameterBinding can be executed in a PluginContext of the given type.

If totalMatch is true, then the PluginParameterBinding binds all parameters of the plugin with all arguments. Otherwise, the PluginParameterBinding only requires a subset of the given arguments and is therefore not directly executable on the given set of arguments.

If orderedParameters is true, then the PluginParameterBinding binds the given arguments in the given order, i.e. no arguments are reordered.

If mustBeUserVisible is true, then the plugin must have the isUserVisible flag set to true.

The PluginParameterBinding can be executed on arguments of the given types. The list of arguments can be empty, in which case no arguments are required to invoke the PluginParameterBinding. Note that only types of arguments are required, not the values. For checking whether arguments can be assigned to parameters of the Plugin, the isParameterAssignable method is used. Any ProMFutures should be unwrapped.

Parameters:

annotation - The annotation that should be present on the plugin (use Plugin.class if none is required).

resultTypes - The exact, sorted list of required result types. If not specific type is requested, this find method should not be used.

contextType - The context type in which this plugin should be executable. Note that this type should be the contextType of the context from which the find is called, or a supertype thereof.

totalMatch - Whether or not all arguments should be used to execute this plugin.

orderedParameters - Whether or not the arguments are given in the right order.

mustBeUserVisible - Whether or not all returned plugins should be user visible.

args - The types of the arguments provided to the plugin. Can be empty.

Returns:

A collection of pluginparameterbindings. They are executable if totalMatch is true.

getPluginsResultingIn

java.util.Set<Pair<java.lang.Integer,PluginDescriptor>> getPluginsResultingIn(java.lang.Class<? extends java.lang.Object> resultType,
                                                                                    java.lang.Class<? extends PluginContext> contextType,
                                                                                    boolean mustBeUserVisible)

Find the plugins resulting in the given type. The result are pairs of integers and plugins, such that for each pair (i,p) holds that resultType.isAssignableFrom(p.getReturnTypes()[i])

Parameters:

resultType - Can be null. if null, then any type is considered.

mustBeUserVisible - Whether or not all returned plugins should be user visible.

Returns:

A collection of pairs of integers and plugins, such that for each pair (i,p) holds that resultType.isAssignableFrom(p.getReturnTypes()[i])

getPluginsAcceptingOrdered

java.util.Set<PluginParameterBinding> getPluginsAcceptingOrdered(java.lang.Class<? extends PluginContext> contextType,
                                                                 boolean mustBeUserVisible,
                                                                 java.lang.Class<?>... parameters)

Returns executable PluginParameterBindings, which can be invoked in the given context on the given parameter types. Note that the PluginParameterBindings are executable.

Parameters:

contextType - The type of the context in which the binding is to be invoked.

mustBeUserVisible - Whether or not the plugin should be user visible.

parameters - The types of the arguments passed to the plugins. They are accepted by the plugin in the order in which they are provided.

Returns:

a list of executable bindings

getPluginsAcceptingAtLeast

java.util.Set<PluginParameterBinding> getPluginsAcceptingAtLeast(java.lang.Class<? extends PluginContext> contextType,
                                                                 boolean mustBeUserVisible,
                                                                 java.lang.Class<?>... parameters)

Returns PluginParameterBindings, which can be invoked in the given context on the given parameter types. Note that the PluginParameterBindings are not necessarily executable. However, they accept all given arguments as parameters.

Parameters:

contextType - The type of the context in which the binding is to be invoked.

mustBeUserVisible - Whether or not the plugin should be user visible.

parameters - The types of the arguments passed to the plugins. They are accepted by the returned plugins, but not necessarily in this order.

Returns:

a list of bindings

getPluginsAcceptingInAnyOrder

java.util.Set<PluginParameterBinding> getPluginsAcceptingInAnyOrder(java.lang.Class<? extends PluginContext> contextType,
                                                                    boolean mustBeUserVisible,
                                                                    java.lang.Class<?>... parameters)

Returns executable PluginParameterBindings, which can be invoked in the given context on the given parameter types. Note that the PluginParameterBindings are executable.

Parameters:

contextType - The type of the context in which the binding is to be invoked.

mustBeUserVisible - Whether or not the plugin should be user visible.

parameters - The types of the arguments passed to the plugins. They are accepted by the returned plugins, but not necessarily in this order.

Returns:

a list of executable bindings

getPlugin

PluginDescriptor getPlugin(PluginDescriptorID id)

Returns a PluginDescriptor with the given id. Note that plugin IDs are persistent between runs.

Parameters:

id - the id of the plugin to get

Returns:

the plugin with the given id.

getPlugin

PluginDescriptor getPlugin(java.lang.String id)

Returns a PluginDescriptor of which the toString() of its id equals the given id. Note that plugin IDs are persistent between runs.

Parameters:

id - the String representation of the id of the plugin to get

Returns:

the plugin with an id of which the String representation equals the given id.

getAllPlugins

java.util.SortedSet<PluginDescriptor> getAllPlugins()

Returns all plugin descriptors

Returns:

all plugin descriptors known to the plugin manager.

getAllPlugins

java.util.SortedSet<PluginDescriptor> getAllPlugins(boolean mustBeVisible)

Returns all plugin descriptors known to the plugin manager. If set, only those plugins which are user visible are returned.

Parameters:

mustBeVisible - wether or not the returned plugins should be user visible.

Returns:

the plugin descriptors.

isParameterAssignable

boolean isParameterAssignable(java.lang.Class<?> instanceType,
                              java.lang.Class<?> requestedType)

Returns true if the instance type can be cast to the requested type, or if the requested type is an array and the instance type can be cast to the component type of the requested type.

Parameters:

instanceType - the type that has to be cast to the requested type.

requestedType - the requested type

Returns:

true if a cast can be made, i.e. if an object of type instanceType can be assigned to a parameter of type requestedType of a plugin.

getKnownObjectTypes

java.util.Set<java.lang.Class<?>> getKnownObjectTypes()

Returns the set of types that is known to the plugin manager. Basically, this set contains all types that are ever used as a parameter or a return type of a plugin.

Returns:

a set of types.

getKnownClassesAnnotatedWith

java.util.Set<java.lang.Class<?>> getKnownClassesAnnotatedWith(java.lang.Class<? extends java.lang.annotation.Annotation> annotationType)

Returns all known classes annotated with a certain annotationType. Not all of these classes are plugins! Note that only classes are available that carry the @KeepInProMCache annotation

Parameters:

annotationType - the type of annotation to be found

Returns:

a (possibly empty) set of classes (not null)