Framework - Revision history

Watkinson: /* Visual Plugins and GUIFramework */

2006-03-15T20:07:13Z

‎Visual Plugins and GUIFramework

Watkinson: /* Visual Plugins and GUIFramework */

2006-03-15T20:06:46Z

‎Visual Plugins and GUIFramework

Watkinson: /* Visual Plugins and GUIFramework */

2006-03-15T20:06:13Z

‎Visual Plugins and GUIFramework

Watkinson: /* The Project Panel and Data Sets */

2006-03-15T20:05:00Z

‎The Project Panel and Data Sets

Watkinson: /* Synchronization Models */

2006-03-15T19:51:01Z

‎Synchronization Models

Watkinson at 19:49, 15 March 2006

2006-03-15T19:49:03Z

Watkinson at 19:47, 15 March 2006

2006-03-15T19:47:07Z

Floratos at 21:33, 14 March 2006

2006-03-14T21:33:53Z

Watkinson: /* Visual Plugins and GUIFramework */

2006-03-14T21:02:37Z

‎Visual Plugins and GUIFramework

Watkinson at 20:58, 14 March 2006

2006-03-14T20:58:39Z

@@ Line 65: / Line 65: @@
 Many plugins have a visual representation. This visual intention is advertised to the framework by the plugin implementing [{{SERVER}}/workbench/api/org/geworkbench/engine/config/VisualPlugin.html <tt>org.geworkbench.engine.config.VisualPlugin</tt>]. Some plugins, such as file parsers and analyses, do not require a visual representation, and so do not implement this interface.
-Those that implement VisualPlugin will have extra directives included in the configuration file to indicate how they should be laid out in the interface. These directives are passed on from the configuration engine to the rendering framework. The rendering framework is itself configurable, and is a class that extends [{{SERVER}}/workbench/api/org/geworkbench/engine/config/GUIFramework.html <tt>org.geworkbench.engine.config.GUIFramework</tt>]. The default and most full-featured implementation of GUIFramework is [{{SERVER}}/workbench/api/org/geworkbench/engine/Skin.html <tt>org.geworkbench.engine.Skin</tt>]. This implementation supports four layout areas (''Project'', ''Selection'', ''Command'' and ''Visual''). It also supports an annotation system for determining which visual components to display based on the selected data set in the Project Panel.
+Those that implement VisualPlugin will have extra directives included in the configuration file to indicate how they should be laid out in the interface. These directives are passed on from the configuration engine to the rendering framework. The rendering framework is itself configurable, and is a class that extends [{{SERVER}}/workbench/api/org/geworkbench/engine/config/GUIFramework.html <tt>org.geworkbench.engine.config.GUIFramework</tt>]. The default and most full-featured implementation of GUIFramework is [{{SERVER}}/workbench/api/org/geworkbench/engine/skin/Skin.html <tt>org.geworkbench.engine.skin.Skin</tt>]. This implementation supports four layout areas (''Project'', ''Selection'', ''Command'' and ''Visual''). It also supports an annotation system for determining which visual components to display based on the selected data set in the Project Panel.
 Visual plugins may annotate their class definition with [{{SERVER}}/workbench/api/org/geworkbench/engine/management/AcceptTypes.html <tt>org.geworkbench.engine.management.AcceptTypes</tt>]. If the annotation is omitted, then the visual plugin will always be rendered by <tt>Skin</tt>. The annotation takes an array of class objects, each of which must be assignable to <tt>DSDataSet</tt>. For example, here is how the ''Color Mosaic Panel'' is annotated:

@@ Line 65: / Line 65: @@
 Many plugins have a visual representation. This visual intention is advertised to the framework by the plugin implementing [{{SERVER}}/workbench/api/org/geworkbench/engine/config/VisualPlugin.html <tt>org.geworkbench.engine.config.VisualPlugin</tt>]. Some plugins, such as file parsers and analyses, do not require a visual representation, and so do not implement this interface.
-Those that implement VisualPlugin will have extra directives included in the configuration file to indicate how they should be laid out in the interface. These directives are passed on from the configuration engine to the rendering framework. The rendering framework is itself configurable, and is a class that extends [{{SERVER}}/workbench/api/org/geworkbench/engine/config/GUIFramework.html <tt>org.geworkbench.engine.config.GUIFramework</tt>]. The default and most full-featured implementation of GUIFramework is [{{SERVER}}/workbench/api/org/geworkbench/engine/config/Skin.html <tt>org.geworkbench.engine.config.Skin</tt>]. This implementation supports four layout areas (''Project'', ''Selection'', ''Command'' and ''Visual''). It also supports an annotation system for determining which visual components to display based on the selected data set in the Project Panel.
+Those that implement VisualPlugin will have extra directives included in the configuration file to indicate how they should be laid out in the interface. These directives are passed on from the configuration engine to the rendering framework. The rendering framework is itself configurable, and is a class that extends [{{SERVER}}/workbench/api/org/geworkbench/engine/config/GUIFramework.html <tt>org.geworkbench.engine.config.GUIFramework</tt>]. The default and most full-featured implementation of GUIFramework is [{{SERVER}}/workbench/api/org/geworkbench/engine/Skin.html <tt>org.geworkbench.engine.Skin</tt>]. This implementation supports four layout areas (''Project'', ''Selection'', ''Command'' and ''Visual''). It also supports an annotation system for determining which visual components to display based on the selected data set in the Project Panel.
 Visual plugins may annotate their class definition with [{{SERVER}}/workbench/api/org/geworkbench/engine/management/AcceptTypes.html <tt>org.geworkbench.engine.management.AcceptTypes</tt>]. If the annotation is omitted, then the visual plugin will always be rendered by <tt>Skin</tt>. The annotation takes an array of class objects, each of which must be assignable to <tt>DSDataSet</tt>. For example, here is how the ''Color Mosaic Panel'' is annotated:

@@ Line 63: / Line 63: @@
 == Visual Plugins and GUIFramework ==
-Many plugins have a visual representation. This visual intention is advertised to the framework by the plugin implementing <tt>org.geworkbench.engine.config.VisualPlugin</tt>. Some plugins, such as file parsers and analyses, do not require a visual representation, and so do not implement this interface.
+Many plugins have a visual representation. This visual intention is advertised to the framework by the plugin implementing [{{SERVER}}/workbench/api/org/geworkbench/engine/config/VisualPlugin.html <tt>org.geworkbench.engine.config.VisualPlugin</tt>]. Some plugins, such as file parsers and analyses, do not require a visual representation, and so do not implement this interface.
-Those that implement VisualPlugin will have extra directives included in the configuration file to indicate how they should be laid out in the interface. These directives are passed on from the configuration engine to the rendering framework. The rendering framework is itself configurable, and is a class that extends <tt>org.geworkbench.engine.config.GUIFramework</tt>. The default and most full-featured implementation of GUIFramework is <tt>org.geworkbench.engine.config.Skin</tt>. This implementation supports four layout areas (''Project'', ''Selection'', ''Command'' and ''Visual''). It also supports an annotation system for determining which visual components to display based on the selected data set in the Project Panel.
+Those that implement VisualPlugin will have extra directives included in the configuration file to indicate how they should be laid out in the interface. These directives are passed on from the configuration engine to the rendering framework. The rendering framework is itself configurable, and is a class that extends [{{SERVER}}/workbench/api/org/geworkbench/engine/config/GUIFramework.html <tt>org.geworkbench.engine.config.GUIFramework</tt>]. The default and most full-featured implementation of GUIFramework is [{{SERVER}}/workbench/api/org/geworkbench/engine/config/Skin.html <tt>org.geworkbench.engine.config.Skin</tt>]. This implementation supports four layout areas (''Project'', ''Selection'', ''Command'' and ''Visual''). It also supports an annotation system for determining which visual components to display based on the selected data set in the Project Panel.
-Visual plugins may annotate their class definition with <tt>org.geworkbench.engine.management.AcceptTypes</tt>. If the annotation is omitted, then the visual plugin will always be rendered by <tt>Skin</tt>. The annotation takes an array of class objects, each of which must be assignable to <tt>DSDataSet</tt>. For example, here is how the ''Color Mosaic Panel'' is annotated:
+Visual plugins may annotate their class definition with [{{SERVER}}/workbench/api/org/geworkbench/engine/management/AcceptTypes.html <tt>org.geworkbench.engine.management.AcceptTypes</tt>]. If the annotation is omitted, then the visual plugin will always be rendered by <tt>Skin</tt>. The annotation takes an array of class objects, each of which must be assignable to <tt>DSDataSet</tt>. For example, here is how the ''Color Mosaic Panel'' is annotated:
   @AcceptTypes({DSMicroarraySet.class, DSSignificanceResultSet.class}) public class ColorMosaicPanel implements VisualPlugin ...
 When the Project Panel generates a <tt>ProjectEvent</tt> resulting from a data set node being selected, the type of the data set is examined by <tt>Skin</tt>. Each component that has a type in its @AcceptTypes annotation that is assignable from the selected data set type is made visible in the interface. Additionally, all unannotated components are also made visible. Annotated components without a type assignable from the selected d ata set are hidden. This way, the user is only presented with relevant components upon selection of a data set node.

@@ Line 57: / Line 57: @@
 While the Project Panel is itself a geWorkbench plugin, it has some special properties that merit a mention. The Project Panel need not be the only source of project selection events, but this is typically the case. In this way, it becomes the central point of organization for the application.
-All entries in the Project Panel below the level of ''Project'' nodes are data sets that implement the interface <tt>org.geworkbench.bison.datastructure.biocollections.DSDataSet</tt>. These nodes are created in one of two ways. The first is that the Project Panel was used to load a data set from disk or some other network resource. In this case, a non-visual plugin extending <tt>org.geworkbench.engine.parsers.FileFormat</tt> is used to parse the data and construct a data set. The second is that the Project Panel receives a <tt>org.geworkbench.events.ProjectNodeAddedEvent</tt> from another component. This events are usually generated as the result of an analysis by the publishing component.
+All entries in the Project Panel below the level of ''Project'' nodes are data sets that implement the interface [{{SERVER}}/workbench/api/org/geworkbench/bison/datastructure/biocollections/DSDataSet.html <tt>org.geworkbench.bison.datastructure.biocollections.DSDataSet</tt>]. These nodes are created in one of two ways. The first is that the Project Panel was used to load a data set from disk or some other network resource. In this case, a non-visual plugin extending <tt>org.geworkbench.engine.parsers.FileFormat</tt> is used to parse the data and construct a data set. The second is that the Project Panel receives a [{{SERVER}}/workbench/api/org/geworkbench/events/ProjectNodeAddedEvent.html <tt>org.geworkbench.events.ProjectNodeAddedEvent</tt>] from another component. This events are usually generated as the result of an analysis by the publishing component.
 The conceppt of data sets is central to geWorkbench development. Many plugins can be characterized by the types of data sets they process and the types of data sets that they produce.

@@ Line 42: / Line 42: @@
 Normally, the above publish/subscribe sequence is processed serially by the same thread that called the publish method. In many situations, this behavior is acceptable. However, occasionally special handling is required for the subscribe methods. For example, a subscribe method for a visual plugin may need to be run on the Swing event-dispatching thread. Another example would be a subscribe method that results in a fairly long-running  computation. It maybe desirable that this subscribe method is called in the background rather than on the publishing thread.
-The author of the plugin can specify a ''synchronization model'' as a parameter to the subscribe method in this case. A syncrhonization model is any class that implements the [{{SERVER}}/workbench/api/org/geworkbench/engine/management/SynchModel.html <tt>org.geworkbench.engine.management.SynchModel</tt>] interface. Four implementations are provided with geWorkbench (all in the <tt>org.geworkbench.engine.management</tt> package):
+The author of the plugin can specify a ''synchronization model'' as a parameter to the subscribe method in this case. A syncrhonization model is any class that implements the [{{SERVER}}/workbench/api/org/geworkbench/engine/management/SynchModel.html <tt>org.geworkbench.engine.management.SynchModel</tt>] interface. Four implementations are provided with geWorkbench (all in the [{{SERVER}}/workbench/api/org/geworkbench/engine/management/package-summary.html <tt>org.geworkbench.engine.management</tt>] package):
-* <tt>Synchronous</tt> - The default, runs the subscribe method synchronously on the publishing thread.
+* [{{SERVER}}/workbench/api/org/geworkbench/engine/management/Synchronous.html <tt>Synchronous</tt>] - The default, runs the subscribe method synchronously on the publishing thread.
-* <tt>Asynchronous</tt>  - Runs the subscribe method in the background on one thread from a thread pool.
+* [{{SERVER}}/workbench/api/org/geworkbench/engine/management/Asynchronous.html <tt>Asynchronous</tt>]  - Runs the subscribe method in the background on one thread from a thread pool.
-* <tt>Overflow</tt> - Similar to <tt>Asynchronous</tt>, this model runs subscribe methods on a background thread. However, if multiple subscribe events for a given component and method accrue during the processing of a subscribe event for that component and method, then all but the last of these events will be dropped. This is very useful in situations where a component may receive many rapid updates to a state from other components, but each update contains complete information about the state at that time, rendering previous state updates obsolete.
+* [{{SERVER}}/workbench/api/org/geworkbench/engine/management/Overflow.html <tt>Overflow</tt>] - Similar to <tt>Asynchronous</tt>, this model runs subscribe methods on a background thread. However, if multiple subscribe events for a given component and method accrue during the processing of a subscribe event for that component and method, then all but the last of these events will be dropped. This is very useful in situations where a component may receive many rapid updates to a state from other components, but each update contains complete information about the state at that time, rendering previous state updates obsolete.
-* <tt>SwingModel</tt> - This ensures that the subscribe method is run on the Swing event-dispatching thread.
+* [{{SERVER}}/workbench/api/org/geworkbench/engine/management/SwingModel.html <tt>SwingModel</tt>] - This ensures that the subscribe method is run on the Swing event-dispatching thread.
 Here is an example of how to specify a synchronization model for a subscribe method:

@@ Line 22: / Line 22: @@
 # Defers to the main classloader of geWorkbench.
-This resolution scheme is similar to web application containers (such as Tomcat). The <tt>org.geworkbench.engine.management.ComponentResource</tt> class holds the classloader data for each component, and the link between components and <tt>ComponentResource</tt> instances is maintained by the <tt>ComponentRegistry</tt>.
+This resolution scheme is similar to web application containers (such as Tomcat). The [{{SERVER}}/workbench/api/org/geworkbench/engine/management/ComponentResource.html <tt>org.geworkbench.engine.management.ComponentResource</tt>] class holds the classloader data for each component, and the link between components and <tt>ComponentResource</tt> instances is maintained by the <tt>ComponentRegistry</tt>.
 == Publish/Subscribe ==
@@ Line 34: / Line 34: @@
   @Publish public ProjectEvent publishProjectEvent() { ... }
-Upon instantiation of a component, the ComponentRegistry finds all methods that are annotated with <tt>org.geworkbench.engine.management.Subscribe</tt>. It maintains a data structure that maps each subscribe method to the type of its first parameter. For example, the above example would link the <tt>receive</tt> method to the <tt>org.geworkbench.events.ProjectEvent</tt> type. Furthermore, this link is ''polymorphic''; that is, a type that extends <tt>ProjectEvent</tt> will also be linked to this method.
+Upon instantiation of a component, the ComponentRegistry finds all methods that are annotated with <tt>org.geworkbench.engine.management.Subscribe</tt>. It maintains a data structure that maps each subscribe method to the type of its first parameter. For example, the above example would link the <tt>receive</tt> method to the [{{SERVER}}/workbench/api/org/geworkbench/events/ProjectEvent.html <tt>org.geworkbench.events.ProjectEvent</tt>] type. Furthermore, this link is ''polymorphic''; that is, a type that extends <tt>ProjectEvent</tt> will also be linked to this method.
 When a publish method is called in a component, the <tt>ComponentRegistry</tt> will intercept the call (via CGLIB). It will allow the method call to proceed normally. The type of the returned value is then examined. Each component that has a subscribe method that is linked to a type that is assignable from the published type will have that method called, with the publish object as the first parameter, and the component that published the object as the second parameter.
@@ Line 42: / Line 42: @@
 Normally, the above publish/subscribe sequence is processed serially by the same thread that called the publish method. In many situations, this behavior is acceptable. However, occasionally special handling is required for the subscribe methods. For example, a subscribe method for a visual plugin may need to be run on the Swing event-dispatching thread. Another example would be a subscribe method that results in a fairly long-running  computation. It maybe desirable that this subscribe method is called in the background rather than on the publishing thread.
-The author of the plugin can specify a ''synchronization model'' as a parameter to the subscribe method in this case. A syncrhonization model is any class that implements the <tt>org.geworkbench.engine.management.SynchModel</tt> interface. Four implementations are provided with geWorkbench (all in the <tt>org.geworkbench.engine.management</tt> package):
+The author of the plugin can specify a ''synchronization model'' as a parameter to the subscribe method in this case. A syncrhonization model is any class that implements the [{{SERVER}}/workbench/api/org/geworkbench/engine/management/SynchModel.html <tt>org.geworkbench.engine.management.SynchModel</tt>] interface. Four implementations are provided with geWorkbench (all in the <tt>org.geworkbench.engine.management</tt> package):
 * <tt>Synchronous</tt> - The default, runs the subscribe method synchronously on the publishing thread.

@@ Line 12: / Line 12: @@
 == Component Instantiation ==
-An XML configuration file specifies which plugins should be instantiated in to components. This is parsed by a set of Apache Digester directives (http://jakarta.apache.org/commons/digester). Also parsed is a plugin-specific configuration file. This file has the same name and path as the component class file, but it has a <tt>.cwb.xml</tt> extension. This file includes some metadata about the plugin, such as the location of its help files, the area of the visual interface that the component should be installed, and what menu items it responds to. This metadata is stored in a class called <tt>PluginDescriptor</tt>. The configuration engine creates the <tt>org.geworkbench.engine.config.PluginDescriptor</tt> object and passes it on to the <tt>ComponentRegistry</tt>. There, the component is instantiated and a CGLIB wrapper is applied. The <tt>ComponentRegistry</tt> stores the component and its associated descriptor for later use. It passes back the instantiated component to the configuration engine. In the case that the component is an instance of a visual plugin, the configuration engine ensures that the component is added to the appropriate visual area.
+An XML configuration file specifies which plugins should be instantiated in to components. This is parsed by a set of Apache Digester directives (http://jakarta.apache.org/commons/digester). Also parsed is a plugin-specific configuration file. This file has the same name and path as the component class file, but it has a <tt>.cwb.xml</tt> extension. This file includes some metadata about the plugin, such as the location of its help files, the area of the visual interface that the component should be installed, and what menu items it responds to. This metadata is stored in a class called [{{SERVER}}/workbench/api/org/geworkbench/engine/config/PluginDescriptor.html <tt>org.geworkbench.engine.config.PluginDescriptor</tt>]. The configuration engine creates the <tt>PluginDescriptor</tt> object and passes it on to the <tt>ComponentRegistry</tt>. There, the component is instantiated and a CGLIB wrapper is applied. The <tt>ComponentRegistry</tt> stores the component and its associated descriptor for later use. It passes back the instantiated component to the configuration engine. In the case that the component is an instance of a visual plugin, the configuration engine ensures that the component is added to the appropriate visual area.
 === Component Resources ===

@@ Line 3: / Line 3: @@
 == Component Registry ==
-The central class to the geWorkbench framework is <tt>org.geworkbench.engine.management.ComponentRegistry</tt>. This class is responsible for maintaining look-up tables of all active plugins (known herein as ''components''). It also keeps track of the publish/subscribe behavior of the plugins. The <tt>ComponentRegistry</tt> makes use of CGLIB (http://cglib.sourceforge.net) to intercept methods and apply framework functionality. This will be covered in detail in the following sections.
+The central class to the geWorkbench framework is [{{SERVER}}/workbench/api/org/geworkbench/engine/management/ComponentRegistry.html <tt>org.geworkbench.engine.management.ComponentRegistry</tt>]. This class is responsible for maintaining look-up tables of all active plugins (known herein as ''components''). It also keeps track of the publish/subscribe behavior of the plugins. The <tt>ComponentRegistry</tt> makes use of CGLIB (http://cglib.sourceforge.net) to intercept methods and apply framework functionality. This will be covered in detail in the following sections.
 Note the following definitions:

← Older revision		Revision as of 21:02, 14 March 2006
Line 67:		Line 67:
	Those that implement VisualPlugin will have extra directives included in the configuration file to indicate how they should be laid out in the interface. These directives are passed on from the configuration engine to the rendering framework. The rendering framework is itself configurable, and is a class that extends <tt>org.geworkbench.engine.config.GUIFramework</tt>. The default and most full-featured implementation of GUIFramework is <tt>org.geworkbench.engine.config.Skin</tt>. This implementation supports four layout areas (''Project'', ''Selection'', ''Command'' and ''Visual''). It also supports an annotation system for determining which visual components to display based on the selected data set in the Project Panel.		Those that implement VisualPlugin will have extra directives included in the configuration file to indicate how they should be laid out in the interface. These directives are passed on from the configuration engine to the rendering framework. The rendering framework is itself configurable, and is a class that extends <tt>org.geworkbench.engine.config.GUIFramework</tt>. The default and most full-featured implementation of GUIFramework is <tt>org.geworkbench.engine.config.Skin</tt>. This implementation supports four layout areas (''Project'', ''Selection'', ''Command'' and ''Visual''). It also supports an annotation system for determining which visual components to display based on the selected data set in the Project Panel.

−	Visual plugins may annotate their class definition with <tt>org.geworkbench.engine.management.AcceptTypes</tt>. If the annotation is omitted, then the visual plugin will always be rendered by <tt>Skin</tt>. The annotation takes an array of class objects, each of which must be assignable to <tt>DSDataSet</tt>.	+	Visual plugins may annotate their class definition with <tt>org.geworkbench.engine.management.AcceptTypes</tt>. If the annotation is omitted, then the visual plugin will always be rendered by <tt>Skin</tt>. The annotation takes an array of class objects, each of which must be assignable to <tt>DSDataSet</tt>. For example, here is how the ''Color Mosaic Panel'' is annotated:
		+
		+	@AcceptTypes({DSMicroarraySet.class, DSSignificanceResultSet.class}) public class ColorMosaicPanel implements VisualPlugin ...
		+
		+	When the Project Panel generates a <tt>ProjectEvent</tt> resulting from a data set node being selected, the type of the data set is examined by <tt>Skin</tt>. Each component that has a type in its @AcceptTypes annotation that is assignable from the selected data set type is made visible in the interface. Additionally, all unannotated components are also made visible. Annotated components without a type assignable from the selected d ata set are hidden. This way, the user is only presented with relevant components upon selection of a data set node.

← Older revision		Revision as of 20:58, 14 March 2006
Line 65:		Line 65:
	Many plugins have a visual representation. This visual intention is advertised to the framework by the plugin implementing <tt>org.geworkbench.engine.config.VisualPlugin</tt>. Some plugins, such as file parsers and analyses, do not require a visual representation, and so do not implement this interface.		Many plugins have a visual representation. This visual intention is advertised to the framework by the plugin implementing <tt>org.geworkbench.engine.config.VisualPlugin</tt>. Some plugins, such as file parsers and analyses, do not require a visual representation, and so do not implement this interface.

−	Those that implement VisualPlugin will have extra directives included in the configuration file to indicate how they should be laid out in the interface. These directives are passed on from the configuration engine to the rendering framework. The rendering framework is itself configurable, and is a class that extends <tt>org.geworkbench.engine.config.GUIFramework</tt>.	+	Those that implement VisualPlugin will have extra directives included in the configuration file to indicate how they should be laid out in the interface. These directives are passed on from the configuration engine to the rendering framework. The rendering framework is itself configurable, and is a class that extends <tt>org.geworkbench.engine.config.GUIFramework</tt>. The default and most full-featured implementation of GUIFramework is <tt>org.geworkbench.engine.config.Skin</tt>. This implementation supports four layout areas (''Project'', ''Selection'', ''Command'' and ''Visual''). It also supports an annotation system for determining which visual components to display based on the selected data set in the Project Panel.
		+
		+	Visual plugins may annotate their class definition with <tt>org.geworkbench.engine.management.AcceptTypes</tt>. If the annotation is omitted, then the visual plugin will always be rendered by <tt>Skin</tt>. The annotation takes an array of class objects, each of which must be assignable to <tt>DSDataSet</tt>.