Changeset 5633


Ignore:
Timestamp:
May 18, 2011, 2:46:35 PM (12 years ago)
Author:
Nicklas Nordborg
Message:

References #1590: Documentation cleanup

Checked and changed the following chapters in Part IV: Developer documentation:

  • Developer overview of BASE
  • Plug-in developer (sections 1-5)
Location:
trunk
Files:
3 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/src/docbook/developerdoc/base_overview.xml

    r4902 r5633  
    316316      <title>The Controller API</title>
    317317      <para>
    318         The Controller API is the very heart of the Base 2 system. This part
     318        The Controller API is the very heart of the BASE system. This part
    319319        of the core is used for boring but essential details, such as
    320320        user authentication, database connection management, transaction
    … …  
    385385      <para>
    386386        Client applications are application that use the BASE Core API. The current web
    387         application is built with Java Server Pages (JSP). It is supported by several
    388         application servers but we have only tested it with Tomcat. Other client
    389         applications are the external job agents that executes plug-ins on separate
    390         servers, and the migration tool that migrates data from a BASE 1.2.x installation
    391         to BASE 2.
     387        application is built with Java Server Pages (JSP). JSP is supported by several
     388        application servers but we have only tested it with Tomcat. Another client
     389        application is the external job agents that executes plug-ins on separate
     390        servers.
    392391      </para>
    393392     

  • trunk/doc/src/docbook/developerdoc/plugin_developer.xml

    r5407 r5633  
    4848          <filename class="directory"><replaceable>pluginname</replaceable>/</filename>
    4949          directory in the listing below. You should also create some subdirectories:
    50          
    51           <literallayout>
     50        </para>
     51       
     52        <literallayout>
    5253<filename class="directory"><replaceable>pluginname</replaceable>/</filename>
    5354<filename class="directory"><replaceable>pluginname</replaceable>/bin/</filename>
    … …  
    5556<filename class="directory"><replaceable>pluginname</replaceable>/src/<replaceable>org/company</replaceable>/</filename>
    5657<filename class="directory"><replaceable>pluginname</replaceable>/META-INF/</filename>
    57           </literallayout>
    58           The
    59           <filename class="directory">bin/</filename>
     58<filename class="directory"><replaceable>pluginname</replaceable>/META-INF/lib/</filename>
     59        </literallayout>
     60        <para>
     61          The <filename class="directory">bin/</filename>
    6062          directory is empty to start with. It will contain the compiled code.
    6163          In the <filename class="directory">lib/</filename>
    62           directory you should put <filename>BASE2Core.jar</filename>
    63           and other library files your plug-in depends on. The
    64           <filename class="directory">src/</filename>
     64          directory you should put <filename>base-core-3.x.x.jar</filename>
     65          and other library files that is needed when compiling the source code,
     66          but doesn't have to be distributed with your plug-in (since they are already
     67          included in the BASE distribution). In the <filename class="directory">META-INF/lib/</filename>
     68          directory you should put other library files that are needed both when compiling
     69          and when distributing your plug-in.
     70        </para>
     71        <para>
     72          The <filename class="directory">src/</filename>
    6573          directory contains your source code. In this directory you should create
    6674          subdirectories corresponding to the package name of your plug-in
    … …  
    6876          >http://en.wikipedia.org/wiki/Java_package</ulink> for information
    6977          about conventions for naming packages. The
    70           <filename class="directory">META-INF</filename> directory contains metadata
    71           about the plug-in and are needed for best functionality.
     78          <filename class="directory">META-INF/</filename> directory contains metadata
     79          about the plug-in and are needed for easy installation. Typically you'll
     80          always need <filename>MANIFEST.MF</filename> and <filename>extensions.xml</filename>
     81          but, depending on what you are developing, other files are also needed.
    7282        </para>
    7383      </sect3>
    … …  
    8292        <example id="plugin_developer.organize.build.file">
    8393          <title>A simple build file</title>
    84 <programlisting language="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
    85 &lt;project
     94          <programlisting language="xml">
     95<![CDATA[
     96<?xml version="1.0" encoding="UTF-8"?>
     97<project
    8698   name="MyPlugin"
    8799   default="build.plugin"
    88100   basedir="."
    89    &gt;
    90 
    91    &lt;!-- variables used --&gt;
    92    &lt;property name="plugin.name" value="MyPlugin" /&gt;
    93    &lt;property name="src" value="src" /&gt;
    94    &lt;property name="bin" value="bin" /&gt;
    95 
    96    &lt;!-- set up classpath for compiling --&gt;
    97    &lt;path id="classpath"&gt;
    98       &lt;fileset dir="lib"&gt;
    99          &lt;include name="**/*.jar"/&gt;
    100       &lt;/fileset&gt;
    101    &lt;/path&gt;
    102 
    103    
    104    &lt;!-- main target --&gt;
    105    &lt;target
     101   >
     102
     103   <!-- variables used -->
     104   <property name="plugin.name" value="MyPlugin" />
     105   <property name="src" value="src" />
     106   <property name="bin" value="bin" />
     107
     108   <!-- set up classpath for compiling -->
     109   <path id="classpath">
     110      <fileset dir="lib">
     111         <include name="**/*.jar"/>
     112      </fileset>
     113      <fileset dir="META-INF/lib">
     114         <include name="**/*.jar"/>
     115      </fileset>
     116   </path>
     117
     118   <!-- main target -->
     119   <target
    106120      name="build.plugin" 
    107121      description="Compiles the plug-in and put in jar"
    108       &gt;
    109       &lt;javac
    110          encoding="ISO-8859-1"
     122      >
     123      <javac
     124         encoding="UTF-8"
    111125         srcdir="${src}"
    112126         destdir="${bin}"
    113          classpathref="classpath"&gt;
    114       &lt;/javac&gt;
    115       &lt;jar
     127         classpathref="classpath">
     128      </javac>
     129      <jar
    116130         jarfile="${plugin.name}.jar"
    117          basedir="bin"
    118131         manifest="META-INF/MANIFEST.MF"
    119          &gt;
    120          &lt;!--Include this to add required files for auto registration wizard--&gt;
    121          &lt;metainf file="META-INF/base-plugins.xml"&gt;&lt;/metainf&gt;
    122          &lt;metainf file="META-INF/base-configurations.xml"&gt;&lt;/metainf&gt;       
    123       &lt;/jar&gt;
    124 
    125     &lt;/target&gt;
    126 &lt;/project&gt; </programlisting>
     132         >
     133         
     134         <!-- compiled source code -->
     135         <fileset dir="${bin}" />
     136         
     137         <!-- metadata and extra JAR files -->
     138         <fileset dir="." includes="META-INF/**" />
     139      </jar>
     140    </target>
     141</project>
     142]]>
     143</programlisting>
    127144        </example>
    128145        <para>
    129           If your plug-in depends on other JAR files than the
    130           <filename>BASE2Core.jar</filename> you must create a file called
     146          If your plug-in depends JAR files not included with the standard
     147          BASE installation, you must create a file called
    131148          <filename>MANIFEST.MF</filename> in the project <filename>META-INF</filename>
    132149          directory. List the other JAR files as in the following example.
    … …  
    135152          attribute of the <sgmltag class="starttag">jar</sgmltag> tag.
    136153<programlisting>Manifest-Version: 1.0
    137 Class-Path: OtherJar.jar ASecondJar.jar</programlisting>
     154Class-Path: lib/OtherJar.jar lib/ASecondJar.jar</programlisting>
    138155        See also <xref linkend="plugin_developer.classload" /> for more information
    139156        regarding class loading when a plug-in depends on a external JAR files.
    140157        </para>
    141         <para>
    142           If your plug-in should support registration with the auto-installation
    143           wizard it is a good idea to add the <sgmltag class="element">metainf</sgmltag>
    144           tags. This will add the two files <filename>META-INF/base-plugins.xml</filename>
    145           and <filename>META-INF/base-configurations.xml</filename> to the
    146           <filename>META-INF</filename> directory in the JAR file. The two files
    147           contains information about your plug-in and BASE can automatically
    148           find and extract information from those. See
     158       
     159        <para>
     160          To make installation of your plug-in easier it is a good idea to include
     161          the <filename>META-INF/extensions.xml</filename>. This file should
     162          include information about your plug-in, such as the name, author, version,
     163          and the main Java class for the plug-in. See
    149164          <xref linkend="plugin_developer.organize.autoinstallcompatible" />
    150165          for get more information about this feature.
    … …  
    162177        </para>
    163178        <para>
    164           To install the plug-in copy the JAR file to the server including the dependent JAR
    165           files (if any). Place all files together in the same directory. For more
    166           information read
     179          To install the plug-in copy the JAR file to the server's plug-in directory.
     180          For more information about the actual installation read
    167181          <xref linkend="plugins.installation" />.
    168182        </para>
    … …  
    170184    </sect2>
    171185   
    172     <sect2 id="plugin_developer.organize.eclipse">
    173       <title>With Eclipse</title>
    174       <para>
    175         If somebody is willing to add information to this chapter please send us a note or
    176         some written text to put here. Otherwise, this chapter will be removed.
    177       </para>
    178     </sect2>
    179 
    180186    <sect2 id="plugin_developer.organize.autoinstallcompatible">
    181187      <title>Make the plug-in compatible with the auto-installation wizard</title>
    … …  
    190196        The auto-install feature requires that a plug-in provides some information
    191197        about itself. The wizard looks in all JAR file for the file
    192         <filename>META-INF/base-plugins.xml</filename>. This file contains
     198        <filename>META-INF/extensions.xml</filename>. This file contains
    193199        some information about the plug-in(s). Here is an example:
    194200      </para>
    195201 
    196202      <programlisting language="xml">
    197 &lt;?xml version="1.0" encoding="UTF-8"?&gt;
    198 &lt;!DOCTYPE plugins SYSTEM "base-plugins.dtd" &gt;
    199 &lt;plugins jarname="jarfile.jar"&gt;
    200   &lt;pluginclass classname="se.lu.thep.PluginClass"&gt;
    201     &lt;minbaseversion&gt;2.4&lt;/minbaseversion&gt;
    202     &lt;hasconfigurations/&gt;
    203     &lt;/pluginclass&gt;
    204     .
    205     .
    206     .
    207 &lt;/plugins&gt;
     203<![CDATA[
     204<?xml version="1.0" encoding="UTF-8" ?>
     205<extensions xmlns="http://base.thep.lu.se/extensions.xsd">
     206  <!-- information about the complete package (which may contain many plug-in definitions) -->
     207  <about>
     208    <name>My plug-in package</name>
     209    <description>
     210      This package contains some very useful plug-ins...
     211    </description>
     212    <version>1.3</version>
     213    <min-base-version>3.0</min-base-version>
     214    <copyright>You</copyright>
     215    <url>http://www.company.org/with/more/info/about/plugins</url>
     216    <email>some.email.address@company.org</email>
     217  </about>
     218 
     219  <!-- Defines a single plug-in (can be repeated multiple times) -->
     220  <plugin-definition id="PluginX">
     221    <about>
     222      <name>Plug-in X</name>
     223      <description>
     224        Calculates the X transform of....
     225      </description>
     226    </about>
     227    <plugin-class>org.company.PluginClassX</plugin-class>
     228  </plugin-definition>
     229</extensions>
     230]]>
    208231</programlisting>
    209232      <para>
    210         The first two lines should be the same in all <filename>base-plugins.xml</filename> files.
     233        The first two lines should be the same in all <filename>extensions.xml</filename> files.
    211234        The rest of the tags are described in following list.
    212235        <variablelist>
    213236          <varlistentry>
    214             <term><sgmltag class="starttag">plugins</sgmltag></term>
     237            <term><sgmltag class="starttag">about</sgmltag></term>
    215238            <listitem>
    216239              <para>
    217                 This is the root element in the XML-file and must have the
    218                 attribute
    219                 <sgmltag class="attribute">jarname</sgmltag>
    220                 set. The value must be the same as name of the JAR file
    221                 the plug-in is located in or the auto-installation wizard
    222                 will fail with an error.
     240                The first <sgmltag class="starttag">about</sgmltag> tag is information
     241                about the package as a whole. We recommend putting in as much information
     242                as possible here. Supported sub-tags are:
     243               
     244                <sgmltag class="starttag">name</sgmltag>, <sgmltag class="starttag">description</sgmltag>,
     245                <sgmltag class="starttag">version</sgmltag>, <sgmltag class="starttag">min-base-version</sgmltag>,
     246                <sgmltag class="starttag">max-base-version</sgmltag>, <sgmltag class="starttag">contact</sgmltag>,
     247                <sgmltag class="starttag">email</sgmltag>, <sgmltag class="starttag">url</sgmltag> and
     248                <sgmltag class="starttag">copyright</sgmltag>
     249              </para>
     250              <para>
     251                Each plug-in that is defined in this file may have it's <sgmltag class="starttag">about</sgmltag>
     252                tag which override the global information. Typically, you'll only overide the name and
     253                description tags.
     254              </para>
     255            </listitem>
     256          </varlistentry>
     257          <varlistentry>
     258            <term><sgmltag class="starttag">plugin-definition</sgmltag></term>
     259            <listitem>
     260              <para>
     261                This is the main element for defining a plug-in. It can override the global
     262                <sgmltag class="starttag">about</sgmltag> information. We recommend that at
     263                least a <sgmltag class="starttag">name</sgmltag> and <sgmltag class="starttag">description</sgmltag>
     264                is provided.               
    223265              </para>
    224266            </listitem>
    … …  
    226268          <varlistentry>
    227269            <term>
    228               <sgmltag class="starttag">pluginclass</sgmltag>
     270              <sgmltag class="starttag">plugin-class</sgmltag>
    229271            </term>
    230272            <listitem>
    231273              <para>
    232                 This tag defines information about a plug-in in the JAR file. The
    233                 <sgmltag class="attribute">classname</sgmltag>
    234                 attribute needs to have the full classname of the plug-in's main
    235                 class. There can be one or several of this element inside the
    236                 <sgmltag class="starttag">plugins</sgmltag>
    237                 tag, which means that there should be one element for
    238                 each plug-in in the JAR file.
     274                The value is the fill class name of the plug-in's main
     275                class.
    239276              </para>
    240277            </listitem>
    … …  
    242279          <varlistentry>
    243280            <term>
    244               <sgmltag class="starttag">minbaseversion</sgmltag>
     281              <sgmltag class="starttag">min-base-version</sgmltag>
     282              <sgmltag class="starttag">max-base-version</sgmltag>
    245283            </term>
    246284            <listitem>
    247285              <para>
    248                 A required child element in
    249                 <sgmltag class="starttag">pluginclass</sgmltag>.
    250                 This defines from which version of BASE the plug-in can be used.
    251                 The plug-in will not be included in auto installer if the
    252                 BASE-version is lower then the value of this tag. The format of the
    253                 value in this tag should be (numeric)
    254                 <emphasis>majorversion</emphasis>.<emphasis>minorversion</emphasis>.
    255                 It is not possible to check the bugfix or revision numbers.
    256               </para>
    257             </listitem>
    258           </varlistentry>
    259           <varlistentry>
    260             <term>
    261               <sgmltag class="starttag">hasconfigurations</sgmltag>             
    262             </term>
    263             <listitem>
    264               <para>
    265                 A required child element in
    266                 <sgmltag class="starttag">pluginclass</sgmltag>.
    267                 This should tell if there are plug-in configurations
    268                 shipped with the plug-in. Setting the value to
    269                 <emphasis>yes</emphasis>
    270                 will indicate that there are available configurations in the
    271                 JAR file. This can be left as an empty tag if no
    272                 configurations are available for import.
    273               </para>
    274               <para>
    275                 Configurations shipped with a JAR file should be exported with the
    276                 plug-in configuration exporter in BASE. The exported file must be
    277                 given the name
    278                 <filename>base-configurations.xml</filename>
    279                 and be placed in
    280                 <filename class="directory">META-INF/</filename>.
     286                Optional sub-tags in the <sgmltag class="starttag">about</sgmltag> section.
     287                Values are two- or three-digits separated by a dot. For example,
     288                3.0.0 and 3.1. If values are given the plug-in will only be installed
     289                if the server's BASE version is within the bounds.
    281290              </para>
    282291            </listitem>
    … …  
    284293        </variablelist>
    285294      </para>
     295     
     296      <sect3 id="plugin_developer.organize.autoinstallcompatible.configurations">
     297        <title>Installing plug-in configurations</title>
     298     
     299        <para>
     300          The installation wizard has support for installing plug-in configurations.
     301          If some of your plug-ins has support for different configurations that you want
     302          to ship as part of the package, use the "Plug-in configuration exporter" in BASE
     303          and include the generated file in <filename>META-INF/plugin-configurations.xml</filename>
     304          inside your JAR file.
     305        </para>
     306     
     307      </sect3>
    286308    </sect2>
    287309   
    … …  
    297319      <title>The main plug-in interfaces</title>
    298320      <para>
    299         The Base2 core defines two interfaces and one
     321        The BASE API defines two interfaces and one
    300322        abstract class that are vital for implementing plug-ins:
    301323        <itemizedlist spacing="compact">
    … …  
    346368        </para>
    347369        <variablelist>
    348           <varlistentry>
    349             <term>
    350               <methodsynopsis language="java">
    351                 <modifier>public</modifier>
    352                 <type>About</type>
    353                 <methodname>getAbout</methodname>
    354                 <void />
    355               </methodsynopsis>
    356             </term>
    357             <listitem>
    358               <para>
    359                 Return information about the plug-in, i.e. the name, version, and a short
    360                 description about what the plug-in does. The
    361                 <classname docapi="net.sf.basedb.core.plugin">About</classname>
    362                 object also has fields for naming the author and various other contact
    363                 information. The returned information is copied by the core at
    364                 installation time into the database. The only required information is
    365                 the name of the plug-in. All other fields may have null values.
    366               </para>
    367               <example id="net.sf.basedb.core.plugin.Plugin.getAbout">
    368                 <title>A typical implementation stores this information in a static field</title>
    369 <programlisting language="java">
    370 private static final About about = new AboutImpl
    371 (
    372    "Spot images creator",
    373    "Converts a full-size scanned image into smaller preview jpg " +
    374      "images for each individual spot.",
    375    "2.0",
    376    "2006, Department of Theoretical Physics, Lund University",
    377    null,
    378    "base@thep.lu.se",
    379    "http://base.thep.lu.se"
    380 );
    381  
    382 public About getAbout()
    383 {
    384    return about;
    385 }</programlisting>
    386               </example>
    387             </listitem>
    388           </varlistentry>
    389370          <varlistentry>
    390371            <term>
    … …  
    553534                to do some initialization this is the place to do it. A typical
    554535                implementation however only stores the passed parameters in instance
    555                 variables for later use. Since it is not possible what the user is going to
     536                variables for later use. Since it is not possible to know what the user is going to
    556537                do at this stage, we recommend lazy initialisation of all other resources.
    557538              </para>
    … …  
    650631                interface. This parameter can be null, but if it is not we recommend all
    651632                plug-ins to use it. However, it should be used sparingly, since each call
    652                 to set the progress results in a database update. If the execution
     633                to set the progress may result in a database update. If the execution
    653634                involves several thousands of items it is a bad idea to update the
    654635                progress after processing each one of them. A good starting point is to
    … …  
    915896                message should be used.
    916897              </para>
    917              
    918               <note>
    919                 <para>
    920                 The contract of this method was changed in in BASE 2.4
    921                 to allow warning and error level message. Prior to BASE
    922                 2.4 all messages were treated as error message. We recommend
    923                 that existing plug-ins are updated to throw exception to indicate
    924                 error-level messages since the default is to not show
    925                 warning messages to users.
    926                 </para>
    927               </note>
    928898             
    929899              <para>
    … …  
    13621332         
    13631333         // We are happy and done
     1334         File file = (File)job.getValue("file");
     1335         response.setSuggestedJobName("Import data from file " + file.getName());
    13641336         response.setDone("Job configuration complete", Job.ExecutionTime.SHORT);
    1365          // TODO - check file size to make a better estimate of execution time
    13661337      }
    13671338   }
    … …  
    14291400                state between the two phases.
    14301401              </para>
    1431              
    14321402            </listitem>
    14331403          </varlistentry>
    … …  
    14661436          <para>
    14671437          Calls are made to <methodname>Plugin.getMainType()</methodname>,
    1468           <methodname>Plugin.supportsConfigurations()</methodname>,
    1469           <methodname>Plugin.requiresConfiguration()</methodname> and
    1470           <methodname>Plugin.getAbout()</methodname> to find out information
     1438          <methodname>Plugin.supportsConfigurations()</methodname> and
     1439          <methodname>Plugin.requiresConfiguration()</methodname> to find out information
    14711440          about the plug-in. This is the only time these methods are called.
    14721441          The information that is returned by them are copied and stored in
    … …  
    17561725          method to report errors or the <methodname>Response.setContinue()</methodname>
    17571726          method to respond to a shutdown signal and tell the core to resume the
    1758           job once the system is up and running again.
     1727          job once the system is up and running again. The <methodname>Response.setContinue()</methodname>
     1728          can also be used when the system is not shutting down. The job will then be
     1729          put back into the job queue and executed again later.
    17591730          </para>
    17601731        </listitem>
    … …  
    17861757        <para>
    17871758          When setting the JSP page you can either specify an absolute path
    1788           of only the filename of the JSP file. If only the filename is specified,
     1759          or only the filename of the JSP file. If only the filename is specified,
    17891760          the JSP file is expected to be located in a special location, generated
    17901761          from the package name of your plug-in. If the plug-in is located in the package
    … …  
    18451816          </simpara>
    18461817<programlisting language="xml">
    1847 &lt;form action="index.jsp" method="post"&gt;
    1848 &lt;input type="hidden" name="ID" value="&lt;%=ID%&gt;"&gt;
    1849 &lt;input type="hidden" name="requestId" value="&lt;%=request.getParameter("requestId")%&gt;"&gt;
    1850 &lt;input type="hidden" name="cmd" value="SetParameters"&gt;
     1818<![CDATA[
     1819<form action="index.jsp" method="post">
     1820<input type="hidden" name="ID" value="<%=ID%>">
     1821<input type="hidden" name="requestId" value="<%=request.getParameter("requestId")%>">
     1822<input type="hidden" name="cmd" value="SetParameters">
    18511823...
    1852 &lt;/form&gt;
     1824</form>
     1825]]>
    18531826</programlisting>
    18541827          <simpara>
    … …  
    18581831            sequence. It is optional, but we recommend that you use it
    18591832            since it protects your plug-in from getting mixed up with
    1860             other plug-in configuration wizards. The <varname>cmd</varname>
     1833            other plug-in configuration wizards. The <varname>cmd=SetParameters</varname>
    18611834            tells BASE to send the parameters to the plug-in for validation
    18621835            and saving.
    … …  
    18831856          <para>
    18841857            If you want a &gbCancel; button to abort the configuration
    1885             you should reload the page with with the url:
     1858            this should be linked to a page reload with with the url:
    18861859            <uri>index.jsp?ID=&lt;%=ID%&gt;&amp;cmd=CancelWizard</uri>. This
    18871860            allows BASE to clean up resources that has been put in global
    … …  
    19191892
    19201893    <para>
    1921       A plugin becomes an import plugin simply by returning
     1894      A plug-in becomes an import plugin simply by returning
    19221895      <constant>Plugin.MainType.IMPORT</constant>
    19231896      from the <methodname>Plugin.getMainType()</methodname> method.
    … …  
    19551928              Check the input stream if it seems to contain data that can be imported by
    19561929              the plugin. Usually it means scanning a few lines for some header
    1957               mathing a predefined string or a regexp.
    1958             </para>
    1959             <para>
    1960               The <classname docapi="net.sf.basedb.plugins">AbstractFlatFileImporter</classname> implements this method
     1930              matching a predefined string or regular expression.
     1931            </para>
     1932            <para>
     1933              The <classname docapi="net.sf.basedb.plugins">AbstractFlatFileImporter</classname>
     1934              can be used for text-based files and implements this method
    19611935              by reading the headers from the input stream and checking if
    19621936              it stopped at an unknown type of line or not:
    … …  
    19861960}
    19871961</programlisting>
    1988             </para>
    1989             <para>
    1990               Note that the input stream doesn't have to be a text file.
     1962           
     1963              The <classname>AbstractFlatFileImporter</classname> also has functions
     1964              for setting the character set and automatic unwrapping of compressed
     1965              files. See the javadoc for more information.
     1966            </para>
     1967            <para>
     1968              Note that the input stream doesn't have to be a text file (but you can't use the
     1969              <classname>AbstractFlatFileImporter</classname> then).
    19911970              It can be any type of file, for example a binary or an XML file.
    19921971              In the case of an XML file you would need to validate the entire
    … …  
    19961975              tag.
    19971976            </para>
     1977           
     1978          <tip>
     1979          <title>Try casting to ImportInputStream</title>
     1980          <para>
     1981            In many cases (but not all) the auto-detect functionality uses a
     1982            <classname docapi="net.sf.basedb.core.plugin">ImportInputStream</classname>
     1983            as the <varname>in</varname> parameter. This class contains some
     1984            metadata about the file the input stream is originating from. The most
     1985            useful feature is the possibility to get information about the
     1986            character set used in the file. This makes it possible to open text
     1987            files using the correct character set.
     1988          </para>
     1989          <programlisting language="java">
     1990String charset = Config.getCharset(); // Default value
     1991if (in instanceof ImportInputStream)
     1992{
     1993   ImportInputStream iim = (ImportInputStream)in;
     1994   if (iim.getCharacterSet() != null) charset = iim.getCharacterSet();
     1995}
     1996Reader reader = new InputStreamReader(in, Charset.forName(charset)));
     1997</programlisting>
     1998        </tip>       
     1999           
    19982000          </listitem>
    19992001        </varlistentry>
    … …  
    20312033        </variablelist>
    20322034       
    2033         <tip>
    2034           <title>Try casting to ImportInputStream</title>
    2035           <para>
    2036             As of BASE 2.9 the auto-detect functionality uses a
    2037             <classname docapi="net.sf.basedb.core.plugin">ImportInputStream</classname>
    2038             as the <varname>in</varname> parameter. This class contains some
    2039             metadata about the file the input stream is originating from. The most
    2040             useful feature is the possibility to get information about the
    2041             character set used in the file. This makes it possible to open text
    2042             files using the correct character set.
    2043           </para>
    2044           <programlisting language="java">
    2045 String charset = Config.getCharset(); // Default value
    2046 if (in instanceof ImportInputStream)
    2047 {
    2048    ImportInputStream iim = (ImportInputStream)in;
    2049    if (iim.getCharacterSet() != null) charset = iim.getCharacterSet();
    2050 }
    2051 Reader reader = new InputStreamReader(in, Charset.forName(charset)));
    2052 </programlisting>
    2053         </tip>       
    20542035      </sect3>
    20552036     
    … …  
    21552136      </para>
    21562137
    2157       <itemizedlist>
    2158       <listitem>
    2159         <para>
    2160         Implement the <methodname>Plugin.getAbout()</methodname> method. See
    2161         <xref linkend="plugin_developer.api.interfaces.plugin" /> for more information.
    2162         </para>
    2163       </listitem>
    2164      
     2138      <itemizedlist> 
    21652139      <listitem>
    21662140        <para>
    … …  
    26162590      </para>
    26172591
     2592      <sect3 id="plugin_developer.import.configurebyexample">
     2593        <title>Configure by example</title>
     2594       
     2595        <para>
     2596          The <interfacename docapi="net.sf.basedb.util.parser">ConfigureByExample</interfacename>
     2597          is a tagging interface that can be used by plug-ins using the
     2598          <classname docapi="net.sf.basedb.util.parser">FlatFileParser</classname> class for parsing.
     2599          The web client detects if a plug-in implements this interface and if the list of
     2600          parameters includes a section parameter with the name <constant>parserSection</constant>
     2601          a <guibutton>Test with file</guibutton> buttons is activated. This button will take the
     2602          user to a form which allows the user to enter values for the parameters defined in
     2603          the <classname>AbstractFlatFileImporter</classname> class. Parameters for column mappings
     2604          must have the string "Mapping" in their names.
     2605        </para>
     2606      </sect3>
    26182607    </sect2>
     2608   
    26192609  </sect1>
    26202610
    … …  
    30072997      <methodname>Plugin.getMainType()</methodname> method. The information returned from
    30082998      <methodname>InteractivePlugin.getGuiContexts()</methodname>
    3009       must include: [<constant>Item.BIOASSAYSET</constant>, <constant>Type.ITEM</constant>]
    3010       since this is the main place where the web client looks for analysis plug-ins. If
     2999      should include: [<constant>Item.BIOASSAYSET</constant>, <constant>Type.ITEM</constant>]
     3000      or [<constant>Item.DERIVEDBIOASSAYSET</constant>, <constant>Type.ITEM</constant>]
     3001      since web client doesn't look for analysis plug-ins in most other places. If
    30113002      the plug-in can work on a subset of the bioassays it may also include
    30123003      [<constant>Item.BIOASSAY</constant>, <constant>Type.LIST</constant>]
    30133004      among the contexts. This will make it possible for a user to select
    3014       bioassays from the list and then invoke the plug-in.
     3005      bioassays from the list and then invoke the plug-in. The following
     3006      code examples are taken from an analysis plug-in that is used in an experiment
     3007      context.
    30153008    </para>
    30163009   
    … …  
    30253018
    30263019    <para>
    3027     If the plugin depends on a specific raw data type or on the number of
     3020    If the plug-in depends on a specific raw data type or on the number of
    30283021    channels, it should check that the current bioassayset is of the
    30293022    correct type in the <methodname>InteractivePlugin.isInContext()</methodname>
    … …  
    30623055
    30633056    <para>
    3064     The plugin should always include a parameter asking for the current
     3057    The plug-in should always include a parameter asking for the current
    30653058    bioassay set when the <methodname>InteractivePlugin.getRequestInformation()</methodname>
    30663059    is called with <literal>command = Request.COMMAND_CONFIGURE_JOB</literal>.
    … …  
    32273220      <para>
    32283221        This class is an abstract base class. It is a useful
    3229         class for most analysis plug-ins to inherit from. Its main
     3222        class for most analysis plug-ins used in an experiment context
     3223        to inherit from. Its main
    32303224        purpose is to define <classname docapi="net.sf.basedb.core">PluginParameter</classname>
    32313225        objects that are commonly used in analysis plug-ins. This includes:

  • trunk/src/core/net/sf/basedb/core/plugin/Plugin.java

    r5610 r5633  
    7676  */
    7777  public MainType getMainType();
    78 
    79   /**
    80     Get information about the plugin, such as
    81     name, version, authors, etc.
    82     @return An {@link About} object
    83     deprecated
    84   */
    85   //public About getAbout();
    8678
    8779  /**
Note: See TracChangeset for help on using the changeset viewer.