source: trunk/doc/src/docbook/developerdoc/plugin_developer.xml @ 3495

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC 
    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" 
    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
<!--
  $Id: plugin_developer.xml 3495 2007-06-14 12:36:26Z nicklas $:
  
  Copyright (C) Authors contributing to this file.
  
  This file is part of BASE - BioArray Software Environment.
  Available at http://base.thep.lu.se/
  
  BASE is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License
  as published by the Free Software Foundation; either version 2
  of the License, or (at your option) any later version.
  
  BASE is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.
  
  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place - Suite 330,
  Boston, MA  02111-1307, USA.
-->

<chapter id="plugin_developer">
  <?dbhtml dir="plugin_developer"?>
  <title>Plug-in developer</title>
  <sect1 id="plugin_developer.organize">
    <title>How to organize your plug-in project</title>
    
    <sect2 id="plugin_developer.organize.ant">
      <title>Using Ant</title>
      <para>
        Here is a simple example of how you might organize your project using ant 
        (<ulink url="http://ant.apache.org">http://ant.apache.org</ulink>) as the build 
        tool. This is just a recommendation that we have found to be working
        well. You may choose to do it another way.
      </para>

      <sect3 id="plugin_developer.organize.ant.directories">
        <title>Directory layout</title>
        <para>
        
          Create a directory on your computer where you want
          to store your plug-in project. This directory is the 
          <filename class="directory"><replaceable>pluginname</replaceable>/</filename>
          directory in the listing below. You should also create some subdirectories:
          
          <literallayout>
<filename class="directory"><replaceable>pluginname</replaceable>/</filename>
<filename class="directory"><replaceable>pluginname</replaceable>/bin/</filename>
<filename class="directory"><replaceable>pluginname</replaceable>/lib/</filename>
<filename class="directory"><replaceable>pluginname</replaceable>/src/<replaceable>org/company</replaceable>/</filename>
          </literallayout>
          The
          <filename class="directory">bin/</filename>
          directory is empty to start with. It will contain the compiled code. 
          In the <filename class="directory">lib/</filename>
          directory you should put <filename>BASE2Core.jar</filename>
          and other library files your plug-in depends on. The
          <filename class="directory">src/</filename>
          directory contains your source code. In this directory you should create
          subdirectories corresponding to the package name of your plug-in
          class(es). See <ulink url="http://en.wikipedia.org/wiki/Java_package"
          >http://en.wikipedia.org/wiki/Java_package</ulink> for information
          about conventions for naming packages.
        </para>
      </sect3>
    
      <sect3 id="plugin_developer.organize.ant.buildfile">
        <title>The build file</title>
        <para>
          In the root of your directory, create the build file:
          <filename>build.xml</filename>
          . Here is an example that will compile your plug-in and put it in a JAR file.
        </para>
        <example id="plugin_developer.organize.build.file">
          <title>A simple build file</title>
<programlisting>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;project 
   name="MyPlugin" 
   default="build.plugin" 
   basedir="."
   &gt;

   &lt;!-- variables used --&gt;
   &lt;property name="plugin.name" value="MyPlugin" /&gt;
   &lt;property name="src" value="src" /&gt;
   &lt;property name="bin" value="bin" /&gt;

   &lt;!-- set up classpath for compiling --&gt;
   &lt;path id="classpath"&gt;
      &lt;fileset dir="lib"&gt;
         &lt;include name="**/*.jar"/&gt;
      &lt;/fileset&gt;
   &lt;/path&gt;

    
   &lt;!-- main target --&gt;
   &lt;target 
      name="build.plugin"  
      description="Compiles the plug-in and put in jar"
      &gt;
      &lt;javac 
         encoding="ISO-8859-1"
         srcdir="${src}"
         destdir="${bin}"
         classpathref="classpath"&gt;
      &lt;/javac&gt;
      &lt;jar 
         jarfile="${plugin.name}.jar" 
         basedir="bin"
         manifest="MANIFEST.MF"
         &gt;
      &lt;/jar&gt;

    &lt;/target&gt;
&lt;/project&gt; </programlisting>
        </example>
        <para>
          If your plug-in depends on other JAR files than the
          <filename>BASE2Core.jar</filename> you must create a file called
          <filename>MANIFEST.MF</filename> in the project root directory. 
          List the other JAR files as in the following example.
          If your plug-in does not depend on other JAR files, remove the 
          <sgmltag class="attribute">manifest</sgmltag> 
          attribute of the <sgmltag class="starttag">jar</sgmltag> tag.
<programlisting>Manifest-Version: 1.0
Class-Path: OtherJar.jar ASecondJar.jar</programlisting>
        </para>
      </sect3>
        
      <sect3 id="plugin_developer.organize.ant.build">
        <title>Building the plug-in</title>
        <para>
          Compile the plug-in simply by typing
          <command>ant</command>
          in the console window. If all went well the
          <filename>MyPlugin.jar</filename>
          will be created in the same directory.
        </para>
        <para>
          To install the plug-in copy the JAR file to the server including the dependent JAR
          files (if any). Place all files together in the same directory. For more
          information read
          <xref linkend="plugins.installation" />
        </para>
      </sect3>
    </sect2>
    
    <sect2 id="plugin_developer.organize.eclipse">
      <title>With Eclipse</title>
      <para>TODO</para>
    </sect2>
    
  </sect1>

  <sect1 id="plugin_developer.api">
    <title>The Plug-in API</title>
    <para>
    </para>
    
    <sect2 id="plugin_developer.api.interfaces">
    
      <title>The main plug-in interfaces</title>
      <para>
        The Base2 core defines two interfaces and one
        abstract class that are vital for implementing plug-ins:
        <itemizedlist spacing="compact">
          <listitem>
            <simpara>
              <interfacename>net.sf.basedb.core.plugin.Plugin</interfacename>
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              <interfacename>net.sf.basedb.core.plugin.InteractivePlugin</interfacename>
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              <classname>net.sf.basedb.core.plugin.AbstractPlugin</classname>
            </simpara>
          </listitem>
        </itemizedlist>
        
        A plug-in is always required to implement the 
        <interfacename>Plugin</interfacename> interface. 
        The <interfacename>InteractivePlugin</interfacename>
        interface is optional, and is only needed if you want user interaction.
        The <classname>AbstractPlugin</classname> is a useful base class
        that your plug-in can use as a superclass. It provides default implementations
        for some of the interface methods and also has utility methods for
        validating and storing job and configuration parameter values. Another
        reason to use this class as a superclass is that it will shield your 
        plug-in from future changes to the Plug-in API. For example, if
        we decide that a new method is needed in the <interfacename>Plugin</interfacename> 
        interface we will also try to add a default implementation in 
        the <classname>AbstractPlugin</classname> class.
      </para>
  
      <important>
        <para>
        A plug-in must also have public no-argument contructor. Otherwise, BASE will not
        be able to create instances of the class.
        </para>
      </important>
      
      <sect3 id="plugin_developer.api.interfaces.plugin">
        <title>net.sf.basedb.core.plugin.Plugin</title>
        <para>This interface defines seven methods and must be implemented by all plug-ins.</para>
        <variablelist>
          <varlistentry>
            <term>
              <methodsynopsis language="java">
                <modifier>public</modifier>
                <type>About</type>
                <methodname>getAbout</methodname>
                <void />
              </methodsynopsis>
            </term>
            <listitem>
              <para>
                Return information about the plug-in, i.e. the name, version, and a short
                description about what the plug-in does. The
                <classname>About</classname>
                object also has fields for naming the author and various other contact
                information. The returned information is copied by the core at
                installation time into the database. The only required information is
                the name of the plug-in. All other fields may have null values.
              </para>
              <example id="net.sf.basedb.core.plugin.Plugin.getAbout">
                <title>A typical implementation stores this information in a static field</title>
<programlisting>private static final About about = new AboutImpl
(
   "Spot images creator",
   "Converts a full-size scanned image into smaller preview jpg " +
   "images for each individual spot.",
   "2.0",
   "2006, Department of Theoretical Physics, Lund University",
   null,
   "base@thep.lu.se",
   "http://base.thep.lu.se"
);
  
public About getAbout()
{
   return about;
}</programlisting>
              </example>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <methodsynopsis language="java">
                <modifier>public</modifier>
                <type>Plugin.MainType</type>
                <methodname>getMainType</methodname>
                <void />
              </methodsynopsis>
            </term>
            <listitem>
              <para>
                Return information about the main type of plug-in. The
                <classname>MainType</classname>
                is an enumeration with five possible values:
                <itemizedlist>
                  <listitem>
                    <para>
                      <constant>ANALYZE</constant>: 
                      An analysis plug-in
                    </para>
                  </listitem>
                  <listitem>
                    <para>
                      <constant>EXPORT</constant>:
                      A plug-in that exports data
                    </para>
                  </listitem>
                  <listitem>
                    <para>
                      <constant>IMPORT</constant>:
                      A plug-in that imports data
                    </para>
                  </listitem>
                  <listitem>
                    <para>
                      <constant>INTENSITY</constant>:
                      A plug-in that calculates the original spot intensities
                      from raw data
                    </para>
                  </listitem>
                  <listitem>
                    <para>
                      <constant>OTHER</constant>:
                      Any other type of plug-in
                    </para>
                  </listitem>
                </itemizedlist>
                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 
                &gbExport;
                will let you select among the export plug-ins.
              </para>
              <example id="net.sf.basedb.core.plugin.Plugin.getMainType">
                <title>A typical implementation just return one of the values</title>
<programlisting>public Plugin.MainType getMainType()
{
   return Plugin.MainType.OTHER;
}</programlisting>
              </example>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <methodsynopsis language="java">
                <modifier>public</modifier>
                <type>boolean</type>
                <methodname>supportsConfigurations</methodname>
                <void />
              </methodsynopsis>
            </term>
            <listitem>
              <para>
                If this method returns true, the plug-in can have different
                configurations, (i.e.
                <classname>PluginConfiguration</classname>).
                Note that this method may return true even if the
                <interfacename>InteractivePlugin</interfacename>
                interface is not implemented. The
                <classname>AbstractPlugin</classname>
                returns true for this method, which is the old way before the
                introduction of this method.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <methodsynopsis language="java">
                <modifier>public</modifier>
                <type>boolean</type>
                <methodname>requiresConfiguration</methodname>
                <void />
              </methodsynopsis>
            </term>
            <listitem>
              <para>
                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
                <classname>AbstractPlugin</classname>
                returns false for this method, which is the old way before the
                introduction of this method.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <methodsynopsis language="java">
                <modifier>public</modifier>
                <void />
                <methodname>init</methodname>
                <methodparam>
                  <type>SessionControl</type>
                  <parameter>sc</parameter>
                </methodparam>
                <methodparam>
                  <type>ParameterValues</type>
                  <parameter>configuration</parameter>
                </methodparam>
                <methodparam>
                  <type>ParameterValues</type>
                  <parameter>job</parameter>
                </methodparam>
                <exceptionname>BaseException</exceptionname>
              </methodsynopsis>
            </term>
            <listitem>
              <para>
                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.
              </para>
              <para>
                The parameters passed to this method has vital information that is
                needed to execute the plug-in. The
                <classname>SessionControl</classname>
                is a central core object holding information about the logged in
                user and is used to create
                <classname>DbControl</classname>
                objects which allows a plug-in to connect to the database to read, add or
                update information. The two
                <classname>ParameterValues</classname>
                objects contain information about the configuration and job 
                parameters to the plug-in. 
                The <varname>configuration</varname> object holds all parameters stored
                together with a <classname>PluginConfiguration</classname>
                object in the database. If the plug-in is started without
                a configuration this object is null.
                The <varname>job</varname> object holds all parameters that are
                stored together with a <classname>Jon</classname> object in the 
                database. This object is null if the plug-in is started without a job.
              </para>
              <para>
                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.
              </para>
              <para>
                The
                <classname>AbstractPlugin</classname>
                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 <code>super.init()</code>.
              </para>
              <example id="net.sf.basedb.core.plugin.Plugin.init">
                <title>The <classname>AbstractPlugin</classname> implementation of this Plugin.init()</title>
<programlisting>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;
}</programlisting>
              </example>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <methodsynopsis language="java">
                <modifier>public</modifier>
                <void />
                <methodname>run</methodname>
                <methodparam>
                  <type>Request</type>
                  <parameter>request</parameter>
                </methodparam>
                <methodparam>
                  <type>Response</type>
                  <parameter>response</parameter>
                </methodparam>
                <methodparam>
                  <type>ProgressReporter</type>
                  <parameter>progress</parameter>
                </methodparam>
              </methodsynopsis>
            </term>
            <listitem>
              <para>
                Runs the plug-in. The <varname>request</varname>
                parameter is of historical interest only. It has no useful information 
                and can be ignored.
              </para>
              <para>
                The <varname>progress</varname> parameter
                can be used by a plug-in to report it's 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 can be null, but if it is not we recommend all
                plug-ins to use it. However, it should be used sparingly, since each call
                to set the progress results in a database update. If the execution
                involves several thousands of items it is a bad idea to update the
                progress after processing each one of them. 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.
              </para>
              <para>
                The <varname>response</varname>
                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 the
                <methodname>setDone()</methodname>
                or the
                <methodname>setError()</methodname>
                methods.
              </para>
              
              <note>
                It is also considered bad practice to let exceptions escape
                out from this method. Always use <code>try...catch</code>
                to catch exceptions and use <code>response.setError()</code>
                to reporter the error back to the core.
              </note>
              
              <example id="net.sf.basedb.core.plugin.Plugin.run">
                <title>
                  Here is a skeleton that we recommend each plug-in to use in it's
                  implementation of the
                  <methodname>run()</methodname>
                  method
                </title>
<programlisting>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();
   }
}</programlisting>
              </example>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <methodsynopsis language="java">
                <modifier>public</modifier>
                <void />
                <methodname>done</methodname>
                <void />
              </methodsynopsis>
            </term>
            <listitem>
              <para>
                Clean up all resources after executing the plug-in. This method must not
                throw any exceptions.
              </para>
              <example id="net.sf.basedb.core.plugin.Plugin.done">
                <title>
                  The
                  <classname>AbstractPlugin</classname>
                  contains an implementation of the <methodname>done()</methodname>
                  method simply sets the
                  parameters passed to the
                  <methodname>init()</methodname>
                  method to null
                </title>
<programlisting>/**
   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;
}</programlisting>
              </example>
            </listitem>
          </varlistentry>
        </variablelist>
      </sect3>
  
      <sect3 id="plugin_developer.api.interfaces.interactive">
        <title>net.sf.basedb.core.plugin.InteractivePlugin</title>
        <para>
          If you want the plug-in to be able to interact with the user you must also implement
          this interface. This is probably the case for most plug-ins. Among the core plug-ins
          shipped with BASE the
          <classname>SpotImageCreator</classname>
          is one plug-in that does not interact with the user. Instead, the web client has
          special JSP pages that handles all the interaction, creates a job for it and sets
          the parameters. This, kind of hardcoded, approach can be used for other plug-ins as
          well, but then it usually requires modification of the client application as well.
        </para>
        <para>
          The
          <interfacename>InteractivePlugin</interfacename>
          has three main tasks:
          
          <orderedlist>
          <listitem>
            <para>
            Tell a client application where the plug-in should be plugged
            in.
            </para>
          </listitem>
          <listitem>
            <para>
            Ask the users for configuration and job parameters.
            </para>
          </listitem>
          
          <listitem>
            <para>
            Validate parameter values entered by the user and store those in the
            database.
            </para>
          </listitem>
          </orderedlist>
          This requires that the following methods are 
          implemented.
        </para>
        
        <variablelist>
          <varlistentry>
            <term>
              <methodsynopsis language="java">
                <modifier>public</modifier>
                <type>Set&lt;GuiContext&gt;</type>
                <methodname>getGuiContexts</methodname>
                <void />
              </methodsynopsis>
            </term>
            <listitem>
              <para>
                Return information about where the plug-in should be plugged in. Each
                place is identified by a
                <classname>GuiContext</classname>
                object, which is an
                <classname>Item</classname>
                and a
                <classname>Type</classname>.
                The item is one of the objects defined by the
                <classname>net.sf.basedb.core.Item</classname>
                enumeration and the type is either
                <constant>Type.LIST</constant>
                or
                <constant>Type.ITEM</constant>, which corresponde to the
                list view and the single-item view in the web client.
              </para>
              <para>
                For example, the
                <varname>GuiContext</varname> = 
                (<constant>Item.REPORTER</constant>, 
                <constant>Type.LIST</constant>)
                tells a client application that this plug-in can be plugged in whenever a
                list of reporters is displayed. The
                <varname>GuiContext</varname> =
                (<constant>Item.REPORTER</constant>,
                <constant>Type.ITEM</constant>)
                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).
              </para>
              <para>
                The returned information is copied by the core at installation time to
                make it easy to ask for all plug-ins for a certain
                <classname>GuiContext</classname>.
              </para>
              <para>
                A typical implementation creates a static unmodifiable
                <classname>Set</classname>
                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.
              </para>
              <example id="net.sf.basedb.core.plugin.InteractivePlugin.getGuiContexts">
                <title>
                  A typical implementation of
                  <methodname>getGuiContexts</methodname>
                </title>
<programlisting>// From the net.sf.basedb.plugins.RawDataFlatFileImporter plug-in
private static final Set&lt;GuiContext&gt; guiContexts = 
   Collections.singleton(new GuiContext(Item.RAWBIOASSAY, GuiContext.Type.ITEM));

public Set&lt;GuiContext&gt; <methodname>getGuiContexts</methodname>()
{
   return <returnvalue>guiContexts</returnvalue>;
}</programlisting>
              </example>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <methodsynopsis language="java">
                <modifier>public</modifier>
                <type>String</type>
                <methodname>isInContext</methodname>
                <methodparam>
                  <type>GuiContext</type>
                  <parameter>context</parameter>
                </methodparam>
                <methodparam>
                  <type>Object</type>
                  <parameter>item</parameter>
                </methodparam>
              </methodsynopsis>
            </term>
            <listitem>
              <para>
                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 <parameter>item</parameter>
                parameter is <constant>null</constant>.  
                The plug-in should return <constant>null</constant> 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.
              </para>
              
              <para>
                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.
              </para>
              
              <para>
                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.
              </para>
              
              <para>
                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.
              </para>
              
              <note>
                <para>
                The contract of this method was changed in in BASE 2.4
                to allow warning and error level message. Prior to BASE
                2.4 all messages were treated as error message. We recommend
                that existing plug-ins are updated to throw exception to indicate
                error-level messages since the default is to not show 
                warning messages to users.
                </para>
              </note>
              
              <para>
                Here is a real example from the
                <classname>RawDataFlatFileImporter</classname>
                plug-in which imports raw data to a
                <classname>RawBioAssay</classname>. 
                
                Thus,
                <varname>GuiContext</varname> = 
                (<constant>Item.RAWBIOASSAY</constant>,
                <constant>Type.ITEM</constant>), 
                
                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.
              </para>
              <example id="net.sf.basedb.core.plugin.InteractivePlugin.isInContext">
                <title>
                  A simple implementation of
                  <methodname>isInContext</methodname>
                </title>
<programlisting>/**
   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))
      {
         message = "Unsupported raw data type: " + rba.getRawDataType().getName();
      }
      else if (!rdt.isStoredInDb())
      {
         message = "Raw data for raw data type '" + rdt + "' is not stored in the database";
      }
      else if (rba.hasData())
      {
         throw new PermissionDeniedException("The raw bioassay already has data.");
      }
      else
      {
         rba.checkPermission(Permission.WRITE);
      }
   }
   return message;    
}</programlisting>
              </example>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <methodsynopsis language="java">
                <modifier>public</modifier>
                <type>RequestInformation</type>
                <methodname>getRequestInformation</methodname>
                <methodparam>
                  <type>GuiContext</type>
                  <parameter>context</parameter>
                </methodparam>
                <methodparam>
                  <type>String</type>
                  <parameter>command</parameter>
                </methodparam>
                <exceptionname>BaseException</exceptionname>
              </methodsynopsis>
            </term>
            <listitem>
              <para>
                Ask the plug-in for parameters that needs to be entered by the user. The
                <classname>GuiContext</classname>
                parameter is one of the contexts returned by the
                <methodname>getGuiContexts</methodname>
                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 it's own commands. The two predefined commands are
                defined in the
                <classname>net.sf.basedb.core.plugin.Request</classname>
                class.
                <variablelist>
                  <varlistentry>
                    <term>
                      <constant>Request.COMMAND_CONFIGURE_PLUGIN</constant>
                    </term>
                    <listitem>
                      <para>
                        Used when an administrator is initiating a configuration
                        of the plug-in.
                      </para>
                    </listitem>
                  </varlistentry>
                  <varlistentry>
                    <term>
                      <constant>Request.COMMAND_CONFIGURE_JOB</constant>
                    </term>
                    <listitem>
                      <para>
                        Used when a user has selected the plug-in for running a
                        job.
                      </para>
                    </listitem>
                  </varlistentry>
                </variablelist>
                Given this information the plug-in must return a
                <classname>RequestInformation</classname>
                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.
              </para>
              <example id="net.sf.basedb.core.plugin.InteractivePlugin.getRequestInformation">
                <title>
                  When running an import plug-in it needs to ask for the file to import
                  from and if existing items should be updated or not
                </title>
<programlisting >// The complete request information
private RequestInformation configure Job;

// The parameter that asks for a file to import from
private PluginParameter&lt;File&gt; file Parameter;

// The parameter that asks if existing items should be updated or not
private PluginParameter&lt;Boolean&gt; 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)
   {
      fileParameter = new PluginParameter&lt;File&gt;(
         "file",
         "File",
         "The file to import the data from",
         new FileParameterType(null, true, 1)
      ); 
      
      updateExistingParameter = new PluginParameter&lt;Boolean&gt;(
         "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&lt;PluginParameter&lt;?&gt;&gt; parameters = 
         new ArrayList&lt;PluginParameter&lt;?&gt;&gt;(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;
}</programlisting>
              </example>
              <para>
                As you can see it takes a lot of code to put together a
                <classname>RequestInformation</classname>
                object. For each parameter you need one
                <classname>PluginParameter</classname>
                object and one
                <classname>ParameterType</classname>
                object. To make life a little easier, a
                <classname>ParameterType</classname>
                can be reused for more than one
                <classname>PluginParameter</classname>.
              </para>
              
<programlisting>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</programlisting>
              <para>
                The
                <classname>ParameterType</classname>
                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.
              </para>
              <note>
                <para>
                  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.
                </para>
              </note>
              <variablelist>
                <varlistentry>
                  <term>
                    <classname>StringParameterType</classname>
                  </term>
                  <listitem>
                    <para>
                      Asks for a string value. Includes an option for
                      specifying the maximum length of the string.
                    </para>
                  </listitem>
                </varlistentry>
                <varlistentry>
                  <term>
                    <classname>FloatParameterType</classname>, 
                    <classname>DoubleParameterType</classname>, 
                    <classname>IntegerParameterType</classname>, 
                    <classname>LongParameterType</classname>
                  </term>
                  <listitem>
                    <para>
                      Asks for numerical values. Includes options for
                      specifying a range (min/max) of allowed values.
                    </para>
                  </listitem>
                </varlistentry>
                <varlistentry>
                  <term>
                    <classname>BooleanParameterType</classname>
                  </term>
                  <listitem>
                    <para>Asks for a boolean value.
                    </para>
                  </listitem>
                </varlistentry>
                <varlistentry>
                  <term>
                    <classname>DateParameterType</classname>
                  </term>
                  <listitem>
                    <para>Asks for a date.
                    </para>
                  </listitem>
                </varlistentry>
                <varlistentry>
                  <term>
                    <classname>FileParameterType</classname>
                  </term>
                  <listitem>
                    <para>Asks for a file item.
                    </para>
                  </listitem>
                </varlistentry>
                <varlistentry>
                  <term>
                    <classname>ItemParameterType</classname>
                  </term>
                  <listitem>
                    <para>
                      Asks for any other item. This parameter type requires
                      that a list of options is supplied, except when the item
                      type asked for matches the current <classname>GuiContext</classname>, in which
                      case the currently selected item is used as the
                      parameter value.
                    </para>
                  </listitem>
                </varlistentry>
                <varlistentry>
                  <term>
                    <classname>PathParameterType</classname>
                  </term>
                  <listitem>
                    <para>
                      Ask for a path to a file or directory. The path may be
                      non-existing and should be used when a plug-in needs an
                      output destination, i.e., the file to export to, or a
                      directory where the output files should be placed.
                    </para>
                  </listitem>
                </varlistentry>
              </variablelist>
              <para>
                You can also create a
                <classname>PluginParameter</classname>
                with a null name and
                <classname>ParameterType</classname>.
                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.
              </para>
<programlisting>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);</programlisting>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <methodsynopsis language="java">
                <modifier>public</modifier>
                <void />
                <methodname>configure</methodname>
                <methodparam>
                  <type>GuiContext</type>
                  <parameter>context</parameter>
                </methodparam>
                <methodparam>
                  <type>Request</type>
                  <parameter>request</parameter>
                </methodparam>
                <methodparam>
                  <type>Response</type>
                  <parameter>response</parameter>
                </methodparam>
              </methodsynopsis>
            </term>
            <listitem>
              <para>
                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.
              </para>
              
              <important>
                <para>
                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
                <classname>Float</classname>
                the input string is parsed and converted to a 
                <classname>Float</classname>. If you have extended the
                <classname>AbstractPlugin</classname>
                class it is very easy to validate the parameters with the
                <methodname>validateRequestParameters()</methodname>
                method. This method takes the same list of
                <classname>PluginParameter</classname>:s
                as used in the
                <classname>RequestInformation</classname>
                object and uses that information for validation. It returns null or a
                list of
                <exceptionname>Throwable</exceptionname>:s that can be 
                given directly to the <code>response.setError()</code>
                methods.
                </para>
              </important>
              <para>
                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
                <methodname>AbstractPlugin.storeValue()</methodname>
                or
                <methodname>AbstractPlugin.storeValues()</methodname>
                methods.
              </para>
              <para>
                The configure method works much like the <methodname>Plugin.run()</methodname> 
                method. It must return the result in the <classname>Response</classname> object, 
                and should not trow any exceptions.
              </para>
              
              <example id="net.sf.basedb.core.plugin.InteractivePlugin.configure">
                <title>
                  Configuration implementation building on the examples above
                </title>
<programlisting>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&lt;Throwable&gt; 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
         response.setDone("Job configuration complete", Job.ExecutionTime.SHORT);
         // TODO - check file size to make a better estimate of execution time
      }
   }
   catch (Throwable ex)
   {
      response.setError(ex.getMessage(), Arrays.asList(ex));
   }
}</programlisting>
              </example>
              
              <para>
                Note that the call to
                <methodname>response.setDone()</methodname>
                has a second parameter
                <constant>Job.ExecutionTime.SHORT</constant>. 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 <constant>Job.ExecutionTime.SHORT</constant>
                out of old habit all the time.
              </para>
              <para>
                The <classname>Response</classname> class also has a
                <methodname>setContinue()</methodname>
                method which tells the core that the plug-in needs more parameters,
                i.e. the core will then call
                <methodname>getRequestInformation()</methodname>
                again with the new command, let the user enter values, and then call
                <methodname>configure()</methodname>
                with the new values. This process is repeated until the plug-in
                reports that it is done or an error occurs.
              </para>
              <para>
                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 
                <methodname>response.setDone()</methodname>.
                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.
              </para>
              <tip>
                  <para>
                    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.
                  </para>
              </tip>
            </listitem>
          </varlistentry>
        </variablelist>
      </sect3>
    
    </sect2>
  
    <sect2 id="plugin_developer.api.callsequence">
      <title>What happens when...</title>
      
      <para>
        This section describes how the BASE core interacts with the
        plug-in in a number of use cases. We will outline the 
        order the methods are invoked on the plug-in.
      </para>
      
      <sect3 id="plugin_developer.api.callsequence.install">
        <title>Installing a plug-in</title>
        
        <para>
          When a plug-in is installed the core is eager to find out
          information about the plug-in. To do this it calls the
          following methods in this order:
        </para>
        
        <orderedlist>
        <listitem>
          <para>
          A new instance of the plug-in class is created. The plug-in must
          have a public no-argument constructor.
          </para>
        </listitem>
        
        <listitem>
          <para>
          Calls are made to <methodname>Plugin.getMainType()</methodname>,
          <methodname>Plugin.supportsConfigurations()</methodname>,
          <methodname>Plugin.requiresConfiguration()</methodname> and
          <methodname>Plugin.getAbout()</methodname> to find out information
          about the plug-in. This is the only time theese methods are called.
          The information that is returned by them are copied and stored in 
          the database for easy access.
          </para>
          
          <note>
            <para>
            The <methodname>Plugin.init()</methodname> method is
            never called during plug-in installation.
            </para>
          </note>
        </listitem>
        
        <listitem>
          <para>
          If the plug-in implements the <interfacename>InteractivePlugin</interfacename>
          interface the <methodname>InteractivePlugin.getGuiContexts()</methodname>
          method is called. This is the only time this method. The information it
          returns are copied and stored in the database.
          </para>
        </listitem>
        
        <listitem>
          <para>
          If the server admin decided to use the plug-in permission system, the
          <methodname>Plugin.getPermissions()</methodname> method is called.
          The returned information is copied and stored in the database.
          </para>
        </listitem>
        
        </orderedlist>
      </sect3>
    
      <sect3 id="plugin_developer.api.callsequence.configure">
        <title>Configuring a plug-in</title>
        
        <para>
          The plug-in must implement the <interfacename>InteractivePlugin</interfacename>
          interface and the <methodname>Plugin.supportsConfigurations()</methodname> method
          must return <constant>TRUE</constant>. The configuration is done with
          a wizard-like interface (see <xref linkend="plugins.configuration.wizard" />). 
          The same plug-in instance is used throughout the entire configuration sequence.
        </para>
        
        <orderedlist>
        <listitem>
          <para>
          A new instance of the plug-in class is created. The plug-in must
          have a public no-argument constructor.
          </para>
        </listitem>
        
        <listitem>
          <para>
          The <methodname>Plugin.init()</methodname> method is called. The 
          <varname>job</varname> parameter is null.
          </para>
        </listitem>
        
        <listitem id="plugin_developer.api.callsequence.configure.requestinformation">
          <para>
          The <methodname>InteractivePlugin.getRequestInformation()</methodname> 
          method is called. The <varname>context</varname> parameter is <constant>null</constant>
          and the <varname>command</varname> is the value of the string 
          constant <constant>Request.COMMAND_CONFIGURE_PLUGIN</constant> 
          (_config_plugin).
          </para>
        </listitem>
        
        <listitem id="plugin_developer.api.callsequence.configure.form">
          <para>
          The web client process this information and displays a form for user
          input. The plug-in will have to wait some time while the user enters 
          data.
          </para>
        </listitem>
        
        <listitem>
          <para>
          The <methodname>InteractivePlugin.configure()</methodname> method
          is called. The <varname>context</varname> parameter is still 
          <constant>null</constant> and the <varname>request</varname>
          parameter contains the parameter values entered by the user.
          </para>
        </listitem>
        
        <listitem>
          <para>
          The plug-in must validate the values and decide whether they should be
          stored in the database or not. We recommend that you use the
          methods in the <classname>AbstractPlugin</classname> class for this.
          </para>
        </listitem>
        
        <listitem>
          <para>
          The plug-in has three different respones:
          
          <itemizedlist>
          <listitem>
            <para>
            <methodname>Response.setDone()</methodname>: The configuration
            is complete. The core will write any configuation changes to the
            database, call the <methodname>Plugin.done()</methodname> method and 
            then discard the plug-in instance.
            </para>
          </listitem>
          
          <listitem>
            <para>
            <methodname>Response.setError()</methodname>: There was one or more
            errors. The web client will display the error messages for the user and
            allow the user to enter new values. The process continues with 
            step <xref linkend="plugin_developer.api.callsequence.configure.form" />.
            </para>
          </listitem>
          
          <listitem>
            <para>
            <methodname>Response.setContinue()</methodname>: The parameters are correct
            but the plug-in wants more parameters. The process continues with
            step <xref linkend="plugin_developer.api.callsequence.configure.requestinformation" />.
            </para>
          </listitem>
          </itemizedlist>
          
          </para>
        </listitem>
        </orderedlist>

      </sect3>    
    
      <sect3 id="plugin_developer.api.callsequence.context">
        <title>Checking if a plug-in can be used in a given context</title>
        
        <para>
          If the plug-in is an <interfacename>InteractivePlugin</interfacename>
          it has specified in which contexts it can be used by the 
          information returned from <methodname>InteractivePlugin.getGuiContexts()</methodname>
          method. The web client uses this information to decide whether,
          for example, a <guibutton>Run plugin</guibutton>
          button should be displayed on a page or not. However, this is not
          always enough to know whether the plug-in can be used or not.
          For example, a raw data importer plug-in cannot be used to
          import raw data if the raw bioassay already has data.
          So, when the user clicks the button, the web client will
          load all plug-ins that possibly can be used in the given context
          and let each one of them check whether they can be used or not.
        </para>
        
      
        <orderedlist>
        <listitem>
          <para>
          A new instance of the plug-in class is created. The plug-in must
          have a public no-argument constructor.
          </para>
        </listitem>
        
        <listitem>
          <para>
          The <methodname>Plugin.init()</methodname> method is called.
          The <varname>job</varname> parameter is <constant>null</constant>. 
          The <varname>configuration</varname> parameter is <constant>null</constant>
          if the plug-in does not have any configuration parameters.
          </para>
        </listitem>
        
        <listitem>
          <para>
          The <methodname>InteractivePlugin.isInContext()</methodname>
          is called. If the context is a list context, the <varname>item</varname>
          parameter is null, otherwise the current item is passed. The plug-in 
          should return <constant>null</constant> if it can be used under the 
          current circumstances, or a message explaining why not.
          </para>
        </listitem>
        
        <listitem>
          <para>
            After this, the plug-in instance is discarded. If there are
            several configurations for a plug-in, this procedure is repeated
            for each configuration.
          </para>

          <warning>
          <para>
            The <methodname>Plugin.done()</methodname> method is never
            called! This is bug that has been reported to the developers
            and hopefully it will be fixed shortly.
          </para>
          </warning>
        </listitem>
        </orderedlist>
      </sect3>
    
      <sect3 id="plugin_developer.api.callsequence.job">
        <title>Creating a new job</title>
        
        <para>
          If the web client found that the plug-in could be
          used in a given context and the user selected the plug-in
          the job configuration sequence is started. It is a wizard-like interface
          identical to the configuration wizard. In fact, the same JSP pages,
          and calling sequence is used. See <xref linkend="plugin_developer.api.callsequence.configure" />.
          We do not repeat everything here. There are a few differences:
        </para>
        
        <itemizedlist>
        <listitem>
          <para>
          The <varname>job</varname> parameter is not null, but it does not contain
          any parameter values to start with. The plug-in should use this
          object to store job-related parameter values. The 
          <varname>configuration</varname> parameter is <constant>null</constant> 
          if the plug-in is started without configuration. In any case,
          the configuration values are write-protected and cannot be modified.
          </para>
        </listitem>
        
        <listitem>
          <para>
          The first call to <methodname>InteractivePlugin.getRequestInformation()</methodname>
          is done with <constant>Request.COMMAND_CONFIGURE_JOB</constant> (_configjob)
          as the command. The <varname>context</varname> parameter reflects the 
          current context.
          </para>
        </listitem>
        
        <listitem>
          <para>
          When calling <methodname>Response.setDone()</methodname> the plug-in
          should use the variant that takes an estimated execution time.
          If the plug-in has support for immediate execution or download 
          (export plug-ins only), it can also respond with 
          <methodname>Response.setExecuteImmediately()</methodname> or
          <methodname>Response.setDownloadImmediately()</methodname>.
          </para>
          
          <para>
          If the plug-in requested and was granted immediate execution or 
          download the same plug-in instance is used to execute the plug-in.
          This may be done with the same or a new thread. Otherwise, a new
          job is added to the job queue, the parameter value are saved
          and the plug-in instance is discarded after calling the
          <methodname>Plugin.done()</methodname> method.
          </para>
        </listitem>
        </itemizedlist>
      </sect3>
    
      <sect3 id="plugin_developer.api.callsequence.execute">
        <title>Executing a job</title>
        
        <para>
          Normally, the creation of a job and the execution of it are
          two different events. The execution may as well be done on a
          different server. See <xref linkend="installation_upgrade.jobagents" />.
          This means that the execution takes place in a different instance
          of the plug-in class than what was used for creating the job.
          The exception is if a plug-in supports immediate execution or download.
          In this case the same instance is used, and it, of course,
          is always executed on the web server.
        </para>
        
        <orderedlist>
        <listitem>
          <para>
          A new instance of the plug-in class is created. The plug-in must
          have a public no-argument constructor.
          </para>
        </listitem>
        
        <listitem>
          <para>
          The <methodname>Plugin.init()</methodname> method is called.
          The <varname>job</varname> parameter contains the job
          configuration paramters. The <varname>configuration</varname> parameter 
          is <constant>null</constant> if the plug-in does not have any 
          configuration parameters.
          </para>
        </listitem>
        
        <listitem>
          <para>
          The <methodname>Plugin.run()</methodname> method is called. 
          It is finally time for the plug-in to do the work it has bee
          designed for. This method should not throw any exceptions.
          Use the <methodname>Response.setDone()</methodname>
          method to report success or the <methodname>Response.setError()</methodname>
          to reporter errors.
          </para>
        </listitem>
        
        <listitem>
          <para>
          In both cases the <methodname>Plugin.done()</methodname>
          method is called and the plug-in instance is discarded.
          </para>
        </listitem>
        
        </orderedlist>
      </sect3>
    
    </sect2>
  
    <sect2 id="plugin_developer.api.jspparameters">
      <title>Using custom JSP pages for parameter input</title>

        <para>
          This is an advanced option for plug-ins that require a different interface for
          specifying plug-in parameters than the default list showing each parameter at a
          time. This feature is used by setting the RequestInformation.getJspPage()
          property when constructing the request information object. If this property has
          a non-null value, the web client will send the browser to the specified JSP page
          instead of to the generic parameter input page.
        </para>
        <para>
          When setting the JSP page you should only set the file name. Do not include 
          any path information. The web
          client has a special location for these JSP pages, generated from the package
          name of your plug-in. If the plug-in is located in the package
          <classname>org.company</classname>
          the JSP page must be located in
          <filename class="directory">&lt;base-dir&gt;/www/plugins/org/company/</filename>.
          Please note that the browser still thinks that it is showing the regular page
          at the usual location:
          <filename class="directory">&lt;base-dir&gt;/www/common/plugin/index.jsp</filename>.
          All links in your JSP page should be relative to that directory.
        </para>
        <para>
          Even if you use your own JSP page we recommend that you use the built-in
          facility for passing the parameters back to the plug-in. For this to work you
          must:
        </para>
        <itemizedlist spacing="compact">
          <listitem>
            <simpara>
            Generate the list of <classname>PluginParameter</classname> 
            objects as usual.
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              Name all your input fields in the JSP like:
              <parameter>
                parameter:<replaceable>name-of-parameter</replaceable>
              </parameter>
            </simpara>
<programlisting>// Plugin generate 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);

// JSP should name fields as:
First string: &lt;input type="text" name="parameter:one"&gt;&lt;br&gt;
Second string: &lt;input type="text" name="parameter:two"&gt;</programlisting>
          </listitem>
          <listitem>
          <simpara>
            Send the form to
            <filename>index.jsp</filename>
            with the <varname>ID</varname> and <varname>cmd</varname> parameters
            as shown below.
          </simpara>
<programlisting>&lt;form action="index.jsp" method="post"&gt;
&lt;input type="hidden" name="ID" value="&lt;%=ID%&gt;"&gt;
&lt;input type="hidden" name="cmd" value="SetParameters"&gt;
...
&lt;/form&gt;</programlisting>

          </listitem>
          </itemizedlist>
            <para>
              In your JSP page you will probably need to access some information like the
              <classname>SessionControl</classname>, <classname>Job</classname>
              and possible even the <classname>RequestInformation</classname>
              object created by your plug-in.
            </para>
<programlisting>// Get session control and it's ID (required to post to index.jsp)
final SessionControl sc = Base.getExistingSessionControl(pageContext, true);
final String ID = sc.getId();

// Get information about the current request to the plug-in
PluginConfigurationRequest pcRequest = 
   (PluginConfigurationRequest)sc.getSessionSetting("plugin.configure.request");
PluginDefinition plugin = 
   (PluginDefinition)sc.getSessionSetting("plugin.configure.plugin");
PluginConfiguration pluginConfig = 
   (PluginConfiguration)sc.getSessionSetting("plugin.configure.config");
PluginDefinition job = 
   (PluginDefinition)sc.getSessionSetting("plugin.configure.job");
RequestInformation ri = pcRequest.getRequestInformation();</programlisting>

    </sect2>
  </sect1>

  <sect1 id="plugin_developer.import">
    <title>Import plug-ins</title>
    <para>
    
      This documentation is only available in the old format.
      See <ulink url="http://base.thep.lu.se/chrome/site/doc/development/plugins/import/index.html"
        >http://base.thep.lu.se/chrome/site/doc/development/plugins/import/index.html</ulink>
    </para>
    
    <sect2 id="plugin_developer.import.autodetect">
      <title>Autodetecting importer</title>
      <para></para>
    </sect2>
    
    <sect2 id="plugin_developer.import.abstractflatfileimporter">
      <title>The AbstractFlatFileImporter superclass</title>
      <para></para>
    </sect2>
  </sect1>

  <sect1 id="plugin_developer.export">
    <title>Export plug-ins</title>
    
    <para>
      Export plug-ins are plug-ins that takes data from BASE, and 
      prepares it for use with some external entity. Usually this
      means that data is taken from the database and put into a file
      with some well-defined file format.
      An export plug-in should return <constant>MainType.EXPORT</constant> from
      the <methodname>Plugin.getMainType()</methodname> method. 
    </para>
    
    <sect2 id="plugin_developer.export.download">
      <title>Immediate download of exported data</title>
      <para>
        An export plug-in may want to give the user a choice
        between saving the exported data in the BASE file system
        or to download it immediately to the client computer. With the basic 
        plug-in API the second option is not possible. The 
        <interfacename>ImmediateDownloadExporter</interfacename> is an
        interface that extends the <interfacename>Plugin</interfacename>
        interface to provide this functionality. If your export
        plug-in wants to provide immediate download functionality it must
        implement the <interfacename>ImmediateDownloadExporter</interfacename>
        interface.
      </para>
      
      <sect3 id="plugin_developer.export.immediatedownloadexporter">
      <title>The ImmediateDownloadExporter interface</title>
      <variablelist>
      <varlistentry>
        <term>
          <methodsynopsis language="java">
            <modifier>public</modifier>
            <void/>
            <methodname>doExport</methodname>
            <methodparam>
              <type>ExportOutputStream</type>
              <parameter>out</parameter>
            </methodparam>
            <methodparam>
              <type>ProgressReporter</type>
              <parameter>progress</parameter>
            </methodparam>
          </methodsynopsis>
        </term>
        <listitem>
          <para>
          Perform the export. The plug-in should write the
          exported data to the <varname>out</varname> stream.
          If the <varname>progress</varname> parameter is not null, 
          the progress should be reported at regular interval in the
          same manner as in the <methodname>Plugin.run()</methodname>
          method.
          </para>
        </listitem>
      </varlistentry>
      </variablelist>
      
      </sect3>
      
      <sect3 id="plugin_developer.export.exportoutputstream">
      <title>The ExportOutputStream class</title>
      
      <para>
        The <classname>ExportOutputStream</classname> is extends
        <classname>java.io.OutputStream</classname>. Use the regular 
        <methodname>write()</methodname> methods to write data to it.
        It also has three additional methods, which are used to generate
        HTTP response headers.
      </para>
      
      <note>
        <para>
        These methods must be called before starting to write data to
        the <varname>out</varname> stream.
        </para>
      </note>
      
      <variablelist>
      <varlistentry>
        <term>
          <methodsynopsis language="java">
            <modifier>public</modifier>
            <void/>
            <methodname>setContentLength</methodname>
            <methodparam>
              <type>long</type>
              <parameter>contentLength</parameter>
            </methodparam>
          </methodsynopsis>
        </term>
        <listitem>
          <para>
          Set the total size of the exported data (if known).
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <methodsynopsis language="java">
            <modifier>public</modifier>
            <void/>
            <methodname>setMimeType</methodname>
            <methodparam>
              <type>String</type>
              <parameter>mimeType</parameter>
            </methodparam>
          </methodsynopsis>
        </term>
        <listitem>
          <para>
          Set the MIME type of the file that is beeing generated.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <methodsynopsis language="java">
            <modifier>public</modifier>
            <void/>
            <methodname>setFilename</methodname>
            <methodparam>
              <type>String</type>
              <parameter>filename</parameter>
            </methodparam>
          </methodsynopsis>
        </term>
        <listitem>
          <para>
          Set a suggested name of the file that is beeing
          generated.
          </para>
        </listitem>
      </varlistentry>
      </variablelist>
      
      </sect3>
      
      <sect3 id="plugin_developer.export.callsequence">
        <title>Call sequence during immediate download</title>

      <para>
        Supporting immediate download also means that the method call
        sequence is a bit altered from the standard sequence described
        in <xref linkend="plugin_developer.api.callsequence.execute" />.
      </para>
      
      <itemizedlist>
      <listitem>
        <para>
        The plug-in must call <methodname>Response.setDownloadImmediately()</methodname>
        instead of <methodname>Response.setDone()</methodname> in <methodname>Plugin.configure()</methodname>
        to to end the job configuration wizard. This requests that the core starts 
        an immediate download.
        </para>
        
        <note>
          <para>
          Even if an immediate download is requested by the plug-in this feature
          may have been disabled by the server administrator. If so, the plug-in
          can choose if the job should be added to job queue or if this is an
          error condition.
          </para>
        </note>
      </listitem>
      
      <listitem>
        <para>
        If immediate download is granted the web client will keep the
        same plug-in instance and call <methodname>ImmediateDownloadExporter.doExport()</methodname>.
        In this case, the <methodname>Plugin.run()</methodname> is never called.
        
        <note>
          <para>
          The <methodname>Plugin.done()</methodname> method is also never
          called. This is a bug which has been reported to the developers.
          </para>
        </note>
        </para>
        
      </listitem>

      <listitem>
        <para>
        If immediate download is not granted and the job is added to the job queue
        the regular job execution sequence is used. That is, the 
        <methodname>Plugin.run()</methodname> method is called.
        </para>
      </listitem>
      </itemizedlist>
      
      </sect3>

    </sect2>
    
    <sect2 id="plugin_developer.export.abstractexporter">
      <title>The AbstractExporterPlugin class</title>
    
      <para>
        This is an abstract superclass that will make it easier
        to implement export plug-ins that support immediate 
        download. It defines <classname>PluginParameter</classname>
        objects for asking a user about a path where the exported
        data should be saved and if existing files should be overwritten or not.
        If the user leaves the path empty the immediate download functionality
        should be used. It also contains implementations of both the 
        <methodname>Plugin.run()</methodname> method and the
        <methodname>ImmediateDownloadExporter.doExport()</methodname> method.
        Here is what you need to do in your own plug-in code (code examples are
        take from the <classname>HelpExporter</classname>):
      </para>
      
      <itemizedlist>
      <listitem>
        <para>
          Your plug-in should extend the <classname>AbstractExporterPlugin</classname>
          class:
          <programlisting>
public class HelpExporter
  extends AbstractExporterPlugin
  implements InteractivePlugin
</programlisting>
        </para>
      </listitem>
      
      <listitem>
        <para>
          You need to implement the 
          <methodname>InteractivePlugin.getRequestInformation()</methodname>
          method. Use the <methodname>getSaveAsParameter()</methodname>
          and <methodname>getOverwriteParameter()</methodname> methods defined in the 
          superclass to create plug-in parameters that asks for the file name to save
          to and if existing files can be overwritten or not.
          You should also check if the administrator has enabled the immediate execution
          functionality for your plug-in. If not, the only option is to 
          export to a file in the BASE file system and the filename is a
          required parameter.
          
          <programlisting>
// Selected parts of the getRequestConfiguration() method
...
List&lt;PluginParameter&lt;?&gt;&gt; parameters = 
   new ArrayList&lt;PluginParameter&lt;?&gt;&gt;();
...
PluginDefinition pd = job.getPluginDefinition();
boolean requireFile = pd == null ? 
   false : !pd.getAllowImmediateExecution();

parameters.add(getSaveAsParameter(null, null, defaultPath, requireFile));
parameters.add(getOverwriteParameter(null, null));

configureJob = new RequestInformation
(
   Request.COMMAND_CONFIGURE_JOB,
   "Help exporter options",
   "Set Client that owns the helptexts, " +
     "the file path where the export file should be saved",
   parameters
);
....
return configureJob;
</programlisting>
        </para>
      </listitem>

      <listitem>
        <para>
        You must also implement the <methodname>configure()</methodname>
        method and check the parameters. If no filename has been given,
        you should check if immediate exection is allowed and set an
        error if it is not. If a filename is present, use the 
        <methodname>pathCanBeUsed()</methodname> method to check if 
        it is possible to save the data to a file with that name. If the
        file already exists it can be overwritten if the <varname>OVERWRITE</varname>
        is <constant>TRUE</constant> or if the file has been flagged for removal.
        Do not forget to store the parameters with the <methodname>storeValue()</methodname>
        method.

        <programlisting>
// Selected parts from the configure() method
if (request.getParameterValue(SAVE_AS) == null)
{
   if (!request.isAllowedImmediateExecution())
   {
      response.setError("Immediate download is not allowed. " + 
         "Please specify a filename.", null);
      return;
   }
   Client client = (Client)request.getParameterValue("client");
   response.setDownloadImmediately("Export help texts for client application " + 
     client.getName(), ExecutionTime.SHORTEST, true);
}
else
{
   if (!pathCanBeUsed((String)request.getParameterValue(SAVE_AS), 
      (Boolean)request.getParameterValue(OVERWRITE)))
   {
      response.setError("File exists: " + 
         (String)request.getParameterValue(SAVE_AS), null);
      return;
   }
   storeValue(job, request, ri.getParameter(SAVE_AS));
   storeValue(job, request, ri.getParameter(OVERWRITE));
   response.setDone("The job configuration is complete", ExecutionTime.SHORTEST);
}
</programlisting>
        
        </para>
      </listitem>
      
      <listitem>
        <para>
        Implement the <methodname>performExport()</methodname> method.
        This is defined as abstract in the <classname>AbstractExporterPlugin</classname>
        class. It has the same parameters as the <methodname>ImmediateDownloadExporter.doExport()</methodname>
        method and they have the same meaning. The only difference is that the 
        <varname>out</varname> stream can be linked to a file and not just to the
        immediate download.
        </para>
      </listitem>
      
      <listitem>
        <para>
        Optionally, implement the <methodname>begin()</methodname>,
        <methodname>end()</methodname> and <methodname>getSuccessMessage()</methodname>
        methods. Theese methods do nothing by default. 
        </para>
      </listitem>
      </itemizedlist>
      
      <para>
        The call sequence for plug-ins extending <classname>AbstractExporterPlugin</classname>
        is:
      </para>
      
      <orderedlist>
      <listitem>
        <para>
        Call <methodname>begin()</methodname>.
        </para>
      </listitem>
      <listitem>
        <para>
        Call <methodname>performExport()</methodname>.
        </para>
      </listitem>
      <listitem>
        <para>
        Call <methodname>end()</methodname>.
        </para>
      </listitem>
      <listitem>
        <para>
        Call <methodname>getSuccessMessage()</methodname> if running as a regular
        job. This method is never called when doing an immediate download since there
        is no place to show the message.
        </para>
      </listitem>
      </orderedlist>
      
    </sect2>
    
  </sect1>
  
  <sect1 id="plugin_developer.analyse">
    <title>Analysis plug-ins</title>
    <para>
      A plug-in becomes an analysis plug-in simply by returning
      <constant>Plugin.MainType.ANALYSIS</constant> from the
      <methodname>Plugin.getMainType()</methodname> method. The information returned from
      <methodname>InteractivePlugin.getGuiContexts()</methodname>
      must include: [<constant>Item.BIOASSAYSET</constant>, <constant>Type.ITEM</constant>] since 
      this is the only place where the web client looks for analysis plug-ins.
    </para>
    
<programlisting>private static final Set&lt;GuiContext&gt; guiContexts = 
   Collections.singleton(new GuiContext(Item.BIOASSAYSET, GuiContext.Type.ITEM));

public Set&lt;GuiContext&gt; getGuiContexts()
{
   return guiContexts;
}</programlisting>

      <para>
        More documentation is available in the old format.
        See <ulink url="http://base.thep.lu.se/chrome/site/doc/development/plugins/analysis/index.html"
          >http://base.thep.lu.se/chrome/site/doc/development/plugins/analysis/index.html</ulink>
      </para>


  </sect1>
  
  <sect1 id="plugin_developer.other">
    <title>Other plug-ins</title>
    <para></para>
    
    <sect2 id="plugin_developer.other.authentication">
      <title>Authentication plug-ins</title>
      
      <para>
        BASE provides a plug-in mechanism for authenticating users 
        (validating the username and password) when they are logging in.
        This plug-in mechanism is not the same as the regular plug-in API.
        That is, you do not have worry about user interaction or implementing the 
        <interfacename>Plugin</interfacename> interface.
      </para>
      
      <sect3 id="plugin_developer.other.authentication.internal_external">
        <title>Internal vs. external authentation</title>
      
        <para>
          BASE can authenticate users in two ways. Either it uses the internal 
          authentiction or the external authentication. With internal 
          authentication BASE stores logins and passwords in it's own database. 
          With external authentication this is handled by some external 
          application. Even with external authentication it is possible to 
          let BASE cache the logins/passwords. This makes it possible to login to 
          BASE if the external authentication server is down.
        </para>
        
        <note>
          <para>
          An external authentication server can only be used to grant or deny 
          a user access to BASE. It cannot be used to give a user permissions,
          or put a user into groups or different roles inside BASE.
          </para>
        </note>

        <para>
          The external authentication service is only used when a user logs in. 
          Now, one or more of several things can happen:
          
          <itemizedlist>
          <listitem>
            <para>
              The ROOT user is logging on. Internal authentication is always 
              used for the root user and the authenticator plug-in is never 
              used.
            </para>
          </listitem>

          <listitem>
            <para>
              The login is correct and the user is already known to BASE. 
              If the plug-in supports extra information (name, email, phone, etc.)
              and the <property>auth.synchronize</property> setting
              is <constant>TRUE</constant> the extra information is copied to 
              the BASE server.
            </para>
          </listitem>
          
          <listitem>
            <para>
              The login is correct, but the user is not known to BASE. This happens
              the first time a user logs in. BASE will create
              a new user account. If the driver supports extra information, it 
              is copied to the BASE server (even if <property>auth.synchronize</property> 
              is not set). The new user account will get the default quota 
              and be added to the all roles and groups which has been
              marked as <emphasis>default</emphasis>.
              
              <note>
              <para>
                Prior to BASE 2.4 it was hardcoded to add the new user to the
                <emphasis>Users</emphasis> role only.
              </para>
              </note>
            </para>
          </listitem>

          <listitem>
            <para>
              If password caching is enabled, the password is copied to BASE. 
              If an expiration timeout has been set, an expiration date
              will be calculated and set on the user account. The expiration
              date is only checked when the external authentication server is 
              down.
            </para>
          </listitem>

          <listitem>
            <para>
              The authentication server says that the login is invalid or 
              the password is incorrect. The user will not be logged in. 
              If a user account with the specified login already exists in 
              BASE, it will be disabled.
            </para>
          </listitem>
          
          <listitem>
            <para>
              The authentication driver says that something else is wrong. 
              If password caching is enabled, internal authentication will be 
              used. Otherwise the user will not be logged in. An already 
              existing account is not modified or disabled.
            </para>
          </listitem>
          </itemizedlist>
          
          <note>
            <para>
            The <guilabel>Encrypt password</guilabel> option that is
            available on the login page does not work with external 
            authentication. The simple reason is that the password is
            encrypted with a one-way algorithm making it impossible to
            call <methodname>Authenticator.authenticate()</methodname>.
            </para>
          </note>
          
        </para>
      </sect3>
      
      <sect3 id="plugin_developer.other.authentication.authenticator">
        <title>The Authenticator interface</title>
        
        <para>
          To be able to use external authentication you must create a class 
          that implements the 
          <interfacename>net.sf.based.core.authentication.Authenticator</interfacename> 
          interface. Specify the name of the class in the <property>auth.driver</property> 
          setting in <filename>base.config</filename> and 
          it's initialisation parameters in the <property>auth.init</property> setting.
        </para>
        
        <para>
          Your class must have a public no-argument constructor. The BASE 
          application will create only one instance of the class for lifetime 
          of the BASE server. It must be thread-safe since it may be invoked by 
          multiple threads at the same time. Here are the methods that you must 
          implement
        </para>
        
        <variablelist>
        <varlistentry>
          <term>
            <methodsynopsis language="java">
              <modifier>public</modifier>
              <void/>
              <methodname>init</methodname>
              <methodparam>
                <type>String</type>
                <parameter>settings</parameter>
              </methodparam>
              <exceptionname>AuthenticationException</exceptionname>
            </methodsynopsis>
          </term>
          <listitem>
            <para>
            This method is called just after the object has been created with it's argument 
            taken from the <property>auth.init</property> setting in your <filename>base.config</filename> 
            file. This method is only called once for an instance of the object. The syntax and meaning of 
            the parameter is driver-dependent and should be documented by the plug-in. 
            It is irrelevant for the BASE core.
            </para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term>
            <methodsynopsis language="java">
              <modifier>public</modifier>
              <type>boolean</type>
              <methodname>supportsExtraInformation</methodname>
            </methodsynopsis>
          </term>
          <listitem>
            <para>
            This method should simply return <constant>TRUE</constant> or <constant>FALSE</constant> 
            depending on if the plug-in supports extra user information or not. The only required 
            information about a user is a unique ID and the login. Extra information includes 
            name, address, phone, email, etc.
            </para>
          </listitem>       
        </varlistentry>

        <varlistentry>
          <term>
            <methodsynopsis language="java">
              <modifier>public</modifier>
              <type>AuthenticationInformation</type>
              <methodname>authenticate</methodname>
              <methodparam>
                <type>String</type>
                <parameter>login</parameter>
              </methodparam>
              <methodparam>
                <type>String</type>
                <parameter>password</parameter>
              </methodparam>
              <exceptionname>UnknownLoginException</exceptionname>
              <exceptionname>InvalidPasswordException</exceptionname>
              <exceptionname>AuthenticationException</exceptionname>
            </methodsynopsis>
          </term>
          <listitem>
            <para>
            Try to authenticate a login/password combination. The plug-in should return 
            an <classname>AuthenticationInformation</classname> object if the 
            authentication is successful or throw an exception if not. 
            
            There are three exceptions to choose from:
            
            <itemizedlist>
            <listitem>
              <para>
              <exceptionname>UnknownLoginException</exceptionname>:
              This exception should be thrown if the login is not know to the 
              external authentication system.
              </para>
            </listitem>

            <listitem>
              <para>
              <exceptionname>InvalidPasswordException</exceptionname>:
              This exception should be thrown if the login is known but the 
              password is invalid. In case it is considered a security issue 
              to reveal that a login exists, the plugin may throw an 
              <exceptionname>UnknowLoginException</exceptionname> instead.
              </para>
            </listitem>
            
            <listitem>
              <para>
              <exceptionname>AuthenticationException</exceptionname>:
              In case there is another problem, such as the authentication service 
              beeing down. This exception triggers the use of cached passwords
              if caching has been enabled.
              </para>
            </listitem>
            </itemizedlist>
            </para>
          </listitem>       
        </varlistentry>
        </variablelist> 
      </sect3>
      
      <sect3 id="plugin_developer.other.authentication.settings">
        <title>Configuration settings</title>
      
        <para>
          The configuration settings for the authentication driver are located 
          in the <filename>base.config</filename> file. 
          Here is an overview of the settings. For more information read 
          <xref linkend="appendix.base.config.authentication" />.
        </para>
        
        <variablelist>
        <varlistentry>
          <term><property>auth.driver</property></term>
          <listitem>
            <para>
            The class name of the authentication plug-in.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><property>auth.init</property></term>
          <listitem>
            <para>
            Initialisation parameters sent to the plug-in when calling the 
            <methodname>Authenticator.init()</methodname> method. 
            </para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><property>auth.synchronize</property></term>
          <listitem>
            <para>
            If extra user information is synchronized at login time or not. 
            This setting is ignored if the driver does not support extra information. 
            </para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><property>auth.cachepasswords</property></term>
          <listitem>
            <para>
              If passwords should be cached by BASE or not. If the passwords are 
              cached a user may login to BASE even if the external authentication 
              server is down.
            </para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><property>auth.daystocache</property></term>
          <listitem>
            <para>
              How many days to cache the passwords if caching has been enabled. 
              A value of 0 caches the passwords for ever.     
            </para>
          </listitem>
        </varlistentry>
        </variablelist>
      </sect3>
      
    </sect2>
    
    <sect2 id="plugin_developer.other.secondary">
      <title>Secondary file storage plugins</title>
      <para>
        This documentation is only available in the old format.
        See <ulink url="http://base.thep.lu.se/chrome/site/doc/development/plugins/storage/index.html"
          >http://base.thep.lu.se/chrome/site/doc/development/plugins/storage/index.html</ulink>
      </para>
    </sect2>
    
    <sect2 id="plugin_developer.other.unpacker">
      <title>File unpacker plug-ins</title>
      <para>
        The BASE web client has integrated support for unpacking of 
        compressed files. See <xref linkend="file_system.handling.upload" />.
        Behind the scenes, this support is provided by plug-ins. The standard 
        BASE distribution comes with support for ZIP files 
        (<classname>net.sf.basedb.plugins.ZipFileUnpacker</classname>).
      </para>
      <para>
        To add support for additional compressed formats you have to create a plug-in that
        implements the <interfacename>net.sf.basedb.util.zip.FileUnpacker</interfacename>
        interface. The best way to do this is to extend the 
        <classname>net.sf.basedb.util.zip.AbstractFileUnpacker</classname> which 
        implements all methods in the <interfacename>Plugin</interfacename>
        and <interfacename>InteractivePlugin</interfacename>
        interfaces except <methodname>Plugin.getAbout()</methodname>. This leaves
        you with the actual unpacking of the files as the only thing to implement.
      </para>
      
      <note>
        <title>No support for configurations</title>
        The integrated upload in the web interface only works with plug-ins that
        does not require a configuration to run.
      </note>
      
      <variablelist>
        <title>Methods in the <interfacename>FileUnpacker</interfacename> interface</title>
        <varlistentry>
          <term>
            <methodsynopsis language="java">
              <modifier>public</modifier>
              <type>String</type>
              <methodname>getFormatName</methodname>
            </methodsynopsis>
          </term>
          <listitem>
            <para>
            Return a short string naming the file format. For example:
            <constant>ZIP files</constant> or <constant>TAR files</constant>.
            </para>
          </listitem>
        </varlistentry>
            
        <varlistentry>
          <term>
            <methodsynopsis language="java">
              <modifier>public</modifier>
              <type>Set&lt;String&gt;</type>
              <methodname>getExtensions</methodname>
            </methodsynopsis>
          </term>
          <listitem>
            <para>
            Return a set of strings with the file extensions that
            are most commonly used with the compressed file format.
            For example: <constant>[zip, jar]</constant>. Do not include
            the dot in the extensions. The web client and the 
            <methodname>AbstractFlatFileUnpacker.isInContext()</methodname> method
            will use this information to automatically guess which plug-in to 
            use for unpacking the files.
            </para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term>
            <methodsynopsis language="java">
              <modifier>public</modifier>
              <type>Set&lt;String&gt;</type>
              <methodname>getMimeTypes</methodname>
            </methodsynopsis>
          </term>
          <listitem>
            <para>
            Return a set of string with the MIME types that commonly used with 
            the compressed file format. For example: 
            <constant>[application/zip, application/java-archive]</constant>. 
            This information is used by the 
            <methodname>AbstractFlatFileUnpacker.isInContext()</methodname> 
            method to automatically guess which plug-in to use for unpacking 
            the files.
            </para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term>
            <methodsynopsis language="java">
              <modifier>public</modifier>
              <type>int</type>
              <methodname>unpack</methodname>
              <methodparam>
                <type>DbControl</type>
                <parameter>dc</parameter>
              </methodparam>
              <methodparam>
                <type>Directory</type>
                <parameter>dir</parameter>
              </methodparam>
              <methodparam>
                <type>InputStream</type>
                <parameter>in</parameter>
              </methodparam>
              <methodparam>
                <type>boolean</type>
                <parameter>overwrite</parameter>
              </methodparam>
              <methodparam>
                <type>AbsoluteProgressReporter</type>
                <parameter>progress</parameter>
              </methodparam>
              <exceptionname>IOException</exceptionname>
              <exceptionname>BaseException</exceptionname>
            </methodsynopsis>
          </term>
          <listitem>
            <para>
            Unpack the files and store them in the BASE file system. 
            
            <itemizedlist>
            <listitem>
              <para>
              Do not <methodname>close()</methodname> or 
              <methodname>commit()</methodname> the 
              <classname>DbControl</classname> passed to this method.
              This is done automatically by the 
              <classname>AbstractFileUnpacker</classname> or by the web client.
              </para>
            </listitem>
            
            <listitem>
              <para>
              The <varname>dir</varname> parameter is the root directory where
              the unpacked files should be placed. If the compressed file
              contains subdirectory the plug-in must create those subdirectories
              unless they already exists.
              </para>
            </listitem>
            
            <listitem>
              <para>
              If the <varname>overwrite</varname> parameter is 
              <constant>FALSE</constant> no existing file should be overwritten
              unless the file is <systemitem>OFFLINE</systemitem>.
              </para>
            </listitem>
            
            <listitem>
              <para>
              The <varname>in</varname> parameter is the stream
              containing the compressed data. The stream may come
              directly from the web upload or from an existing
              file in the BASE file system.
              </para>
            </listitem>
            
            <listitem>
              <para>
              The <varname>progress</varname> parameter, if not 
              <constant>null</constant>, should be used to reporter the
              progress back to the calling code. The plug-in should count
              the number of bytes read from the <varname>in</varname>
              stream.
              </para>
            </listitem>
            </itemizedlist>
            
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
      
      <para>
        When the compressed file is uncompressed during the file upload
        from the web interface, the call sequence to the plug-in is slightly
        altered from the standard call sequence described in 
        <xref linkend="plugin_developer.api.callsequence.execute" />.
        
        <itemizedlist>
        <listitem>
          <para>
          After the plug-in instance has been created, the 
          <methodname>Plugin.init()</methodname> method is called with <constant>null</constant>
          values for both the <varname>configuration</varname> and <varname>job</varname>
          parameters.
          </para>
        </listitem>
        
        <listitem>
          <para>
          Then, the <methodname>unpack()</methodname> method is called. The
          <methodname>Plugin.run()</methodname> method is never called in this case.
          The <methodname>Plugin.done()</methodname> method is also never called.
          </para>
        </listitem>
        
        </itemizedlist>
        
      </para>
      
    </sect2>
  </sect1>
  
  <sect1 id="plugin_developer.example">
    <title>Example plug-ins (with download)</title>
    <para>
      <para>
        This documentation is only available in the old format.
        See <ulink url="http://base.thep.lu.se/chrome/site/doc/development/index.html#plugins"
          >http://base.thep.lu.se/chrome/site/doc/development/index.html#plugins</ulink>
      </para>
    </para>
  </sect1>
</chapter>