org.rhq.core.clientapi.agent.metadata

Class PluginDependencyGraph

java.lang.Object

org.rhq.core.clientapi.agent.metadata.PluginDependencyGraph

public class PluginDependencyGraph
extends Object

This class determines the deployment order for plugins by building the dependency graph of the plugins. You use this class by first adding plugins to the graph, and then when all plugins have been added you can get the deployment order that lists all the plugins in the order in which they should be deployed.

Note that circular dependencies are NOT allowed nor supported.

Author:

John Mazzitelli

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	PluginDependencyGraph.PluginDependency

Constructor Summary

Constructors

Constructor and Description
PluginDependencyGraph()

Method Summary

Methods

Modifier and Type	Method and Description
void	addPlugin(String pluginName, List<PluginDependencyGraph.PluginDependency> dependencies) Adds a plugin to the graph.
Collection<String>	getAllDependencies(String pluginName) Given a plugin that is in this dependency graph, this will return all those plugins the plugin either directly or indirectly depends on it.
Collection<String>	getAllDependents(String pluginName) Given a plugin that is in this dependency graph, this will return all those plugins that either directly or indirectly depend on it (both optional and required dependencies).
List<String>	getDeploymentOrder() Returns the deployment order for all added plugins.
List<String>	getOptionalDependents(String pluginName) Given a plugin that is in this dependency graph, this will return all those plugins that optionally depend on it.
List<String>	getPluginDependencies(String pluginName) Given a plugin that is in this dependency graph, this will return the list of its direct dependencies (the plugins this plugin explicitly depends on).
Set<String>	getPlugins() Returns the set of plugin names that have been added to the dependency graph.
String	getUseClassesDependency(String pluginName) Returns the name of the plugin who's classloader will be used as the parent of this plugin.
boolean	isComplete(StringBuilder errorBuffer) Returns true if the dependency graph has no missing required plugins.
PluginDependencyGraph	reduceGraph() If the current dependency graph is not yet complete, you can call this method to reduce the graph such that plugins with missing required dependencies are removed and only those plugins whose dependencies exist are in the returned graph.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

PluginDependencyGraph

public PluginDependencyGraph()

Method Detail

addPlugin

public void addPlugin(String pluginName,
             List<PluginDependencyGraph.PluginDependency> dependencies)

Adds a plugin to the graph. The plugin names in the dependencies must match names of other plugins that were, or will be, added to this graph.

If the plugin already exists, it will be overridden such that the given dependencies replace its old ones.

Parameters:

pluginName - the name of the plugin getting added to the graph

dependencies - list of plugin names that are dependencies of this plugin

getUseClassesDependency

public String getUseClassesDependency(String pluginName)

Returns the name of the plugin who's classloader will be used as the parent of this plugin. If none is explicitly declared, the last one in the dependency list will be used.

Parameters:

the - name of the plugin whose required dependency contains classes that are to be accessible by the plugin

Returns:

the required dependency for the given plugin, or null if there is no required dependency

getPlugins

public Set<String> getPlugins()

Returns the set of plugin names that have been added to the dependency graph.

Returns:

set of all plugin names that were added to this graph

getPluginDependencies

public List<String> getPluginDependencies(String pluginName)

Given a plugin that is in this dependency graph, this will return the list of its direct dependencies (the plugins this plugin explicitly depends on). The list will be empty if there are no dependencies or the plugin does not exist in this graph. Note that if a dependency is not required to exist, and it does not exist, it will not be returned in the list. This is to say that if a plugin was configured to depend on another plugin, but that dependency was not required, that other plugin will not be in the returned list if it hasn't been added to this graph yet.

Parameters:

pluginName - the plugin name

Returns:

list of plugin dependencies

getOptionalDependents

public List<String> getOptionalDependents(String pluginName)

Given a plugin that is in this dependency graph, this will return all those plugins that optionally depend on it. If a plugin has a required dependency on the given plugin, or a plugin does not depend on the given plugin at all, that plugin will not be in the returned list.

Parameters:

pluginName - the plugin whose dependents are to be returned

Returns:

list of all plugins that optionally depend on the given plugin

getAllDependencies

public Collection<String> getAllDependencies(String pluginName)

Given a plugin that is in this dependency graph, this will return all those plugins the plugin either directly or indirectly depends on it. This is different than getPluginDependencies(String) because this method does a deep dive and returns all direct dependencies and dependencies of those dependencies.

Parameters:

pluginName - the plugin whose dependencies are to be returned

Returns:

list of all plugins that the given plugin depends on

getAllDependents

public Collection<String> getAllDependents(String pluginName)

Given a plugin that is in this dependency graph, this will return all those plugins that either directly or indirectly depend on it (both optional and required dependencies).

Parameters:

pluginName - the plugin whose dependents are to be returned

Returns:

list of all plugins that depend on the given plugin

isComplete

public boolean isComplete(StringBuilder errorBuffer)
                   throws IllegalStateException

Returns true if the dependency graph has no missing required plugins. That is to say, all required dependencies of all plugins can be found in this graph. If this returns true, you can safely call getDeploymentOrder() and expect it to return an ordered list of plugins. This will return false if one or more required dependencies are missing and still need to be added. This will throw an exception if a circular dependency has been detected.

Parameters:

errorBuffer - if not null and this method returns false, this will be appended with the error message that will contain information on the first plugin found to be missing

Returns:

true if there are no missing dependencies and getDeploymentOrder() can be called

Throws:

IllegalStateException - if a circular dependency has been detected

getDeploymentOrder

public List<String> getDeploymentOrder()
                                throws IllegalStateException,
                                       IllegalArgumentException

Returns the deployment order for all added plugins. If a required dependency is missing and thus one or more plugins cannot be deployed, an exception is thrown. If an optional dependency is missing, that optional dependency plugin will be ignored and not returned in the list.

Returns:

the list of plugin names, in the order in which they can be deployed.

Throws:

IllegalStateException - if a circular dependency has been detected

IllegalArgumentException - if one or more plugins depend on other plugins that are missing from the graph

reduceGraph

public PluginDependencyGraph reduceGraph()

If the current dependency graph is not yet complete, you can call this method to reduce the graph such that plugins with missing required dependencies are removed and only those plugins whose dependencies exist are in the returned graph. In other words, this method will return a dependency graph that is guaranteed to be complete and return a getDeploymentOrder() - albeit with only those plugins that currently have all dependencies.

Returns:

a reduced graph that contains only those plugins that have all their dependencies

toString

public String toString()

Overrides:

toString in class Object