org.platonos.pluginengine
Class Plugin

java.lang.Object
  org.platonos.pluginengine.Plugin

All Implemented Interfaces:

java.lang.Comparable

public class Plugin

extends java.lang.Object

implements java.lang.Comparable

Provides a feature or ability through Java classes, ExtensionPoints, and/or Extensions. A Plugin is defined in the plugin.xml file. Here is an example plugin.xml with links to the corresponding methods:

<plugin start="true">
<name>Example Plugin</name>
<version>1.0.0</version>
<uid>example</uid>
<lifecycleclass>example.ExamplePluginLifecycle</lifecycleclass>
<dependencies>
<dependency uid="example.someOtherPlugin" minversion="0.5" maxversion="1" />
<dependency uid="example.otherPlugin" version="1.0" optional="true" />
</dependencies>
<extensionpoints>
<extensionpoint name="startup" interface="example.IStartup" />
</extensionpoints>
<extensions>
<extension uid="example.otherPlugin" name="help" class="example.HelpAction" />
</extensions>
</plugin>

The "uid" element is required, all other elements and attributes are optional.

Author:

Kevin Duffey (kevinmduffey@yahoo.com), Evert, Nathan Sweet (misc@n4te.com)

See Also:

PluginLifecycle, Dependency, ExtensionPoint, Extension

Constructor Summary

Plugin(PluginEngine pluginEngine)
Creates a new Plugin that cannot load classes and resources.

Plugin(PluginEngine pluginEngine, java.net.URL pluginURL)
Creates a new Plugin that can load classes and resources at the specified Plugin URL.

Method Summary

void	addDependency(Dependency dependency) Adds a Dependency that represents a Plugin that this Plugin is dependent upon.
void	addExtension(Extension extension) Adds an Extension to this Plugin.
void	addExtensionPoint(ExtensionPoint extensionPoint) Adds an ExtensionPoint to this Plugin.
int	compareTo(java.lang.Object object)
int	compareTo(Plugin plugin) Compares this Plugin's version with the specified Plugin's version.
void	disable() Unresolves this specified Plugin and prohibits it from becoming resolved again.
void	enable() Allows this previously disabled Plugin to become resolved again.
java.util.List	getDependencies() Returns a List of this Plugin's Dependencies.
Dependency	getDependency(java.lang.String pluginUID) Returns the Dependency for the specified Plugin UID or null if no Dependency was found.
boolean	getDependentPluginLookup() Returns true if this Plugin will look for classes in Plugins dependent upon it.
java.util.List	getDependentPlugins() Returns a List of Plugins that are dependent upon this Plugin.
ExtensionPoint	getExtensionPoint(java.lang.String name) Returns an ExtensionPoint defined in this Plugin or null if the ExtensionPoint does not exist in this Plugin.
java.util.List	getExtensionPoints() Returns all ExtensionPoints for this Plugin.
java.util.List	getExtensions() Returns a List of all Extensions for this Plugin.
java.lang.String	getExtractedResourcePath(java.lang.String name) Returns an absolute path to the resource with the given name.
java.lang.String	getLifecycleClassName() Returns the name of the lifecycle Class that manages this Plugin's lifecycle or null if there is no lifecycle class.
PluginLifecycle	getLifecycleInstance() Starts the Plugin if not started and returns the lifecycle instance that manages this Plugin's lifecycle or null if there is no lifecycle class or the Plugin could not be started.
PluginXmlNode	getMetadataXmlNode() Returns the PluginXmlNode that represents the "metadata" XML element in the plugin.xml file or null if there is none.
java.lang.String	getName() Returns the friendly name given to this Plugin.
java.lang.ClassLoader	getPluginClassLoader() Returns the ClassLoader used to load classes within this Plugin.
PluginEngine	getPluginEngine() Returns the PluginEngine instance that this Plugin is associated with.
java.net.URL	getPluginURL() Returns the location this Plugin uses to lookup class files and resources.
boolean	getStartWhenResolved() Returns true if this Plugin will be started as soon as possible after being loaded into the PluginEngine.
java.lang.String	getUID() Returns the unique ID for this Plugin.
PluginVersion	getVersion() Returns the version of this Plugin.
int	hashCode() Implements hashCode by using the hash of the objects used in the equals() comparison and multiplying by prime numbers.
boolean	isArchive() Returns true if this Plugin resides in an archive file.
boolean	isCompatible(Plugin plugin) Returns true if the specified Plugin is version compatible with a Dependency of this Plugin or if no Dependency exists.
boolean	isDisabled() Returns true if this Plugin has been disabled.
boolean	isResolved() Returns true if this Plugin has been resolved.
boolean	isStarted() Returns true if this Plugin has been started.
void	removeDependency(Dependency dependency) Unresolves the specified Dependency and removes it from this Plugin.
void	removeExtension(Extension extension) Unresolves the specified Extension and removes it from this Plugin.
void	removeExtensionPoint(ExtensionPoint extensionPoint) Unresolves all Extensions attached to the specified ExtensionPoint and removes it from this Plugin.
java.lang.String	replaceToken(java.lang.String token) Replaces the specified token with a PluginEngine token, System property, or String for the plugin.properties resource file.
void	setDependentPluginLookup(boolean dependentPluginLookup) If true, when this Plugin is unable to find a class within its own classpath and its Dependencies, it first will look in the Plugins that are dependent upon this Plugin for the class before delegating to the class loader that loaded the PluginEngine class.
void	setLifecycleClassName(java.lang.String lifecycleClassName) Sets the name of the lifecycle Class that manages this Plugin's lifecycle.
void	setMetadataXmlNode(PluginXmlNode metadataXmlNode) Sets the root PluginXmlNode for this Plugin's metadata.
void	setName(java.lang.String name) Sets the friendly name of this Plugin.
void	setStartWhenResolved(boolean startWhenResolved) If true, this Plugin will be started as soon as possible after being resolved.
void	setUID(java.lang.String uid) Sets the unique ID for this Plugin.
void	setVersion(PluginVersion version) Sets the version of this Plugin.
boolean	start() Starts this Plugin if it is not already started.
void	stop() Stops this Plugin if it is not already stopped.
java.lang.String	toString() Returns this Plugin's friendly name.
void	unload() Unloads this Plugin.

Methods inherited from class java.lang.Object

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

Constructor Detail

Plugin

public Plugin(PluginEngine pluginEngine)

Creates a new Plugin that cannot load classes and resources.

Plugin

public Plugin(PluginEngine pluginEngine,
              java.net.URL pluginURL)

Creates a new Plugin that can load classes and resources at the specified Plugin URL.

Parameters:

pluginURL - The location this Plugin uses to lookup class files and resources.

Method Detail

start

public boolean start()

Starts this Plugin if it is not already started. A Plugin will not start if it has required Dependencies that are not resolved or if it has an unresolved Extension to a required Dependency.

stop

public void stop()

Stops this Plugin if it is not already stopped.

unload

public void unload()

Unloads this Plugin. This will cause other Plugins that have a required Dependency on the specified Plugin to become unresolved.

disable

public void disable()

Unresolves this specified Plugin and prohibits it from becoming resolved again.

enable

public void enable()

Allows this previously disabled Plugin to become resolved again.

addExtensionPoint

public void addExtensionPoint(ExtensionPoint extensionPoint)

Adds an ExtensionPoint to this Plugin. ExtensionPoints must be added before a Plugin is added to the PluginEngine.

removeExtensionPoint

public void removeExtensionPoint(ExtensionPoint extensionPoint)

Unresolves all Extensions attached to the specified ExtensionPoint and removes it from this Plugin.

getExtensionPoint

public ExtensionPoint getExtensionPoint(java.lang.String name)

Returns an ExtensionPoint defined in this Plugin or null if the ExtensionPoint does not exist in this Plugin.

Parameters:

name - The name of the ExtensionPoint.

getExtensionPoints

public java.util.List getExtensionPoints()

Returns all ExtensionPoints for this Plugin.

addExtension

public void addExtension(Extension extension)

Adds an Extension to this Plugin. Extensions must be added before a Plugin is added to the PluginEngine. If no Dependency exists to the Plugin that the Extension attaches to, then an optional Dependency will be created to the other Plugin.

removeExtension

public void removeExtension(Extension extension)

Unresolves the specified Extension and removes it from this Plugin. If the Dependency on the Plugin the Extension was attached to is optional and this Plugin has no other Extensions to that Plugin, then the Dependency will be removed.

getExtensions

public java.util.List getExtensions()

Returns a List of all Extensions for this Plugin.

addDependency

public void addDependency(Dependency dependency)

Adds a Dependency that represents a Plugin that this Plugin is dependent upon. Dependencies must be added before a Plugin is added to the PluginEngine. If the Dependency already exists it will be overwritten.

removeDependency

public void removeDependency(Dependency dependency)

Unresolves the specified Dependency and removes it from this Plugin. If the Dependency is required and is resolved then this Plugin will be unresolved. If this Plugin has an Extension to the Dependency's plugin then the old Dependency will be replaced by an optional Dependency (see addExtension(Extension)).

getDependencies

public java.util.List getDependencies()

Returns a List of this Plugin's Dependencies.

getDependency

public Dependency getDependency(java.lang.String pluginUID)

Returns the Dependency for the specified Plugin UID or null if no Dependency was found.

getDependentPlugins

public java.util.List getDependentPlugins()

Returns a List of Plugins that are dependent upon this Plugin.

getPluginClassLoader

public java.lang.ClassLoader getPluginClassLoader()

Returns the ClassLoader used to load classes within this Plugin. This is not the ClassLoader that loaded the Plugin class.

isCompatible

public boolean isCompatible(Plugin plugin)

Returns true if the specified Plugin is version compatible with a Dependency of this Plugin or if no Dependency exists.

getExtractedResourcePath

public java.lang.String getExtractedResourcePath(java.lang.String name)
                                          throws java.io.IOException

Returns an absolute path to the resource with the given name. If a Plugin is an archive the resource will be extracted to the user's temp directory. Each Plugin is given its own extracted resource location. Extraction of a specific resource is only done once during the lifetime of the Plugin. This method either returns a path or throws IOException, it never returns null.

Throws:

java.io.IOException - if the resource does not exist or could not be extracted.

replaceToken

public java.lang.String replaceToken(java.lang.String token)

Replaces the specified token with a PluginEngine token, System property, or String for the plugin.properties resource file.

Parameters:

token - A String starting and ending with "%%" for a PluginEngine token or System property, or with "$$" for a plugin.properties resource.

setLifecycleClassName

public void setLifecycleClassName(java.lang.String lifecycleClassName)

Sets the name of the lifecycle Class that manages this Plugin's lifecycle.

See Also:

PluginLifecycle

getLifecycleClassName

public java.lang.String getLifecycleClassName()

Returns the name of the lifecycle Class that manages this Plugin's lifecycle or null if there is no lifecycle class.

See Also:

PluginLifecycle

getLifecycleInstance

public PluginLifecycle getLifecycleInstance()

Starts the Plugin if not started and returns the lifecycle instance that manages this Plugin's lifecycle or null if there is no lifecycle class or the Plugin could not be started.

See Also:

PluginLifecycle

setMetadataXmlNode

public void setMetadataXmlNode(PluginXmlNode metadataXmlNode)

Sets the root PluginXmlNode for this Plugin's metadata.

getMetadataXmlNode

public PluginXmlNode getMetadataXmlNode()

Returns the PluginXmlNode that represents the "metadata" XML element in the plugin.xml file or null if there is none. This can contain any XML that the Plugin wants to provide, such as vendor name, copyright, description, etc.

setName

public void setName(java.lang.String name)

Sets the friendly name of this Plugin.

getName

public java.lang.String getName()

Returns the friendly name given to this Plugin. This can be used for display in lists, logging, etc. If the name is null or unset the UID will be returned.

isArchive

public boolean isArchive()

Returns true if this Plugin resides in an archive file. Returns false if it is an exploded directory on disk.

getPluginURL

public java.net.URL getPluginURL()

Returns the location this Plugin uses to lookup class files and resources. If the Plugin resides on disk in an exploded directory, this will be the absolute path to the directory. If the Plugin is an archive file, this will point directly to the file on disk.

See Also:

isArchive()

isStarted

public boolean isStarted()

Returns true if this Plugin has been started.

See Also:

start(), PluginLifecycle.start()

isResolved

public boolean isResolved()

Returns true if this Plugin has been resolved. A Plugin is resolved as soon as all of its required Dependencies have resolved.

isDisabled

public boolean isDisabled()

Returns true if this Plugin has been disabled.

See Also:

PluginEngine.disablePlugin(Plugin)

getUID

public java.lang.String getUID()

Returns the unique ID for this Plugin. This is used to obtain a reference to this Plugin through the PluginEngine.

setUID

public void setUID(java.lang.String uid)

Sets the unique ID for this Plugin.

setStartWhenResolved

public void setStartWhenResolved(boolean startWhenResolved)

If true, this Plugin will be started as soon as possible after being resolved. If the PluginEngine is not started yet, the Plugin won't be started until the PluginEngine is started.

See Also:

start(), PluginLifecycle.start()

getStartWhenResolved

public boolean getStartWhenResolved()

Returns true if this Plugin will be started as soon as possible after being loaded into the PluginEngine.

setDependentPluginLookup

public void setDependentPluginLookup(boolean dependentPluginLookup)

If true, when this Plugin is unable to find a class within its own classpath and its Dependencies, it first will look in the Plugins that are dependent upon this Plugin for the class before delegating to the class loader that loaded the PluginEngine class. Defaults to false. This feature is very rarely needed but can be useful when code that is not modifiable (such as a third party library) does a class lookup without allowing the classloader to be specified.

getDependentPluginLookup

public boolean getDependentPluginLookup()

Returns true if this Plugin will look for classes in Plugins dependent upon it.

See Also:

setDependentPluginLookup(boolean)

setVersion

public void setVersion(PluginVersion version)

Sets the version of this Plugin.

getVersion

public PluginVersion getVersion()

Returns the version of this Plugin.

hashCode

public int hashCode()

Implements hashCode by using the hash of the objects used in the equals() comparison and multiplying by prime numbers.

toString

public java.lang.String toString()

Returns this Plugin's friendly name.

getPluginEngine

public PluginEngine getPluginEngine()

Returns the PluginEngine instance that this Plugin is associated with.

compareTo

public int compareTo(java.lang.Object object)

Specified by:

compareTo in interface java.lang.Comparable

See Also:

compareTo(Plugin)

compareTo

public int compareTo(Plugin plugin)

Compares this Plugin's version with the specified Plugin's version.

Returns:

A negative int, zero, or a positive int if this Plugin's version is less than, equal to, or greater than the specified Plugin's version.