source: trunk/doc/src/docbook/admindoc/plugin_installation.xml @ 3329

Last change on this file since 3329 was 3329, checked in by Nicklas Nordborg, 14 years ago

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

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 18.7 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE chapter PUBLIC
3    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
4    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
5<!--
6  $Id: plugin_installation.xml 3329 2007-05-11 12:20:35Z nicklas $
7
8  Copyright (C) Authors contributing to this file.
9
10  This file is part of BASE - BioArray Software Environment.
11  Available at http://base.thep.lu.se/
12
13  BASE is free software; you can redistribute it and/or
14  modify it under the terms of the GNU General Public License
15  as published by the Free Software Foundation; either version 2
16  of the License, or (at your option) any later version.
17
18  BASE is distributed in the hope that it will be useful,
19  but WITHOUT ANY WARRANTY; without even the implied warranty of
20  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
21  GNU General Public License for more details.
22
23  You should have received a copy of the GNU General Public License
24  along with this program; if not, write to the Free Software
25  Foundation, Inc., 59 Temple Place - Suite 330,
26  Boston, MA  02111-1307, USA.
27-->
28
29<chapter id="plugins">
30  <?dbhtml dir="plugin_installation"?>
31  <title>Plug-ins</title>
32
33  <para>
34    BASE can get extended functionality by the use of plug-ins. In fact, most
35    of the hard work, such as data import/export and analysis is done with plug-ins.
36    BASE ships with a number of standard plug-ins, the core plug-ins, which gives
37    basic import/export and analysis functionality. See <xref linkend="resources" />
38    for more information about the core plug-ins and 3rd-party plug-ins.
39  </para>
40
41
42  <sect1 id="plugins.installation">
43    <title>Installing plug-ins</title>
44    <para>
45      The first step is to install the plug-in on the web server. To make
46      these instructions easier to read we assume the the plug-in comes as
47      a single JAR file and that it doesn't depend on any other JAR files.
48    </para>
49   
50    <para>
51      We recommend that you install the plug-in JAR file outside the web
52      server's classpath. Do not put the plug-in in the
53      <filename>&lt;base-dir&gt;/www/WEB-INF/lib</filename>
54      directory or any other directory where the web server keeps it's classes.
55      This makes BASE use it's own classloader that support unloading of classes
56      as well. This means that you can install new plug-ins and update
57      existing ones without restarting the web server.
58    </para>
59   
60    <para>
61      We recommend that you create a separate directory for plug-ins and
62      install all of them there. You may use a sub-directory for each plug-in
63      if you like, for example:
64      <filename>&lt;base-dir&gt;/plugins/&lt;name-of-plugin&gt;</filename>
65    </para>
66   
67    <note>
68      <title>Plug-ins that use other JAR files</title>
69      <para>
70        Some plug-ins may depend on other JAR files. Normally,
71        these JAR files should be put in the same directory as the
72        plug-in JAR file. This may, however, vary from plug-in to plug-in
73        so always check the plug-in documentation first.
74      </para>
75    </note>
76   
77    <para>
78      When the plug-in is installed on the server you must register it
79      with BASE. BASE lacks functionality for discovering plug-ins automatically
80      so you have to enter information about the JAR file and plug-in manually.
81      This can be hard to get right. To register the plug-in with BASE go to
82      <menuchoice>
83        <guimenu>Administrate</guimenu>
84        <guisubmenu>Plugins</guisubmenu>
85        <guimenuitem>Definitions</guimenuitem>
86      </menuchoice> and click on the <guibutton>New&hellip;</guibutton>
87      button.
88    </para>
89   
90    <sect2 id="plugins.install.properties">
91      <title>Plug-in properties</title>
92   
93    <figure id="plugins.figures.install">
94      <title>Installing a plug-in</title>
95      <screenshot>
96        <mediaobject>
97          <imageobject><imagedata 
98            fileref="figures/install_plugin.png" format="PNG"
99            /></imageobject>
100        </mediaobject>
101      </screenshot>
102    </figure>
103   
104    <helptext external_id="plugindefinition.edit" 
105      title="Edit plugin">
106     
107      <variablelist>
108      <varlistentry>
109        <term><guilabel>Name</guilabel></term>
110        <listitem>
111          <para>
112            The name of the plug-in. This name is set automatically by
113            the plug-in and can't be changed.
114          </para>
115        </listitem>
116      </varlistentry>
117      <varlistentry>
118        <term><guilabel>Class</guilabel></term>
119        <listitem>
120          <para>
121            The Java class name of the plug-in.
122          </para>
123        </listitem>
124      </varlistentry>
125      <varlistentry>
126        <term><guilabel>Path</guilabel></term>
127        <listitem>
128          <para>
129            The path to the JAR file on the web server. If left empty
130            the plug-in must be on the web server's class path (not
131            recommended).
132          </para>
133        </listitem>
134      </varlistentry>
135      <varlistentry>
136        <term><guilabel>Max memory</guilabel></term>
137        <listitem>
138          <para>
139            The maximum amount of memory the plug-in may use. This setting
140            only applies when the plug-in is executed with a job agent. If
141            the inernal job queue is used this setting has no effect and the
142            plug-in may use as much memory as it likes.
143            <nohelp>See <xref linkend="plugins.jobagents" /> later
144            in this chapter.</nohelp>
145          </para>
146        </listitem>
147      </varlistentry>
148      <varlistentry>
149        <term><guilabel>Trusted</guilabel></term>
150        <listitem>
151          <para>
152            If the plug-in is trusted enough to be executed in an
153            unprotected environment. This setting has currently no
154            effect since BASE can't run in a protected environment.
155            When this becomes implemented in the future a
156            <guilabel>no</guilabel> value will apply security restrictions
157            to plug-ins similiar to those a web browser put on applets.
158            For example, the plug-in is not allowed to access the file
159            system, open ports, shut down the server, and a lot of
160            other nasty things.
161          </para>
162        </listitem>
163      </varlistentry>
164      <varlistentry>
165        <term><guilabel>Trusted</guilabel></term>
166        <listitem>
167          <para>
168            If the plug-in is trusted enough to be executed in an
169            unprotected environment. This setting has currently no
170            effect since BASE can't run in a protected environment.
171            When this becomes implemented in the future a
172            <guilabel>no</guilabel> value will apply security restrictions
173            to plug-ins similiar to those a web browser put on applets.
174            For example, the plug-in is not allowed to access the file
175            system, open ports, shut down the server, and a lot of
176            other nasty things.
177          </para>
178        </listitem>
179      </varlistentry>
180      <varlistentry>
181        <term><guilabel>Allow immediate execution</guilabel></term>
182        <listitem>
183          <para>
184            If the plug-in is allowed to bypass the job queue
185            and be executed immediately.
186           
187            <itemizedlist>
188              <listitem>
189                <para>
190                <guilabel>No</guilabel>: The plug-in must always use
191                the job queue.
192                </para>
193              </listitem>
194              <listitem>
195                <para>
196                <guilabel>Yes</guilabel>: The plug-in is allowed to bypass
197                the job queue. This also means that the plug-in always
198                executes on the web server, job agents are not used.
199                This setting is mainly useful for export plug-ins that
200                needs to support immediate download of the exported data.
201                <nohelp>
202                See <xref linkend="import_export_data.export.immediatedownload" />.
203                </nohelp>
204                </para>
205               
206                <note>
207                  If a plug-in should be executed immediately or not
208                  is always decided by the plug-in. BASE will never give
209                  the users a choice.
210                </note>
211               
212              </listitem>
213              <listitem>
214                <para>
215                <guilabel>Auto</guilabel>: BASE will allow export plug-ins
216                to execute immediately, and deny all other types of plug-ins.
217                This alternative is only available when registering a new
218                plug-in.
219                </para>
220              </listitem>
221            </itemizedlist>
222           
223          </para>
224        </listitem>
225      </varlistentry>
226      </variablelist>
227     
228      <para>
229        Click on <guibutton>Save</guibutton> to finish the registration
230        or on <guibutton>Cancel</guibutton> to abort.
231      </para>
232     
233      <seeother>
234        <other external_id="plugindefinition.edit.permissions">Plugin permissions</other>
235      </seeother>   
236     
237    </helptext>
238    </sect2>
239   
240    <sect2 id="plugins.installation.base1">
241      <title>BASE 1 plug-ins</title>
242      <para>TODO</para>
243    </sect2>
244   
245  </sect1>
246
247  <sect1 id="plugins.permissions">
248    <title>Plug-in permissions</title>
249
250    <helptext external_id="plugindefinition.edit.permissions" 
251      title="Edit plug-in permissions">
252
253   
254      <para>
255        When a plug-in is executed the default is to give it the same
256        permissions as the user that started it. This can be seen as a
257        security risk if the plug-in is not trusted, or if someone manages
258        to replace the plug-in code with their own code. A malicious plugin can,
259        for example, delete the entire database if invoked by the root user.
260      </para>
261     
262      <para>
263        To limit this problem it is possible to tune the permissions for
264        a the plug-in so that it only has permission to do things that it
265        is supposed to do. For example, a plug-in that import reporters
266        may only need permission to update and create new reporter and
267        nothing else.
268      </para>
269   
270      <nohelp>
271      <para>
272        To enable the permission system for a plug-in go the
273        edit view of the plug-in and select the <guilabel>Permissions</guilabel>
274        tab.
275      </para>
276     
277      <figure id="plugins.figures.permissions">
278        <title>Setting permissions on a plug-in</title>
279        <screenshot>
280          <mediaobject>
281            <imageobject><imagedata 
282              fileref="figures/plugin_permissions.png" format="PNG"
283              /></imageobject>
284          </mediaobject>
285        </screenshot>
286      </figure>
287      </nohelp>
288
289      <variablelist>
290      <varlistentry>
291        <term><guilabel>Use permissions</guilabel></term>
292        <listitem>
293          <para>
294            Select if the plug-in should use the permission system
295            or not. If <guilabel>no</guilabel> is selected, the rest
296            of the form is disabled.
297          </para>
298        </listitem>
299      </varlistentry>
300      <varlistentry>
301        <term><guilabel>Item types</guilabel></term>
302        <listitem>
303          <para>
304            The list contains all item types found in BASE that
305            can have permissions set on them. The list is more or less the
306            same as the permission list for roles.
307            <nohelp>
308              See <xref linkend="user_administration.roles.edit.permissions" />.
309            </nohelp>
310          </para>
311        </listitem>
312      </varlistentry>
313      <varlistentry>
314        <term><guilabel>Always grant</guilabel></term>
315        <listitem>
316          <para>
317            The selected permissions will always be granted
318            to the plug-in no matter if the logged in user had the
319            permission to begin with or not. This makes it possible to
320            develop a plugin that allows users to do things that they
321            are normally not allowed to do. The reporter importer is
322            for example allowed to create and use reporter types.
323          </para>
324        </listitem>
325      </varlistentry>
326      <varlistentry>
327        <term><guilabel>Always deny</guilabel></term>
328        <listitem>
329          <para>
330            The selected permissions will always be denied
331            to the plug-in no matter if the logged in user had the
332            permission to begin with or not. The default is to always
333            deny all permissions. Permissions that are not always
334            denied and not always granted uses permissions from
335            the logged in user.
336          </para>
337        </listitem>
338      </varlistentry>
339      <varlistentry>
340        <term><guilabel>Requested by plug-in</guilabel></term>
341        <listitem>
342          <para>
343            To make it easier for the server administrator
344            to assign permissions, the plug-in developer can
345            let the plug-in include a list of permissions that
346            are needed. Plug-in developers are advised to
347            only include the minimal set of permissions that are
348            required for the plug-in to function. Click on the
349            <guibutton>Use requested permissions</guibutton>
350            button to give the plug-in the requested permissions.
351          </para>
352        </listitem>
353      </varlistentry>
354      </variablelist>
355   
356      <seeother>
357        <other external_id="plugindefinition.edit">Plugin properties</other>
358        <other external_id="role.edit.permissions">Role permissions</other>
359      </seeother>   
360    </helptext>
361   
362   
363  </sect1>
364
365
366  <sect1 id="plugins.jobagents">
367    <title>Job agents</title>
368    <para>
369      TODO - see also <xref linkend="installation_upgrade.jobagents" />.
370    </para>
371   
372   
373  </sect1>
374
375 
376  <sect1 id="plugins.configuration">
377    <title>Plug-in configurations</title>
378
379    <para>
380      While some plug-ins work right out of the box, some
381      may require configuration before they can be used. For example,
382      most of the core import plug-ins need configurations in the
383      form of regular expressions to be able to find headers and
384      data in the data files and the BASE 1 plug-in executer uses
385      configurations to store information about the BASE 1 plug-ins.
386    </para>
387
388    <para>
389      Configurations are managed from a plug-in's single-item view page
390      or from the
391      <menuchoice>
392        <guimenu>Administrate</guimenu>
393        <guisubmenu>Plugins</guisubmenu>
394        <guimenuitem>Configurations</guimenuitem>
395      </menuchoice>
396      page.
397    </para>
398   
399    <para>
400      Click on the <guibutton>New&hellip;</guibutton> button
401      to create a new configuration.
402    </para>
403   
404    <figure id="plugins.figures.configuration">
405      <title>Create plug-in configuration</title>
406      <screenshot>
407        <mediaobject>
408          <imageobject><imagedata 
409            fileref="figures/plugin_configuration.png" format="PNG"
410            /></imageobject>
411        </mediaobject>
412      </screenshot>
413    </figure>
414   
415    <helptext external_id="pluginconfiguration.edit" 
416      title="Edit plugin configuration">
417     
418      <variablelist>
419      <varlistentry>
420        <term><guilabel>Plugin</guilabel></term>
421        <listitem>
422          <para>
423            The plug-in this configuration belongs to. This can't
424            be changed for existing configurations. Use the
425            <guibutton>Select&hellip;</guibutton> button
426            to open a popup window where you can select a plug-in.
427          </para>
428        </listitem>
429      </varlistentry>
430      <varlistentry>
431        <term><guilabel>Name</guilabel></term>
432        <listitem>
433          <para>
434            The name of the configuration.
435          </para>
436        </listitem>
437      </varlistentry>
438      <varlistentry>
439        <term><guilabel>Description</guilabel></term>
440        <listitem>
441          <para>
442            A description of the configuration (optional).
443          </para>
444        </listitem>
445      </varlistentry>
446      </variablelist>
447     
448      <note>
449        You can't create configurations for plug-ins that
450        doesn't support being configured.
451      </note>
452   
453      <para>
454        Use the <guibutton>Save</guibutton> button to save the
455        configuration or the <guibutton>Save and configure</guibutton>
456        button to save and then start the configuration wizard.
457      </para>
458   
459    </helptext>
460   
461    <sect2 id="plugins.configuration.wizard">
462      <title>Configuring plug-in configurations</title>
463
464      <helptext external_id="runplugin.configure"
465        title="The plug-in configuration wizard">
466     
467      <para>
468        Configuring a plug-in is done with a wizard-like
469        interface. Since the configuration parameters may vary
470        from plug-in to plug-in BASE uses a generic interface
471        to enter parameter values. In short, it works like this:
472       
473        <orderedlist>
474          <listitem>
475            <para>
476              BASE asks the plug-in for information about
477              the parameters the plug-in needs. For example,
478              if the value is a string or number or should be
479              selected among a list of predefined values.
480            </para>
481          </listitem>
482         
483          <listitem>
484            <para>
485              BASE uses this information to create a generic form
486              for entering the values. The form consists of three
487              parts:
488             
489              <nohelp>
490              <figure id="plugins.figures.wizard">
491                <title>The plug-in configuration wizard</title>
492                <screenshot>
493                  <mediaobject>
494                    <imageobject><imagedata 
495                      fileref="figures/plugin_wizard.png" format="PNG"
496                      /></imageobject>
497                  </mediaobject>
498                </screenshot>
499              </figure>
500              </nohelp>
501             
502              <itemizedlist>
503              <listitem>
504                <para>
505                <emphasis>The top part</emphasis>: Displays
506                the name of the selected plug-in and configuration.
507                </para>
508              </listitem>
509             
510              <listitem>
511                <para>
512                <emphasis>The left part</emphasis>: Displays
513                a list of all parameters supported by the plug-in.
514                Parameters with an <guilabel>X</guilabel> in front
515                of their names already have a value. Parameters
516                marked with a blue rectangle are required and
517                must be given a value before it is possible to
518                proceed.
519                </para>
520              </listitem>
521             
522              <listitem>
523                <para>
524                <emphasis>The right part</emphasis>: Click on a parameter
525                in the list to display a form for entering values for
526                that parameter. The form may be a simple free text field,
527                a list of checkboxes or radiobuttons, or something else
528                depending on the kind of values supported by that
529                parameter.
530                </para>
531              </listitem>
532              </itemizedlist> 
533             
534            </para>
535          </listitem>
536
537          <listitem>
538            <para>
539              When the user clicks <guibutton>Next</guibutton>
540              the entered values are sent to the plug-in which
541              validate the correctness. The plug-in may return
542              three different replies:
543             
544              <itemizedlist>
545              <listitem>
546                <para>
547                <emphasis>ERROR</emphasis>:
548                There is an error in the input. BASE will redisplay
549                the same form with any additional error information that
550                the plug-in sends back.
551                </para>
552              </listitem>
553              <listitem>
554                <para>
555                <emphasis>DONE</emphasis>:
556                All parameter values are ok and no more values
557                are needed. BASE will save the values to the database
558                and finish the configuration wizard.
559                </para>
560              </listitem>
561              <listitem>
562                <para>
563                <emphasis>CONTINUE</emphasis>:
564                All parameter values are ok, but the plug-in
565                wants more parameters. The procedure is repeated from the
566                first step.
567                </para>
568              </listitem>
569              </itemizedlist>
570            </para>
571          </listitem>
572         
573        </orderedlist>
574      </para>
575
576      <note>
577        <title>Don't go back</title>
578        It is not possible to go backwards in the wizard.
579        If you try it will most likely result in an
580        unexpected error and the configuration must be restarted
581        from the beginning.
582      </note>
583     
584      <seeother>
585        <other external_id="runplugin.configure.import">Common parameter for import plug-ins</other>
586        <other external_id="runplugin.configure.export">Common parameter for export plug-ins</other>
587        <other external_id="runplugin.configure.analysis">Common parameter for analysis plug-ins</other>
588      </seeother>
589      </helptext>
590     
591    </sect2>
592
593    <sect2 id="plugins.configuration.core">
594      <title>Core plug-in configurations</title>
595    </sect2>
596
597   
598    <sect2 id="plugins.configuration.testwithfile">
599      <title>The <guilabel>Test with file</guilabel> function</title>
600     
601    </sect2>
602 
603  </sect1>
604 
605
606</chapter>
Note: See TracBrowser for help on using the repository browser.