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

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

fixed linkes
fixed some methodname tags

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