Context Navigation

source: branches/webservices/doc/src/docbook/developerdoc/plugin_developer.xml @ 3581

Visit:

Last change on this file since 3581 was 3581, checked in by Jari Häkkinen, 16 years ago
Merged log:trunk#3533:3580 into the wwebservices branch.
Property svn:eol-style set to `native` Property svn:keywords set to `Id`
File size: 120.3 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_developer.xml 3581 2007-07-20 06:23:48Z jari $:
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_developer">
30	<?dbhtml dir="plugin_developer"?>
31	<title>Plug-in developer</title>
32	<sect1 id="plugin_developer.organize">
33	<title>How to organize your plug-in project</title>
34
35	<sect2 id="plugin_developer.organize.ant">
36	<title>Using Ant</title>
37	<para>
38	Here is a simple example of how you might organize your project using ant
39	(<ulink url="http://ant.apache.org">http://ant.apache.org</ulink>) as the build
40	tool. This is just a recommendation that we have found to be working
41	well. You may choose to do it another way.
42	</para>
43
44	<sect3 id="plugin_developer.organize.ant.directories">
45	<title>Directory layout</title>
46	<para>
47
48	Create a directory on your computer where you want
49	to store your plug-in project. This directory is the
50	<filename class="directory"><replaceable>pluginname</replaceable>/</filename>
51	directory in the listing below. You should also create some subdirectories:
52
53	<literallayout>
54	<filename class="directory"><replaceable>pluginname</replaceable>/</filename>
55	<filename class="directory"><replaceable>pluginname</replaceable>/bin/</filename>
56	<filename class="directory"><replaceable>pluginname</replaceable>/lib/</filename>
57	<filename class="directory"><replaceable>pluginname</replaceable>/src/<replaceable>org/company</replaceable>/</filename>
58	</literallayout>
59	The
60	<filename class="directory">bin/</filename>
61	directory is empty to start with. It will contain the compiled code.
62	In the <filename class="directory">lib/</filename>
63	directory you should put <filename>BASE2Core.jar</filename>
64	and other library files your plug-in depends on. The
65	<filename class="directory">src/</filename>
66	directory contains your source code. In this directory you should create
67	subdirectories corresponding to the package name of your plug-in
68	class(es). See <ulink url="http://en.wikipedia.org/wiki/Java_package"
69	>http://en.wikipedia.org/wiki/Java_package</ulink> for information
70	about conventions for naming packages.
71	</para>
72	</sect3>
73
74	<sect3 id="plugin_developer.organize.ant.buildfile">
75	<title>The build file</title>
76	<para>
77	In the root of your directory, create the build file:
78	<filename>build.xml</filename>
79	. Here is an example that will compile your plug-in and put it in a JAR file.
80	</para>
81	<example id="plugin_developer.organize.build.file">
82	<title>A simple build file</title>
83	<programlisting><?xml version="1.0" encoding="UTF-8"?>
84	<project
85	name="MyPlugin"
86	default="build.plugin"
87	basedir="."
88	>
89
90	<!-- variables used -->
91	<property name="plugin.name" value="MyPlugin" />
92	<property name="src" value="src" />
93	<property name="bin" value="bin" />
94
95	<!-- set up classpath for compiling -->
96	<path id="classpath">
97	<fileset dir="lib">
98	<include name="*/.jar"/>
99	</fileset>
100	</path>
101
102
103	<!-- main target -->
104	<target
105	name="build.plugin"
106	description="Compiles the plug-in and put in jar"
107	>
108	<javac
109	encoding="ISO-8859-1"
110	srcdir="${src}"
111	destdir="${bin}"
112	classpathref="classpath">
113	</javac>
114	<jar
115	jarfile="${plugin.name}.jar"
116	basedir="bin"
117	manifest="MANIFEST.MF"
118	>
119	</jar>
120
121	</target>
122	</project> </programlisting>
123	</example>
124	<para>
125	If your plug-in depends on other JAR files than the
126	<filename>BASE2Core.jar</filename> you must create a file called
127	<filename>MANIFEST.MF</filename> in the project root directory.
128	List the other JAR files as in the following example.
129	If your plug-in does not depend on other JAR files, remove the
130	<sgmltag class="attribute">manifest</sgmltag>
131	attribute of the <sgmltag class="starttag">jar</sgmltag> tag.
132	<programlisting>Manifest-Version: 1.0
133	Class-Path: OtherJar.jar ASecondJar.jar</programlisting>
134	</para>
135	</sect3>
136
137	<sect3 id="plugin_developer.organize.ant.build">
138	<title>Building the plug-in</title>
139	<para>
140	Compile the plug-in simply by typing
141	<command>ant</command>
142	in the console window. If all went well the
143	<filename>MyPlugin.jar</filename>
144	will be created in the same directory.
145	</para>
146	<para>
147	To install the plug-in copy the JAR file to the server including the dependent JAR
148	files (if any). Place all files together in the same directory. For more
149	information read
150	<xref linkend="plugins.installation" />
151	</para>
152	</sect3>
153	</sect2>
154
155	<sect2 id="plugin_developer.organize.eclipse">
156	<title>With Eclipse</title>
157	<para>
158	If somebody is willing to add information to this
159	chapter please send us a note or some written text to put here.
160	Otherwise, this chapter will be removed.
161	</para>
162	</sect2>
163
164	</sect1>
165
166	<sect1 id="plugin_developer.api">
167	<title>The Plug-in API</title>
168	<para>
169	</para>
170
171	<sect2 id="plugin_developer.api.interfaces">
172
173	<title>The main plug-in interfaces</title>
174	<para>
175	The Base2 core defines two interfaces and one
176	abstract class that are vital for implementing plug-ins:
177	<itemizedlist spacing="compact">
178	<listitem>
179	<simpara>
180	<interfacename>net.sf.basedb.core.plugin.Plugin</interfacename>
181	</simpara>
182	</listitem>
183	<listitem>
184	<simpara>
185	<interfacename>net.sf.basedb.core.plugin.InteractivePlugin</interfacename>
186	</simpara>
187	</listitem>
188	<listitem>
189	<simpara>
190	<classname>net.sf.basedb.core.plugin.AbstractPlugin</classname>
191	</simpara>
192	</listitem>
193	</itemizedlist>
194
195	A plug-in must always implement the
196	<interfacename>Plugin</interfacename> interface.
197	The <interfacename>InteractivePlugin</interfacename>
198	interface is optional, and is only needed if you want user interaction.
199	The <classname>AbstractPlugin</classname> is a useful base class
200	that your plug-in can use as a superclass. It provides default implementations
201	for some of the interface methods and also has utility methods for
202	validating and storing job and configuration parameter values. Another
203	reason to use this class as a superclass is that it will shield your
204	plug-in from future changes to the Plug-in API. For example, if
205	we decide that a new method is needed in the <interfacename>Plugin</interfacename>
206	interface we will also try to add a default implementation in
207	the <classname>AbstractPlugin</classname> class.
208	</para>
209
210	<important>
211	<para>
212	A plug-in must also have public no-argument contructor. Otherwise, BASE will not
213	be able to create new instances of the plug-in class.
214	</para>
215	</important>
216
217	<sect3 id="plugin_developer.api.interfaces.plugin">
218	<title>The net.sf.basedb.core.plugin.Plugin interface</title>
219	<para>
220	This interface defines the following methods and must be implemented
221	by all plug-ins.
222	</para>
223	<variablelist>
224	<varlistentry>
225	<term>
226	<methodsynopsis language="java">
227	<modifier>public</modifier>
228	<type>About</type>
229	<methodname>getAbout</methodname>
230	<void />
231	</methodsynopsis>
232	</term>
233	<listitem>
234	<para>
235	Return information about the plug-in, i.e. the name, version, and a short
236	description about what the plug-in does. The
237	<classname>About</classname>
238	object also has fields for naming the author and various other contact
239	information. The returned information is copied by the core at
240	installation time into the database. The only required information is
241	the name of the plug-in. All other fields may have null values.
242	</para>
243	<example id="net.sf.basedb.core.plugin.Plugin.getAbout">
244	<title>A typical implementation stores this information in a static field</title>
245	<programlisting>private static final About about = new AboutImpl
246	(
247	"Spot images creator",
248	"Converts a full-size scanned image into smaller preview jpg " +
249	"images for each individual spot.",
250	"2.0",
251	"2006, Department of Theoretical Physics, Lund University",
252	null,
253	"base@thep.lu.se",
254	"http://base.thep.lu.se"
255	);
256
257	public About getAbout()
258	{
259	return about;
260	}</programlisting>
261	</example>
262	</listitem>
263	</varlistentry>
264	<varlistentry>
265	<term>
266	<methodsynopsis language="java">
267	<modifier>public</modifier>
268	<type>Plugin.MainType</type>
269	<methodname>getMainType</methodname>
270	<void />
271	</methodsynopsis>
272	</term>
273	<listitem>
274	<para>
275	Return information about the main type of plug-in. The
276	<classname>MainType</classname>
277	is an enumeration with five possible values:
278	<itemizedlist>
279	<listitem>
280	<para>
281	<constant>ANALYZE</constant>:
282	An analysis plug-in
283	</para>
284	</listitem>
285	<listitem>
286	<para>
287	<constant>EXPORT</constant>:
288	A plug-in that exports data
289	</para>
290	</listitem>
291	<listitem>
292	<para>
293	<constant>IMPORT</constant>:
294	A plug-in that imports data
295	</para>
296	</listitem>
297	<listitem>
298	<para>
299	<constant>INTENSITY</constant>:
300	A plug-in that calculates the original spot intensities
301	from raw data
302	</para>
303	</listitem>
304	<listitem>
305	<para>
306	<constant>OTHER</constant>:
307	Any other type of plug-in
308	</para>
309	</listitem>
310	</itemizedlist>
311	The returned value is stored in the database but is otherwise not used
312	by the core. Client applications (such as the web client) will probably
313	use this information to group the plug-ins, i.e., a button labeled
314	&gbExport;
315	will let you select among the export plug-ins.
316	</para>
317	<example id="net.sf.basedb.core.plugin.Plugin.getMainType">
318	<title>A typical implementation just return one of the values</title>
319	<programlisting>public Plugin.MainType getMainType()
320	{
321	return Plugin.MainType.OTHER;
322	}</programlisting>
323	</example>
324	</listitem>
325	</varlistentry>
326	<varlistentry>
327	<term>
328	<methodsynopsis language="java">
329	<modifier>public</modifier>
330	<type>boolean</type>
331	<methodname>supportsConfigurations</methodname>
332	<void />
333	</methodsynopsis>
334	</term>
335	<listitem>
336	<para>
337	If this method returns true, the plug-in can have different
338	configurations, (i.e.
339	<classname>PluginConfiguration</classname>).
340	Note that this method may return true even if the
341	<interfacename>InteractivePlugin</interfacename>
342	interface is not implemented. The
343	<classname>AbstractPlugin</classname>
344	returns true for this method, which is the old way before the
345	introduction of this method.
346	</para>
347	</listitem>
348	</varlistentry>
349	<varlistentry>
350	<term>
351	<methodsynopsis language="java">
352	<modifier>public</modifier>
353	<type>boolean</type>
354	<methodname>requiresConfiguration</methodname>
355	<void />
356	</methodsynopsis>
357	</term>
358	<listitem>
359	<para>
360	If this method returns true, the plug-in must have a configuration
361	to be able to run. For example, some of the core import plug-ins
362	must have information about the file format, to be able to import
363	any data.
364	The
365	<classname>AbstractPlugin</classname>
366	returns false for this method, which is the old way before the
367	introduction of this method.
368	</para>
369	</listitem>
370	</varlistentry>
371	<varlistentry>
372	<term>
373	<methodsynopsis language="java">
374	<modifier>public</modifier>
375	<type>Collection<Permissions></type>
376	<methodname>getPermissions</methodname>
377	<void />
378	</methodsynopsis>
379	</term>
380	<listitem>
381	<para>
382	Return a collection of permissions that the plug-in needs
383	to be able to function as expected. This method may return null
384	or an empty collection. In this case the plug-in permission system
385	isn't used and the plug-in always get the same permissions as the
386	logged in user. If permissions are specified the plug-in should
387	list all permissions it require. Permissions that are not listed
388	are denied.
389	</para>
390	<note>
391	<para>
392	The final assignment of permissions to a plug-in is always
393	at the hands of a server administrator. He/she may decide to
394	disable the plug-in permission system or revoke some of the
395	requested permissions. The permissions returned by this method is
396	only a recommendation that the server administrator may or may not
397	accept. See <xref linkend="plugins.permissions" />
398	for more information about plug-in permissions.
399	</para>
400	</note>
401	</listitem>
402	</varlistentry>
403	<varlistentry>
404	<term>
405	<methodsynopsis language="java">
406	<modifier>public</modifier>
407	<void />
408	<methodname>init</methodname>
409	<methodparam>
410	<type>SessionControl</type>
411	<parameter>sc</parameter>
412	</methodparam>
413	<methodparam>
414	<type>ParameterValues</type>
415	<parameter>configuration</parameter>
416	</methodparam>
417	<methodparam>
418	<type>ParameterValues</type>
419	<parameter>job</parameter>
420	</methodparam>
421	<exceptionname>BaseException</exceptionname>
422	</methodsynopsis>
423	</term>
424	<listitem>
425	<para>
426	Prepare the plug-in for execution or configuration. If the plug-in needs
427	to do some initialization this is the place to do it. A typical
428	implementation however only stores the passed parameters in instance
429	variables for later use. Since it is not possible what the user is going to
430	do at this stage, we recommend lazy initialisation of all other resources.
431	</para>
432	<para>
433	The parameters passed to this method has vital information that is
434	needed to execute the plug-in. The
435	<classname>SessionControl</classname>
436	is a central core object holding information about the logged in
437	user and is used to create
438	<classname>DbControl</classname>
439	objects which allows a plug-in to connect to the database to read, add or
440	update information. The two
441	<classname>ParameterValues</classname>
442	objects contain information about the configuration and job
443	parameters to the plug-in.
444	The <varname>configuration</varname> object holds all parameters stored
445	together with a <classname>PluginConfiguration</classname>
446	object in the database. If the plug-in is started without
447	a configuration this object is null.
448	The <varname>job</varname> object holds all parameters that are
449	stored together with a <classname>Job</classname> object in the
450	database. This object is null if the plug-in is started without a job.
451	</para>
452	<para>
453	The difference between a configuration parameter and a job parameter is
454	that a configuration is usually something an administrator sets up,
455	while a job is an actual execution of a plug-in. For example, a
456	configuration for an import plug-in holds the regular expressions needed
457	to parse a text file and find the headers, sections and data lines,
458	while the job holds the file to parse.
459	</para>
460	<para>
461	The
462	<classname>AbstractPlugin</classname>
463	contains an implementation of this method that saves the passed objects
464	in protected instance variables. If you override this method
465	we recommend that you also call <code>super.init()</code>.
466	</para>
467	<example id="net.sf.basedb.core.plugin.Plugin.init">
468	<title>The <classname>AbstractPlugin</classname> implementation of Plugin.init()</title>
469	<programlisting>protected SessionControl sc = null;
470	protected ParameterValues configuration = null;
471	protected ParameterValues job = null;
472	/**
473	Store copies of the session control, plug-in and job configuration. These
474	are available to subclasses in the {@link #sc}, {@link #configuration}
475	and {@link #job} variables. If a subclass overrides this method it is
476	recommended that it also calls super.init(sc, configuration, job).
477	*/
478	public void init(SessionControl sc,
479	ParameterValues configuration, ParameterValues job)
480	throws BaseException
481	{
482	this.sc = sc;
483	this.configuration = configuration;
484	this.job = job;
485	}</programlisting>
486	</example>
487	</listitem>
488	</varlistentry>
489	<varlistentry>
490	<term>
491	<methodsynopsis language="java">
492	<modifier>public</modifier>
493	<void />
494	<methodname>run</methodname>
495	<methodparam>
496	<type>Request</type>
497	<parameter>request</parameter>
498	</methodparam>
499	<methodparam>
500	<type>Response</type>
501	<parameter>response</parameter>
502	</methodparam>
503	<methodparam>
504	<type>ProgressReporter</type>
505	<parameter>progress</parameter>
506	</methodparam>
507	</methodsynopsis>
508	</term>
509	<listitem>
510	<para>
511	Run the plug-in.
512	</para>
513	<para>
514	The <varname>request</varname>
515	parameter is of historical interest only. It has no useful information
516	and can be ignored.
517	</para>
518	<para>
519	The <varname>progress</varname> parameter
520	can be used by a plug-in to report it's progress back to the core. The
521	core will usually send the progress information to the database, which
522	allows users to see exactly how the plug-in is progressing from the web
523	interface. This parameter can be null, but if it is not we recommend all
524	plug-ins to use it. However, it should be used sparingly, since each call
525	to set the progress results in a database update. If the execution
526	involves several thousands of items it is a bad idea to update the
527	progress after processing each one of them. A good starting point is to
528	divide the work into 100 pieces each representing 1% of the work, i.e.,
529	if the plug-in should export 100 000 items it should report progress
530	after every 1000 items.
531	</para>
532	<para>
533	The <varname>response</varname>
534	parameter is used to tell the core if the plug-in was successful or
535	failed. Not setting a response is considered a failure by the core. From
536	the run method it is only allowed to use the
537	<methodname>Response.setDone()</methodname>
538	or the
539	<methodname>Response.setError()</methodname>
540	methods.
541	</para>
542
543	<important>
544	It is also considered bad practice to let exceptions escape
545	out from this method. Always use <code>try...catch</code>
546	to catch exceptions and use <code>Response.setError()</code>
547	to reporter the error back to the core.
548	</important>
549
550	<example id="net.sf.basedb.core.plugin.Plugin.run">
551	<title>
552	Here is a skeleton that we recommend each plug-in to use in it's
553	implementation of the
554	<methodname>run()</methodname>
555	method
556	</title>
557	<programlisting>public void run(Request request, Response response, ProgressReporter progress)
558	{
559	// Open a connection to the database
560	// sc is set by init() method
561	DbControl dc = sc.newDbControl();
562	try
563	{
564	// Insert code for plug-in here
565
566	// Commit the work
567	dc.commit();
568	response.setDone("Plug-in ended successfully");
569	}
570	catch (Throwable t)
571	{
572	// All exceptions must be catched and sent back
573	// using the response object
574	response.setError(t.getMessage(), Arrays.asList(t));
575	}
576	finally
577	{
578	// IMPORTANT!!! Make sure opened connections are closed
579	if (dc != null) dc.close();
580	}
581	}</programlisting>
582	</example>
583	</listitem>
584	</varlistentry>
585	<varlistentry>
586	<term>
587	<methodsynopsis language="java">
588	<modifier>public</modifier>
589	<void />
590	<methodname>done</methodname>
591	<void />
592	</methodsynopsis>
593	</term>
594	<listitem>
595	<para>
596	Clean up all resources after executing the plug-in. This method must not
597	throw any exceptions.
598	</para>
599	<example id="net.sf.basedb.core.plugin.Plugin.done">
600	<title>
601	The
602	<classname>AbstractPlugin</classname>
603	contains an implementation of the <methodname>done()</methodname>
604	method simply sets the
605	parameters passed to the
606	<methodname>init()</methodname>
607	method to null
608	</title>
609	<programlisting>/**
610	Clears the variables set by the init method. If a subclass
611	overrides this method it is recommended that it also calls super.done().
612	*/
613	public void done()
614	{
615	configuration = null;
616	job = null;
617	sc = null;
618	}</programlisting>
619	</example>
620	</listitem>
621	</varlistentry>
622	</variablelist>
623	</sect3>
624
625	<sect3 id="plugin_developer.api.interfaces.interactive">
626	<title>The net.sf.basedb.core.plugin.InteractivePlugin interface</title>
627	<para>
628	If you want the plug-in to be able to interact with the user you must also implement
629	this interface. This is probably the case for most plug-ins. Among the core plug-ins
630	shipped with BASE the
631	<classname>SpotImageCreator</classname>
632	is one plug-in that does not interact with the user. Instead, the web client has
633	special JSP pages that handles all the interaction, creates a job for it and sets
634	the parameters. This, kind of hardcoded, approach can also be used for other
635	plug-ins, but then it usually requires modification of the client application
636	as well.
637	</para>
638	<para>
639	The
640	<interfacename>InteractivePlugin</interfacename>
641	has three main tasks:
642
643	<orderedlist>
644	<listitem>
645	<para>
646	Tell a client application where the plug-in should be plugged
647	in.
648	</para>
649	</listitem>
650	<listitem>
651	<para>
652	Ask the users for configuration and job parameters.
653	</para>
654	</listitem>
655
656	<listitem>
657	<para>
658	Validate parameter values entered by the user and store those in the
659	database.
660	</para>
661	</listitem>
662	</orderedlist>
663	This requires that the following methods are
664	implemented.
665	</para>
666
667	<variablelist>
668	<varlistentry>
669	<term>
670	<methodsynopsis language="java">
671	<modifier>public</modifier>
672	<type>Set<GuiContext></type>
673	<methodname>getGuiContexts</methodname>
674	<void />
675	</methodsynopsis>
676	</term>
677	<listitem>
678	<para>
679	Return information about where the plug-in should be plugged in. Each
680	place is identified by a
681	<classname>GuiContext</classname>
682	object, which is an
683	<classname>Item</classname>
684	and a
685	<classname>Type</classname>.
686	The item is one of the objects defined by the
687	<classname>net.sf.basedb.core.Item</classname>
688	enumeration and the type is either
689	<constant>Type.LIST</constant>
690	or
691	<constant>Type.ITEM</constant>, which corresponde to the
692	list view and the single-item view in the web client.
693	</para>
694	<para>
695	For example, the
696	<varname>GuiContext</varname> =
697	(<constant>Item.REPORTER</constant>,
698	<constant>Type.LIST</constant>)
699	tells a client application that this plug-in can be plugged in whenever a
700	list of reporters is displayed. The
701	<varname>GuiContext</varname> =
702	(<constant>Item.REPORTER</constant>,
703	<constant>Type.ITEM</constant>)
704	tells a client application that this plug-in can be plugged in whenever
705	a single reporter is displayed. The first case may be appropriate for a
706	plug-in that imports or exports reporters. The second case may be used by
707	a plug-in that updates the reporter information from an external source
708	(well, it may make sense to use this in the list case as well).
709	</para>
710	<para>
711	The returned information is copied by the core at installation time to
712	make it easy to ask for all plug-ins for a certain
713	<classname>GuiContext</classname>.
714	</para>
715	<para>
716	A typical implementation creates a static unmodifiable
717	<classname>Set</classname>
718	which is returned by this method. It is important that the returned set
719	cannot be modified. It may be a security issue if a misbehaving
720	client application does that.
721	</para>
722	<example id="net.sf.basedb.core.plugin.InteractivePlugin.getGuiContexts">
723	<title>
724	A typical implementation of
725	<methodname>getGuiContexts</methodname>
726	</title>
727	<programlisting>// From the net.sf.basedb.plugins.RawDataFlatFileImporter plug-in
728	private static final Set<GuiContext> guiContexts =
729	Collections.singleton(new GuiContext(Item.RAWBIOASSAY, GuiContext.Type.ITEM));
730
731	public Set<GuiContext> <methodname>getGuiContexts</methodname>()
732	{
733	return <returnvalue>guiContexts</returnvalue>;
734	}</programlisting>
735	</example>
736	</listitem>
737	</varlistentry>
738	<varlistentry>
739	<term>
740	<methodsynopsis language="java">
741	<modifier>public</modifier>
742	<type>String</type>
743	<methodname>isInContext</methodname>
744	<methodparam>
745	<type>GuiContext</type>
746	<parameter>context</parameter>
747	</methodparam>
748	<methodparam>
749	<type>Object</type>
750	<parameter>item</parameter>
751	</methodparam>
752	</methodsynopsis>
753	</term>
754	<listitem>
755	<para>
756	This method is called to check if a particular item is usable for the
757	plug-in. This method is invoked to check if a plug-in can be used
758	in a given context. If invoked from a list context the <parameter>item</parameter>
759	parameter is <constant>null</constant>.
760	The plug-in should return <constant>null</constant> if it
761	finds that it can be used. If the plug-in can't be used it
762	must decide if the reason should be a warning or an error condition.
763	</para>
764
765	<para>
766	A warning is issued by returning a string with the warning
767	message. It should be used when the plug-in can't be used because
768	it is unrelated to the current task. For example, a plug-in for
769	importing Genepix data should return a warning when somebody wants
770	to import data to an Agilent raw bioassay.
771	</para>
772
773	<para>
774	An error message is issued by throwing an exception. This
775	should be used when the plug-in is related to the current task
776	but still can't do what it is supposed to do. For example,
777	trying to import raw data if the logged in user doesn't have
778	write permission to the raw bioassay.
779	</para>
780
781	<para>
782	As a rule of thumb, if there is a chance that another plug-in
783	might be able to perform the same task a warning should be used.
784	If it is guaranteed that no other plug-in can do it an error
785	message should be used.
786	</para>
787
788	<note>
789	<para>
790	The contract of this method was changed in in BASE 2.4
791	to allow warning and error level message. Prior to BASE
792	2.4 all messages were treated as error message. We recommend
793	that existing plug-ins are updated to throw exception to indicate
794	error-level messages since the default is to not show
795	warning messages to users.
796	</para>
797	</note>
798
799	<para>
800	Here is a real example from the
801	<classname>RawDataFlatFileImporter</classname>
802	plug-in which imports raw data to a
803	<classname>RawBioAssay</classname>.
804
805	Thus,
806	<varname>GuiContext</varname> =
807	(<constant>Item.RAWBIOASSAY</constant>,
808	<constant>Type.ITEM</constant>),
809
810	but the plug-in can only import data if the logged in user has write permission,
811	there is no data already, and
812	if the raw bioassay has the same raw data type as the plug-in has been
813	configured for.
814	</para>
815	<example id="net.sf.basedb.core.plugin.InteractivePlugin.isInContext">
816	<title>
817	A simple implementation of
818	<methodname>isInContext</methodname>
819	</title>
820	<programlisting>/**
821	Returns null if the item is a {@link RawBioAssay} of the correct
822	{@link RawDataType} and doesn't already have spots.
823	@throws PermissionDeniedException If the raw bioasssay already has raw data
824	or if the logged in user doesn't have write permission
825	*/
826	public String isInContext(GuiContext context, Object item)
827	{
828	String message = null;
829	if (item == null)
830	{
831	message = "The object is null";
832	}
833	else if (!(item instanceof RawBioAssay))
834	{
835	message = "The object is not a RawBioAssay: " + item;
836	}
837	else
838	{
839	RawBioAssay rba = (RawBioAssay)item;
840	String rawDataType = (String)configuration.getValue("rawDataType");
841	RawDataType rdt = rba.getRawDataType();
842	if (!rdt.getId().equals(rawDataType))
843	{
844	message = "Unsupported raw data type: " + rba.getRawDataType().getName();
845	}
846	else if (!rdt.isStoredInDb())
847	{
848	message = "Raw data for raw data type '" + rdt + "' is not stored in the database";
849	}
850	else if (rba.hasData())
851	{
852	throw new PermissionDeniedException("The raw bioassay already has data.");
853	}
854	else
855	{
856	rba.checkPermission(Permission.WRITE);
857	}
858	}
859	return message;
860	}</programlisting>
861	</example>
862	</listitem>
863	</varlistentry>
864	<varlistentry>
865	<term>
866	<methodsynopsis language="java">
867	<modifier>public</modifier>
868	<type>RequestInformation</type>
869	<methodname>getRequestInformation</methodname>
870	<methodparam>
871	<type>GuiContext</type>
872	<parameter>context</parameter>
873	</methodparam>
874	<methodparam>
875	<type>String</type>
876	<parameter>command</parameter>
877	</methodparam>
878	<exceptionname>BaseException</exceptionname>
879	</methodsynopsis>
880	</term>
881	<listitem>
882	<para>
883	Ask the plug-in for parameters that needs to be entered by the user. The
884	<classname>GuiContext</classname>
885	parameter is one of the contexts returned by the
886	<methodname>getGuiContexts</methodname>
887	method. The command is a string telling the plug-in what command was
888	executed. There are two predefined commands but as you will see the
889	plug-in may define it's own commands. The two predefined commands are
890	defined in the
891	<classname>net.sf.basedb.core.plugin.Request</classname>
892	class.
893	<variablelist>
894	<varlistentry>
895	<term>
896	<constant>Request.COMMAND_CONFIGURE_PLUGIN</constant>
897	</term>
898	<listitem>
899	<para>
900	Used when an administrator is initiating a configuration
901	of the plug-in.
902	</para>
903	</listitem>
904	</varlistentry>
905	<varlistentry>
906	<term>
907	<constant>Request.COMMAND_CONFIGURE_JOB</constant>
908	</term>
909	<listitem>
910	<para>
911	Used when a user has selected the plug-in for running a
912	job.
913	</para>
914	</listitem>
915	</varlistentry>
916	</variablelist>
917	Given this information the plug-in must return a
918	<classname>RequestInformation</classname>
919	object. This is simply a title, a description, and a list of parameters.
920	Usually the title will end up as the input form title and the
921	description as a help text for the entire form. Do not put information
922	about the individual parameters in this description, since each
923	parameter has a description of its own.
924	</para>
925	<example id="net.sf.basedb.core.plugin.InteractivePlugin.getRequestInformation">
926	<title>
927	When running an import plug-in it needs to ask for the file to import
928	from and if existing items should be updated or not
929	</title>
930	<programlisting >// The complete request information
931	private RequestInformation configure Job;
932
933	// The parameter that asks for a file to import from
934	private PluginParameter<File> file Parameter;
935
936	// The parameter that asks if existing items should be updated or not
937	private PluginParameter<Boolean> updateExistingParameter;
938
939	public RequestInformation getRequestInformation(GuiContext context, String command)
940	throws BaseException
941	{
942	RequestInformation requestInformation = null;
943	if (command.equals(Request.COMMAND_CONFIGURE_PLUGIN))
944	{
945	requestInformation = getConfigurePlugin();
946	}
947	else if (command.equals(Request.COMMAND_CONFIGURE_JOB))
948	{
949	requestInformation = getConfigureJob();
950	}
951	return requestInformation;
952	}
953
954	/**
955	Get (and build) the request information for starting a job.
956	*/
957	private RequestInformation getConfigureJob()
958	{
959	if (configureJob == null)
960	{
961	fileParameter = new PluginParameter<File>(
962	"file",
963	"File",
964	"The file to import the data from",
965	new FileParameterType(null, true, 1)
966	);
967
968	updateExistingParameter = new PluginParameter<Boolean>(
969	"updateExisting",
970	"Update existing items",
971	"If this option is selected, already existing items will be updated " +
972	" with the information in the file. If this option is not selected " +
973	" existing items are left untouched.",
974	new BooleanParameterType(false, true)
975	);
976
977	List<PluginParameter<?>> parameters =
978	new ArrayList<PluginParameter<?>>(2);
979	parameters.add(fileParameter);
980	parameters.add(updateExistingParameter);
981
982	configureJob = new RequestInformation
983	(
984	Request.COMMAND_CONFIGURE_JOB,
985	"Select a file to import items from",
986	"Description",
987	parameters
988	);
989	}
990	return configureJob;
991	}</programlisting>
992	</example>
993	<para>
994	As you can see it takes a lot of code to put together a
995	<classname>RequestInformation</classname>
996	object. For each parameter you need one
997	<classname>PluginParameter</classname>
998	object and one
999	<classname>ParameterType</classname>
1000	object. To make life a little easier, a
1001	<classname>ParameterType</classname>
1002	can be reused for more than one
1003	<classname>PluginParameter</classname>.
1004	</para>
1005
1006	<programlisting>StringParameterType stringPT = new StringParameterType(255, null, true);
1007	PluginParameter one = new PluginParameter("one", "One", "First string", stringPT);
1008	PluginParameter two = new PluginParameter("two", "Two", "Second string", stringPT);
1009	// ... and so on</programlisting>
1010	<para>
1011	The
1012	<classname>ParameterType</classname>
1013	is an abstract base class for several subclasses each implementing a
1014	specific type of parameter. The list of subclasses may grow in the
1015	future, but here are the most important ones currently implemented.
1016	</para>
1017	<note>
1018	<para>
1019	Most parameter types include support for supplying a predefined list
1020	of options to select from. In that case the list will be displayed
1021	as a drop-down list for the user, otherwise a free input field is
1022	used.
1023	</para>
1024	</note>
1025	<variablelist>
1026	<varlistentry>
1027	<term>
1028	<classname>StringParameterType</classname>
1029	</term>
1030	<listitem>
1031	<para>
1032	Asks for a string value. Includes an option for
1033	specifying the maximum length of the string.
1034	</para>
1035	</listitem>
1036	</varlistentry>
1037	<varlistentry>
1038	<term>
1039	<classname>FloatParameterType</classname>,
1040	<classname>DoubleParameterType</classname>,
1041	<classname>IntegerParameterType</classname>,
1042	<classname>LongParameterType</classname>
1043	</term>
1044	<listitem>
1045	<para>
1046	Asks for numerical values. Includes options for
1047	specifying a range (min/max) of allowed values.
1048	</para>
1049	</listitem>
1050	</varlistentry>
1051	<varlistentry>
1052	<term>
1053	<classname>BooleanParameterType</classname>
1054	</term>
1055	<listitem>
1056	<para>Asks for a boolean value.
1057	</para>
1058	</listitem>
1059	</varlistentry>
1060	<varlistentry>
1061	<term>
1062	<classname>DateParameterType</classname>
1063	</term>
1064	<listitem>
1065	<para>Asks for a date.
1066	</para>
1067	</listitem>
1068	</varlistentry>
1069	<varlistentry>
1070	<term>
1071	<classname>FileParameterType</classname>
1072	</term>
1073	<listitem>
1074	<para>Asks for a file item.
1075	</para>
1076	</listitem>
1077	</varlistentry>
1078	<varlistentry>
1079	<term>
1080	<classname>ItemParameterType</classname>
1081	</term>
1082	<listitem>
1083	<para>
1084	Asks for any other item. This parameter type requires
1085	that a list of options is supplied, except when the item
1086	type asked for matches the current <classname>GuiContext</classname>, in which
1087	case the currently selected item is used as the
1088	parameter value.
1089	</para>
1090	</listitem>
1091	</varlistentry>
1092	<varlistentry>
1093	<term>
1094	<classname>PathParameterType</classname>
1095	</term>
1096	<listitem>
1097	<para>
1098	Ask for a path to a file or directory. The path may be
1099	non-existing and should be used when a plug-in needs an
1100	output destination, i.e., the file to export to, or a
1101	directory where the output files should be placed.
1102	</para>
1103	</listitem>
1104	</varlistentry>
1105	</variablelist>
1106	<para>
1107	You can also create a
1108	<classname>PluginParameter</classname>
1109	with a null name and
1110	<classname>ParameterType</classname>.
1111	In this case, the web client will not ask for input from the user, instead
1112	it is used as a section header, allowing you to group parameters into
1113	different sections which increase the readability of the input
1114	parameters page.
1115	</para>
1116	<programlisting>PluginParameter firstSection = new PluginParameter(null, "First section", null, null);
1117	PluginParameter secondSection = new PluginParameter(null, "Second section", null, null);
1118	// ...
1119
1120	parameters.add(firstSection);
1121	parameters.add(firstParameterInFirstSection);
1122	parameters.add(secondParameteInFirstSection);
1123
1124	parameters.add(secondSection);
1125	parameters.add(firstParameterInSecondSection);
1126	parameters.add(secondParameteInSecondSection);</programlisting>
1127	</listitem>
1128	</varlistentry>
1129	<varlistentry>
1130	<term>
1131	<methodsynopsis language="java">
1132	<modifier>public</modifier>
1133	<void />
1134	<methodname>configure</methodname>
1135	<methodparam>
1136	<type>GuiContext</type>
1137	<parameter>context</parameter>
1138	</methodparam>
1139	<methodparam>
1140	<type>Request</type>
1141	<parameter>request</parameter>
1142	</methodparam>
1143	<methodparam>
1144	<type>Response</type>
1145	<parameter>response</parameter>
1146	</methodparam>
1147	</methodsynopsis>
1148	</term>
1149	<listitem>
1150	<para>
1151	Sends parameter values entered by the user for processing by the plug-in.
1152	The plug-in must validate that the parameter values are
1153	correct and then store them in database.
1154	</para>
1155
1156	<important>
1157	<para>
1158	No validation is done by the core, except converting the input to the
1159	correct object type, i.e. if the plug-in asked for a
1160	<classname>Float</classname>
1161	the input string is parsed and converted to a
1162	<classname>Float</classname>. If you have extended the
1163	<classname>AbstractPlugin</classname>
1164	class it is very easy to validate the parameters with the
1165	<methodname>validateRequestParameters()</methodname>
1166	method. This method takes the same list of
1167	<classname>PluginParameter</classname>:s
1168	as used in the
1169	<classname>RequestInformation</classname>
1170	object and uses that information for validation. It returns null or a
1171	list of
1172	<exceptionname>Throwable</exceptionname>:s that can be
1173	given directly to the <code>response.setError()</code>
1174	methods.
1175	</para>
1176	</important>
1177	<para>
1178	When the parameters have been validated, they need to be stored
1179	in the database. Once again, it is very easy, if you use one of the
1180	<methodname>AbstractPlugin.storeValue()</methodname>
1181	or
1182	<methodname>AbstractPlugin.storeValues()</methodname>
1183	methods.
1184	</para>
1185	<para>
1186	The configure method works much like the <methodname>Plugin.run()</methodname>
1187	method. It must return the result in the <classname>Response</classname> object,
1188	and should not throw any exceptions.
1189	</para>
1190
1191	<example id="net.sf.basedb.core.plugin.InteractivePlugin.configure">
1192	<title>
1193	Configuration implementation building on the examples above
1194	</title>
1195	<programlisting>public void configure(GuiContext context, Request request, Response response)
1196	{
1197	String command = request.getCommand();
1198	try
1199	{
1200	if (command.equals(Request.COMMAND_CONFIGURE_PLUGIN))
1201	{
1202	// TODO
1203	}
1204	else if (command.equals(Request.COMMAND_CONFIGURE_JOB))
1205	{
1206	// Validate user input
1207	List<Throwable> errors =
1208	validateRequestParameters(getConfigureJob().getParameters(), request);
1209	if (errors != null)
1210	{
1211	response.setError(errors.size() +
1212	" invalid parameter(s) were found in the request", errors);
1213	return;
1214	}
1215
1216	// Store user input
1217	storeValue(job, request, fileParameter);
1218	storeValue(job, request, updateExistingParameter);
1219
1220	// We are happy and done
1221	response.setDone("Job configuration complete", Job.ExecutionTime.SHORT);
1222	// TODO - check file size to make a better estimate of execution time
1223	}
1224	}
1225	catch (Throwable ex)
1226	{
1227	response.setError(ex.getMessage(), Arrays.asList(ex));
1228	}
1229	}</programlisting>
1230	</example>
1231
1232	<para>
1233	Note that the call to
1234	<methodname>response.setDone()</methodname>
1235	has a second parameter
1236	<constant>Job.ExecutionTime.SHORT</constant>. It is an indication
1237	about how long time it will take to execute the
1238	plug-in. This is of interest for job queue managers which probably
1239	does not want to start too many long-running jobs at the same time
1240	blocking the entire system. Please try to use this parameter wisely and
1241	not use <constant>Job.ExecutionTime.SHORT</constant>
1242	out of old habit all the time.
1243	</para>
1244	<para>
1245	The <classname>Response</classname> class also has a
1246	<methodname>setContinue()</methodname>
1247	method which tells the core that the plug-in needs more parameters,
1248	i.e. the core will then call
1249	<methodname>getRequestInformation()</methodname>
1250	again with the new command, let the user enter values, and then call
1251	<methodname>configure()</methodname>
1252	with the new values. This process is repeated until the plug-in
1253	reports that it is done or an error occurs.
1254	</para>
1255	<para>
1256	An important note is that during this iteration it is the same instance
1257	of the plug-in that is used. However, no parameter values are stored in
1258	the database until the plugin sends a
1259	<methodname>response.setDone()</methodname>.
1260	After that, the plug-in instance is usually discarded, and a job is placed
1261	in the job queue. The execution of the plug-in happens in a new instance
1262	and maybe on a different server.
1263	</para>
1264	<tip>
1265	<para>
1266	You do not have to store all values the plug-in asked for in the
1267	first place. You may even choose to store different values than
1268	those that were entered. For example, you might ask for the mass
1269	and height of a person and then only store the body mass index,
1270	which is calculated from those values.
1271	</para>
1272	</tip>
1273	</listitem>
1274	</varlistentry>
1275	</variablelist>
1276	</sect3>
1277
1278	</sect2>
1279
1280	<sect2 id="plugin_developer.api.callsequence">
1281	<title>How the BASE core interacts with the plug-in when...</title>
1282
1283	<para>
1284	This section describes how the BASE core interacts with the
1285	plug-in in a number of use cases. We will outline the
1286	order the methods are invoked on the plug-in.
1287	</para>
1288
1289	<sect3 id="plugin_developer.api.callsequence.install">
1290	<title>Installing a plug-in</title>
1291
1292	<para>
1293	When a plug-in is installed the core is eager to find out
1294	information about the plug-in. To do this it calls the
1295	following methods in this order:
1296	</para>
1297
1298	<orderedlist>
1299	<listitem>
1300	<para>
1301	A new instance of the plug-in class is created. The plug-in must
1302	have a public no-argument constructor.
1303	</para>
1304	</listitem>
1305
1306	<listitem>
1307	<para>
1308	Calls are made to <methodname>Plugin.getMainType()</methodname>,
1309	<methodname>Plugin.supportsConfigurations()</methodname>,
1310	<methodname>Plugin.requiresConfiguration()</methodname> and
1311	<methodname>Plugin.getAbout()</methodname> to find out information
1312	about the plug-in. This is the only time theese methods are called.
1313	The information that is returned by them are copied and stored in
1314	the database for easy access.
1315	</para>
1316
1317	<note>
1318	<para>
1319	The <methodname>Plugin.init()</methodname> method is
1320	never called during plug-in installation.
1321	</para>
1322	</note>
1323	</listitem>
1324
1325	<listitem>
1326	<para>
1327	If the plug-in implements the <interfacename>InteractivePlugin</interfacename>
1328	interface the <methodname>InteractivePlugin.getGuiContexts()</methodname>
1329	method is called. This is the only time this method is called and the information it
1330	returns are copied and stored in the database.
1331	</para>
1332	</listitem>
1333
1334	<listitem>
1335	<para>
1336	If the server admin decided to use the plug-in permission system, the
1337	<methodname>Plugin.getPermissions()</methodname> method is called.
1338	The returned information is copied and stored in the database.
1339	</para>
1340	</listitem>
1341
1342	</orderedlist>
1343	</sect3>
1344
1345	<sect3 id="plugin_developer.api.callsequence.configure">
1346	<title>Configuring a plug-in</title>
1347
1348	<para>
1349	The plug-in must implement the <interfacename>InteractivePlugin</interfacename>
1350	interface and the <methodname>Plugin.supportsConfigurations()</methodname> method
1351	must return <constant>TRUE</constant>. The configuration is done with
1352	a wizard-like interface (see <xref linkend="plugins.configuration.wizard" />).
1353	The same plug-in instance is used throughout the entire configuration sequence.
1354	</para>
1355
1356	<orderedlist>
1357	<listitem>
1358	<para>
1359	A new instance of the plug-in class is created. The plug-in must
1360	have a public no-argument constructor.
1361	</para>
1362	</listitem>
1363
1364	<listitem>
1365	<para>
1366	The <methodname>Plugin.init()</methodname> method is called. The
1367	<varname>job</varname> parameter is null.
1368	</para>
1369	</listitem>
1370
1371	<listitem id="plugin_developer.api.callsequence.configure.requestinformation">
1372	<para>
1373	The <methodname>InteractivePlugin.getRequestInformation()</methodname>
1374	method is called. The <varname>context</varname> parameter is <constant>null</constant>
1375	and the <varname>command</varname> is the value of the string
1376	constant <constant>Request.COMMAND_CONFIGURE_PLUGIN</constant>
1377	(_config_plugin).
1378	</para>
1379	</listitem>
1380
1381	<listitem id="plugin_developer.api.callsequence.configure.form">
1382	<para>
1383	The web client process this information and displays a form for user
1384	input. The plug-in will have to wait some time while the user enters
1385	data.
1386	</para>
1387	</listitem>
1388
1389	<listitem>
1390	<para>
1391	The <methodname>InteractivePlugin.configure()</methodname> method
1392	is called. The <varname>context</varname> parameter is still
1393	<constant>null</constant> and the <varname>request</varname>
1394	parameter contains the parameter values entered by the user.
1395	</para>
1396	</listitem>
1397
1398	<listitem>
1399	<para>
1400	The plug-in must validate the values and decide whether they should be
1401	stored in the database or not. We recommend that you use the
1402	methods in the <classname>AbstractPlugin</classname> class for this.
1403	</para>
1404	</listitem>
1405
1406	<listitem>
1407	<para>
1408	The plug-in can choose between three different respones:
1409
1410	<itemizedlist>
1411	<listitem>
1412	<para>
1413	<methodname>Response.setDone()</methodname>: The configuration
1414	is complete. The core will write any configuation changes to the
1415	database, call the <methodname>Plugin.done()</methodname> method and
1416	then discard the plug-in instance.
1417	</para>
1418	</listitem>
1419
1420	<listitem>
1421	<para>
1422	<methodname>Response.setError()</methodname>: There was one or more
1423	errors. The web client will display the error messages for the user and
1424	allow the user to enter new values. The process continues with
1425	step <xref linkend="plugin_developer.api.callsequence.configure.form" />.
1426	</para>
1427	</listitem>
1428
1429	<listitem>
1430	<para>
1431	<methodname>Response.setContinue()</methodname>: The parameters are correct
1432	but the plug-in wants more parameters. The process continues with
1433	step <xref linkend="plugin_developer.api.callsequence.configure.requestinformation" />
1434	but the <varname>command</varname> has the value that was passed to the
1435	<methodname>setContinue()</methodname> method.
1436	</para>
1437	</listitem>
1438	</itemizedlist>
1439
1440	</para>
1441	</listitem>
1442	</orderedlist>
1443
1444	</sect3>
1445
1446	<sect3 id="plugin_developer.api.callsequence.context">
1447	<title>Checking if a plug-in can be used in a given context</title>
1448
1449	<para>
1450	If the plug-in is an <interfacename>InteractivePlugin</interfacename>
1451	it has specified in which contexts it can be used by the
1452	information returned from <methodname>InteractivePlugin.getGuiContexts()</methodname>
1453	method. The web client uses this information to decide whether,
1454	for example, a <guibutton>Run plugin</guibutton>
1455	button should be displayed on a page or not. However, this is not
1456	always enough to know whether the plug-in can be used or not.
1457	For example, a raw data importer plug-in cannot be used to
1458	import raw data if the raw bioassay already has data.
1459	So, when the user clicks the button, the web client will
1460	load all plug-ins that possibly can be used in the given context
1461	and let each one of them check whether they can be used or not.
1462	</para>
1463
1464
1465	<orderedlist>
1466	<listitem>
1467	<para>
1468	A new instance of the plug-in class is created. The plug-in must
1469	have a public no-argument constructor.
1470	</para>
1471	</listitem>
1472
1473	<listitem>
1474	<para>
1475	The <methodname>Plugin.init()</methodname> method is called.
1476	The <varname>job</varname> parameter is <constant>null</constant>.
1477	The <varname>configuration</varname> parameter is <constant>null</constant>
1478	if the plug-in does not have any configuration parameters.
1479	</para>
1480	</listitem>
1481
1482	<listitem>
1483	<para>
1484	The <methodname>InteractivePlugin.isInContext()</methodname>
1485	is called. If the context is a list context, the <varname>item</varname>
1486	parameter is null, otherwise the current item is passed. The plug-in
1487	should return <constant>null</constant> if it can be used under the
1488	current circumstances, or a message explaining why not.
1489	</para>
1490	</listitem>
1491
1492	<listitem>
1493	<para>
1494	After this, <methodname>Plugin.done()</methodname> is called and
1495	the plug-in instance is discarded. If there are
1496	several configurations for a plug-in, this procedure is repeated
1497	for each configuration.
1498	</para>
1499	</listitem>
1500	</orderedlist>
1501	</sect3>
1502
1503	<sect3 id="plugin_developer.api.callsequence.job">
1504	<title>Creating a new job</title>
1505
1506	<para>
1507	If the web client found that the plug-in could be
1508	used in a given context and the user selected the plug-in
1509	the job configuration sequence is started. It is a wizard-like interface
1510	identical to the configuration wizard. In fact, the same JSP pages,
1511	and calling sequence is used. See <xref linkend="plugin_developer.api.callsequence.configure" />.
1512	We do not repeat everything here. There are a few differences:
1513	</para>
1514
1515	<itemizedlist>
1516	<listitem>
1517	<para>
1518	The <varname>job</varname> parameter is not null, but it does not contain
1519	any parameter values to start with. The plug-in should use this
1520	object to store job-related parameter values. The
1521	<varname>configuration</varname> parameter is <constant>null</constant>
1522	if the plug-in is started without configuration. In any case,
1523	the configuration values are write-protected and cannot be modified.
1524	</para>
1525	</listitem>
1526
1527	<listitem>
1528	<para>
1529	The first call to <methodname>InteractivePlugin.getRequestInformation()</methodname>
1530	is done with <constant>Request.COMMAND_CONFIGURE_JOB</constant> (_configjob)
1531	as the command. The <varname>context</varname> parameter reflects the
1532	current context.
1533	</para>
1534	</listitem>
1535
1536	<listitem>
1537	<para>
1538	When calling <methodname>Response.setDone()</methodname> the plug-in
1539	should use the variant that takes an estimated execution time.
1540	If the plug-in has support for immediate execution or download
1541	(export plug-ins only), it can also respond with
1542	<methodname>Response.setExecuteImmediately()</methodname> or
1543	<methodname>Response.setDownloadImmediately()</methodname>.
1544	</para>
1545
1546	<para>
1547	If the plug-in requested and was granted immediate execution or
1548	download the same plug-in instance is used to execute the plug-in.
1549	This may be done with the same or a new thread. Otherwise, a new
1550	job is added to the job queue, the parameter value are saved
1551	and the plug-in instance is discarded after calling the
1552	<methodname>Plugin.done()</methodname> method.
1553	</para>
1554	</listitem>
1555	</itemizedlist>
1556	</sect3>
1557
1558	<sect3 id="plugin_developer.api.callsequence.execute">
1559	<title>Executing a job</title>
1560
1561	<para>
1562	Normally, the creation of a job and the execution of it are
1563	two different events. The execution may as well be done on a
1564	different server. See <xref linkend="installation_upgrade.jobagents" />.
1565	This means that the execution takes place in a different instance
1566	of the plug-in class than what was used for creating the job.
1567	The exception is if a plug-in supports immediate execution or download.
1568	In this case the same instance is used, and it, of course,
1569	is always executed on the web server.
1570	</para>
1571
1572	<orderedlist>
1573	<listitem>
1574	<para>
1575	A new instance of the plug-in class is created. The plug-in must
1576	have a public no-argument constructor.
1577	</para>
1578	</listitem>
1579
1580	<listitem>
1581	<para>
1582	The <methodname>Plugin.init()</methodname> method is called.
1583	The <varname>job</varname> parameter contains the job
1584	configuration paramters. The <varname>configuration</varname> parameter
1585	is <constant>null</constant> if the plug-in does not have any
1586	configuration parameters.
1587	</para>
1588	</listitem>
1589
1590	<listitem>
1591	<para>
1592	The <methodname>Plugin.run()</methodname> method is called.
1593	It is finally time for the plug-in to do the work it has bee
1594	designed for. This method should not throw any exceptions.
1595	Use the <methodname>Response.setDone()</methodname>
1596	method to report success or the <methodname>Response.setError()</methodname>
1597	to report errors.
1598	</para>
1599	</listitem>
1600
1601	<listitem>
1602	<para>
1603	In both cases the <methodname>Plugin.done()</methodname>
1604	method is called and the plug-in instance is discarded.
1605	</para>
1606	</listitem>
1607
1608	</orderedlist>
1609	</sect3>
1610
1611	</sect2>
1612
1613	<sect2 id="plugin_developer.api.jspparameters">
1614	<title>Using custom JSP pages for parameter input</title>
1615
1616	<para>
1617	This is an advanced option for plug-ins that require a different interface for
1618	specifying plug-in parameters than the default list showing one parameter at a
1619	time. This feature is used by setting the
1620	<methodname>RequestInformation.getJspPage()</methodname>
1621	property when constructing the request information object. If this property has
1622	a non-null value, the web client will send the browser to the specified JSP page
1623	instead of to the generic parameter input page.
1624	</para>
1625	<para>
1626	When setting the JSP page you should only set the file name. Do not include
1627	any path information. The web
1628	client has a special location for these JSP pages, generated from the package
1629	name of your plug-in. If the plug-in is located in the package
1630	<classname>org.company</classname>
1631	the JSP page must be located in
1632	<filename class="directory"><base-dir>/www/plugins/org/company/</filename>.
1633	Please note that the browser still thinks that it is showing the regular page
1634	at the usual location:
1635	<filename class="directory"><base-dir>/www/common/plugin/index.jsp</filename>.
1636	All links in your JSP page should be relative to that directory.
1637	</para>
1638	<para>
1639	Even if you use your own JSP page we recommend that you use the built-in
1640	facility for passing the parameters back to the plug-in. For this to work you
1641	must:
1642	</para>
1643	<itemizedlist spacing="compact">
1644	<listitem>
1645	<simpara>
1646	Generate the list of <classname>PluginParameter</classname>
1647	objects as usual.
1648	</simpara>
1649	</listitem>
1650	<listitem>
1651	<simpara>
1652	Name all your input fields in the JSP like:
1653	<parameter>
1654	parameter:<replaceable>name-of-parameter</replaceable>
1655	</parameter>
1656	</simpara>
1657	<programlisting>// Plugin generate PluginParameter
1658	StringParameterType stringPT = new StringParameterType(255, null, true);
1659	PluginParameter one = new PluginParameter("one", "One", "First string", stringPT);
1660	PluginParameter two = new PluginParameter("two", "Two", "Second string", stringPT);
1661
1662	// JSP should name fields as:
1663	First string: <input type="text" name="parameter:one"><br>
1664	Second string: <input type="text" name="parameter:two"></programlisting>
1665	</listitem>
1666	<listitem>
1667	<simpara>
1668	Send the form to
1669	<filename>index.jsp</filename>
1670	with the <varname>ID</varname>,
1671	<varname>cmd</varname> and <varname>requestId</varname>
1672	parameters as shown below.
1673	</simpara>
1674	<programlisting><form action="index.jsp" method="post">
1675	<input type="hidden" name="ID" value="<%=ID%>">
1676	<input type="hidden" name="requestId" value="<%=request.getParameter("requestId")%>">
1677	<input type="hidden" name="cmd" value="SetParameters">
1678	...
1679	</form></programlisting>
1680	<simpara>
1681	The <varname>ID</varname> is the session ID for the logged
1682	in user and is required. The <varname>requestId</varname>
1683	is the ID for this particular plug-in/job configuration
1684	sequence. It is optional, but we recommend that you use it
1685	since it protects your plug-in from getting mixed up with
1686	other plug-in configuration wizards. The <varname>cmd</varname>
1687	tells BASE to send the parameters to the plug-in for validation
1688	and saving.
1689	</simpara>
1690
1691	</listitem>
1692	</itemizedlist>
1693
1694	<para>
1695	If you want a &gbCancel; button to abort the configuration
1696	you should reload the page with with the url:
1697	<uri>index.jsp?ID=<%=ID%>&cmd=CancelWizard</uri>. This
1698	allows BASE to clean up resources that has been put in global
1699	session variables.
1700	</para>
1701
1702	<para>
1703	In your JSP page you will probably need to access some information like the
1704	<classname>SessionControl</classname>, <classname>Job</classname>
1705	and possible even the <classname>RequestInformation</classname>
1706	object created by your plug-in.
1707	</para>
1708	<programlisting>// Get session control and it's ID (required to post to index.jsp)
1709	final SessionControl sc = Base.getExistingSessionControl(pageContext, true);
1710	final String ID = sc.getId();
1711
1712	// Get information about the current request to the plug-in
1713	PluginConfigurationRequest pcRequest =
1714	(PluginConfigurationRequest)sc.getSessionSetting("plugin.configure.request");
1715	PluginDefinition plugin =
1716	(PluginDefinition)sc.getSessionSetting("plugin.configure.plugin");
1717	PluginConfiguration pluginConfig =
1718	(PluginConfiguration)sc.getSessionSetting("plugin.configure.config");
1719	PluginDefinition job =
1720	(PluginDefinition)sc.getSessionSetting("plugin.configure.job");
1721	RequestInformation ri = pcRequest.getRequestInformation();</programlisting>
1722
1723	</sect2>
1724	</sect1>
1725
1726	<sect1 id="plugin_developer.import">
1727	<title>Import plug-ins</title>
1728
1729	<para>
1730	A plugin becoms an import plugin simply by returning
1731	<constant>Plugin.MainType.IMPORT</constant>
1732	from the <methodname>Plugin.getMainType()</methodname> method.
1733	</para>
1734
1735	<sect2 id="plugin_developer.import.autodetect">
1736	<title>Autodetect file formats</title>
1737	<para>
1738	BASE has built-in functionality for autodetecting file formats.
1739	Your plug-in can be part of that feature if it reads it data
1740	from a single file. It must also implement the
1741	<interfacename>AutoDetectingImporter</interfacename>
1742	interface.
1743	</para>
1744
1745	<sect3 id="plugin_developer.api.interfaces.autodetecting">
1746	<title>The net.sf.basedb.core.plugin.AutoDetectingImporter interface</title>
1747
1748	<variablelist>
1749	<varlistentry>
1750	<term>
1751	<methodsynopsis language="java">
1752	<modifier>public</modifier>
1753	<type>boolean</type>
1754	<methodname>isImportable</methodname>
1755	<methodparam>
1756	<type>InputStream</type>
1757	<parameter>in</parameter>
1758	</methodparam>
1759	<exceptionname>BaseException</exceptionname>
1760	</methodsynopsis>
1761	</term>
1762	<listitem>
1763	<para>
1764	Check the input stream if it seems to contain data that can be imported by
1765	the plugin. Usually it means scanning a few lines for some header
1766	mathing a predefined string or a regexp.
1767	</para>
1768	<para>
1769	The <classname>AbstractFlatFileImporter</classname> implements this method
1770	by reading the headers from the input stream and checking if
1771	it stopped at an unknown type of line or not:
1772	<programlisting>
1773	public final boolean isImportable(InputStream in)
1774	throws BaseException
1775	{
1776	FlatFileParser ffp = getInitializedFlatFileParser();
1777	ffp.setInputStream(in);
1778	try
1779	{
1780	FlatFileParser.LineType result = ffp.parseHeaders();
1781	return result != FlatFileParser.LineType.UNKNOWN;
1782	}
1783	catch (IOException ex)
1784	{
1785	throw new BaseException(ex);
1786	}
1787	}
1788	</programlisting>
1789	</para>
1790	<para>
1791	Note that the input stream doesn't have to be a text file.
1792	It can be any type of file, for example a binary or an XML file.
1793	In the case of an XML file you would need to validate the entiry
1794	input stream in order to be a 100% sure that it is a valid
1795	xml file, but we recommend that you only check the first few XML tags,
1796	for example, the <!DOCTYPE > declaration and/or the root element
1797	tag.
1798	</para>
1799	</listitem>
1800	</varlistentry>
1801	<varlistentry>
1802	<term>
1803	<methodsynopsis language="java">
1804	<modifier>public</modifier>
1805	<void/>
1806	<methodname>doImport</methodname>
1807	<methodparam>
1808	<type>InputStream</type>
1809	<parameter>in</parameter>
1810	</methodparam>
1811	<methodparam>
1812	<type>ProgressReporter</type>
1813	<parameter>progress</parameter>
1814	</methodparam>
1815	<exceptionname>BaseException</exceptionname>
1816	</methodsynopsis>
1817	</term>
1818	<listitem>
1819	<para>
1820	Parse the input stream and import all data that is found.
1821	This method is of course only called if the
1822	<methodname>isImportable()</methodname> has returned true. Note
1823	however that the input stream is reopened at the start of the
1824	file. It may even be the case that the <methodname>isImportable()</methodname>
1825	method is called on one instance of the plugin and the
1826	<methodname>doImport()</methodname> method is called on another.
1827	Thus, the <methodname>doImport()</methodname> can't rely on any state set
1828	by the <methodname>isImportable()</methodname> method.
1829	</para>
1830	</listitem>
1831	</varlistentry>
1832	</variablelist>
1833	</sect3>
1834
1835	<sect3 id="plugin_developer.import.autodetect.callsequence">
1836	<title>Call sequence during autodetection</title>
1837
1838	<para>
1839	The call sequence for autodetection resembles the call sequence for
1840	checking if the plug-in can be used in a given context.
1841	</para>
1842
1843	<orderedlist>
1844	<listitem>
1845	<para>
1846	A new instance of the plug-in class is created. The plug-in must
1847	have a public no-argument constructor.
1848	</para>
1849	</listitem>
1850
1851	<listitem>
1852	<para>
1853	The <methodname>Plugin.init()</methodname> method is called.
1854	The <varname>job</varname> parameter is <constant>null</constant>.
1855	The <varname>configuration</varname> parameter is <constant>null</constant>
1856	if the plug-in does not have any configuration parameters.
1857	</para>
1858	</listitem>
1859
1860	<listitem>
1861	<para>
1862	If the plug-in is interactive the the <methodname>InteractivePlugin.isInContext()</methodname>
1863	is called. If the context is a list context, the <varname>item</varname>
1864	parameter is null, otherwise the current item is passed. The plug-in
1865	should return <constant>null</constant> if it can be used under the
1866	current circumstances, or a message explaining why not.
1867	</para>
1868	</listitem>
1869
1870	<listitem>
1871	<para>
1872	If the plug-in can be used the <methodname>AutoDetectingImporter.isImportable()</methodname>
1873	method is called to check if the selected file is importable or not.
1874	</para>
1875	</listitem>
1876
1877	<listitem>
1878	<para>
1879	After this, <methodname>Plugin.done()</methodname> is called and
1880	the plug-in instance is discarded. If there are
1881	several configurations for a plug-in, this procedure is repeated
1882	for each configuration. If the plug-in can be used without
1883	a configuration the procedure is also repeated without
1884	configuration parameters.
1885	</para>
1886	</listitem>
1887
1888	<listitem>
1889	<para>
1890	If a single plug-in was found the user is taken to the regular
1891	job configuration wizard. A new plug-in instance is created for
1892	this. If more than one plug-in was found the user is presented
1893	with a list of the plug-ins. After selecting one of them the
1894	regular job configuration wizard is used with a new plug-in instance.
1895	</para>
1896	</listitem>
1897
1898	</orderedlist>
1899
1900	</sect3>
1901
1902	</sect2>
1903
1904	<sect2 id="plugin_developer.import.abstractflatfileimporter">
1905	<title>The AbstractFlatFileImporter superclass</title>
1906	<para>
1907	The <classname>AbstractFlatFileImporter</classname> is a very useful abstract
1908	class to use as a superclass for your own import plug-ins. It can be used
1909	if your plug-in uses regular text files that can be parsed by an instance of the
1910	<classname>net.sf.basedb.util.FlatFileParser</classname> class. This class parses a file
1911	by checking each line against a few regular expressions. Depending on which regular
1912	expression matches the line, it is classified as a header line, a section line,
1913	a comment, a data line, a footer line or unknown. Header lines are inspected as a group,
1914	but data lines individually, meaning that it consumes very little memory since only
1915	a few lines at a time needs to be loaded.
1916	</para>
1917
1918	<para>
1919	The <classname>AbstractFlatFileImporter</classname> defines
1920	<classname>PluginParameter</classname> objects
1921	for each of the regular expressions and other parameters used by the parser. It also
1922	implements the <methodname>Plugin.run()</methodname> method and does most of
1923	the ground work for instantiating a <methodname>FlatFileParser</methodname> and
1924	parsing the file. What you have to do in your plugin is to put together the
1925	<classname>RequestInformation</classname> objects
1926	for configuring the plugin and creating a job and implement the
1927	<methodname>InteractivePlugin.configure()</methodname> method for validating and
1928	storing the parameteters. You should also implement or override some methods
1929	defined by <classname>AbstractFlatFileImporter</classname>.
1930	</para>
1931
1932	<para>
1933	Here is what you need to do:
1934	</para>
1935
1936	<itemizedlist>
1937	<listitem>
1938	<para>
1939	Implement the <methodname>Plugin.getAbout()</methodname> and
1940	<methodname>Plugin.getMainType()</methodname> methods. See
1941	<xref linkend="plugin_developer.api.interfaces.plugin" /> for more information.
1942	</para>
1943	</listitem>
1944
1945	<listitem>
1946	<para>
1947	Implement the <interfacename>InteractivePlugin</interfacename> methods.
1948	See <xref linkend="plugin_developer.api.interfaces.interactive" /> for more information. Note that the
1949	<classname>AbstractFlatFileImporter</classname>
1950	has defined many parameters for regular expressions used by the parser
1951	already. You should just pick them and put in your <classname>RequestInformation</classname>
1952	object.
1953	</para>
1954
1955	<programlisting>
1956	// Parameter that maps the items name from a column
1957	private PluginParameter<String> nameColumnMapping;
1958
1959	// Parameter that maps the items description from a column
1960	private PluginParameter<String> descriptionColumnMapping;
1961
1962	private RequestInformation getConfigurePluginParameters(GuiContext context)
1963	{
1964	if (configurePlugin == null)
1965	{
1966	// To store parameters for CONFIGURE_PLUGIN
1967	List<PluginParameter<?>> parameters =
1968	new ArrayList<PluginParameter<?>>();
1969
1970	// Parser regular expressions - from AbstractFlatFileParser
1971	parameters.add(parserSection);
1972	parameters.add(headerRegexpParameter);
1973	parameters.add(dataHeaderRegexpParameter);
1974	parameters.add(dataSplitterRegexpParameter);
1975	parameters.add(ignoreRegexpParameter);
1976	parameters.add(dataFooterRegexpParameter);
1977	parameters.add(minDataColumnsParameter);
1978	parameters.add(maxDataColumnsParameter);
1979
1980	// Column mappings
1981	nameColumnMapping = new PluginParameter<String>(
1982	"nameColumnMapping",
1983	"Name",
1984	"Mapping that picks the items name from the data columns",
1985	new StringParameterType(255, null, true)
1986	);
1987
1988	descriptionColumnMapping = new PluginParameter<String>(
1989	"descriptionColumnMapping",
1990	"Description",
1991	"Mapping that picks the items description from the data columns",
1992	new StringParameterType(255, null, false)
1993	);
1994
1995	parameters.add(mappingSection);
1996	parameters.add(nameColumnMapping);
1997	parameters.add(descriptionColumnMapping);
1998
1999	configurePlugin = new RequestInformation
2000	(
2001	Request.COMMAND_CONFIGURE_PLUGIN,
2002	"File parser settings",
2003	"",
2004	parameters
2005	);
2006
2007	}
2008	return configurePlugin;
2009	}
2010	</programlisting>
2011	</listitem>
2012
2013	<listitem>
2014	<para>
2015	Implement/override some of the methods defined by
2016	<classname>AbstractFlatFileParser</classname>. The most important
2017	methods are listed below.
2018	</para>
2019	</listitem>
2020
2021	</itemizedlist>
2022
2023	<variablelist>
2024	<varlistentry>
2025	<term>
2026	<methodsynopsis language="java">
2027	<modifier>protected</modifier>
2028	<type>FlatFileParser</type>
2029	<methodname>getInitializedFlatFileParser</methodname>
2030	<exceptionname>BaseException</exceptionname>
2031	</methodsynopsis>
2032	</term>
2033	<listitem>
2034	<para>
2035	The method is called to create a <classname>FlatFileParser</classname>
2036	and set the regular expressions that should be used for parsing the file.
2037	The default implementation assumes that your plug-in has used the built-in
2038	<classname>PluginParameter</classname> objects and has stored the values
2039	at the configuration level. You should override this method if you need to
2040	initiailise the parser in a different way. See for example the
2041	code for the <classname>PrintMapFlatFileImporter</classname> plug-in which
2042	has a fixed format and doesn't use configurations.
2043	</para>
2044	<programlisting>
2045	@Override
2046	protected FlatFileParser getInitializedFlatFileParser()
2047	throws BaseException
2048	{
2049	FlatFileParser ffp = new FlatFileParser();
2050	ffp.setSectionRegexp(Pattern.compile("\\[(.+)\\]"));
2051	ffp.setHeaderRegexp(Pattern.compile("(.+)=,(.*)"));
2052	ffp.setDataSplitterRegexp(Pattern.compile(","));
2053	ffp.setDataFooterRegexp(Pattern.compile(""));
2054	ffp.setMinDataColumns(12);
2055	return ffp;
2056	}
2057	</programlisting>
2058	</listitem>
2059	</varlistentry>
2060
2061	<varlistentry>
2062	<term>
2063	<methodsynopsis language="java">
2064	<modifier>protected</modifier>
2065	<void/>
2066	<methodname>begin</methodname>
2067	<methodparam>
2068	<type>FlatFileParser</type>
2069	<parameter>ffp</parameter>
2070	</methodparam>
2071	<exceptionname>BaseException</exceptionname>
2072	</methodsynopsis>
2073	</term>
2074	<listitem>
2075	<para>
2076	This method is called just before the parsing of the file
2077	begins. Override this method if you need to initialise some
2078	internal state. This is, for example, a good place to open
2079	a <classname>DbControl</classname> object, read parameters from the
2080	job and configuration and put them into more useful variables. The default
2081	implementation does nothing, but we recommend that
2082	<methodname>super.begin()</methodname> is always called.
2083	</para>
2084	<programlisting>
2085	// Snippets from the RawDataFlatFileImporter class
2086	private DbControl dc;
2087	private RawDataBatcher batcher;
2088	private RawBioAssay rawBioAssay;
2089	private Map<String, String> columnMappings;
2090	private int numInserted;
2091
2092	@Override
2093	protected void begin()
2094	throws BaseException
2095	{
2096	super.begin();
2097
2098	// Get DbControl
2099	dc = sc.newDbControl();
2100	rawBioAssay = (RawBioAssay)job.getValue(rawBioAssayParameter.getName());
2101
2102	// Reload raw bioassay using current DbControl
2103	rawBioAssay = RawBioAssay.getById(dc, rawBioAssay.getId());
2104
2105	// Create a batcher for inserting spots
2106	batcher = rawBioAssay.getRawDataBatcher();
2107
2108	// For progress reporting
2109	numInserted = 0;
2110	}
2111	</programlisting>
2112	</listitem>
2113	</varlistentry>
2114	<varlistentry>
2115	<term>
2116	<methodsynopsis language="java">
2117	<modifier>protected</modifier>
2118	<void/>
2119	<methodname>handleHeader</methodname>
2120	<methodparam>
2121	<type>FlatFileParser.Line</type>
2122	<parameter>line</parameter>
2123	</methodparam>
2124	<exceptionname>BaseException</exceptionname>
2125	</methodsynopsis>
2126	</term>
2127	<listitem>
2128	<para>
2129	This method is called once for every header line that is found in
2130	the file. The <varname>line</varname> parameter contains information
2131	about the header. The default implementation of this method does
2132	nothing.
2133	</para>
2134	<programlisting>
2135	@Override
2136	protected void handleHeader(Line line)
2137	throws BaseException
2138	{
2139	super.handleHeader(line);
2140	if (line.name() != null && line.value() != null)
2141	{
2142	rawBioAssay.setHeader(line.name(), line.value());
2143	}
2144	}
2145	</programlisting>
2146	</listitem>
2147	</varlistentry>
2148	<varlistentry>
2149	<term>
2150	<methodsynopsis language="java">
2151	<modifier>protected</modifier>
2152	<void/>
2153	<methodname>handleSection</methodname>
2154	<methodparam>
2155	<type>FlatFileParser.Line</type>
2156	<parameter>line</parameter>
2157	</methodparam>
2158	<exceptionname>BaseException</exceptionname>
2159	</methodsynopsis>
2160	</term>
2161	<listitem>
2162	<para>
2163	This method is called once for each section that is found in the file.
2164	The <varname>line</varname> parameter contains information
2165	about the section. The default implementation of this method does
2166	nothing.
2167	</para>
2168	</listitem>
2169	</varlistentry>
2170
2171	<varlistentry>
2172	<term>
2173	<methodsynopsis language="java">
2174	<modifier>protected abstract</modifier>
2175	<void/>
2176	<methodname>beginData</methodname>
2177	<exceptionname>BaseException</exceptionname>
2178	</methodsynopsis>
2179	</term>
2180	<listitem>
2181	<para>
2182	This method is called after the headers has been parsed, but before
2183	the first line of data. This is a good place to add code that
2184	depends on information in the headers, for example, put
2185	together column mappings.
2186	</para>
2187
2188	<programlisting>
2189	private Mapper reporterMapper;
2190	private Mapper blockMapper;
2191	private Mapper columnMapper;
2192	private Mapper rowMapper;
2193	// ... more mappers
2194
2195	@Override
2196	protected void beginData()
2197	{
2198	boolean cropStrings = ("crop".equals(job.getValue("stringTooLongError")));
2199
2200	// Mapper that always return null; used if no mapping expression has been entered
2201	Mapper nullMapper = new ConstantMapper((String)null);
2202
2203	// Column mappers
2204	reporterMapper = getMapper(ffp, (String)configuration.getValue("reporterIdColumnMapping"),
2205	cropStrings ? ReporterData.MAX_EXTERNAL_ID_LENGTH : null, nullMapper);
2206	blockMapper = getMapper(ffp, (String)configuration.getValue("blockColumnMapping"), null, nullMapper);
2207	columnMapper = getMapper(ffp, (String)configuration.getValue("columnColumnMapping"), null, nullMapper);
2208	rowMapper = getMapper(ffp, (String)configuration.getValue("rowColumnMapping"), null, nullMapper);
2209	// ... more mappers: metaGrid coordinate, X-Y coordinate, extended properties
2210	// ...
2211	}
2212	</programlisting>
2213
2214	</listitem>
2215	</varlistentry>
2216
2217	<varlistentry>
2218	<term>
2219	<methodsynopsis language="java">
2220	<modifier>protected abstract</modifier>
2221	<void/>
2222	<methodname>handleData</methodname>
2223	<methodparam>
2224	<type>FlatFileParser.Data</type>
2225	<parameter>data</parameter>
2226	</methodparam>
2227	<exceptionname>BaseException</exceptionname>
2228	</methodsynopsis>
2229	</term>
2230	<listitem>
2231	<para>
2232	This method is abstract and must be implemented by all subclasses.
2233	It is called once for every data line in the the file.
2234	</para>
2235
2236	<programlisting>
2237	// Snippets from the RawDataFlatFileImporter class
2238	@Override
2239	protected void handleData(Data data)
2240	throws BaseException
2241	{
2242	// Create new RawData object
2243	RawData raw = batcher.newRawData();
2244
2245	// External ID for the reporter
2246	String externalId = reporterMapper.getValue(data);
2247
2248	// Block, row and column numbers
2249	raw.setBlock(blockMapper.getInt(data));
2250	raw.setColumn(columnMapper.getInt(data));
2251	raw.setRow(rowMapper.getInt(data));
2252	// ... more: metaGrid coordinate, X-Y coordinate, extended properties
2253
2254	// Insert raw data to the database
2255	batcher.insert(raw, externalId);
2256	numInserted++;
2257	}
2258	</programlisting>
2259
2260	</listitem>
2261	</varlistentry>
2262
2263	<varlistentry>
2264	<term>
2265	<methodsynopsis language="java">
2266	<modifier>protected</modifier>
2267	<void/>
2268	<methodname>end</methodname>
2269	<methodparam>
2270	<type>boolean</type>
2271	<parameter>success</parameter>
2272	</methodparam>
2273	</methodsynopsis>
2274	</term>
2275	<listitem>
2276	<para>
2277	Called when the parsing has ended, either because the end of
2278	file was reached or because an error has occurred. The subclass
2279	should close any open resources, ie. the <classname>DbControl</classname>
2280	object. The <varname>success</varname> parameter is <constant>true</constant>
2281	if the parsing was successful, <constant>false</constant> otherwise.
2282	The default implementation does nothing.
2283	</para>
2284
2285	<programlisting>
2286	@Override
2287	protected void end(boolean success)
2288	throws BaseException
2289	{
2290	try
2291	{
2292	// Commit if the parsing was successful
2293	if (success)
2294	{
2295	batcher.close();
2296	dc.commit();
2297	}
2298	}
2299	catch (BaseException ex)
2300	{
2301	// Well, now we got an exception
2302	success = false;
2303	throw ex;
2304	}
2305	finally
2306	{
2307	// Always close... and call super.end()
2308	if (dc != null) dc.close();
2309	super.end(success);
2310	}
2311	}
2312	</programlisting>
2313	</listitem>
2314	</varlistentry>
2315
2316	<varlistentry>
2317	<term>
2318	<methodsynopsis language="java">
2319	<modifier>protected</modifier>
2320	<type>String</type>
2321	<methodname>getSuccessMessage</methodname>
2322	<void/>
2323	</methodsynopsis>
2324	</term>
2325	<listitem>
2326	<para>
2327	This is the last method that is called, and it is only called if
2328	everything went suceessfully. This method allows a subclass to generate
2329	a short message that is sent back to the database as a final progress
2330	report. The default implementation returns null, which means that no
2331	message will be generated.
2332	</para>
2333	<programlisting>
2334	@Override
2335	protected String getSuccessMessage()
2336	{
2337	return numInserted + " spots inserted";
2338	}
2339	</programlisting>
2340	</listitem>
2341	</varlistentry>
2342	</variablelist>
2343
2344	<para>
2345	The <classname>AbstractFlatFileImporter</classname> has a lot of
2346	other methods that you may use and/or override in your own plug-in.
2347	Check the javadoc for more information.
2348	</para>
2349
2350	</sect2>
2351	</sect1>
2352
2353	<sect1 id="plugin_developer.export">
2354	<title>Export plug-ins</title>
2355
2356	<para>
2357	Export plug-ins are plug-ins that takes data from BASE, and
2358	prepares it for use with some external entity. Usually this
2359	means that data is taken from the database and put into a file
2360	with some well-defined file format.
2361	An export plug-in should return <constant>MainType.EXPORT</constant> from
2362	the <methodname>Plugin.getMainType()</methodname> method.
2363	</para>
2364
2365	<sect2 id="plugin_developer.export.download">
2366	<title>Immediate download of exported data</title>
2367	<para>
2368	An export plug-in may want to give the user a choice
2369	between saving the exported data in the BASE file system
2370	or to download it immediately to the client computer. With the basic
2371	plug-in API the second option is not possible. The
2372	<interfacename>ImmediateDownloadExporter</interfacename> is an
2373	interface that extends the <interfacename>Plugin</interfacename>
2374	interface to provide this functionality. If your export
2375	plug-in wants to provide immediate download functionality it must
2376	implement the <interfacename>ImmediateDownloadExporter</interfacename>
2377	interface.
2378	</para>
2379
2380	<sect3 id="plugin_developer.export.immediatedownloadexporter">
2381	<title>The ImmediateDownloadExporter interface</title>
2382	<variablelist>
2383	<varlistentry>
2384	<term>
2385	<methodsynopsis language="java">
2386	<modifier>public</modifier>
2387	<void/>
2388	<methodname>doExport</methodname>
2389	<methodparam>
2390	<type>ExportOutputStream</type>
2391	<parameter>out</parameter>
2392	</methodparam>
2393	<methodparam>
2394	<type>ProgressReporter</type>
2395	<parameter>progress</parameter>
2396	</methodparam>
2397	</methodsynopsis>
2398	</term>
2399	<listitem>
2400	<para>
2401	Perform the export. The plug-in should write the
2402	exported data to the <varname>out</varname> stream.
2403	If the <varname>progress</varname> parameter is not null,
2404	the progress should be reported at regular interval in the
2405	same manner as in the <methodname>Plugin.run()</methodname>
2406	method.
2407	</para>
2408	</listitem>
2409	</varlistentry>
2410	</variablelist>
2411
2412	</sect3>
2413
2414	<sect3 id="plugin_developer.export.exportoutputstream">
2415	<title>The ExportOutputStream class</title>
2416
2417	<para>
2418	The <classname>ExportOutputStream</classname> is extends
2419	<classname>java.io.OutputStream</classname>. Use the regular
2420	<methodname>write()</methodname> methods to write data to it.
2421	It also has three additional methods, which are used to generate
2422	HTTP response headers.
2423	</para>
2424
2425	<note>
2426	<para>
2427	These methods must be called before starting to write data to
2428	the <varname>out</varname> stream.
2429	</para>
2430	</note>
2431
2432	<variablelist>
2433	<varlistentry>
2434	<term>
2435	<methodsynopsis language="java">
2436	<modifier>public</modifier>
2437	<void/>
2438	<methodname>setContentLength</methodname>
2439	<methodparam>
2440	<type>long</type>
2441	<parameter>contentLength</parameter>
2442	</methodparam>
2443	</methodsynopsis>
2444	</term>
2445	<listitem>
2446	<para>
2447	Set the total size of the exported data. Don't call this method if the
2448	total size is not known.
2449	</para>
2450	</listitem>
2451	</varlistentry>
2452	<varlistentry>
2453	<term>
2454	<methodsynopsis language="java">
2455	<modifier>public</modifier>
2456	<void/>
2457	<methodname>setMimeType</methodname>
2458	<methodparam>
2459	<type>String</type>
2460	<parameter>mimeType</parameter>
2461	</methodparam>
2462	</methodsynopsis>
2463	</term>
2464	<listitem>
2465	<para>
2466	Set the MIME type of the file that is beeing generated.
2467	</para>
2468	</listitem>
2469	</varlistentry>
2470	<varlistentry>
2471	<term>
2472	<methodsynopsis language="java">
2473	<modifier>public</modifier>
2474	<void/>
2475	<methodname>setFilename</methodname>
2476	<methodparam>
2477	<type>String</type>
2478	<parameter>filename</parameter>
2479	</methodparam>
2480	</methodsynopsis>
2481	</term>
2482	<listitem>
2483	<para>
2484	Set a suggested name of the file that is beeing
2485	generated.
2486	</para>
2487	</listitem>
2488	</varlistentry>
2489	</variablelist>
2490
2491	</sect3>
2492
2493	<sect3 id="plugin_developer.export.callsequence">
2494	<title>Call sequence during immediate download</title>
2495
2496	<para>
2497	Supporting immediate download also means that the method call
2498	sequence is a bit altered from the standard sequence described
2499	in <xref linkend="plugin_developer.api.callsequence.execute" />.
2500	</para>
2501
2502	<itemizedlist>
2503	<listitem>
2504	<para>
2505	The plug-in must call <methodname>Response.setDownloadImmediately()</methodname>
2506	instead of <methodname>Response.setDone()</methodname> in <methodname>Plugin.configure()</methodname>
2507	to end the job configuration wizard. This requests that the core starts
2508	an immediate download.
2509	</para>
2510
2511	<note>
2512	<para>
2513	Even if an immediate download is requested by the plug-in this feature
2514	may have been disabled by the server administrator. If so, the plug-in
2515	can choose if the job should be added to job queue or if this is an
2516	error condition.
2517	</para>
2518	</note>
2519	</listitem>
2520
2521	<listitem>
2522	<para>
2523	If immediate download is granted the web client will keep the
2524	same plug-in instance and call <methodname>ImmediateDownloadExporter.doExport()</methodname>.
2525	In this case, the <methodname>Plugin.run()</methodname> is never called.
2526	After the export, <methodname>Plugin.done()</methodname> is called as
2527	usual.
2528	</para>
2529
2530	</listitem>
2531
2532	<listitem>
2533	<para>
2534	If immediate download is not granted and the job is added to the job queue
2535	the regular job execution sequence is used.
2536	</para>
2537	</listitem>
2538	</itemizedlist>
2539
2540	</sect3>
2541
2542	</sect2>
2543
2544	<sect2 id="plugin_developer.export.abstractexporter">
2545	<title>The AbstractExporterPlugin class</title>
2546
2547	<para>
2548	This is an abstract superclass that will make it easier
2549	to implement export plug-ins that support immediate
2550	download. It defines <classname>PluginParameter</classname>
2551	objects for asking a user about a path where the exported
2552	data should be saved and if existing files should be overwritten or not.
2553	If the user leaves the path empty the immediate download functionality
2554	should be used. It also contains implementations of both the
2555	<methodname>Plugin.run()</methodname> method and the
2556	<methodname>ImmediateDownloadExporter.doExport()</methodname> method.
2557	Here is what you need to do in your own plug-in code (code examples are
2558	take from the <classname>HelpExporter</classname>):
2559	</para>
2560
2561	<itemizedlist>
2562	<listitem>
2563	<para>
2564	Your plug-in should extend the <classname>AbstractExporterPlugin</classname>
2565	class:
2566	<programlisting>
2567	public class HelpExporter
2568	extends AbstractExporterPlugin
2569	implements InteractivePlugin
2570	</programlisting>
2571	</para>
2572	</listitem>
2573
2574	<listitem>
2575	<para>
2576	You need to implement the
2577	<methodname>InteractivePlugin.getRequestInformation()</methodname>
2578	method. Use the <methodname>getSaveAsParameter()</methodname>
2579	and <methodname>getOverwriteParameter()</methodname> methods defined in the
2580	superclass to create plug-in parameters that asks for the file name to save
2581	to and if existing files can be overwritten or not.
2582	You should also check if the administrator has enabled the immediate execution
2583	functionality for your plug-in. If not, the only option is to
2584	export to a file in the BASE file system and the filename is a
2585	required parameter.
2586
2587	<programlisting>
2588	// Selected parts of the getRequestConfiguration() method
2589	...
2590	List<PluginParameter<?>> parameters =
2591	new ArrayList<PluginParameter<?>>();
2592	...
2593	PluginDefinition pd = job.getPluginDefinition();
2594	boolean requireFile = pd == null ?
2595	false : !pd.getAllowImmediateExecution();
2596
2597	parameters.add(getSaveAsParameter(null, null, defaultPath, requireFile));
2598	parameters.add(getOverwriteParameter(null, null));
2599
2600	configureJob = new RequestInformation
2601	(
2602	Request.COMMAND_CONFIGURE_JOB,
2603	"Help exporter options",
2604	"Set Client that owns the helptexts, " +
2605	"the file path where the export file should be saved",
2606	parameters
2607	);
2608	....
2609	return configureJob;
2610	</programlisting>
2611	</para>
2612	</listitem>
2613
2614	<listitem>
2615	<para>
2616	You must also implement the <methodname>configure()</methodname>
2617	method and check the parameters. If no filename has been given,
2618	you should check if immediate exection is allowed and set an
2619	error if it is not. If a filename is present, use the
2620	<methodname>pathCanBeUsed()</methodname> method to check if
2621	it is possible to save the data to a file with that name. If the
2622	file already exists it can be overwritten if the <varname>OVERWRITE</varname>
2623	is <constant>TRUE</constant> or if the file has been flagged for removal.
2624	Do not forget to store the parameters with the <methodname>storeValue()</methodname>
2625	method.
2626
2627	<programlisting>
2628	// Selected parts from the configure() method
2629	if (request.getParameterValue(SAVE_AS) == null)
2630	{
2631	if (!request.isAllowedImmediateExecution())
2632	{
2633	response.setError("Immediate download is not allowed. " +
2634	"Please specify a filename.", null);
2635	return;
2636	}
2637	Client client = (Client)request.getParameterValue("client");
2638	response.setDownloadImmediately("Export help texts for client application " +
2639	client.getName(), ExecutionTime.SHORTEST, true);
2640	}
2641	else
2642	{
2643	if (!pathCanBeUsed((String)request.getParameterValue(SAVE_AS),
2644	(Boolean)request.getParameterValue(OVERWRITE)))
2645	{
2646	response.setError("File exists: " +
2647	(String)request.getParameterValue(SAVE_AS), null);
2648	return;
2649	}
2650	storeValue(job, request, ri.getParameter(SAVE_AS));
2651	storeValue(job, request, ri.getParameter(OVERWRITE));
2652	response.setDone("The job configuration is complete", ExecutionTime.SHORTEST);
2653	}
2654	</programlisting>
2655
2656	</para>
2657	</listitem>
2658
2659	<listitem>
2660	<para>
2661	Implement the <methodname>performExport()</methodname> method.
2662	This is defined as abstract in the <classname>AbstractExporterPlugin</classname>
2663	class. It has the same parameters as the <methodname>ImmediateDownloadExporter.doExport()</methodname>
2664	method and they have the same meaning. The only difference is that the
2665	<varname>out</varname> stream can be linked to a file in the BASE filesystem
2666	and not just to the HTTP response stream.
2667	</para>
2668	</listitem>
2669
2670	<listitem>
2671	<para>
2672	Optionally, implement the <methodname>begin()</methodname>,
2673	<methodname>end()</methodname> and <methodname>getSuccessMessage()</methodname>
2674	methods. Theese methods do nothing by default.
2675	</para>
2676	</listitem>
2677	</itemizedlist>
2678
2679	<para>
2680	The call sequence for plug-ins extending <classname>AbstractExporterPlugin</classname>
2681	is:
2682	</para>
2683
2684	<orderedlist>
2685	<listitem>
2686	<para>
2687	Call <methodname>begin()</methodname>.
2688	</para>
2689	</listitem>
2690	<listitem>
2691	<para>
2692	Call <methodname>performExport()</methodname>.
2693	</para>
2694	</listitem>
2695	<listitem>
2696	<para>
2697	Call <methodname>end()</methodname>.
2698	</para>
2699	</listitem>
2700	<listitem>
2701	<para>
2702	Call <methodname>getSuccessMessage()</methodname> if running as a regular
2703	job. This method is never called when doing an immediate download since there
2704	is no place to show the message.
2705	</para>
2706	</listitem>
2707	</orderedlist>
2708
2709	</sect2>
2710
2711	</sect1>
2712
2713	<sect1 id="plugin_developer.analyse">
2714	<title>Analysis plug-ins</title>
2715	<para>
2716	A plug-in becomes an analysis plug-in simply by returning
2717	<constant>Plugin.MainType.ANALYSIS</constant> from the
2718	<methodname>Plugin.getMainType()</methodname> method. The information returned from
2719	<methodname>InteractivePlugin.getGuiContexts()</methodname>
2720	must include: [<constant>Item.BIOASSAYSET</constant>, <constant>Type.ITEM</constant>]
2721	since this is the main place where the web client looks for analysis plug-ins. If
2722	the plug-in can work on a subset of the bioassays it may also include
2723	[<constant>Item.BIOASSAY</constant>, <constant>Type.LIST</constant>]
2724	among the contexts. This will make it possible for a user to select
2725	bioassays from the list and then invoke the plug-in.
2726	</para>
2727
2728	<programlisting>
2729	private static final Set<GuiContext> guiContexts =
2730	Collections.singleton(new GuiContext(Item.BIOASSAYSET, GuiContext.Type.ITEM));
2731
2732	public Set<GuiContext> getGuiContexts()
2733	{
2734	return guiContexts;
2735	}</programlisting>
2736
2737	<para>
2738	If the plugin depends on a specific raw data type or on the number of
2739	channels, it should check that the current bioassayset is of the
2740	correct type in the <methodname>InteractivePlugin.isInContext()</methodname>
2741	method. It is also a good idea to check if the current user has permission
2742	to use the current experiment. This permission is needed to create new bioassaysets or
2743	other data belonging to the experiment.
2744	</para>
2745
2746	<programlisting>
2747	public boolean isInContext(GuiContext context, Object item)
2748	{
2749	if (item == null)
2750	{
2751	message = "The object is null";
2752	}
2753	else if (!(item instanceof BioAssaySet))
2754	{
2755	message = "The object is not a BioAssaySet: " + item;
2756	}
2757	else
2758	{
2759	BioAssaySet bas = (BioAssaySet)item;
2760	int channels = bas.getRawDataType().getChannels();
2761	if (channels != 2)
2762	{
2763	message = "This plug-in requires 2-channel data, not " + channels + "-channel.";
2764	}
2765	else
2766	{
2767	Experiment e = bas.getExperiment();
2768	e.checkPermission(Permission.USE);
2769	}
2770	}
2771	}
2772	</programlisting>
2773
2774	<para>
2775	The plugin should always include a parameter asking for the current
2776	bioassay set when the <methodname>InteractivePlugin.getRequestInformation()</methodname>
2777	is called with <literal>command = Request.COMMAND_CONFIGURE_JOB</literal>.
2778	</para>
2779
2780	<programlisting>
2781	private static final RequestInformation configurePlugin;
2782	private RequestInformation configureJob;
2783	private PluginParameter<BioAssaySet> bioAssaySetParameter;
2784
2785	public RequestInformation getRequestInformation(GuiContext context, String command)
2786	throws BaseException
2787	{
2788	RequestInformation requestInformation = null;
2789	if (command.equals(Request.COMMAND_CONFIGURE_PLUGIN))
2790	{
2791	requestInformation = getConfigurePlugin(context);
2792	}
2793	else if (command.equals(Request.COMMAND_CONFIGURE_JOB))
2794	{
2795	requestInformation = getConfigureJob(context);
2796	}
2797	return requestInformation;
2798	}
2799
2800	private RequestInformation getConfigureJob(GuiContext context)
2801	{
2802	if (configureJob == null)
2803	{
2804	bioAssaySetParameter; = new PluginParameter<BioAssaySet>(
2805	"bioAssaySet",
2806	"Bioassay set",
2807	"The bioassay set used as the source for this analysis plugin",
2808	new ItemParameterType<BioAssaySet>(BioAssaySet.class, null, true, 1, null)
2809	);
2810
2811	List<PluginParameter<?>> parameters = new ArrayList<PluginParameter<?>>();
2812	parameters.add(bioAssaySetParameter);
2813	// Add more plug-in-specific parameters here...
2814
2815	configureJob = new RequestInformation(
2816	Request.COMMAND_CONFIGURE_JOB,
2817	"Configure job",
2818	"Set parameter for plug-in execution",
2819	parameters
2820	);
2821	}
2822	return configureJob;
2823	}
2824	</programlisting>
2825
2826	<para>
2827	Of course, the <methodname>InteractivePlugin.configure()</methodname> method needs
2828	to validate and store the bioassay set parameter as well:
2829	</para>
2830
2831	<programlisting>
2832	public void configure(GuiContext context, Request request, Response response)
2833	{
2834	String command = request.getCommand();
2835	try
2836	{
2837	if (command.equals(Request.COMMAND_CONFIGURE_PLUGIN))
2838	{
2839	// Validate and store configuration parameters
2840	response.setDone("Plugin configuration complete");
2841	}
2842	else if (command.equals(Request.COMMAND_CONFIGURE_JOB))
2843	{
2844	List<Throwable> errors =
2845	validateRequestParameters(configureJob.getParameters(), request);
2846	if (errors != null)
2847	{
2848	response.setError(errors.size() +
2849	" invalid parameter(s) were found in the request", errors);
2850	return;
2851	}
2852	storeValue(job, request, bioAssaySetParameter);
2853	// Store other plugin-specific parameters
2854
2855	response.setDone("Job configuration complete", Job.ExecutionTime.SHORT);
2856	}
2857	}
2858	catch (Throwable ex)
2859	{
2860	// Never throw exception, always set response!
2861	response.setError(ex.getMessage(), Arrays.asList(ex));
2862	}
2863	}
2864	</programlisting>
2865
2866	<para>
2867	Now, the typical <methodname>Plugin.run()</methodname> method loads the specfied bioassay set
2868	and it's spot data. It may do some filtering and recalculation of the spot
2869	intensity value(s). In most cases it will store the result as a child bioassay
2870	set with one bioassay for each bioassay in the parent bioassay set.
2871	Here is an example, which just copies the intensity values, while
2872	removing those with a negative value in either channel.
2873	</para>
2874
2875	<programlisting>
2876	public void run(Request request, Response response, ProgressReporter progress)
2877	{
2878	DbControl dc = sc.newDbControl();
2879	try
2880	{
2881	BioAssaySet source = (BioAssaySet)job.getParameter("bioAssaySet");
2882	// Reload with current DbControl
2883	source = BioAssaySet.getById(dc, source.getId());
2884	int channels = source.getRawDataType().getChannels();
2885
2886	// Create transformation and new bioassay set
2887	Job j = Job.getById(dc, job.getId());
2888	Transformation t = source.newTransformation(j);
2889	t.setName("Copy spot intensities >= 0");
2890	dc.saveItem(t);
2891
2892	BioAssaySet result = t.newProduct(null, "new", true);
2893	result.setName("After: Copying spot intensities");
2894	dc.saveItem(result);
2895
2896	// Get query for source data
2897	DynamicSpotQuery query = source.getSpotData();
2898
2899	// Do not return spots with intensities < 0
2900	for (int ch = 1; ch <= channels; ++ch)
2901	{
2902	query.restrict(
2903	Restrictions.gteq(
2904	Dynamic.column(VirtualColumn.channel(ch)),
2905	Expressions.integer(0)
2906	)
2907	);
2908	}
2909
2910	// Create batcher and copy data
2911	SpotBatcher batcher = result.getSpotBatcher();
2912	int spotsCopied = batcher.insert(query);
2913	batcher.close();
2914
2915	// Commit and return
2916	dc.commit();
2917	response.setDone("Copied " + spotsCopied + " spots.");
2918	}
2919	catch (Throwable t)
2920	{
2921	response.setError(t.getMessage(), Arrays.asList(t));
2922	}
2923	finally
2924	{
2925	if (dc != null) dc.close();
2926	}
2927	}
2928	</programlisting>
2929
2930	<para>
2931	See <xref linkend="api_overview.dynamic_and_batch_api" />
2932	for more examples of using the analysis API.
2933	</para>
2934
2935	<sect2 id="plugin_developer.analyse.abstractanalysis">
2936	<title>The AbstractAnalysisPlugin class</title>
2937
2938	<para>
2939	This class is an abstract base class. It is a useful
2940	class for most analysis plug-ins to inherit from. It's main
2941	purpose is to define <classname>PluginParameter</classname>
2942	objects that are commonly used in analysis plug-ins. This includes:
2943	</para>
2944
2945	<itemizedlist>
2946	<listitem>
2947	<para>
2948	The source bioassay set:
2949	<methodname>getSourceBioAssaySetParameter()</methodname>,
2950	<methodname>getCurrentBioAssaySet()</methodname>,
2951	<methodname>getSourceBioAssaySet()</methodname>
2952	</para>
2953	</listitem>
2954	<listitem>
2955	<para>
2956	The name and description of the child bioassay set that
2957	is going to be created by the plug-in:
2958	<methodname>getChildNameParameter()</methodname>,
2959	<methodname>getChildDescriptionParameter()</methodname>
2960	</para>
2961	</listitem>
2962	<listitem>
2963	<para>
2964	The name and description of the transformation that
2965	represents the execution of the plug-in:
2966	<methodname>getTransformationNameParameter()</methodname>,
2967	<methodname>getTransformationName()</methodname>
2968	</para>
2969	</listitem>
2970	</itemizedlist>
2971
2972	</sect2>
2973
2974	</sect1>
2975
2976	<sect1 id="plugin_developer.other">
2977	<title>Other plug-ins</title>
2978	<para></para>
2979
2980	<sect2 id="plugin_developer.other.authentication">
2981	<title>Authentication plug-ins</title>
2982
2983	<para>
2984	BASE provides a plug-in mechanism for authenticating users
2985	(validating the username and password) when they are logging in.
2986	This plug-in mechanism is not the same as the regular plug-in API.
2987	That is, you do not have worry about user interaction or implementing the
2988	<interfacename>Plugin</interfacename> interface.
2989	</para>
2990
2991	<sect3 id="plugin_developer.other.authentication.internal_external">
2992	<title>Internal vs. external authentation</title>
2993
2994	<para>
2995	BASE can authenticate users in two ways. Either it uses the internal
2996	authentiction or the external authentication. With internal
2997	authentication BASE stores logins and passwords in it's own database.
2998	With external authentication this is handled by some external
2999	application. Even with external authentication it is possible to
3000	let BASE cache the logins/passwords. This makes it possible to login to
3001	BASE if the external authentication server is down.
3002	</para>
3003
3004	<note>
3005	<para>
3006	An external authentication server can only be used to grant or deny
3007	a user access to BASE. It cannot be used to give a user permissions,
3008	or put a user into groups or different roles inside BASE.
3009	</para>
3010	</note>
3011
3012	<para>
3013	The external authentication service is only used when a user logs in.
3014	Now, one or more of several things can happen:
3015
3016	<itemizedlist>
3017	<listitem>
3018	<para>
3019	The ROOT user is logging on. Internal authentication is always
3020	used for the root user and the authenticator plug-in is never
3021	used.
3022	</para>
3023	</listitem>
3024
3025	<listitem>
3026	<para>
3027	The login is correct and the user is already known to BASE.
3028	If the plug-in supports extra information (name, email, phone, etc.)
3029	and the <property>auth.synchronize</property> setting
3030	is <constant>TRUE</constant> the extra information is copied to
3031	the BASE server.
3032	</para>
3033	</listitem>
3034
3035	<listitem>
3036	<para>
3037	The login is correct, but the user is not known to BASE. This happens
3038	the first time a user logs in. BASE will create
3039	a new user account. If the driver supports extra information, it
3040	is copied to the BASE server (even if <property>auth.synchronize</property>
3041	is not set). The new user account will get the default quota
3042	and be added to the all roles and groups which has been
3043	marked as <emphasis>default</emphasis>.
3044
3045	<note>
3046	<para>
3047	Prior to BASE 2.4 it was hardcoded to add the new user to the
3048	<emphasis>Users</emphasis> role only.
3049	</para>
3050	</note>
3051	</para>
3052	</listitem>
3053
3054	<listitem>
3055	<para>
3056	If password caching is enabled, the password is copied to BASE.
3057	If an expiration timeout has been set, an expiration date
3058	will be calculated and set on the user account. The expiration
3059	date is only checked when the external authentication server is
3060	down.
3061	</para>
3062	</listitem>
3063
3064	<listitem>
3065	<para>
3066	The authentication server says that the login is invalid or
3067	the password is incorrect. The user will not be logged in.
3068	If a user account with the specified login already exists in
3069	BASE, it will be disabled.
3070	</para>
3071	</listitem>
3072
3073	<listitem>
3074	<para>
3075	The authentication driver says that something else is wrong.
3076	If password caching is enabled, internal authentication will be
3077	used. Otherwise the user will not be logged in. An already
3078	existing account is not modified or disabled.
3079	</para>
3080	</listitem>
3081	</itemizedlist>
3082
3083	<note>
3084	<para>
3085	The <guilabel>Encrypt password</guilabel> option that is
3086	available on the login page does not work with external
3087	authentication. The simple reason is that the password is
3088	encrypted with a one-way algorithm making it impossible to
3089	call <methodname>Authenticator.authenticate()</methodname>.
3090	</para>
3091	</note>
3092
3093	</para>
3094	</sect3>
3095
3096	<sect3 id="plugin_developer.other.authentication.authenticator">
3097	<title>The Authenticator interface</title>
3098
3099	<para>
3100	To be able to use external authentication you must create a class
3101	that implements the
3102	<interfacename>net.sf.based.core.authentication.Authenticator</interfacename>
3103	interface. Specify the name of the class in the <property>auth.driver</property>
3104	setting in <filename>base.config</filename> and
3105	it's initialisation parameters in the <property>auth.init</property> setting.
3106	</para>
3107
3108	<para>
3109	Your class must have a public no-argument constructor. The BASE
3110	application will create only one instance of the class for lifetime
3111	of the BASE server. It must be thread-safe since it may be invoked by
3112	multiple threads at the same time. Here are the methods that you must
3113	implement
3114	</para>
3115
3116	<variablelist>
3117	<varlistentry>
3118	<term>
3119	<methodsynopsis language="java">
3120	<modifier>public</modifier>
3121	<void/>
3122	<methodname>init</methodname>
3123	<methodparam>
3124	<type>String</type>
3125	<parameter>settings</parameter>
3126	</methodparam>
3127	<exceptionname>AuthenticationException</exceptionname>
3128	</methodsynopsis>
3129	</term>
3130	<listitem>
3131	<para>
3132	This method is called just after the object has been created with it's argument
3133	taken from the <property>auth.init</property> setting in your <filename>base.config</filename>
3134	file. This method is only called once for an instance of the object. The syntax and meaning of
3135	the parameter is driver-dependent and should be documented by the plug-in.
3136	It is irrelevant for the BASE core.
3137	</para>
3138	</listitem>
3139	</varlistentry>
3140
3141	<varlistentry>
3142	<term>
3143	<methodsynopsis language="java">
3144	<modifier>public</modifier>
3145	<type>boolean</type>
3146	<methodname>supportsExtraInformation</methodname>
3147	</methodsynopsis>
3148	</term>
3149	<listitem>
3150	<para>
3151	This method should simply return <constant>TRUE</constant> or <constant>FALSE</constant>
3152	depending on if the plug-in supports extra user information or not. The only required
3153	information about a user is a unique ID and the login. Extra information includes
3154	name, address, phone, email, etc.
3155	</para>
3156	</listitem>
3157	</varlistentry>
3158
3159	<varlistentry>
3160	<term>
3161	<methodsynopsis language="java">
3162	<modifier>public</modifier>
3163	<type>AuthenticationInformation</type>
3164	<methodname>authenticate</methodname>
3165	<methodparam>
3166	<type>String</type>
3167	<parameter>login</parameter>
3168	</methodparam>
3169	<methodparam>
3170	<type>String</type>
3171	<parameter>password</parameter>
3172	</methodparam>
3173	<exceptionname>UnknownLoginException</exceptionname>
3174	<exceptionname>InvalidPasswordException</exceptionname>
3175	<exceptionname>AuthenticationException</exceptionname>
3176	</methodsynopsis>
3177	</term>
3178	<listitem>
3179	<para>
3180	Try to authenticate a login/password combination. The plug-in should return
3181	an <classname>AuthenticationInformation</classname> object if the
3182	authentication is successful or throw an exception if not.
3183
3184	There are three exceptions to choose from:
3185
3186	<itemizedlist>
3187	<listitem>
3188	<para>
3189	<exceptionname>UnknownLoginException</exceptionname>:
3190	This exception should be thrown if the login is not known to the
3191	external authentication system.
3192	</para>
3193	</listitem>
3194
3195	<listitem>
3196	<para>
3197	<exceptionname>InvalidPasswordException</exceptionname>:
3198	This exception should be thrown if the login is known but the
3199	password is invalid. In case it is considered a security issue
3200	to reveal that a login exists, the plugin may throw an
3201	<exceptionname>UnknowLoginException</exceptionname> instead.
3202	</para>
3203	</listitem>
3204
3205	<listitem>
3206	<para>
3207	<exceptionname>AuthenticationException</exceptionname>:
3208	In case there is another problem, such as the authentication service
3209	beeing down. This exception triggers the use of cached passwords
3210	if caching has been enabled.
3211	</para>
3212	</listitem>
3213	</itemizedlist>
3214	</para>
3215	</listitem>
3216	</varlistentry>
3217	</variablelist>
3218	</sect3>
3219
3220	<sect3 id="plugin_developer.other.authentication.settings">
3221	<title>Configuration settings</title>
3222
3223	<para>
3224	The configuration settings for the authentication driver are located
3225	in the <filename>base.config</filename> file.
3226	Here is an overview of the settings. For more information read
3227	<xref linkend="appendix.base.config.authentication" />.
3228	</para>
3229
3230	<variablelist>
3231	<varlistentry>
3232	<term><property>auth.driver</property></term>
3233	<listitem>
3234	<para>
3235	The class name of the authentication plug-in.
3236	</para>
3237	</listitem>
3238	</varlistentry>
3239
3240	<varlistentry>
3241	<term><property>auth.init</property></term>
3242	<listitem>
3243	<para>
3244	Initialisation parameters sent to the plug-in when calling the
3245	<methodname>Authenticator.init()</methodname> method.
3246	</para>
3247	</listitem>
3248	</varlistentry>
3249
3250	<varlistentry>
3251	<term><property>auth.synchronize</property></term>
3252	<listitem>
3253	<para>
3254	If extra user information is synchronized at login time or not.
3255	This setting is ignored if the driver does not support extra information.
3256	</para>
3257	</listitem>
3258	</varlistentry>
3259
3260	<varlistentry>
3261	<term><property>auth.cachepasswords</property></term>
3262	<listitem>
3263	<para>
3264	If passwords should be cached by BASE or not. If the passwords are
3265	cached a user may login to BASE even if the external authentication
3266	server is down.
3267	</para>
3268	</listitem>
3269	</varlistentry>
3270
3271	<varlistentry>
3272	<term><property>auth.daystocache</property></term>
3273	<listitem>
3274	<para>
3275	How many days to cache the passwords if caching has been enabled.
3276	A value of 0 caches the passwords for ever.
3277	</para>
3278	</listitem>
3279	</varlistentry>
3280	</variablelist>
3281	</sect3>
3282
3283	</sect2>
3284
3285	<sect2 id="plugin_developer.other.secondary">
3286	<title>Secondary file storage plugins</title>
3287	<para>
3288	This documentation is only available in the old format.
3289	See <ulink url="http://base.thep.lu.se/chrome/site/doc/development/plugins/storage/index.html"
3290	>http://base.thep.lu.se/chrome/site/doc/development/plugins/storage/index.html</ulink>
3291	</para>
3292	</sect2>
3293
3294	<sect2 id="plugin_developer.other.unpacker">
3295	<title>File unpacker plug-ins</title>
3296	<para>
3297	The BASE web client has integrated support for unpacking of
3298	compressed files. See <xref linkend="file_system.handling.upload" />.
3299	Behind the scenes, this support is provided by plug-ins. The standard
3300	BASE distribution comes with support for ZIP files
3301	(<classname>net.sf.basedb.plugins.ZipFileUnpacker</classname>)
3302	and TAR files (<classname>net.sf.basedb.plugins.ZipFileUnpacker</classname>).
3303	</para>
3304	<para>
3305	To add support for additional compressed formats you have to create a plug-in that
3306	implements the <interfacename>net.sf.basedb.util.zip.FileUnpacker</interfacename>
3307	interface. The best way to do this is to extend the
3308	<classname>net.sf.basedb.util.zip.AbstractFileUnpacker</classname> which
3309	implements all methods in the <interfacename>Plugin</interfacename>
3310	and <interfacename>InteractivePlugin</interfacename>
3311	interfaces except <methodname>Plugin.getAbout()</methodname>. This leaves
3312	you with the actual unpacking of the files as the only thing to implement.
3313	</para>
3314
3315	<note>
3316	<title>No support for configurations</title>
3317	The integrated upload in the web interface only works with plug-ins that
3318	does not require a configuration to run.
3319	</note>
3320
3321	<variablelist>
3322	<title>Methods in the <interfacename>FileUnpacker</interfacename> interface</title>
3323	<varlistentry>
3324	<term>
3325	<methodsynopsis language="java">
3326	<modifier>public</modifier>
3327	<type>String</type>
3328	<methodname>getFormatName</methodname>
3329	</methodsynopsis>
3330	</term>
3331	<listitem>
3332	<para>
3333	Return a short string naming the file format. For example:
3334	<constant>ZIP files</constant> or <constant>TAR files</constant>.
3335	</para>
3336	</listitem>
3337	</varlistentry>
3338
3339	<varlistentry>
3340	<term>
3341	<methodsynopsis language="java">
3342	<modifier>public</modifier>
3343	<type>Set<String></type>
3344	<methodname>getExtensions</methodname>
3345	</methodsynopsis>
3346	</term>
3347	<listitem>
3348	<para>
3349	Return a set of strings with the file extensions that
3350	are most commonly used with the compressed file format.
3351	For example: <constant>[zip, jar]</constant>. Do not include
3352	the dot in the extensions. The web client and the
3353	<methodname>AbstractFlatFileUnpacker.isInContext()</methodname> method
3354	will use this information to automatically guess which plug-in to
3355	use for unpacking the files.
3356	</para>
3357	</listitem>
3358	</varlistentry>
3359
3360	<varlistentry>
3361	<term>
3362	<methodsynopsis language="java">
3363	<modifier>public</modifier>
3364	<type>Set<String></type>
3365	<methodname>getMimeTypes</methodname>
3366	</methodsynopsis>
3367	</term>
3368	<listitem>
3369	<para>
3370	Return a set of string with the MIME types that commonly used with
3371	the compressed file format. For example:
3372	<constant>[application/zip, application/java-archive]</constant>.
3373	This information is used by the
3374	<methodname>AbstractFlatFileUnpacker.isInContext()</methodname>
3375	method to automatically guess which plug-in to use for unpacking
3376	the files.
3377	</para>
3378	</listitem>
3379	</varlistentry>
3380
3381	<varlistentry>
3382	<term>
3383	<methodsynopsis language="java">
3384	<modifier>public</modifier>
3385	<type>int</type>
3386	<methodname>unpack</methodname>
3387	<methodparam>
3388	<type>DbControl</type>
3389	<parameter>dc</parameter>
3390	</methodparam>
3391	<methodparam>
3392	<type>Directory</type>
3393	<parameter>dir</parameter>
3394	</methodparam>
3395	<methodparam>
3396	<type>InputStream</type>
3397	<parameter>in</parameter>
3398	</methodparam>
3399	<methodparam>
3400	<type>boolean</type>
3401	<parameter>overwrite</parameter>
3402	</methodparam>
3403	<methodparam>
3404	<type>AbsoluteProgressReporter</type>
3405	<parameter>progress</parameter>
3406	</methodparam>
3407	<exceptionname>IOException</exceptionname>
3408	<exceptionname>BaseException</exceptionname>
3409	</methodsynopsis>
3410	</term>
3411	<listitem>
3412	<para>
3413	Unpack the files and store them in the BASE file system.
3414
3415	<itemizedlist>
3416	<listitem>
3417	<para>
3418	Do not <methodname>close()</methodname> or
3419	<methodname>commit()</methodname> the
3420	<classname>DbControl</classname> passed to this method.
3421	This is done automatically by the
3422	<classname>AbstractFileUnpacker</classname> or by the web client.
3423	</para>
3424	</listitem>
3425
3426	<listitem>
3427	<para>
3428	The <varname>dir</varname> parameter is the root directory where
3429	the unpacked files should be placed. If the compressed file
3430	contains subdirectories the plug-in must create those subdirectories
3431	unless they already exists.
3432	</para>
3433	</listitem>
3434
3435	<listitem>
3436	<para>
3437	If the <varname>overwrite</varname> parameter is
3438	<constant>FALSE</constant> no existing file should be overwritten
3439	unless the file is <systemitem>OFFLINE</systemitem>.
3440	</para>
3441	</listitem>
3442
3443	<listitem>
3444	<para>
3445	The <varname>in</varname> parameter is the stream
3446	containing the compressed data. The stream may come
3447	directly from the web upload or from an existing
3448	file in the BASE file system.
3449	</para>
3450	</listitem>
3451
3452	<listitem>
3453	<para>
3454	The <varname>progress</varname> parameter, if not
3455	<constant>null</constant>, should be used to reporter the
3456	progress back to the calling code. The plug-in should count
3457	the number of bytes read from the <varname>in</varname>
3458	stream. If it is not possible by other means the stream can
3459	be wrapped by a <classname>net.sf.basedb.util.InputStreamTracker</classname>
3460	object which has a <methodname>getNumRead()</methodname> method.
3461	</para>
3462	</listitem>
3463	</itemizedlist>
3464
3465	</para>
3466	</listitem>
3467	</varlistentry>
3468	</variablelist>
3469
3470	<para>
3471	When the compressed file is uncompressed during the file upload
3472	from the web interface, the call sequence to the plug-in is slightly
3473	altered from the standard call sequence described in
3474	<xref linkend="plugin_developer.api.callsequence.execute" />.
3475
3476	<itemizedlist>
3477	<listitem>
3478	<para>
3479	After the plug-in instance has been created, the
3480	<methodname>Plugin.init()</methodname> method is called with <constant>null</constant>
3481	values for both the <varname>configuration</varname> and <varname>job</varname>
3482	parameters.
3483	</para>
3484	</listitem>
3485
3486	<listitem>
3487	<para>
3488	Then, the <methodname>unpack()</methodname> method is called. The
3489	<methodname>Plugin.run()</methodname> method is never called in this case.
3490	</para>
3491	</listitem>
3492
3493	</itemizedlist>
3494
3495	</para>
3496
3497	</sect2>
3498	</sect1>
3499
3500	<sect1 id="plugin_developer.example">
3501	<title>Example plug-ins (with download)</title>
3502	<para>
3503	<para>
3504	This documentation is only available in the old format.
3505	See <ulink url="http://base.thep.lu.se/chrome/site/doc/development/index.html#plugins"
3506	>http://base.thep.lu.se/chrome/site/doc/development/index.html#plugins</ulink>
3507	</para>
3508	</para>
3509	</sect1>
3510	</chapter>

Note: See TracBrowser for help on using the repository browser.

Download in other formats: