26.8. Extension points defined by BASE

26.8.1. Menu: extensions
26.8.2. Toolbars
26.8.3. Edit dialogs
26.8.4. Bioassay set: Tools
26.8.5. Bioassay set: Overview plots
26.8.6. Services
26.8.7. Connection managers
26.8.8. Fileset validators

In this section, we will give an overview of the extension points defined by BASE. Most extension points are used in the web client to add buttons and menu items, but there are a few for the core API as well.

26.8.1. Menu: extensions

Menu items can be added to the top-level Extensions menu. Actions should implement the interface: MenuItemAction

The MenuItemAction.getMenuType() provides support for MENUITEM, SUBMENU and SEPARATOR menus. Which of the other properties that are needed depend on the menu type. Read the javadoc for more information. This extension point doesn't support custom javascripts or stylesheets and the rendering is internal (eg. extensions can't provide their own renderers).

BASE ships with two action factories: FixedMenuItemFactory and PermissionMenuItemFactory. The fixed factory provides a menu that is the same for all users. The permission factory can disable or hide a menu depending on the logged in user's role-based permissions. The title, icon, etc. can have different values depending on if the menu item is disabled or enabled.

26.8.2. Toolbars

Most toolbars on all list and single-item view pages can be extended with extra buttons. Actions should implement the interface: ButtonAction. Button actions are very simple and only need to provide things like a title, tooltip, on-click script, etc. This extension point has support for custom javascript, stylesheets and renderers. The default renderer is ToolbarButtonRendererFactory.

BASE ships with two action factories: FixedButtonFactory and PermissionButtonFactory. The fixed factory provides a toolbar button that is the same for all users. The permission factory can disable or hide a buton depending on the logged in user's role-based permissions. The title, icon, etc. can have different values depending on if the menu item is disabled or enabled.

26.8.3. Edit dialogs

Most item edit dialogs can be extended with additional tabs. Actions should implement the interface: TabAction. The actions are, in principle, simple and only need to provide a title and content (HTML). The action may also provide javascripts for validation, etc. This extension point has support for custom stylesheets and javascript. Rendering is fixed and can't be overridden.

BASE ships with two action factories: FixedTabFactory and IncludeContentTabFactory. The fixed factory provides a tab with fixed content that is the same for all users and all items. This factory is not very useful in a real scenario. The other factory provides content by including the output from another resource, eg. a JSP page, a servlet, etc. The current context is stored in a request-scoped attribute under the key given by JspContext.ATTRIBUTE_KEY. A JSP or servlet should use this to hook into the current flow. Here is a code example:


// Get the JspContext that was created on the main edit page
final JspContext jspContext = (JspContext)request.getAttribute(JspContext.ATTRIBUTE_KEY);

// The current item is found in the context. NOTE! Can be null if a new item
final BasicItem item = (BasicItem)jspContext.getCurrentItem();

// Get the DbControl and SessionControl used to handle the request (do not close!)
final DbControl dc = jspContext.getDbControl();
final SessionControl sc = dc.getSessionControl();

The extra tab need to be paired with an extension that is invoked when the edit form is saved. Each edit-dialog extension point has a corresponding on-save extension point. Actions should implement the interface: OnSaveAction. This interface define three callback methods that BASE will call when saving an item. The OnSaveAction.onSave() method is called first, but not until all regular properties have been updated. If the transaction is committed the OnSaveAction.onCommit() method is also called, otherwise the OnSaveAction.onRollback() is called. The onSave() method can throw an exception that will be displayed to the user. The other callback method should not throw exceptions at all, since that may result in undefined behaviour and can be confusing for the user.

26.8.4. Bioassay set: Tools

The bioassay set listing for an experiment has a Tools column which can be extended by extensions. This extension point is similar to the toolbar extension points and actions should implement the interface: ButtonAction.

Note that the list can contain BioAssaySet, Transformation and ExtraValue items. The factory implementation need to be aware of this if it uses the JspContext.getItem() method to examine the current item.

26.8.5. Bioassay set: Overview plots

The bioassay set page has a tab Overview plots. The contents of this tab is supposed to be some kind of images that have been generated from the data in the current bioassay set. What kind of plots that can be generated typically depends on the kind of data you have. BASE ships with an extension (MAPlotFactory) that creates MA plots and Correction factor plots for 2-channel bioassays. Actions should implement the interface: OverviewPlotAction. A single action generates a sub-tab in the Overview plots tab. The sub-tab may contain one or more images. Each image is defined by a PlotGenerator which sets the size of the image and provides an URL to a servlet that generates the actual image. It is recommended that the servlet cache images since the data in a bioassay set never changes. The BASE core API provides a system-managed file cache that is suitable for this. Call Application.getStaticCache() to get a StaticCache instance. See the source code for the core PlotServlet for details of how to use the cache.

26.8.6. Services

A service is a piece of code that is loaded when the BASE web server starts up. The service is then running as long as the BASE web server is running. It is possible to manually stop and start services. This extension point is different from most others in that it doesn't affects the visible interface. Since services are loaded at startup time, this also means that the context passed to ActionFactory methods will not have any ClientContext associated with it (eg. the InvokationContext.getClientContext() always return null). There is also no meaning for extensions to specify a RendererFactory. Service actions should implement the interface: ServiceControllerAction. The interface provides start() and stop() methods for controlling the service. BASE doesn't ship with any service, but there is an FTP service available at the BASE plug-ins site: http://baseplugins.thep.lu.se/wiki/net.sf.basedb.ftp

26.8.7. Connection managers

This extension point adds support for using external files in BASE. This is a core extension point and is available independently of the web client. Actions should implement the interface: ConnectionManagerFactory.

The getDisplayName() and getDescription() methods are used in the gui when a user manually selects which connection manager to use. The supports(URI) is used when auto-selecting a connection manager based on the URI of the resource.

BASE ships with factory that supports HTTP and HTTPS file references: HttpConnectionManagerFactory. The BASE plug-ins site has an connection manager that support the Hadoop distributed file system (HDFS): http://baseplugins.thep.lu.se/wiki/net.sf.basedb.hdfs

26.8.8. Fileset validators

In those cases where files are used to store data instead of importing it to the database, BASE can use extensions to check that the supplied files are valid and also to extract metadata from the files. For example, the CelValidationAction is used to check if a file is a valid Affymetrix CEL file and to extract data headers and the number of spots from it.

Validation and metadata extraction actions should implement the ValidationAction interface. This is a core extension point and is available independently of the web client.

This extension point is a bit more complex than most other extension points. To begin with, the factory class will be called with the owner of the file set as the current item. Eg. the ClientContext.getCurrentItem() should return a FileStoreEnabled item. It is recommended that the factory performs a pre-filtering of the items to avoid calling the actual validation code on unsupported files. For example, the CelValidationFactory will check that the item is a RawBioAssay item using the Affymetrix platform.

Each file in the file set is then passed to the ValidationAction.acceptFile(FileSetMember) which may accept or reject the file. If the file is accepted it may be accepted for immediate validation or later validation. The latter option is useful in more complex scenarios were files need to be validated as a group. If the file is accepted the ValidationAction.validateAndExtractMetadata() is called, which is were the real work should happen.

The extensions for this extension point is also called when a file is replaced or removed from the file set. The calling sequence to set up the validation is more or less the same as described above, but the last step is to call ValidationAction.resetMetadata() instead of ValidationAction.validateAndExtractMetadata().

[Tip] Use the SingleFileValidationAction class.

Most validators that work on a single file at a time may find the SingleFileValidationAction class useful. Is should simplify the task of making sure that only the desired file type is validated. See the source code of the CelValidationAction class for an example.