Search Datasource Plugin

This document describes the search datasource plugin architecture and how to create and add a datasource plugin to the MBAT Search Workspace.

Architecture

The MBAT Search Workspace allows the user to query across multiple datasources. Each datasource is a plugin and communicates with the MBAT Search Workspace using the following input/output model:

• Plugin Input:
  1. list of search parameters (SearchParam)
• Plugin Output:
  1. list of query results (mbQueryResult)

Events

To better understand the interaction between the MBAT Search Workspace and its plugin, the events that cause certain plugin methods to be invoked are summarized below:

Requirements Specification

This section describes the expected behavior for the datasource plugins.

• Returned results
  • To ensure interoperability with the built-in workspaces (Search, Registration, Comparison Viewer), the results returned by searchByKeyword() and searchByQueryTerms() will be subclasses of the mbAnnotatedObject classes found in net.nbirn.mbat.core.datatypes.
• Error Handling
  • In the datasource plugin constructor, searchBKeyword(), and searchByQuertyTerms() methods, a mbDataSourceException will be thrown for the following connection errors:
    1. error establishing connection to datasource
    2. connection to datasource dropped after initial connection
    3. internal error on datasource server side

For testing purposes, please document the following on the MouseBIRN Partner Plugins wiki page:

1. User Manual
   1. brief description of intent and use of plugin
   2. describe how to start and use your plugin
2. Functional Specification
   1. Search and Data Types (describe what types of searches your support and what type of data will be returned)
   2. Supported Query Terms (describe which ones you support and any assumptions/default values for unsupported query terms)
   3. Annotations (for each data type returned, list the annotations expected)
   4. Credentials (describe security issues, if any)
   5. Database Connection Type (ie: HTTP/JDBC/etc)
   6. Workspace Interoperability (describe how you expect the returned data to used in other workspaces)
   7. Error Handling (describe how you handle the error cases above)

SVN repository

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

• svn+ssh://svn.loni.ucla.edu/cvs/MouseBIRN/mbSearch (plugin API and search GUI)
• svn+ssh://svn.loni.ucla.edu/cvs/MouseBIRN/mbSearchPlugins (sample plugins)
• svn+ssh://svn.loni.ucla.edu/cvs/MouseBIRN/common (mbAnnotatedObject derived classes)

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/mbSearch)

Creating a new plugin

Creating a datasouce plugin involves the following steps:

1. Create a java class that implements one of the derived mbDataSourceBase interface. The mbDataSourceBase interface defines the common interface for all datasource plugins. The derived classes of mbDataSourceBase are helper classes to simplify the connections to the underlying databases:

   Class	Description
   mbDataSourceHTTP	Data sources access through http port like Web Services
   mbDataSourceJDBC	Data Sources using JDBC connection
   mbDataSourceMySQL	Local MySQL databases
   mbDataSourceOracle	Local Oracle databases
   mbDataSourcePostgresql	Postgresql 8.1 databases or Postgresql 8.2 databases through JDBC3
   mbDataSourceSerializedDB	Any serializable database objects.

   We describe here the major methods of the mbDataSourceBase interface (see mbDataSourceBase.java for more detailed inline documentation).

         public class DataSource extends implements mbDataSourceHTTP {   
           ...
         }

2. Implement what types of searches are supported by this plugin. For example, if the plugin only supports query term searches, then we would define:

          public boolean hasQueryTermSearch () { return true; }
          public boolean hasKeywordSearch () { return false; }
          public boolean hasSemanticSearch () { return false; }
      

3. Implement handling of the supported search methods by defining the appropriate searchByXXX(). The plugin is responsible for retrieving the search results and converting the results into the mbQueryResult object.

         public Vector< mbQueryResult > searchByQueryTerms ( Vector<SearchParam> vSearchParams ) {
            // parse search parameters and form query statement
            // do search
            // parse search results and create mbQueryResult
         }

   A mbQueryResult contains a list of mbAnnotatedObjects, sorted by their datatype (ie: 2D image, 2D image series, probe, gene, etc). The plugin is required to convert and group the search results into one of the derived classes of mbAnnotatedObjects (see mbObject Class Hierarchy). For example, returning a list of 2D image series might look this:

       // main vector of results
       Vector<mbQueryResult> vResults = new Vector<mbQueryResult>();
   
       Vector<mbAnnotatedObject> vImgSeriesList = new Vector<mbAnnotatedObject>();
       // ...populate vImgSeriesList with Image2DSeries objects...
       mbQueryResult queryResult = new mbQueryResult();
       queryResult.addAnnotatedObjects( mbQueryResult.DATATYPE.IMAGE2D_SERIES, vImgSeriesList );
       vResults.add( queryResult );
   

4. 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="Search" to load correctly. The parameters "class" and "DisplayName" are requried fields for each data source. "DisplayName" is the text string shown in the Search Workspace-->Data Sources options. The optional field, "baseURL", is the connection string for mbDataSourceHTTP sources. For most purposes, you can copy the plugin.xml from the mbSearchPlugins project and edit the extension section:

   <extension plugin-id="net.nbirn.mbat.plugins.search.core" point-id="Search" id="datasourceABA"> <parameter id="class" value="net.nbirn.mbat.plugins.search.aba.DataSourceABA"/> <parameter id="DisplayName" value="Allen Brain Atlas"/> <parameter id="baseURL" value="http://www.brain-map.org" /> </extension>

   The full parameter list for the extension section can be found in in net.nbirn.mbat.plugins.search.Core/src/plugin.xml. For more detailed information, consult the JPF Tutorial.

Running standalone client

For testing and prototyping purposes, there is a standalone client included in the mbSearch project that loads and runs the MBAT Search Workspace:

• net.nbirn.mbat.search.client.Main

NOTE: When developing and testing your plugin, make sure you update your .zip archive and place it in the plugins folder before running the standalone client!