ti.chimera
Class Plugin

java.lang.Object
  extended byti.chimera.Plugin
Direct Known Subclasses:
AbstractModePlugin, SwingWorkerPlugin, WindowManagerPlugin

public abstract class Plugin
extends java.lang.Object

The abstract base class for all plugins. This class provides an easy to use framework for adding modules to chimera, and a mechanism to manage resources created by this plugin.

The plugin class itself should be a lightweight container for all the resources created and/or provided by the plugin. The plugin class will be instantiated at startup regardless of whether the plugin is actually started. As much as possible, all resources created by a plugin should not be created until the the plugin is started. This can be accomplish by using managed resources.

The Resource mechanism is used for managing resources created by this plugin. A plugin is active (ie. running) whenever it has installed resources, and it is in-active (ie. stopped) whenever all it's resources have been uninstalled. There are two types of resources that can be created (see addResource(ti.chimera.Resource), managed, and unmanaged. A managed resources is automatically Resource.install()ed when the plugin is started, and Resource.uninstall()ed when the plugin is stopped. An unmanaged resource is Resource.install()ed when it is added (addResource(ti.chimera.Resource)), and Resource.uninstall()ed when it is removed (removeResource(ti.chimera.Resource)). Adding an unmanaged resource will cause the plugin to become active, if it wasn't already active, and removing an unmanaged resource could cause the plugin to become inactive if there are no more unmanaged resources.

Version:
0.1
Author:
Rob Clark

Nested Class Summary
 class Plugin.MenuBarItemResource
          A MenuBarItemResource adds to / removes from the system wide menubar.
 class Plugin.RegistrySubscriberResource
          A registry resource handles installing/uninstalling various registry subscribers when the plugin becomes active/inactive.
 class Plugin.ServiceFactory
          Because the garbage collection of a service instance (among other things) is used to determine if a Plugin should be stopped, the Registry cannot hold a reference to the service itself.
static interface Plugin.ToolBarFactory
          In order to create the ToolBarResource without creating the JToolBar itself, a ToolBarResource is created with a reference to a ToolBarFactory which is called on demand to create the tool-bar.
 class Plugin.ToolBarResource
          A tool-bar-resource adds a tool-bar when installed, and removes when uninstalled.
static interface Plugin.ViewFactory
          In order to create a managed ViewResource, we need to create the resource without creating the view itself.
 class Plugin.ViewResource
          A view-resource adds a view, when installed, and removes the view when uninstalled.
 
Field Summary
protected  Main main
          The main application.
 
Constructor Summary
Plugin(Main main, java.lang.String name)
          Class Constructor.
 
Method Summary
 void addResource(Resource r)
          Add a resource.
 java.lang.String getName()
          Get the name of this plugin instance.
 boolean isActive()
          Determine if this plugin is currently active.
 void registerService(Service s)
          Deprecated. use registerServiceFactory instead.
 void registerServiceFactory(Plugin.ServiceFactory sh)
          Register a service provided by this plugin.
 void registerServiceFactory(oscript.data.Value fxn)
          This is provided to make life easy for script code...
 void removeResource(Resource r)
          Remove a resource.
 java.lang.String toString()
          Overloaded to provide some info about the state of the plugin, which might be useful while debugging/developing plugins.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

main

protected Main main
The main application.

Constructor Detail

Plugin

public Plugin(Main main,
              java.lang.String name)
Class Constructor.

Parameters:
main - the main application
name - the name of this plugin instance
Method Detail

getName

public java.lang.String getName()
Get the name of this plugin instance.

Returns:
the name

registerServiceFactory

public final void registerServiceFactory(Plugin.ServiceFactory sh)
Register a service provided by this plugin. The serviced provided by the plugin should be registered by the plugin's constructor, rather than by the #start method, so that the registry can determine which services are provided by which plugin.

A service is registered via a Plugin.ServiceFactory, which should be the one to actually create an instance of the service. This is done this way because the registry tracks the instances of a service, and adds/removes managed resources to when a service instance is created/ GC'd. If the registry, or any other code, where to hold a reference to the service itself, rather than the service-factory, the service would never get garbage collected.

The only reason this method is public is for the benefit of plugins implemented as script. The way the ObjectScript interpreter works, script code only has access to public methods of a class. This method should be treated as if it were protected.

Parameters:
sh - a factory to a service provided by this plugin

registerServiceFactory

public final void registerServiceFactory(oscript.data.Value fxn)
This is provided to make life easy for script code... script code can simply pass in a function that returns a service, rather than having to pass in an instance of Plugin.ServiceFactory.

Parameters:
fxn - a script function that takes no args and returns a instance of a service

registerService

public final void registerService(Service s)
Deprecated. use registerServiceFactory instead.


addResource

public void addResource(Resource r)
Add a resource. If the resource is unmanaged, this could cause the plugin to become active if it is not already. This does nothing if the resource has already been added.

Parameters:
r - the resource to add
See Also:
removeResource(ti.chimera.Resource)

removeResource

public void removeResource(Resource r)
Remove a resource. If the resource is unmanged, and there no more unmanaged resources, this will cause the plugin to become inactive. This does nothing if the resource has not already been added.

Parameters:
r - the resource to add
See Also:
addResource(ti.chimera.Resource)

isActive

public final boolean isActive()
Determine if this plugin is currently active. An active plugin is one for which the #start method has been called since the last time #stop has been called.

See Also:
#start, #stop

toString

public java.lang.String toString()
Overloaded to provide some info about the state of the plugin, which might be useful while debugging/developing plugins.

Returns:
a string