Changeset 3339


Ignore:
Timestamp:
May 15, 2007, 1:13:14 PM (15 years ago)
Author:
Nicklas Nordborg
Message:

References #548: Write "Installing plug-ins" section

Now ready for reading.

Location:
trunk
Files:
4 added
3 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc/src/docbook/admindoc/installation_upgrade.xml

    r3329 r3339  
    587587
    588588  <sect1 id="installation_upgrade.jobagents">
    589     <title>Job agents</title>
     589    <title>Installing job agents</title>
    590590    <para>TODO</para>
    591591  </sect1>
  • trunk/doc/src/docbook/admindoc/plugin_installation.xml

    r3329 r3339  
    103103   
    104104    <helptext external_id="plugindefinition.edit"
    105       title="Edit plugin">
     105      title="Plug-in properties">
    106106     
    107107      <variablelist>
     
    232232     
    233233      <seeother>
    234         <other external_id="plugindefinition.edit.permissions">Plugin permissions</other>
     234        <other external_id="plugindefinition.edit.permissions">Plug-in permissions</other>
     235        <other external_id="plugindefinition.jobagents">Job agents</other>
    235236      </seeother>   
    236237     
     
    240241    <sect2 id="plugins.installation.base1">
    241242      <title>BASE 1 plug-ins</title>
    242       <para>TODO</para>
     243      <para>
     244        BASE 1 plug-ins are supported by BASE 2 through the use of
     245        the <emphasis>BASE 1 plug-in executer</emphasis> plug-in. This
     246        is itself a plug-in and BASE 1 plug-ins are added as configurations
     247        to this plug-in. See <xref linkend="plugins.configuration" />. To
     248        install a BASE 1 plug-in to BASE 2 follow these instructions:
     249      </para>
     250     
     251      <orderedlist>
     252        <listitem>
     253        <para>
     254          Install the BASE 1 plug-in executable and any
     255          other files needed by it on the BASE server. Check the documentation
     256          for the plug-in for information about what is needed.
     257        </para>
     258        </listitem>
     259       
     260        <listitem>
     261        <para>
     262          Upload the <filename>*.base</filename> file for the BASE 1 plug-in
     263          to BASE 2. If you can't the file, you can let BASE 1 create one for you.
     264          In your BASE 1 installation go to
     265          <menuchoice>
     266            <guimenu>Analyze data</guimenu>
     267            <guimenuitem>Plug-ins</guimenuitem>
     268          </menuchoice>
     269          and use the <guilabel>Export</guilabel> function. This will create a
     270          configuration file for your BASE 1 plug-in that you can upload to BASE 2.
     271        </para>
     272        </listitem>
     273       
     274        <listitem>
     275          <para>
     276            Create a new plug-in configuration in BASE 2 using, for example,
     277            the <guibutton>New configuration</guibutton> button
     278            in single-item view for the <emphasis>BASE 1 plug-in executer</emphasis>
     279            plug-in.
     280          </para>
     281        </listitem>
     282       
     283        <listitem>
     284          <para>
     285            Start the configuration wizard and select the <filename>*.base</filename>
     286            file describing the BASE 1 plug-in and enter the path and
     287            filename to the location of the executable.
     288          </para>
     289        </listitem>
     290       
     291        <listitem>
     292          <para>
     293            To check that the new plug-in works correctly, you need
     294            to have an experiment with some data. Go to the single-item
     295            view for a bioassayset and click on the <guibutton>Run analysis</guibutton>
     296            button. Select the <emphasis>Base1PluginExecutor</emphasis>
     297            plug-in. The list of configurations should include the newly
     298            installed plug-in. Select it and click on <guibutton>Next</guibutton>.
     299          </para>
     300        </listitem>
     301       
     302        <listitem>
     303          <para>
     304            This will enter regular plug-in execution wizard and you
     305            will have to enter paraters needed by the plug-in.
     306          </para>
     307        </listitem>
     308       
     309      </orderedlist>
     310     
     311
    243312    </sect2>
    244313   
     
    355424   
    356425      <seeother>
    357         <other external_id="plugindefinition.edit">Plugin properties</other>
     426        <other external_id="plugindefinition.edit">Plug-in properties</other>
     427        <other external_id="plugindefinition.jobagents">Job agents</other>
    358428        <other external_id="role.edit.permissions">Role permissions</other>
    359429      </seeother>   
     
    367437    <title>Job agents</title>
    368438    <para>
    369       TODO - see also <xref linkend="installation_upgrade.jobagents" />.
     439      Job agents are used for executing plug-ins on external servers. This is a good
     440      way to free up the web server so that it can concentrate on serving web pages.
     441      Job agents are optional and must be installed separately. See
     442      <xref linkend="installation_upgrade.jobagents" /> for more information about this.     
     443      The standard BASE installation doesn't include any job agents.
     444      The rest of this section assumes that you have installed at least one job agent.
    370445    </para>
    371446   
    372    
     447    <para>
     448      A job agent will not execute a plug-in unless the admin has configured
     449      told the job agent to do so. This can be done either from the plug-in
     450      side or from the job agent side. To register a plug-in with one or more
     451      job agents from the plug-in side go to the edit view the plug-in and
     452      select the <guilabel>Job agents</guilabel> tab. To do the same from
     453      the job agent side go to the edit view of the job agent and select
     454      the <guilabel>Plugins</guilabel> tab. The two dialogs are very similar.
     455      Here is the plug-in side of the registration, the job agent side is described
     456      in <xref linkend="installation_upgrade.jobagents" />.
     457    </para>
     458   
     459    <figure id="plugins.figures.jobagents">
     460      <title>Select job agents for a plug-in</title>
     461      <screenshot>
     462        <mediaobject>
     463          <imageobject><imagedata
     464            fileref="figures/plugin_jobagents.png" format="PNG"
     465            /></imageobject>
     466        </mediaobject>
     467      </screenshot>
     468    </figure>
     469   
     470    <helptext external_id="plugindefinition.jobagents"
     471      title="Job agents">
     472     
     473      <para>
     474        Use this tab to specify which job agents the plug-in is
     475        installed and allowed to be executed on.
     476      </para>
     477     
     478      <variablelist>
     479      <varlistentry>
     480        <term><guilabel>Run this plugin on</guilabel></term>
     481        <listitem>
     482          <para>
     483            A list with the job agents where the plug-in is installed and
     484            allowed to be executed. Select a plug-in in this list to display
     485            more configuration options for the plug-in.
     486          </para>
     487        </listitem>
     488      </varlistentry>
     489      <varlistentry>
     490        <term><guilabel>Add job agents</guilabel></term>
     491        <listitem>
     492          <para>
     493            Use this button to open a popup window for selecting
     494            job agents.
     495          </para>
     496        </listitem>
     497      </varlistentry>
     498      <varlistentry>
     499        <term><guilabel>Remove</guilabel></term>
     500        <listitem>
     501          <para>
     502            Remove the selected plug-in from the list.
     503          </para>
     504        </listitem>
     505      </varlistentry>
     506      </variablelist>
     507     
     508      <para>
     509        The following properties are only displayed when a
     510        job agent has been selected in the list. Each job agent may have it's
     511        own settings of these properties. If you leave the values unspecified
     512        the job agent will use the default values specified on the
     513        <guilabel>Plugin</guilabel> tab.
     514      </para>
     515     
     516      <variablelist>
     517      <varlistentry>
     518        <term><guilabel>Jar path</guilabel></term>
     519        <listitem>
     520          <para>
     521            The path on the external server to the JAR file containing the
     522            plug-in code. If not specified the same path as on the web server
     523            is used.
     524          </para>
     525        </listitem>
     526      </varlistentry>
     527      <varlistentry>
     528        <term><guilabel>Max memory</guilabel></term>
     529        <listitem>
     530          <para>
     531            The maximum amount of memory the plug-in is allowed to use.
     532            Add around 40MB for the Java runtime environment and BASE.
     533            If not specified Java will choose it's default value which is 64MB.
     534          </para>
     535        </listitem>
     536      </varlistentry>
     537      <varlistentry>
     538        <term><guilabel>Trusted</guilabel></term>
     539        <listitem>
     540          <para>
     541            If the plug-in should be executed in a protected or
     542            unprotected environment. Currently, BASE only supports
     543            running plug-ins in an unprotected environment.
     544          </para>
     545        </listitem>
     546      </varlistentry>
     547      <varlistentry>
     548        <term><guilabel>Priority boost</guilabel></term>
     549        <listitem>
     550          <para>
     551            Used to give a plug-in higher priority in the queue.
     552            Values between 0 and 10 are allowed. A higher value will
     553            give the plug-in higher priority. The priority boost is useful
     554            if we, for example, want to use one server mainly for importing
     555            data. By giving all import plugins a priority boost they will
     556            be executed before all other jobs, which will have to wait
     557            until there are no more waiting imports.
     558          </para>
     559        </listitem>
     560      </varlistentry>
     561      </variablelist>
     562     
     563      <seeother>
     564        <other external_id="plugindefinition.edit">Plug-in properties</other>
     565        <other external_id="plugindefinition.edit.permissions">Plug-in permissions</other>
     566      </seeother>
     567    </helptext>
    373568  </sect1>
    374 
    375569 
    376570  <sect1 id="plugins.configuration">
     
    591785    </sect2>
    592786
    593     <sect2 id="plugins.configuration.core">
    594       <title>Core plug-in configurations</title>
     787    <sect2 id="plugins.configuration.importexport">
     788      <title>Importing and exporting plug-in configurations</title>
     789      <para>
     790        BASE ships with one importer and one exporter that allows
     791        you to import and export plug-in configurations. This makes
     792        it easy to copy configurations between servers. The BASE website
     793        also has a <ulink url="http://base.thep.lu.se/chrome/site/doc/admin/plugin_configuration/coreplugins.html"
     794        >page where you can download additional configurations</ulink>
     795        not included in the main distribution.
     796      </para>
     797     
     798      <para>
     799        Both the import and the export is started from the plug-in
     800        configuration list view:
     801        <menuchoice>
     802          <guimenu>Administrate</guimenu>
     803          <guisubmenu>Plugins</guisubmenu>
     804          <guimenuitem>Configurations</guimenuitem>
     805        </menuchoice>
     806      </para>
     807     
     808      <para>
     809        The importer supports auto detection. Simply upload and select the
     810        XML file with the configurations. No more parameters are needed.
     811      </para>
     812     
     813      <para>
     814        To use the exporter you must first select the configurations
     815        that should be exported in the list. Then, enter a path and filename
     816        if you wish to leave the XML file on the BASE server or leave it
     817        empty to download it immediately.
     818      </para>
     819     
     820      <note>
     821        The import and export only supports simple values, such as strings,
     822        numbers, etc. It doesn't support configuration values that reference
     823        other items. If the plug-in has such values they must be fixed by
     824        hand after the import.
     825      </note>
     826     
    595827    </sect2>
    596828
    597    
    598829    <sect2 id="plugins.configuration.testwithfile">
    599830      <title>The <guilabel>Test with file</guilabel> function</title>
     831     
     832      <para>
     833        The <guilabel>Test with file</guilabel> function is avery useful
     834        function for specifying import file formats. It is supported by
     835        many of the import plug-ins that read data from a simple text
     836        file. This includes the raw data importer, the reporter importer,
     837        plate reporter, etc.
     838      </para>
     839
     840      <note>
     841        The <guilabel>Test with file</guilabel> function can only
     842        be used with simple (tab- or comma-separated) text files.
     843        It doesn't work with XML files or binary files. The text file
     844        may have headers in the beginning.
     845      </note>
     846     
     847      <para>
     848        As you can see in figure <xref linkend="plugins.figures.wizard"/>
     849        there is a <guibutton>Test with file</guibutton> button. This
     850        will appear in the file format setup step for all plug-ins that
     851        support the test with file function. For detailed technical
     852        information about this see <xref linkend="plugin_developer.import" />
     853        in <xref linkend="plugin_developer" />. Clicking on the
     854        <guibutton>Test with file</guibutton> button opens the following dialog:
     855      </para>
     856     
     857      <figure id="plugins.figures.testwithfile">
     858        <title>The test with file function</title>
     859        <screenshot>
     860          <mediaobject>
     861            <imageobject><imagedata
     862              fileref="figures/test_with_file.png" format="PNG"
     863              /></imageobject>
     864          </mediaobject>
     865        </screenshot>
     866      </figure>
     867     
     868      <helptext external_id="runplugin.testwithfile"
     869        title="Test with file">
     870       
     871      <para>
     872        The window consists of two parts, the upper part where the file
     873        to parse and the parmeters used to parse it are entered, and
     874        the lower part that displays information about the parsing.
     875      </para>
     876       
     877      <variablelist>
     878      <varlistentry>
     879        <term><guilabel>File to test</guilabel></term>
     880        <listitem>
     881          <para>
     882            The path and filename of the file to use for testing.
     883            Use the <guibutton>Browse</guibutton> button to
     884            select a file from the BASE file system or upload
     885            a new file. Click on the <guibutton>Parse the file</guibutton>
     886            button to start parsing. The lower part will update itself with
     887            information about the parsed file. The file must follow a few simple rules:
     888           
     889            <itemizedlist>
     890            <listitem>
     891              <para>Data must be organised into columns, with one record per line.</para>
     892            </listitem>
     893            <listitem>
     894              <para>
     895                Each data column must be separated by some special character or
     896                character sequence not occuring in the data, for example a tab or a comma.
     897                Data in fixed-size columns cannot be parsed.
     898              </para>
     899            </listitem>
     900            <listitem>
     901              <para>
     902                Data may optionally be preceeded by a data header, for example,
     903                the names of the columns.
     904              </para>
     905            </listitem>
     906            <listitem>
     907              <para>
     908                The data header may optionally be preceeded by file headers.
     909                A file header is something that can be split into a name-value pair.
     910              </para>
     911            </listitem>
     912            <listitem>
     913              <para>
     914                The file may contain comments, which are ignored by the parser.
     915              </para>
     916            </listitem>
     917            </itemizedlist>
     918          </para>
     919        </listitem>
     920      </varlistentry>
     921      <varlistentry>
     922        <term><guilabel>Lines to parse</guilabel></term>
     923        <listitem>
     924          <para>
     925            The number of lines to parse. The default is 100.
     926          </para>
     927        </listitem>
     928      </varlistentry>
     929      <varlistentry>
     930        <term><guilabel>Encoding</guilabel></term>
     931        <listitem>
     932          <para>
     933            The character encoding of the file. The default
     934            is ISO-8859-1 (same as Latin-1). This list contains all encodings
     935            supported by the underlying Java runtime and can be quite long.
     936          </para>
     937        </listitem>
     938      </varlistentry>
     939      <varlistentry>
     940        <term><guilabel>Header regexp</guilabel></term>
     941        <listitem>
     942          <para>
     943            A regular expression matching a header line. A header
     944            is a key-value pair with information about the
     945            data in the file. The regular expression must contain two capturing groups,
     946            the first should capture the name and the second the value of the header.
     947            For example, the file contains headers like:
     948<screen>
     949"Type=GenePix Results 3"
     950"DateTime=2006/05/16 13:17:59"
     951</screen>
     952            To match this we can use the following regular expression:
     953            <userinput>"(.*)=(.*)"</userinput>.
     954          </para>
     955         
     956          <para>
     957            Use the <guibutton>Predefined</guibutton> button to select from a
     958            list of common regular expressions.
     959          </para>
     960         
     961        </listitem>
     962      </varlistentry>
     963     
     964      <varlistentry>
     965        <term><guilabel>Data splitter regexp</guilabel></term>
     966        <listitem>
     967          <para>
     968            A regular expression used to split a data line into columns. For
     969            example, <userinput>\t</userinput> to split on tabs. Use
     970            <guibutton>Predefined</guibutton> button to select from a list of
     971            common regular expressions.
     972          </para>
     973        </listitem>
     974      </varlistentry>
     975     
     976      <varlistentry>
     977        <term><guilabel>Ignore regexp</guilabel></term>
     978        <listitem>
     979          <para>
     980            A regular expression that matches all lines that should be ignored.
     981            For example, <userinput>\#.*</userinput> to ignore all lines starting with
     982            a #. Use
     983            <guibutton>Predefined</guibutton> button to select from a list of
     984            common regular expressions.
     985          </para>
     986        </listitem>
     987      </varlistentry>
     988     
     989      <varlistentry>
     990        <term><guilabel>Data header regexp</guilabel></term>
     991        <listitem>
     992          <para>
     993            A regular expression that matches the line containing the data header.
     994            Usually the data header contains the column names separated with the
     995            same separator as the data. For example, the file contains a header
     996            like:
     997<screen>
     998"Block"{tab}"Column"{tab}"Row"{tab}"Name"{tab}"ID" ...and so on
     999</screen>
     1000            To match this we can use the following regular expression:
     1001            <userinput>"Block"\t"Column"\t"Row"\t"Name"\t"ID".*</userinput>.
     1002          </para>
     1003         
     1004          <para>
     1005            The easiest way to set this regular is expression is to leave it empty
     1006            to start with, click on the <guibutton>Parse the file</guibutton> button.
     1007            Then, in the <guilabel>File data</guilabel> tab, use the dropdown lists
     1008            in the <guilabel>Use as</guilabel> column to select the line containing the
     1009            data header. BASE will automatically generate a regular expression matching
     1010            the line.
     1011          </para>
     1012        </listitem>
     1013      </varlistentry>
     1014
     1015      <varlistentry>
     1016        <term><guilabel>Date footer regexp</guilabel></term>
     1017        <listitem>
     1018          <para>
     1019            A regular expression that matches the first line of non-data after
     1020            all data lines. In most cases you can leave this empty.
     1021          </para>
     1022        </listitem>
     1023      </varlistentry>
     1024
     1025      <varlistentry>
     1026        <term><guilabel>Min and max data columns</guilabel></term>
     1027        <listitem>
     1028          <para>
     1029            If you specify values a data line is ignored if the number of
     1030            columns doesn't fall within the range. If your data file doesn't have
     1031            a data header with column names you can use these settings to find the
     1032            start of data.
     1033          </para>
     1034        </listitem>
     1035      </varlistentry>
     1036      <varlistentry>
     1037        <term><guilabel>Remove quotes</guilabel></term>
     1038        <listitem>
     1039          <para>
     1040            If enabled, the parser will remove quotes around data entries.
     1041          </para>
     1042        </listitem>
     1043      </varlistentry>
     1044 
     1045      <varlistentry>
     1046        <term><guilabel>File data</guilabel></term>
     1047        <listitem>
     1048          <para>
     1049            Press the <guilabel>Parse the file</guilabel> button
     1050            to start parsing the file. This tab will be updated with the data
     1051            from the file, organised as a table. For each line the following information
     1052            is displayed:
     1053            <itemizedlist>
     1054            <listitem>
     1055              <para>
     1056              <emphasis>Line</emphasis>: The line number in the file
     1057              </para>
     1058            </listitem>
     1059
     1060            <listitem>
     1061              <para>
     1062              <emphasis>Columns</emphasis>: The number of columns the line could be
     1063              split into with the data splitter regular expression.
     1064              </para>
     1065            </listitem>
     1066
     1067            <listitem>
     1068              <para>
     1069              <emphasis>Type</emphasis>: The type of line as detected by the parser.
     1070              It should be one of the following: <emphasis>Unknown</emphasis>,
     1071              <emphasis>Header</emphasis>, <emphasis>Data header</emphasis>,
     1072              <emphasis>Data</emphasis> or <emphasis>Data footer</emphasis>.
     1073              </para>
     1074            </listitem>
     1075           
     1076            <listitem>
     1077              <para>
     1078              <emphasis>Use as</emphasis>: Use the dropdown lists to use a
     1079              line as either the data header or data footer. BASE will automatically
     1080              generate a regular expression.
     1081              </para>
     1082            </listitem>
     1083           
     1084            <listitem>
     1085              <para>
     1086              <emphasis>File data</emphasis>: The contents of the file after
     1087              splitting and, optionally, removal of quotes.
     1088              </para>
     1089            </listitem>
     1090            </itemizedlist>
     1091           
     1092          </para>
     1093        </listitem>
     1094      </varlistentry>
     1095      <varlistentry>
     1096        <term><guilabel>Column mappings</guilabel></term>
     1097        <listitem>
     1098          <para>
     1099            This tab is only displayed if data has been found in the file and a
     1100            data header is present. It allows you to easily select the mapping
     1101            between columns in the file and the properties in the database.
     1102          </para>
     1103          <nohelp>
     1104          <figure id="plugins.figures.testwithfilemappings">
     1105            <title>Mapping columns from a file</title>
     1106            <screenshot>
     1107              <mediaobject>
     1108                <imageobject><imagedata
     1109                  fileref="figures/test_with_file_mappings.png" format="PNG"
     1110                  /></imageobject>
     1111              </mediaobject>
     1112            </screenshot>
     1113          </figure>
     1114          </nohelp>
     1115         
     1116          <itemizedlist>
     1117          <listitem>
     1118            <para>
     1119              <emphasis>Mapping style</emphasis>: The type
     1120              of mapping to use when you pick a column from the
     1121              <emphasis>File columns</emphasis> list boxes.
     1122            </para>
     1123          </listitem>
     1124         
     1125          <listitem>
     1126            <para>
     1127              <emphasis>Property</emphasis>: The database property.
     1128            </para>
     1129          </listitem>
     1130
     1131          <listitem>
     1132            <para>
     1133              <emphasis>Mapping expression</emphasis>: An expression that
     1134              maps the data in the file columns to the property in the
     1135              database. There are two types of mappings, simple and expressions.
     1136              A simple mapping is a string template with placeholders for data
     1137              from the file. An expression mapping starts with an equal sign and
     1138              is evaluated dynamically for each line of data. The simple
     1139              mapping has better performance and we recommend that you use
     1140              it unless you have to recalculate any of the numerical values.
     1141              Here are a few mapping examples:
     1142            </para>
     1143           
     1144<informalexample>
     1145<literallayout>\Name\
     1146\1\
     1147[\row\, \column\]
     1148=2 * col('radius')
     1149</literallayout>
     1150</informalexample>
     1151           
     1152            <note>
     1153              Column numbers are 0-based. We recommend that you use
     1154              column names at all times if they are present in the
     1155              file.
     1156            </note>
     1157          </listitem>
     1158         
     1159          <listitem>
     1160            <para>
     1161              <emphasis>File columns</emphasis>: Lists of column found in the file.
     1162              Select a value from this list to let BASE automatically
     1163              generate a mapping that picks the selected column.
     1164            </para>
     1165          </listitem>
     1166          </itemizedlist>
     1167        </listitem>
     1168      </varlistentry>
     1169      </variablelist>     
     1170     
     1171      </helptext>
     1172     
    6001173     
    6011174    </sect2>
  • trunk/lib/docbook/custom-styles/docbook/plain/css/docbook.css

    r3314 r3339  
    125125}
    126126
     127.userinput, .literallayout {
     128  font-family: monospace;
     129  font-weight: normal;     
     130}
     131
     132.property {
     133  font-family: monospace;
     134  font-weight: bold;     
     135}
     136
    127137
    128138/* ------------------------------------------------------------------- }}} */
Note: See TracChangeset for help on using the changeset viewer.