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

Last change on this file since 3176 was 3176, checked in by Johan Enell, 16 years ago

added image

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 5.4 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    "http://www.cs.put.poznan.pl/dweiss/dtd/dweiss-docbook-extensions.dtd">
5<!--
6  $Id:
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="plugin_installation">
30  <title id="plugin_installation.title">Installing plugins</title>
31
32  <para>
33    We recommend that each plugin or group of related plugins are compiled separately. To be
34    able to use the plugin it must be put in a JAR file. Place the JAR file on the server
35    <emphasis>outside</emphasis>
36    the web servers classpath, ie. not in the
37    <filename class="directory">WEB-INF/lib</filename>
38    . Our recommendation is to place the plugin JAR in
39    <filename class="directory">
40      <replaceable>&lt;base-dir&gt;</replaceable>
41      /plugins/
42      <replaceable>&lt;name-of-plugin&gt;</replaceable>
43      /
44    </filename>
45  </para>
46  <mediaobject>
47    <imageobject>
48      <imagedata align="right" fileref="figures/install_plugin.png" format="PNG"/>
49    </imageobject>
50    <textobject>
51      <phrase>How to install a plugin</phrase>
52    </textobject>
53  </mediaobject>
54
55
56
57  <para>
58    The main benefit from placing the JAR file outside the classpath is that
59    Base uses it's own classloader that supports unloading of the classes as well.
60    This means that you may replace the JAR file with a new version without
61    restarting the web server.
62  </para>
63 
64  <para>
65    Then, to install the plugin log in a an administrator and go to the
66    <menuchoice>
67      <guimenu>Administrate</guimenu>
68      <guisubmenu>Plugins</guisubmenu>
69      <guimenuitem>Definitions</guimenuitem>
70    </menuchoice>
71    page. Click the
72    <guibutton>New</guibutton>
73    button and enter the class name and the path to the JAR file in the form that opens in the
74    popup window.
75  </para>
76
77  <para>
78    When you click save, the Base class loader will load the specified JAR file and class and
79    check that it implements the
80    <interfacename>Plugin</interfacename>
81    interface. Then, it creates an instance of that class, calls
82    <methodname>Plugin.getAbout()</methodname>
83    and
84    <methodname>Plugin.getMainType()</methodname>
85    . If it is an
86    <interfacename>InteractivePlugin</interfacename>
87    it will also call
88    <methodname>InteractivePlugin.getGuiContexts()</methodname>
89    . This information is stored in the database.
90  </para>
91
92  <para>
93    The installation will do one more thing. It will check which other interfaces the plugin
94    implements and check against the list of registered
95    <classname>PluginType</classname>
96    s. The
97    <classname>PluginType</classname>
98    system has not really been put into use yet. The core defines the
99    <interfacename>AutoDetectingImporter</interfacename>
100    which can be used for all import plugins that supports automatic detection of file formats.
101    Read more about this in the
102    <xref linkend="plugin_developer.import_plugins"/>
103    chapter.
104  </para>
105
106
107  <para>
108    Now the administrator may continue by creating a new configuration for the plugin (assuming
109    that is an
110    <interfacename>InteractivePlugin</interfacename>
111    ). When the administrator starts the configuration sequence the following will happen:
112  </para>
113
114  <itemizedlist>
115    <listitem>
116      <simpara>The core creates a new instance of the plugin.</simpara>
117    </listitem>
118    <listitem>
119      <simpara>
120        Call the
121        <methodname>Plugin.init</methodname>
122        () method.
123      </simpara>
124    </listitem>
125    <listitem>
126      <simpara>
127        Call the
128        <methodname>InteractivePlugin.getRequestInformation()</methodname>
129        method, with
130        <varname>command</varname>
131        <literal>=</literal>
132        <constant>Request.COMMAND_CONFIGURE_PLUGIN</constant>
133        and a null
134        <classname>GuiContext</classname>
135        .
136      </simpara>
137    </listitem>
138    <listitem>
139      <simpara>Display the list of parameters and let the user enter values.</simpara>
140    </listitem>
141    <listitem>
142      <simpara>
143        Call
144        <methodname>InteractivePlugin.configure()</methodname>
145        .
146      </simpara>
147    </listitem>
148    <listitem>
149      <simpara>
150        If the plugin wants more parameters the above two steps are repeated but with the
151        command returned in the response. Note! Be careful so you don't create infinite
152        loops.
153      </simpara>
154    </listitem>
155    <listitem>
156      <simpara>
157        If the plugin reports that it is done,
158        <methodsynopsis>
159          <methodname>done</methodname>
160          <void/>
161        </methodsynopsis>
162        <methodname>Plugin.done()</methodname>
163        is called and the plugin instance is discarded.
164      </simpara>
165    </listitem>
166  </itemizedlist>
167
168  <para>
169    The steps for creating a new job follows the same procedure except that the first command is
170    <classname>Request.</classname>
171    <constant>COMMAND_CONFIGURE_JOB</constant>
172    and the
173    <classname>GuiContext</classname>
174    isn't null.
175  </para>
176
177</chapter>
Note: See TracBrowser for help on using the repository browser.