Workspace Plugin

This document describes the workspace plugin architecture and how to create and add a new workspace plugin to the MBAT framework.

Architecture

The MBAT framework consists of core libraries and workspace plugins. These workspace plugins are dynamically loaded at runtime. The MBAT framework simply displays the canvas and menubar for the workspace in the main window. A workspace plugin communicates with the MBAT framework using the following input/output model:

• Plugin Input:
  1. None
• Plugin Output:
  1. main canvas (JPanel) of the workspace GUI
  2. menu bar of the workspace

All the workspaces share a single global menu bar. As described below, the workspace can customize this menu bar but is responsible for adding and removing its workspace specific components to and from this shared menu bar. All workspaces can also access any of the MBAT core library functionality.

Events

The MBAT framework handles instantiating and switching of the workspaces. The following table describes the plugin methods that are called on these events (more details about the specific methods are given below):

SVN repository

For SVN setup, see the Eclipse SVN Configuration. The key projects for the workspace plugins are:

• svn+ssh://svn.loni.ucla.edu/cvs/MouseBIRN/mbWorkspace (plugin API)
• svn+ssh://svn.loni.ucla.edu/cvs/MouseBIRN/mbWorkspacePlugins (default workspaces)

Adding a new plugin

For detailed instructions on how to create and add a plugin to the MBAT source code tree using Eclipse, see CreatingPlugins.

Once you have created and compiled your plugin, you must archive it and place it in the plugins folder. If you follow the above instructions for Eclipse, the build.xml will automatically archive and zip the plugin to the correct folder:

1. Create a zip file of the plugin.xml and classes/ folder. The zip file should have the following structure:

      {root}
          classes/
          plugin.xml

2. Add the .zip file to the plugins folder (mbat/dist/plugins/workspaces)

Creating a new plugin

Creating a workspace plugin involves the following steps:

1. Create a java class that implements the mbWorkspaceBase interface. The mbWorkspaceBase interface defines the common interface for all workspace plugins. We describe here the major methods of the interface (see mbWorkspaceBase.java for more detailed inline documentation).

         public class MyWorkspace implements mbWorkspaceBase {   
             private JMenu m_menuMyWorkspace;
             ...
         }

2. Implement any initialization that requires an input parameter by defining init(...). When the plugin is instantiated by the mbPluginManager, it can only call the default constructor of the workspace. After the workspace is instantiated by the default constructor, the init(...) method is called by the MBAT framework. In mbat3.0, by default, the "PluginDirectory" parameter in the plugin manifest (plugin.xml) is passed as the argument to init(...).

         public void init ( Object arg0 )
         {       
             String sPluginDirectory = (String)arg0;
             ...
         }

3. Implement any initialization of workspace specific menu bar items by defining initMenuBar(). This method will be called by the MBAT framework after init(...) is called. [might deprecate this method and subsume into default constructor]

         public void initMenuBar ()
         {
             // create search menu
             m_menuMyWorkspace = new JMenu( "MyWorkspace" );
             ...
         }
         

4. Implement retrieving of the workspace GUI by defining getMainPanel(). For performance reasons, it is recommended that you avoid instantiating JComponents inside this function; only layout of the JComponents should be done here since getMainPanel() is called everytime the workspace plugin is activated:

         public JPanel getMainPanel ( JPanel panel ) {
             // get main panel
             return m_mainPanel;
         }

5. Implement hiding of the workspace by defining hide(). This method is called before the new workspace is shown. This method is responsible for performing any cleanup associated with any global items, such as removing workspace specific components from the menu bar, hiding any dockable frames, and removing any listeners from mbManagerCart.

         public void hide () {
             // remove workspace menu from global menubar
             mbWorkspaceBase.getMenuBar().remove( m_menuMyWorkspace );
             mbWorkspaceBase.getMenuBar().revalidate();
         }

6. Implement displaying of the workspace by defining show(). This method is called after the old workspace is hidden. This method is responsible for performing any initialization associated with any global items, such as adding workspace specific components to the menu bar, showing any dockable frames, and adding any listeners to mbManagerCart.

         public void show () {
             // add workspace menu from global menubar
             mbWorkspaceBase.getMenuBar().add( m_menuMyWorkspace );
             mbWorkspaceBase.getMenuBar().revalidate();
         }

7. Create plugin.xml. This file is required by the Java Plugin Framework (JPF) and defines the extension point of the plugin. The extension point-id must be specified as point-id="Workspace" to load correctly. For most purposes, you can copy the plugin.xml from the mbWorkspacePlugins project and edit the extension section. The "PluginDirectory" parameter is an optional parameter to specify the directory for the tool plugins of the workspace that is passed to init( Object arg0 ):

   <extension plugin-id="net.nbirn.mbat.plugins.workspace.core" point-id="Workspace" id="MyWorkspace"> <parameter id="class" value="net.nbirn.mbat.plugins.workspace.MyWorkspace"/> <parameter id="DisplayName" value="My Workspace"/> <parameter id="PluginDirectory" value="../myWorkspace/plugins"/> </extension>

   For more detailed information, consult the JPF Tutorial.

Running mbat3.0

To run mbat3.0 with the workspace plugins, follow the instructions in Build Instructions.