Return information about the main type of plug-in. The Plugin.MainType is an enumeration with five possible values:

The returned value is stored in the database but is otherwise not used by the core. Client applications (such as the web client) will probably use this information to group the plug-ins, i.e., a button labeled Export will let you select among the export plug-ins.

public Plugin.MainType getMainType()
{
   return Plugin.MainType.OTHER;
}

If this method returns true, the plug-in can have different configurations, (i.e. PluginConfiguration). Note that this method may return true even if the InteractivePlugin interface is not implemented. The AbstractPlugin returns true for this method, which is the old way before the introduction of this method.

If this method returns true, the plug-in must have a configuration to be able to run. For example, some of the core import plug-ins must have information about the file format, to be able to import any data. The AbstractPlugin returns false for this method, which is the old way before the introduction of this method.

Return a collection of permissions that the plug-in needs to be able to function as expected. This method may return null or an empty collection. In this case the plug-in permission system is not used and the plug-in always gets the same permissions as the logged in user. If permissions are specified the plug-in should list all permissions it requires. Permissions that are not listed are denied.

Note

The final assignment of permissions to a plug-in is always at the hands of a server administrator. He/she may decide to disable the plug-in permission system or revoke some of the requested permissions. The permissions returned by this method is only a recommendation that the server administrator may or may not accept. See Section 22.1.6, “Plug-in permissions” for more information about plug-in permissions.

Prepare the plug-in for execution or configuration. If the plug-in needs to do some initialization this is the place to do it. A typical implementation however only stores the passed parameters in instance variables for later use. Since it is not possible to know what the user is going to do at this stage, we recommend lazy initialisation of all other resources.

The parameters passed to this method has vital information that is needed to execute the plug-in. The SessionControl is a central core object holding information about the logged in user and is used to create DbControl objects which allows a plug-in to connect to the database to read, add or update information. The two ParameterValues objects contain information about the configuration and job parameters to the plug-in. The configuration object holds all parameters stored together with a PluginConfiguration object in the database. If the plug-in is started without a configuration this object is null. The job object holds all parameters that are stored together with a Job object in the database. This object is null if the plug-in is started without a job.

The difference between a configuration parameter and a job parameter is that a configuration is usually something an administrator sets up, while a job is an actual execution of a plug-in. For example, a configuration for an import plug-in holds the regular expressions needed to parse a text file and find the headers, sections and data lines, while the job holds the file to parse.

The AbstractPlugin contains an implementation of this method that saves the passed objects in protected instance variables. If you override this method we recommend that you also call super.init().

protected SessionControl sc = null;
protected ParameterValues configuration = null;
protected ParameterValues job = null;
/**
   Store copies of the session control, plug-in and job configuration. These
   are available to subclasses in the {@link #sc}, {@link #configuration}
   and {@link #job} variables. If a subclass overrides this method it is 
   recommended that it also calls super.init(sc, configuration, job).
*/
public void init(SessionControl sc, 
   ParameterValues configuration, ParameterValues job)
   throws BaseException
{
   this.sc = sc;
   this.configuration = configuration;
   this.job = job;
}

Run the plug-in.

The request parameter is of historical interest only. It has no useful information and can be ignored.

The progress parameter should be used by a plug-in to report its progress back to the core. The core will usually send the progress information to the database, which allows users to see exactly how the plug-in is progressing from the web interface. This parameter is allowed to be null, but BASE will always use a progress reporter. The plug-in should try to not over-use the progress reporter. The default implementation used by BASE has a time threshold so that calls that occur too often with too little change in the progress are ignored. A good starting point is to divide the work into 100 pieces each representing 1% of the work, i.e., if the plug-in should export 100 000 items it should report progress after every 1000 items.

The response parameter is used to tell the core if the plug-in was successful or failed. Not setting a response is considered a failure by the core. From the run method it is only allowed to use on of the Response.setDone(), Response.setError() or Response.setContinue() methods.

	Important
	It is also considered bad practice to let exceptions escape out from this method. Always use try...catch to catch exceptions and use Response.setError() to report the error back to the core.

public void run(Request request, Response response, ProgressReporter progress)
{
   // Open a connection to the database
   // sc is set by init() method
   DbControl dc = sc.newDbControl();
   try
   {
      // Insert code for plug-in here

      // Commit the work
      dc.commit();
      response.setDone("Plug-in ended successfully");
   }
   catch (Throwable t)
   {
      // All exceptions must be catched and sent back 
      // using the response object
      response.setError(t.getMessage(), Arrays.asList(t));
   }
   finally
   {
      // IMPORTANT!!! Make sure opened connections are closed
      if (dc != null) dc.close();
   }
}

Clean up all resources after executing the plug-in. This method must not throw any exceptions.

/**
   Clears the variables set by the init method. If a subclass 
   overrides this method it is recommended that it also calls super.done().
*/
public void done()
{
   configuration = null;
   job = null;
   sc = null;
}

Return information about where the plug-in should be plugged in. Each place is identified by a GuiContext object, which is an Item and a Type. The item is one of the objects defined by the Item enumeration and the type is either Type.LIST or Type.ITEM, which corresponde to the list view and the single-item view in the web client.

For example, the GuiContext = (Item.REPORTER, Type.LIST) tells a client application that this plug-in can be plugged in whenever a list of reporters is displayed. The GuiContext = (Item.REPORTER, Type.ITEM) tells a client application that this plug-in can be plugged in whenever a single reporter is displayed. The first case may be appropriate for a plug-in that imports or exports reporters. The second case may be used by a plug-in that updates the reporter information from an external source (well, it may make sense to use this in the list case as well).

The returned information is copied by the core at installation time to make it easy to ask for all plug-ins for a certain GuiContext.

A typical implementation creates a static unmodifiable Set which is returned by this method. It is important that the returned set cannot be modified. It may be a security issue if a misbehaving client application does that.

// From the net.sf.basedb.plugins.RawDataFlatFileImporter plug-in
private static final Set<GuiContext> guiContexts = 
   Collections.singleton(new GuiContext(Item.RAWBIOASSAY, GuiContext.Type.ITEM));

public Set<GuiContext> getGuiContexts()
{
   return guiContexts;
}

This method is called to check if a particular item is usable for the plug-in. This method is invoked to check if a plug-in can be used in a given context. If invoked from a list context the item parameter is null. The plug-in should return null if it finds that it can be used. If the plug-in can't be used it must decide if the reason should be a warning or an error condition.

A warning is issued by returning a string with the warning message. It should be used when the plug-in can't be used because it is unrelated to the current task. For example, a plug-in for importing Genepix data should return a warning when somebody wants to import data to an Agilent raw bioassay.

An error message is issued by throwing an exception. This should be used when the plug-in is related to the current task but still can't do what it is supposed to do. For example, trying to import raw data if the logged in user doesn't have write permission to the raw bioassay.

As a rule of thumb, if there is a chance that another plug-in might be able to perform the same task a warning should be used. If it is guaranteed that no other plug-in can do it an error message should be used.

Here is a real example from the RawDataFlatFileImporter plug-in which imports raw data to a RawBioAssay. Thus, GuiContext = (Item.RAWBIOASSAY, Type.ITEM), but the plug-in can only import data if the logged in user has write permission, there is no data already, and if the raw bioassay has the same raw data type as the plug-in has been configured for.

/**
   Returns null if the item is a {@link RawBioAssay} of the correct
   {@link RawDataType} and doesn't already have spots.
   @throws PermissionDeniedException If the raw bioasssay already has raw data
   or if the logged in user doesn't have write permission
*/
public String isInContext(GuiContext context, Object item)
{
   String message = null;
   if (item == null)
   {
      message = "The object is null";
   }
   else if (!(item instanceof RawBioAssay))
   {
      message = "The object is not a RawBioAssay: " + item;
   }
   else
   {
      RawBioAssay rba = (RawBioAssay)item;
      String rawDataType = (String)configuration.getValue("rawDataType");
      RawDataType rdt = rba.getRawDataType();
      if (!rdt.getId().equals(rawDataType))
      {
         // Warning
         message = "Unsupported raw data type: " + rba.getRawDataType().getName();
      }
      else if (!rdt.isStoredInDb())
      {
         // Warning
         message = "Raw data for raw data type '" + rdt + "' is not stored in the database";
      }
      else if (rba.hasData())
      {
         // Error
         throw new PermissionDeniedException("The raw bioassay already has data.");
      }
      else
      {
         // Error
         rba.checkPermission(Permission.WRITE);
      }
   }
   return message;		
}

Ask the plug-in for parameters that need to be entered by the user. The GuiContext parameter is one of the contexts returned by the getGuiContexts method. The command is a string telling the plug-in what command was executed. There are two predefined commands but as you will see the plug-in may define its own commands. The two predefined commands are defined in the net.sf.basedb.core.plugin.Request class.

Given this information the plug-in must return a RequestInformation object. This is simply a title, a description, and a list of parameters. Usually the title will end up as the input form title and the description as a help text for the entire form. Do not put information about the individual parameters in this description, since each parameter has a description of its own.

// The complete request information
private RequestInformation configure Job;

// The parameter that asks for a file to import from
private PluginParameter<File> file Parameter;

// The parameter that asks if existing items should be updated or not
private PluginParameter<Boolean> updateExistingParameter;

public RequestInformation getRequestInformation(GuiContext context, String command)
   throws BaseException
{
   RequestInformation requestInformation = null;
   if (command.equals(Request.COMMAND_CONFIGURE_PLUGIN))
   {
      requestInformation = getConfigurePlugin();
   }
   else if (command.equals(Request.COMMAND_CONFIGURE_JOB))
   {
      requestInformation = getConfigureJob();
   }
   return requestInformation;
}

/**
   Get (and build) the request information for starting a job.
*/
private RequestInformation getConfigureJob()
{
   if (configureJob == null)
   {
      // A file is required
      fileParameter = new PluginParameter<File>(
         "file",
         "File",
         "The file to import the data from",
         new FileParameterType(null, true, 1)
      ); 
		  
      // The default value is 'false'
      updateExistingParameter = new PluginParameter<Boolean>(
         "updateExisting",
         "Update existing items",
         "If this option is selected, already existing items will be updated " +
         " with the information in the file. If this option is not selected " +
         " existing items are left untouched.",
         new BooleanParameterType(false, true)
      );

      List<PluginParameter<?>> parameters = 
         new ArrayList<PluginParameter<?>>(2);
      parameters.add(fileParameter);
      parameters.add(updateExistingParameter);
			
      configureJob = new RequestInformation
      (
         Request.COMMAND_CONFIGURE_JOB,
         "Select a file to import items from",
         "Description",
         parameters
      );
   }
   return configureJob;
}

As you can see it takes a lot of code to put together a RequestInformation object. For each parameter you need one PluginParameter object and one ParameterType object. To make life a little easier, a ParameterType can be reused for more than one PluginParameter.

StringParameterType stringPT = new StringParameterType(255, null, true);
PluginParameter one = new PluginParameter("one", "One", "First string", stringPT);
PluginParameter two = new PluginParameter("two", "Two", "Second string", stringPT);
// ... and so on

The ParameterType is an abstract base class for several subclasses each implementing a specific type of parameter. The list of subclasses may grow in the future, but here are the most important ones currently implemented.

	Note
	Most parameter types include support for supplying a predefined list of options to select from. In that case the list will be displayed as a drop-down list for the user, otherwise a free input field is used.

You can also create a PluginParameter with a null name and ParameterType. In this case, the web client will not ask for input from the user, instead it is used as a section header, allowing you to group parameters into different sections which increase the readability of the input parameters page.

PluginParameter firstSection = new PluginParameter(null, "First section", null, null);
PluginParameter secondSection = new PluginParameter(null, "Second section", null, null);
// ...

parameters.add(firstSection);
parameters.add(firstParameterInFirstSection);
parameters.add(secondParameteInFirstSection);

parameters.add(secondSection);
parameters.add(firstParameterInSecondSection);
parameters.add(secondParameteInSecondSection);

Sends parameter values entered by the user for processing by the plug-in. The plug-in must validate that the parameter values are correct and then store them in database.

Important

No validation is done by the core, except converting the input to the correct object type, i.e. if the plug-in asked for a Float the input string is parsed and converted to a Float. If you have extended the AbstractPlugin class it is very easy to validate the parameters with the AbstractPlugin.validateRequestParameters() method. This method takes the same list of PluginParameter:s as used in the RequestInformation object and uses that information for validation. It returns null or a list of Throwable:s that can be given directly to the response.setError() methods.

When the parameters have been validated, they need to be stored in the database. Once again, it is very easy, if you use one of the AbstractPlugin.storeValue() or AbstractPlugin.storeValues() methods.

The configure method works much like the Plugin.run() method. It must return the result in the Response object, and should not throw any exceptions.

public void configure(GuiContext context, Request request, Response response)
{
   String command = request.getCommand();
   try
   {
      if (command.equals(Request.COMMAND_CONFIGURE_PLUGIN))
      {
         // TODO
      }
      else if (command.equals(Request.COMMAND_CONFIGURE_JOB))
      {
         // Validate user input
         List<Throwable> errors = 
            validateRequestParameters(getConfigureJob().getParameters(), request);
         if (errors != null)
         {
            response.setError(errors.size() +
               " invalid parameter(s) were found in the request", errors);
            return;
         }
         
         // Store user input
         storeValue(job, request, fileParameter);
         storeValue(job, request, updateExistingParameter);
         
         // We are happy and done
         File file = (File)job.getValue("file");
         response.setSuggestedJobName("Import data from file " + file.getName());
         response.setDone("Job configuration complete", Job.ExecutionTime.SHORT);
      }
   }
   catch (Throwable ex)
   {
      response.setError(ex.getMessage(), Arrays.asList(ex));
   }
}

Note that the call to response.setDone() has a second parameter Job.ExecutionTime.SHORT. It is an indication about how long time it will take to execute the plug-in. This is of interest for job queue managers which probably does not want to start too many long-running jobs at the same time blocking the entire system. Please try to use this parameter wisely and not use Job.ExecutionTime.SHORT out of old habit all the time.

The Response class also has a setContinue() method which tells the core that the plug-in needs more parameters, i.e. the core will then call getRequestInformation() again with the new command, let the user enter values, and then call configure() with the new values. This process is repeated until the plug-in reports that it is done or an error occurs.

	Tip
	You do not have to store all values the plug-in asked for in the first place. You may even choose to store different values than those that were entered. For example, you might ask for the mass and height of a person and then only store the body mass index, which is calculated from those values.

An important note is that during this iteration it is the same instance of the plug-in that is used. However, no parameter values are stored in the database until the plugin sends a response.setDone(). After that, the plug-in instance is usually discarded, and a job is placed in the job queue. The execution of the plug-in happens in a new instance and maybe on a different server. This means that a plug-in can't store state from the configuration phase internally and expect it to be there in the execution phase. Everything the plug-in needs to do it's job must be stored as parameters in the database.

The only exception to the above rule is if the plug-in answers with Response.setExecuteImmediately() or Response.setDownloadImmediately(). Doing so bypasses the entire job queue system and requests that the job is started immediately. This is a permission that has to be granted to each plug-in by the server administrator. If the plug-in has this permission, the same object instance that was used in the configuration phase is also used in the execution phase. This is the only case where a plug-in can retain internal state between the two phases.