doc/src/docbook/developer/base_api.xml

Code
Comments
Other
Rev Date Author Line
3160 05 Mar 07 martin 1 <?xml version="1.0" encoding="UTF-8"?>
3160 05 Mar 07 martin 2 <!DOCTYPE chapter PUBLIC 
3160 05 Mar 07 martin 3     "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" 
3192 13 Mar 07 martin 4     "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
3160 05 Mar 07 martin 5 <!--
3192 13 Mar 07 martin 6   $Id$
3160 05 Mar 07 martin 7
3675 16 Aug 07 jari 8   Copyright (C) 2007 Peter Johansson, Nicklas Nordborg, Martin Svensson
3160 05 Mar 07 martin 9
3160 05 Mar 07 martin 10   This file is part of BASE - BioArray Software Environment.
3160 05 Mar 07 martin 11   Available at http://base.thep.lu.se/
3160 05 Mar 07 martin 12
3160 05 Mar 07 martin 13   BASE is free software; you can redistribute it and/or
3160 05 Mar 07 martin 14   modify it under the terms of the GNU General Public License
4477 05 Sep 08 jari 15   as published by the Free Software Foundation; either version 3
3160 05 Mar 07 martin 16   of the License, or (at your option) any later version.
3160 05 Mar 07 martin 17
3160 05 Mar 07 martin 18   BASE is distributed in the hope that it will be useful,
3160 05 Mar 07 martin 19   but WITHOUT ANY WARRANTY; without even the implied warranty of
3160 05 Mar 07 martin 20   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
3160 05 Mar 07 martin 21   GNU General Public License for more details.
3160 05 Mar 07 martin 22
3160 05 Mar 07 martin 23   You should have received a copy of the GNU General Public License
4509 11 Sep 08 jari 24   along with BASE. If not, see <http://www.gnu.org/licenses/>.
3160 05 Mar 07 martin 25 -->
3160 05 Mar 07 martin 26
5780 04 Oct 11 nicklas 27 <chapter id="base_api">
5782 04 Oct 11 nicklas 28   <?dbhtml dir="api" filename="index.html" ?>
5780 04 Oct 11 nicklas 29   <title>The BASE API</title>
3315 09 May 07 nicklas 30
5780 04 Oct 11 nicklas 31   <sect1 id="base_api.public">
5782 04 Oct 11 nicklas 32     <?dbhtml filename="public_api.html" ?>
3409 30 May 07 nicklas 33     <title>The Public API of BASE</title>
3409 30 May 07 nicklas 34     
3409 30 May 07 nicklas 35     <para>
5780 04 Oct 11 nicklas 36       Not all public classes and methods in the <filename>base-*.jar</filename>
5780 04 Oct 11 nicklas 37       files and other JAR files shipped with BASE are considered as
3409 30 May 07 nicklas 38       <emphasis>Public API</emphasis>. This is important knowledge
3409 30 May 07 nicklas 39       since we will always try to maintain backwards compatibility
3409 30 May 07 nicklas 40       for classes that are part of the public API. For other
3940 08 Nov 07 martin 41       classes, changes may be introduced at any time without
3409 30 May 07 nicklas 42       notice or specific documentation. In other words:
3409 30 May 07 nicklas 43     </para>
3409 30 May 07 nicklas 44     
3409 30 May 07 nicklas 45     <note>
5780 04 Oct 11 nicklas 46       <title>Only use the public API when developing plug-ins and extensions</title>
3409 30 May 07 nicklas 47       <para>
5780 04 Oct 11 nicklas 48         This will maximize the chance that your code will continue
3409 30 May 07 nicklas 49         to work with the next BASE release. If you use the non-public API
3409 30 May 07 nicklas 50         you do so at your own risk.
3409 30 May 07 nicklas 51       </para>
3409 30 May 07 nicklas 52     </note>
3409 30 May 07 nicklas 53     
3409 30 May 07 nicklas 54     <para>
5818 21 Oct 11 nicklas 55       See the <ulink url="../../../api/index.html"
5780 04 Oct 11 nicklas 56         >BASE API javadoc</ulink> for information about
3409 30 May 07 nicklas 57       what parts of the API that contributes to the public API.
3415 31 May 07 nicklas 58       Methods, classes and other elements that have been tagged as 
3415 31 May 07 nicklas 59       <code>@deprecated</code> should be considered as part of the internal API 
3940 08 Nov 07 martin 60       and may be removed in a subsequent release without warning.
3409 30 May 07 nicklas 61     </para>
3415 31 May 07 nicklas 62     
3415 31 May 07 nicklas 63     <para>
5780 04 Oct 11 nicklas 64       Keeping the backwards compatibility is an aim only. It may not
5780 04 Oct 11 nicklas 65       always be possible. See <xref linkend="appendix.incompatible" /> to 
5780 04 Oct 11 nicklas 66       read more about changes that have been introduced by each release
5780 04 Oct 11 nicklas 67       that may affect existing code.
3415 31 May 07 nicklas 68     </para>
3409 30 May 07 nicklas 69
5780 04 Oct 11 nicklas 70     <sect2 id="base_api.compatibility">
3409 30 May 07 nicklas 71       <title>What is backwards compatibility?</title>
3409 30 May 07 nicklas 72       
3409 30 May 07 nicklas 73       <para>
3409 30 May 07 nicklas 74         There is a great article about this subject on <ulink 
3409 30 May 07 nicklas 75         url="http://wiki.eclipse.org/index.php/Evolving_Java-based_APIs"
3409 30 May 07 nicklas 76           >http://wiki.eclipse.org/index.php/Evolving_Java-based_APIs</ulink>.
3487 13 Jun 07 peter 77         This is what we will try to comply with. If you do not want to
3409 30 May 07 nicklas 78         read the entire article, here are some of the most important points:
3409 30 May 07 nicklas 79       </para>
3409 30 May 07 nicklas 80       
3415 31 May 07 nicklas 81       
5780 04 Oct 11 nicklas 82       <sect3 id="core_api.compatibility.binary">
3415 31 May 07 nicklas 83         <title>Binary compatibility</title>
3415 31 May 07 nicklas 84         <para>
3415 31 May 07 nicklas 85         <blockquote>
3415 31 May 07 nicklas 86           Pre-existing Client binaries must link and run with new releases of the 
3415 31 May 07 nicklas 87           Component without recompiling.
3415 31 May 07 nicklas 88         </blockquote>
3415 31 May 07 nicklas 89         
3415 31 May 07 nicklas 90         For example:
3415 31 May 07 nicklas 91         <itemizedlist>
3409 30 May 07 nicklas 92         <listitem>
3409 30 May 07 nicklas 93           <para>
3487 13 Jun 07 peter 94             We cannot change the number or types of parameters to a method
3415 31 May 07 nicklas 95             or constructor.
3415 31 May 07 nicklas 96           </para>
3415 31 May 07 nicklas 97         </listitem>
3415 31 May 07 nicklas 98         <listitem>
3415 31 May 07 nicklas 99           <para>
3487 13 Jun 07 peter 100             We cannot add or change methods to interfaces that are intended
3415 31 May 07 nicklas 101             to be implemented by plug-in or client code.
3415 31 May 07 nicklas 102           </para>
3415 31 May 07 nicklas 103         </listitem>
3415 31 May 07 nicklas 104         </itemizedlist>
3415 31 May 07 nicklas 105         </para>        
3415 31 May 07 nicklas 106       </sect3>
3415 31 May 07 nicklas 107       
5780 04 Oct 11 nicklas 108       <sect3 id="base_api.compatibility.contract">
3415 31 May 07 nicklas 109         <title>Contract compatibility</title>
3415 31 May 07 nicklas 110         <para>
3409 30 May 07 nicklas 111           <blockquote>
3415 31 May 07 nicklas 112           API changes must not invalidate formerly legal Client code.
3409 30 May 07 nicklas 113           </blockquote>
3415 31 May 07 nicklas 114         
3409 30 May 07 nicklas 115           For example:
3409 30 May 07 nicklas 116           <itemizedlist>
3409 30 May 07 nicklas 117           <listitem>
3409 30 May 07 nicklas 118             <para>
3487 13 Jun 07 peter 119               We cannot change the implementation of a method to do
3415 31 May 07 nicklas 120               things differently than before. For example, allow <constant>null</constant>
3487 13 Jun 07 peter 121               as a return value when it was not allowed before.
3409 30 May 07 nicklas 122             </para>
3409 30 May 07 nicklas 123           </listitem>
3415 31 May 07 nicklas 124           </itemizedlist>
3415 31 May 07 nicklas 125         
3415 31 May 07 nicklas 126           <note>
3409 30 May 07 nicklas 127             <para>
3415 31 May 07 nicklas 128             Sometimes there is a very fine line between what is considered a
3415 31 May 07 nicklas 129             bug and what is considered a feature. For example, if the
3487 13 Jun 07 peter 130             actual implementation does not do what the javadoc says,
3415 31 May 07 nicklas 131             do we change the code or do we change the documentation?
3415 31 May 07 nicklas 132             This has to be considered from case to case and depends on 
3415 31 May 07 nicklas 133             the age of the code and if we expect plug-ins and clients to be
3415 31 May 07 nicklas 134             affected by it or not.
3409 30 May 07 nicklas 135             </para>
3415 31 May 07 nicklas 136           </note>
3415 31 May 07 nicklas 137         </para>
3415 31 May 07 nicklas 138       </sect3>
3415 31 May 07 nicklas 139       
5780 04 Oct 11 nicklas 140       <sect3 id="base_api.compatibility.source">
3415 31 May 07 nicklas 141         <title>Source code compatibility</title>
3415 31 May 07 nicklas 142         <para>
3415 31 May 07 nicklas 143         This is not an important matter and is not always possible to
3415 31 May 07 nicklas 144         achieve. In most cases, the problems are easy to fix.
3415 31 May 07 nicklas 145         Example:
3415 31 May 07 nicklas 146         
3415 31 May 07 nicklas 147         <itemizedlist>
3409 30 May 07 nicklas 148         <listitem>
3409 30 May 07 nicklas 149           <para>
3415 31 May 07 nicklas 150           Adding a class may break a plug-in or client that import
3415 31 May 07 nicklas 151           classes with <constant>.*</constant> if the same class name
3415 31 May 07 nicklas 152           exists in another package.
3409 30 May 07 nicklas 153           </para>
3409 30 May 07 nicklas 154         </listitem>
3415 31 May 07 nicklas 155         </itemizedlist>
3415 31 May 07 nicklas 156         </para>
3415 31 May 07 nicklas 157       </sect3>
3409 30 May 07 nicklas 158     </sect2>
3409 30 May 07 nicklas 159   </sect1>
3409 30 May 07 nicklas 160
5780 04 Oct 11 nicklas 161   <sect1 id="base_api.data" chunked="1">
5782 04 Oct 11 nicklas 162     <?dbhtml filename="data_api.html" ?>
5780 04 Oct 11 nicklas 163     <title>The Data Layer API</title>
3315 09 May 07 nicklas 164
3315 09 May 07 nicklas 165     <para>
3715 11 Sep 07 nicklas 166       This section gives an overview of the entire data layer API. 
3715 11 Sep 07 nicklas 167       The figure below show how different modules relate to each other.
3315 09 May 07 nicklas 168     </para>
4902 24 Apr 09 nicklas 169   
3715 11 Sep 07 nicklas 170     <figure id="data_api.figures.overview">
3715 11 Sep 07 nicklas 171       <title>Data layer overview</title>
3715 11 Sep 07 nicklas 172       <screenshot>
3715 11 Sep 07 nicklas 173         <mediaobject>
3715 11 Sep 07 nicklas 174           <imageobject>
3715 11 Sep 07 nicklas 175             <imagedata 
3943 09 Nov 07 nicklas 176               align="center"
3943 09 Nov 07 nicklas 177               scalefit="1" width="100%"
3715 11 Sep 07 nicklas 178               fileref="figures/uml/datalayer.overview.png" format="PNG" />
3715 11 Sep 07 nicklas 179           </imageobject>
3715 11 Sep 07 nicklas 180         </mediaobject>
3715 11 Sep 07 nicklas 181       </screenshot>
3715 11 Sep 07 nicklas 182     </figure>
3715 11 Sep 07 nicklas 183
3715 11 Sep 07 nicklas 184     <sect2 id="data_api.basic">
3715 11 Sep 07 nicklas 185       <title>Basic classes and interfaces</title>
3715 11 Sep 07 nicklas 186       
3715 11 Sep 07 nicklas 187       <para>
3715 11 Sep 07 nicklas 188         This document contains information about the basic classes and interfaces in this package. 
3715 11 Sep 07 nicklas 189         They are important since all data-layer classes must inherit from one of the already 
3715 11 Sep 07 nicklas 190         existing abstract base classes or implement one or more of the
3715 11 Sep 07 nicklas 191         existing interfaces. They contain code that is common to all classes, 
3715 11 Sep 07 nicklas 192         for example implementations of the <methodname>equals()</methodname>
3715 11 Sep 07 nicklas 193         and <methodname>hashCode()</methodname> methods or how to link with the owner of an 
3715 11 Sep 07 nicklas 194         item.
3715 11 Sep 07 nicklas 195       </para>
3715 11 Sep 07 nicklas 196       
3715 11 Sep 07 nicklas 197         <figure id="data_api.figures.basic">
3715 11 Sep 07 nicklas 198           <title>Basic classes and interfaces</title>
3715 11 Sep 07 nicklas 199           <screenshot>
3715 11 Sep 07 nicklas 200             <mediaobject>
3715 11 Sep 07 nicklas 201               <imageobject>
3715 11 Sep 07 nicklas 202                 <imagedata 
3943 09 Nov 07 nicklas 203                   align="center"
3715 11 Sep 07 nicklas 204                   fileref="figures/uml/datalayer.basic.png" format="PNG" />
3715 11 Sep 07 nicklas 205               </imageobject>
3715 11 Sep 07 nicklas 206             </mediaobject>
3715 11 Sep 07 nicklas 207           </screenshot>
3715 11 Sep 07 nicklas 208         </figure>
3715 11 Sep 07 nicklas 209       
3715 11 Sep 07 nicklas 210       <sect3 id="data_api.basic.classes">
3715 11 Sep 07 nicklas 211         <title>Classes</title>
3715 11 Sep 07 nicklas 212         
3715 11 Sep 07 nicklas 213         <variablelist>
3715 11 Sep 07 nicklas 214         <varlistentry>
3947 12 Nov 07 nicklas 215           <term><classname docapi="net.sf.basedb.core.data">BasicData</classname></term>
3715 11 Sep 07 nicklas 216           <listitem>
3715 11 Sep 07 nicklas 217             <para>
3715 11 Sep 07 nicklas 218             The root class. It overrides the <methodname>equals()</methodname>, 
3715 11 Sep 07 nicklas 219             <methodname>hashCode()</methodname> and <methodname>toString()</methodname> methods 
3715 11 Sep 07 nicklas 220             from the <classname>Object</classname> class. It also defines the 
3715 11 Sep 07 nicklas 221             <varname>id</varname> and <varname>version</varname> properties.
3715 11 Sep 07 nicklas 222             All data layer classes must inherit from this class or one of it's subclasses.
3715 11 Sep 07 nicklas 223             </para>
3715 11 Sep 07 nicklas 224           </listitem>
3715 11 Sep 07 nicklas 225         </varlistentry>
3715 11 Sep 07 nicklas 226         
3715 11 Sep 07 nicklas 227         <varlistentry>
3947 12 Nov 07 nicklas 228           <term><classname docapi="net.sf.basedb.core.data">OwnedData</classname></term>
3715 11 Sep 07 nicklas 229           <listitem>
3715 11 Sep 07 nicklas 230             <para>
3715 11 Sep 07 nicklas 231             Extends the <classname>BasicData</classname> class and adds 
3715 11 Sep 07 nicklas 232             an <varname>owner</varname> property. The owner is a required link to a 
3947 12 Nov 07 nicklas 233             <classname docapi="net.sf.basedb.core.data">UserData</classname> object, representing the user that
3715 11 Sep 07 nicklas 234             is the owner of the item.
3715 11 Sep 07 nicklas 235             </para>
3715 11 Sep 07 nicklas 236           </listitem>
3715 11 Sep 07 nicklas 237         </varlistentry>
3715 11 Sep 07 nicklas 238
3715 11 Sep 07 nicklas 239         <varlistentry>
3947 12 Nov 07 nicklas 240           <term><classname docapi="net.sf.basedb.core.data">SharedData</classname></term>
3715 11 Sep 07 nicklas 241           <listitem>
3715 11 Sep 07 nicklas 242             <para>
3715 11 Sep 07 nicklas 243             Extends the <classname>OwnedData</classname> class and adds 
3715 11 Sep 07 nicklas 244             properties (<varname>itemKey</varname> and <varname>projectKey</varname>)
3715 11 Sep 07 nicklas 245             that holds access permission information for an item.
3947 12 Nov 07 nicklas 246             Access permissions are held in <classname docapi="net.sf.basedb.core.data">ItemKeyData</classname> and/or 
3947 12 Nov 07 nicklas 247             <classname docapi="net.sf.basedb.core.data">ProjectKeyData</classname> objects. These objects only exists if 
3715 11 Sep 07 nicklas 248             the item has been shared.
3715 11 Sep 07 nicklas 249             </para>
3715 11 Sep 07 nicklas 250           </listitem>
3715 11 Sep 07 nicklas 251         </varlistentry>
3715 11 Sep 07 nicklas 252
3715 11 Sep 07 nicklas 253         <varlistentry>
3947 12 Nov 07 nicklas 254           <term><classname docapi="net.sf.basedb.core.data">CommonData</classname></term>
3715 11 Sep 07 nicklas 255           <listitem>
3715 11 Sep 07 nicklas 256             <para>
3715 11 Sep 07 nicklas 257             This is a convenience class for items that extends the <classname>SharedData</classname>
3947 12 Nov 07 nicklas 258             class and implements the <interfacename docapi="net.sf.basedb.core.data">NameableData</interfacename> and 
3947 12 Nov 07 nicklas 259             <interfacename docapi="net.sf.basedb.core.data">RemoveableData</interfacename> interfaces. This is one of
3715 11 Sep 07 nicklas 260             the most common situations.
3715 11 Sep 07 nicklas 261             </para>
3715 11 Sep 07 nicklas 262           </listitem>
3715 11 Sep 07 nicklas 263         </varlistentry>
3715 11 Sep 07 nicklas 264
3715 11 Sep 07 nicklas 265         <varlistentry>
3947 12 Nov 07 nicklas 266           <term><classname docapi="net.sf.basedb.core.data">AnnotatedData</classname></term>
3715 11 Sep 07 nicklas 267           <listitem>
3715 11 Sep 07 nicklas 268             <para>
3715 11 Sep 07 nicklas 269             This is a convenience class for items that can be annotated. 
3947 12 Nov 07 nicklas 270             Annotations are held in <classname docapi="net.sf.basedb.core.data">AnnotationSetData</classname> objects. 
3715 11 Sep 07 nicklas 271             The annotation set only exists if annotations has been created for the item.
3715 11 Sep 07 nicklas 272             </para>
3715 11 Sep 07 nicklas 273           </listitem>
3715 11 Sep 07 nicklas 274         </varlistentry>
3715 11 Sep 07 nicklas 275         </variablelist>
3715 11 Sep 07 nicklas 276         
3715 11 Sep 07 nicklas 277       </sect3>
3715 11 Sep 07 nicklas 278       
3715 11 Sep 07 nicklas 279       <sect3 id="data_api.basic.interfaces">
3715 11 Sep 07 nicklas 280         <title>Interfaces</title>
3715 11 Sep 07 nicklas 281         
3715 11 Sep 07 nicklas 282         <variablelist>
3715 11 Sep 07 nicklas 283         <varlistentry>
3947 12 Nov 07 nicklas 284           <term><classname docapi="net.sf.basedb.core.data">IdentifiableData</classname></term>
3715 11 Sep 07 nicklas 285           <listitem>
3715 11 Sep 07 nicklas 286             <para>
3715 11 Sep 07 nicklas 287             All items are identifiable, which means that they have a unique <varname>id</varname>. 
3715 11 Sep 07 nicklas 288             The id is unique for all items of a specific type (ie. class). The id is number 
3715 11 Sep 07 nicklas 289             that is automatically generated by the database and has no other meaning 
3715 11 Sep 07 nicklas 290             outside of the application. The <varname>version</varname> property is used for 
3715 11 Sep 07 nicklas 291             detecting and preventing concurrent modifications to an item. 
3715 11 Sep 07 nicklas 292             </para>
3715 11 Sep 07 nicklas 293           </listitem>
3715 11 Sep 07 nicklas 294         </varlistentry>
3715 11 Sep 07 nicklas 295         
3715 11 Sep 07 nicklas 296         <varlistentry>
3947 12 Nov 07 nicklas 297           <term><classname docapi="net.sf.basedb.core.data">OwnableData</classname></term>
3715 11 Sep 07 nicklas 298           <listitem>
3715 11 Sep 07 nicklas 299             <para>
3715 11 Sep 07 nicklas 300             An ownable item is an item which has an owner. The owner is represented as a 
3947 12 Nov 07 nicklas 301             required link to a <classname docapi="net.sf.basedb.core.data">UserData</classname> object. 
3715 11 Sep 07 nicklas 302             </para>
3715 11 Sep 07 nicklas 303           </listitem>
3715 11 Sep 07 nicklas 304         </varlistentry>        
3715 11 Sep 07 nicklas 305
3715 11 Sep 07 nicklas 306         <varlistentry>
3947 12 Nov 07 nicklas 307           <term><classname docapi="net.sf.basedb.core.data">ShareableData</classname></term>
3715 11 Sep 07 nicklas 308           <listitem>
3715 11 Sep 07 nicklas 309             <para>
3715 11 Sep 07 nicklas 310             A shareable item is an item which can be shared to other users, groups or projects.
3947 12 Nov 07 nicklas 311             Access permissions are held in <classname docapi="net.sf.basedb.core.data">ItemKeyData</classname> and/or 
3947 12 Nov 07 nicklas 312             <classname docapi="net.sf.basedb.core.data">ProjectKeyData</classname> objects. 
3715 11 Sep 07 nicklas 313             </para>
3715 11 Sep 07 nicklas 314           </listitem>
3715 11 Sep 07 nicklas 315         </varlistentry>
3715 11 Sep 07 nicklas 316               
3715 11 Sep 07 nicklas 317         <varlistentry>
3947 12 Nov 07 nicklas 318           <term><classname docapi="net.sf.basedb.core.data">NameableData</classname></term>
3715 11 Sep 07 nicklas 319           <listitem>
3715 11 Sep 07 nicklas 320             <para>
3715 11 Sep 07 nicklas 321             A nameable item is an item that has a name (required) and a description
3715 11 Sep 07 nicklas 322             (optional). The name doesn't have to be unique, except in a few special 
3715 11 Sep 07 nicklas 323             cases (for example, the name of a file).
3715 11 Sep 07 nicklas 324             </para>
3715 11 Sep 07 nicklas 325           </listitem>
3715 11 Sep 07 nicklas 326         </varlistentry>
3715 11 Sep 07 nicklas 327         
3715 11 Sep 07 nicklas 328         <varlistentry>
3947 12 Nov 07 nicklas 329           <term><classname docapi="net.sf.basedb.core.data">RemovableData</classname></term>
3715 11 Sep 07 nicklas 330           <listitem>
3715 11 Sep 07 nicklas 331             <para>
3715 11 Sep 07 nicklas 332             A removable item is an item that can be flagged as removed. This doesn't 
3715 11 Sep 07 nicklas 333             remove the information about the item from the database, but can be used by 
3715 11 Sep 07 nicklas 334             client applications to hide items that the user is not interested in. 
3715 11 Sep 07 nicklas 335             A trashcan function can be used to either restore or permanently 
3715 11 Sep 07 nicklas 336             remove items that has the flag set.
3715 11 Sep 07 nicklas 337             </para>
3715 11 Sep 07 nicklas 338           </listitem>
3715 11 Sep 07 nicklas 339         </varlistentry>
3715 11 Sep 07 nicklas 340                 
3715 11 Sep 07 nicklas 341         <varlistentry>
3947 12 Nov 07 nicklas 342           <term><classname docapi="net.sf.basedb.core.data">SystemData</classname></term>
3715 11 Sep 07 nicklas 343           <listitem>
3715 11 Sep 07 nicklas 344             <para>
3715 11 Sep 07 nicklas 345             A system item is an item which has an additional id in the form of string. A system id 
3715 11 Sep 07 nicklas 346             is required when we need to make sure that we can get a specific item without 
3715 11 Sep 07 nicklas 347             knowing the numeric id. Example of such items are the root user and the everyone group. 
3715 11 Sep 07 nicklas 348             A system id is generally constructed like: 
3715 11 Sep 07 nicklas 349             <constant>net.sf.basedb.core.User.ROOT</constant>. The system id:s are defined in the 
3715 11 Sep 07 nicklas 350             core layer by each item class. 
3715 11 Sep 07 nicklas 351             </para>
3715 11 Sep 07 nicklas 352           </listitem>
3715 11 Sep 07 nicklas 353         </varlistentry>
3715 11 Sep 07 nicklas 354
3715 11 Sep 07 nicklas 355         <varlistentry>
3947 12 Nov 07 nicklas 356           <term><classname docapi="net.sf.basedb.core.data">DiskConsumableData</classname></term>
3715 11 Sep 07 nicklas 357           <listitem>
3715 11 Sep 07 nicklas 358             <para>
3715 11 Sep 07 nicklas 359             This interface is used by items which occupies a lot of disk space and 
3715 11 Sep 07 nicklas 360             should be part of the quota system, for example files. The required 
3947 12 Nov 07 nicklas 361             <classname docapi="net.sf.basedb.core.data">DiskUsageData</classname> contains information about the size, 
3715 11 Sep 07 nicklas 362             location, owner etc. of the item.
3715 11 Sep 07 nicklas 363             </para>
3715 11 Sep 07 nicklas 364           </listitem>
3715 11 Sep 07 nicklas 365         </varlistentry>
3715 11 Sep 07 nicklas 366         
3715 11 Sep 07 nicklas 367         <varlistentry>
3947 12 Nov 07 nicklas 368           <term><classname docapi="net.sf.basedb.core.data">AnnotatableData</classname></term>
3715 11 Sep 07 nicklas 369           <listitem>
3715 11 Sep 07 nicklas 370             <para>
3715 11 Sep 07 nicklas 371             This interface is used by items which can be annotated. Annotations are name/value 
3715 11 Sep 07 nicklas 372             pairs that are attached as extra information to an item. All annotations are
3947 12 Nov 07 nicklas 373             contained in an <classname docapi="net.sf.basedb.core.data">AnnotationSetData</classname> object. 
3715 11 Sep 07 nicklas 374             </para>
3715 11 Sep 07 nicklas 375           </listitem>
3715 11 Sep 07 nicklas 376         </varlistentry>
3715 11 Sep 07 nicklas 377         
3715 11 Sep 07 nicklas 378         <varlistentry>
3947 12 Nov 07 nicklas 379           <term><classname docapi="net.sf.basedb.core.data">ExtendableData</classname></term>
3715 11 Sep 07 nicklas 380           <listitem>
3715 11 Sep 07 nicklas 381             <para>
3715 11 Sep 07 nicklas 382             This interface is used by items which can have extra administrator-defined 
3715 11 Sep 07 nicklas 383             columns. The functionality is similar to annotations. It is not as flexible, 
3715 11 Sep 07 nicklas 384             since it is a global configuration, but has better performance. BASE will
3715 11 Sep 07 nicklas 385             generate extra database columns to store the data in the tables for items that
3715 11 Sep 07 nicklas 386             can be extended.
3715 11 Sep 07 nicklas 387             </para>
3715 11 Sep 07 nicklas 388           </listitem>
3715 11 Sep 07 nicklas 389         </varlistentry>
3715 11 Sep 07 nicklas 390         
3715 11 Sep 07 nicklas 391         <varlistentry>
3947 12 Nov 07 nicklas 392           <term><classname docapi="net.sf.basedb.core.data">BatchableData</classname></term>
3715 11 Sep 07 nicklas 393           <listitem>
3715 11 Sep 07 nicklas 394             <para>
3715 11 Sep 07 nicklas 395             This interface is a tagging interface which is used by items that needs batch 
3715 11 Sep 07 nicklas 396             functionality in the core.
3715 11 Sep 07 nicklas 397             </para>
3715 11 Sep 07 nicklas 398           </listitem>
3715 11 Sep 07 nicklas 399         </varlistentry>
4696 09 Dec 08 nicklas 400         
4696 09 Dec 08 nicklas 401         <varlistentry>
5780 04 Oct 11 nicklas 402           <term><interfacename docapi="net.sf.basedb.core.data">RegisteredData</interfacename></term>
4696 09 Dec 08 nicklas 403           <listitem>
4696 09 Dec 08 nicklas 404             <para>
4696 09 Dec 08 nicklas 405             This interface is used by items which registered the date they were
4696 09 Dec 08 nicklas 406             created in the database. The registration date is set at creation time
5071 21 Aug 09 nicklas 407             and can't be modified later. Since this didn't exist prior to BASE 2.10,
4696 09 Dec 08 nicklas 408             null values are allowed on all pre-existing items. Note! For backwards 
4696 09 Dec 08 nicklas 409             compatibility reasons with existing code in 
4696 09 Dec 08 nicklas 410             <classname docapi="net.sf.basedb.core.data">BioMaterialEventData</classname>
4696 09 Dec 08 nicklas 411             the method name is <methodname>getEntryDate()</methodname>.
4696 09 Dec 08 nicklas 412             </para>
4696 09 Dec 08 nicklas 413           </listitem>
4696 09 Dec 08 nicklas 414         </varlistentry>
5071 21 Aug 09 nicklas 415         
5071 21 Aug 09 nicklas 416         <varlistentry>
5071 21 Aug 09 nicklas 417           <term><interfacename docapi="net.sf.basedb.core.data">LoggableData</interfacename></term>
5071 21 Aug 09 nicklas 418           <listitem>
5071 21 Aug 09 nicklas 419             <para>
5071 21 Aug 09 nicklas 420             This is a tagging interface that indicates that the <classname 
5071 21 Aug 09 nicklas 421             docapi="net.sf.basedb.core.log.db">DbLogManagerFactory</classname> logging
5071 21 Aug 09 nicklas 422             implementation should log changes made to items that implements it.
5071 21 Aug 09 nicklas 423             </para>
5071 21 Aug 09 nicklas 424           </listitem>
5071 21 Aug 09 nicklas 425         </varlistentry>
5780 04 Oct 11 nicklas 426
5780 04 Oct 11 nicklas 427         <varlistentry>
5780 04 Oct 11 nicklas 428           <term><interfacename docapi="net.sf.basedb.core.data">FileStoreEnabledData</interfacename></term>
5780 04 Oct 11 nicklas 429           <listitem>
5780 04 Oct 11 nicklas 430             <para>
5780 04 Oct 11 nicklas 431             This interface is implemented by all items that can have files with related data
5780 04 Oct 11 nicklas 432             attached to them. The file types that can be used for a specific item are usually
5780 04 Oct 11 nicklas 433             determined by the main type, the subtype or platform.
5780 04 Oct 11 nicklas 434             </para>
5780 04 Oct 11 nicklas 435           </listitem>
5780 04 Oct 11 nicklas 436         </varlistentry>
5780 04 Oct 11 nicklas 437
5780 04 Oct 11 nicklas 438         <varlistentry>
5780 04 Oct 11 nicklas 439           <term><interfacename docapi="net.sf.basedb.core.data">SubtypableData</interfacename></term>
5780 04 Oct 11 nicklas 440           <listitem>
5780 04 Oct 11 nicklas 441             <para>
5780 04 Oct 11 nicklas 442             This interface should be implemented by all items that can be subtyped.
5780 04 Oct 11 nicklas 443             Unless otherwise noted the subtype is always an optional link to
5780 04 Oct 11 nicklas 444             a <classname docapi="net.sf.basedb.core.data">ItemSubtypeData</classname>.
5780 04 Oct 11 nicklas 445             item. In the simplest form, the subtype is a kind of an annotation, but
5780 04 Oct 11 nicklas 446             for items that also implements the <interfacename 
5780 04 Oct 11 nicklas 447             docapi="net.sf.basedb.core.data">FileStoreEnabledData</interfacename>
5780 04 Oct 11 nicklas 448             interface, the subtype can be used to specify the file types that
5780 04 Oct 11 nicklas 449             are applicable for each item.
5780 04 Oct 11 nicklas 450             </para>
5780 04 Oct 11 nicklas 451           </listitem>
5780 04 Oct 11 nicklas 452         </varlistentry>
4696 09 Dec 08 nicklas 453         </variablelist>
3715 11 Sep 07 nicklas 454
3715 11 Sep 07 nicklas 455       </sect3>
3715 11 Sep 07 nicklas 456     </sect2>
3715 11 Sep 07 nicklas 457     
3715 11 Sep 07 nicklas 458     <sect2 id="data_api.authentication">
3715 11 Sep 07 nicklas 459       <title>User authentication and access control</title>
3715 11 Sep 07 nicklas 460       
3715 11 Sep 07 nicklas 461       <para>
3715 11 Sep 07 nicklas 462          This section gives an overview of user authentication and
3715 11 Sep 07 nicklas 463          how groups, roles and projects are used for access control
3715 11 Sep 07 nicklas 464          to items.
3715 11 Sep 07 nicklas 465       </para>
3715 11 Sep 07 nicklas 466       
3715 11 Sep 07 nicklas 467         <figure id="data_api.figures.authentication">
3715 11 Sep 07 nicklas 468           <title>User authentication and access control</title>
3715 11 Sep 07 nicklas 469           <screenshot>
3715 11 Sep 07 nicklas 470             <mediaobject>
3715 11 Sep 07 nicklas 471               <imageobject>
3715 11 Sep 07 nicklas 472                 <imagedata 
3943 09 Nov 07 nicklas 473                   align="center"
3943 09 Nov 07 nicklas 474                   scalefit="1" width="100%"
3715 11 Sep 07 nicklas 475                   fileref="figures/uml/datalayer.authentication.png" format="PNG" />
3715 11 Sep 07 nicklas 476               </imageobject>
3715 11 Sep 07 nicklas 477             </mediaobject>
3715 11 Sep 07 nicklas 478           </screenshot>
3715 11 Sep 07 nicklas 479         </figure>
3715 11 Sep 07 nicklas 480       
3715 11 Sep 07 nicklas 481       <sect3 id="data_api.authentication.users">
3715 11 Sep 07 nicklas 482         <title>Users and passwords</title>      
3715 11 Sep 07 nicklas 483       
3715 11 Sep 07 nicklas 484         <para>
3947 12 Nov 07 nicklas 485           The <classname docapi="net.sf.basedb.core.data">UserData</classname> class holds information about users. 
3715 11 Sep 07 nicklas 486           We keep the passwords in a separate table and use proxies to avoid loading 
3715 11 Sep 07 nicklas 487           password data each time a user is loaded to minimize security risks. It is
3947 12 Nov 07 nicklas 488           only if the password needs to be changed that the <classname docapi="net.sf.basedb.core.data">PasswordData</classname>
3715 11 Sep 07 nicklas 489           object is loaded. The one-to-one mapping between user and password is controlled 
3715 11 Sep 07 nicklas 490           by the password class, but a cascade attribute on the user class makes sure 
3715 11 Sep 07 nicklas 491           that the password is deleted when a user is deleted.
3715 11 Sep 07 nicklas 492         </para>
3715 11 Sep 07 nicklas 493       </sect3>
3715 11 Sep 07 nicklas 494
3715 11 Sep 07 nicklas 495       <sect3 id="data_api.authentication.groups">
5368 22 Jun 10 nicklas 496         <title>Groups, roles, projects and permission template</title>      
3715 11 Sep 07 nicklas 497       
3715 11 Sep 07 nicklas 498         <para>
5780 04 Oct 11 nicklas 499           The <classname docapi="net.sf.basedb.core.data">GroupData</classname>, 
5780 04 Oct 11 nicklas 500           <classname docapi="net.sf.basedb.core.data">RoleData</classname> and 
5780 04 Oct 11 nicklas 501           <classname docapi="net.sf.basedb.core.data">ProjectData</classname> classes holds 
5780 04 Oct 11 nicklas 502           information about groups, roles 
3715 11 Sep 07 nicklas 503           and projects respectively. A user may be a member of any number of groups,
5780 04 Oct 11 nicklas 504           roles and/or projects. New users are automatically added as members of all 
5780 04 Oct 11 nicklas 505           groups and roles that has the <varname>default</varname> property set.
5780 04 Oct 11 nicklas 506         </para>
5780 04 Oct 11 nicklas 507           
5780 04 Oct 11 nicklas 508         <para>
5780 04 Oct 11 nicklas 509           The membership in a project comes with an attached
3715 11 Sep 07 nicklas 510           permission values. This is the highest permission the user has in the
3715 11 Sep 07 nicklas 511           project. No matter what permission an item has been shared with the
3715 11 Sep 07 nicklas 512           user will not get higher permission. Groups may be members of other groups and 
5368 22 Jun 10 nicklas 513           also in projects. A <classname docapi="net.sf.basedb.core.data">PermissionTemplateData</classname>
5368 22 Jun 10 nicklas 514           is just a holder for permissions that users can use when sharing items. The
5368 22 Jun 10 nicklas 515           template is never part of the actual permission control mechanism.
3715 11 Sep 07 nicklas 516         </para>
3715 11 Sep 07 nicklas 517         
4689 08 Dec 08 nicklas 518         <para>
4689 08 Dec 08 nicklas 519           Group membership is always accounted for, but the core only allows
4689 08 Dec 08 nicklas 520           one project at a time to be use, this is the <emphasis>active project</emphasis>.
4689 08 Dec 08 nicklas 521           When a project is active new items that are created are automatically
5368 22 Jun 10 nicklas 522           shared according to the settings for the project. There are two cases.
5368 22 Jun 10 nicklas 523           If the project has a permission template, the new item is given the same 
5368 22 Jun 10 nicklas 524           permissions as the template has. If the project doesn't have a permission
5368 22 Jun 10 nicklas 525           template, the new item is shared to the active project with the permission
5368 22 Jun 10 nicklas 526           given by the <varname>autoPermission</varname> property. Note that in the
5368 22 Jun 10 nicklas 527           first case the new item may or may not be shared to the active project
5368 22 Jun 10 nicklas 528           depending on if the template is shared to the project or not.
4689 08 Dec 08 nicklas 529         </para>
5368 22 Jun 10 nicklas 530         
5368 22 Jun 10 nicklas 531         <para>
5368 22 Jun 10 nicklas 532           Note that the permission template is only used (by the core) when creating 
5368 22 Jun 10 nicklas 533           new items. The permissions held by the template are copied and when the new item
5368 22 Jun 10 nicklas 534           has been saved to the database there is no longer any reference back to
5368 22 Jun 10 nicklas 535           the template that was used to create it. This means that changes to the
5368 22 Jun 10 nicklas 536           template does not affect already existing items and that the template
5368 22 Jun 10 nicklas 537           can be deleted without problems.
5368 22 Jun 10 nicklas 538         </para>
3715 11 Sep 07 nicklas 539       </sect3>
3715 11 Sep 07 nicklas 540       
3715 11 Sep 07 nicklas 541       <sect3 id="data_api.authentication.keys">
3715 11 Sep 07 nicklas 542         <title>Keys</title>      
3715 11 Sep 07 nicklas 543       
3715 11 Sep 07 nicklas 544         <para>
3947 12 Nov 07 nicklas 545           The <classname docapi="net.sf.basedb.core.data">KeyData</classname> class and it's subclasses 
3947 12 Nov 07 nicklas 546           <classname docapi="net.sf.basedb.core.data">ItemKeyData</classname>, <classname docapi="net.sf.basedb.core.data">ProjectKeyData</classname> and 
3947 12 Nov 07 nicklas 547           <classname docapi="net.sf.basedb.core.data">RoleKeyData</classname>, are used to store information about access 
3715 11 Sep 07 nicklas 548           permissions to items. To get permission to manipulate an item a user must have 
3715 11 Sep 07 nicklas 549           access to a key giving that permission. There are three types of keys:
3715 11 Sep 07 nicklas 550         </para>
3715 11 Sep 07 nicklas 551         
3715 11 Sep 07 nicklas 552         <variablelist>
3715 11 Sep 07 nicklas 553         <varlistentry>
3947 12 Nov 07 nicklas 554           <term><classname docapi="net.sf.basedb.core.data">ItemKey</classname></term>
3715 11 Sep 07 nicklas 555           <listitem>
3715 11 Sep 07 nicklas 556             <para>
3715 11 Sep 07 nicklas 557             Is used to give a user or group access to a specific item. The item 
3947 12 Nov 07 nicklas 558             must be a <interfacename docapi="net.sf.basedb.core.data">ShareableData</interfacename> item.
4689 08 Dec 08 nicklas 559             The permissions are usually set by the owner of the item. Once created an 
3715 11 Sep 07 nicklas 560             item key cannot be changed. This allows the core to reuse a key if the 
3715 11 Sep 07 nicklas 561             permissions match exactly, ie. for a given set of users/groups/permissions 
3715 11 Sep 07 nicklas 562             there can be only one item key object.
3715 11 Sep 07 nicklas 563             </para>
3715 11 Sep 07 nicklas 564           </listitem>
3715 11 Sep 07 nicklas 565         </varlistentry>
3715 11 Sep 07 nicklas 566
3715 11 Sep 07 nicklas 567         <varlistentry>
3947 12 Nov 07 nicklas 568           <term><classname docapi="net.sf.basedb.core.data">ProjectKey</classname></term>
3715 11 Sep 07 nicklas 569           <listitem>
3715 11 Sep 07 nicklas 570             <para>
3715 11 Sep 07 nicklas 571             Is used to give members of a project access to a specific item. The item 
3947 12 Nov 07 nicklas 572             must be a <interfacename docapi="net.sf.basedb.core.data">ShareableData</interfacename> item. Once created a 
3715 11 Sep 07 nicklas 573             project key cannot be changed. This allows the core to reuse a key if the 
3715 11 Sep 07 nicklas 574             permissions match exactly, ie. for a given set of projects/permissions 
3715 11 Sep 07 nicklas 575             there can be only one project key object.
3715 11 Sep 07 nicklas 576             </para>
3715 11 Sep 07 nicklas 577           </listitem>
3715 11 Sep 07 nicklas 578         </varlistentry>
3715 11 Sep 07 nicklas 579
3715 11 Sep 07 nicklas 580         <varlistentry>
3947 12 Nov 07 nicklas 581           <term><classname docapi="net.sf.basedb.core.data">RoleKey</classname></term>
3715 11 Sep 07 nicklas 582           <listitem>
3715 11 Sep 07 nicklas 583             <para>
3715 11 Sep 07 nicklas 584             Is used to give a user access to all items of a specific type, ie. 
3715 11 Sep 07 nicklas 585             <constant>READ</constant> all <constant>SAMPLES</constant>. The installation 
3715 11 Sep 07 nicklas 586             will make sure that there already exists a role key for each type of item, and 
3715 11 Sep 07 nicklas 587             it is not possible to add new or delete existing keys. Unlike the other two types 
3715 11 Sep 07 nicklas 588             this key can be modified.
3715 11 Sep 07 nicklas 589             </para>
3715 11 Sep 07 nicklas 590             
3715 11 Sep 07 nicklas 591             <para>
3715 11 Sep 07 nicklas 592             A role key is also used to assign permissions to plug-ins. If a plug-in has 
3715 11 Sep 07 nicklas 593             been specified to use permissions the default is to deny everything. 
3715 11 Sep 07 nicklas 594             The mapping to the role key is used to grant permissions to the plugin. 
3715 11 Sep 07 nicklas 595             The <varname>granted</varname> value gives the plugin access to all items 
3715 11 Sep 07 nicklas 596             of the related item type regardless of if the user that is running the plug-in has the 
3715 11 Sep 07 nicklas 597             permission or not. The <varname>denied</varname> values denies access to all 
3715 11 Sep 07 nicklas 598             items of the related item type even if the logged in user has the permission. 
3715 11 Sep 07 nicklas 599             Permissions that are not granted nor denied are checked against the 
3715 11 Sep 07 nicklas 600             logged in users regular permissions. Permissions to items that are 
3715 11 Sep 07 nicklas 601             not linked are always denied.
3715 11 Sep 07 nicklas 602             </para>
3715 11 Sep 07 nicklas 603           </listitem>
3715 11 Sep 07 nicklas 604         </varlistentry>
3715 11 Sep 07 nicklas 605         </variablelist>
3715 11 Sep 07 nicklas 606         
3715 11 Sep 07 nicklas 607       </sect3>
3715 11 Sep 07 nicklas 608
3715 11 Sep 07 nicklas 609       <sect3 id="data_api.authentication.permissions">
3715 11 Sep 07 nicklas 610         <title>Permissions</title>
3715 11 Sep 07 nicklas 611         
3715 11 Sep 07 nicklas 612         <para>
3715 11 Sep 07 nicklas 613           The <varname>permission</varname> property appearing in many classes is an 
3715 11 Sep 07 nicklas 614           integer values describing the permission:
3715 11 Sep 07 nicklas 615         </para>
3715 11 Sep 07 nicklas 616         
3715 11 Sep 07 nicklas 617         <informaltable>
3715 11 Sep 07 nicklas 618         <tgroup cols="2">
3715 11 Sep 07 nicklas 619           <colspec colname="value" />
3715 11 Sep 07 nicklas 620           <colspec colname="permission" />
3715 11 Sep 07 nicklas 621           <thead>
3715 11 Sep 07 nicklas 622             <row>
3715 11 Sep 07 nicklas 623               <entry>Value</entry>
3715 11 Sep 07 nicklas 624               <entry>Permission</entry>
3715 11 Sep 07 nicklas 625             </row>
3715 11 Sep 07 nicklas 626           </thead>
3715 11 Sep 07 nicklas 627           <tbody>
3715 11 Sep 07 nicklas 628             <row>
3715 11 Sep 07 nicklas 629               <entry>1</entry>
3715 11 Sep 07 nicklas 630               <entry>Read</entry>
3715 11 Sep 07 nicklas 631             </row>
3715 11 Sep 07 nicklas 632             <row>
3715 11 Sep 07 nicklas 633               <entry>3</entry>
3715 11 Sep 07 nicklas 634               <entry>Use</entry>
3715 11 Sep 07 nicklas 635             </row>
3715 11 Sep 07 nicklas 636             <row>
3715 11 Sep 07 nicklas 637               <entry>7</entry>
3715 11 Sep 07 nicklas 638               <entry>Restricted write</entry>
3715 11 Sep 07 nicklas 639             </row>
3715 11 Sep 07 nicklas 640             <row>
3715 11 Sep 07 nicklas 641               <entry>15</entry>
3715 11 Sep 07 nicklas 642               <entry>Write</entry>
3715 11 Sep 07 nicklas 643             </row>
3715 11 Sep 07 nicklas 644             <row>
3715 11 Sep 07 nicklas 645               <entry>31</entry>
3715 11 Sep 07 nicklas 646               <entry>Delete</entry>
3715 11 Sep 07 nicklas 647             </row>
3715 11 Sep 07 nicklas 648             <row>
3715 11 Sep 07 nicklas 649               <entry>47 (=32+15)</entry>
3715 11 Sep 07 nicklas 650               <entry>Set owner</entry>
3715 11 Sep 07 nicklas 651             </row>
3715 11 Sep 07 nicklas 652             <row>
3715 11 Sep 07 nicklas 653               <entry>79 (=64+15)</entry>
3715 11 Sep 07 nicklas 654               <entry>Set permissions</entry>
3715 11 Sep 07 nicklas 655             </row>
3715 11 Sep 07 nicklas 656             <row>
3715 11 Sep 07 nicklas 657               <entry>128</entry>
3715 11 Sep 07 nicklas 658               <entry>Create</entry>
3715 11 Sep 07 nicklas 659             </row>
3715 11 Sep 07 nicklas 660             <row>
3715 11 Sep 07 nicklas 661               <entry>256</entry>
3715 11 Sep 07 nicklas 662               <entry>Denied</entry>
3715 11 Sep 07 nicklas 663             </row>
3715 11 Sep 07 nicklas 664           </tbody>
3715 11 Sep 07 nicklas 665         </tgroup>
3715 11 Sep 07 nicklas 666         </informaltable>
3715 11 Sep 07 nicklas 667         
3715 11 Sep 07 nicklas 668         <para>
3715 11 Sep 07 nicklas 669           The values are constructed so that 
3715 11 Sep 07 nicklas 670           <constant>READ</constant> -&gt;
3715 11 Sep 07 nicklas 671           <constant>USE</constant> -&gt;
3715 11 Sep 07 nicklas 672           <constant>RESTRICTED_WRITE</constant> -&gt;
3715 11 Sep 07 nicklas 673           <constant>WRITE</constant> -&gt;
3715 11 Sep 07 nicklas 674           <constant>DELETE</constant>
3715 11 Sep 07 nicklas 675           are chained in the sense that a higher permission always implies the lower permissions 
3715 11 Sep 07 nicklas 676           also. The <constant>SET_OWNER</constant> and <constant>SET_PERMISSION</constant>
3715 11 Sep 07 nicklas 677           both implies <constant>WRITE</constant> permission. The <constant>DENIED</constant>
3715 11 Sep 07 nicklas 678           permission is only valid for role keys, and if specified it overrides all 
3715 11 Sep 07 nicklas 679           other permissions.                
3715 11 Sep 07 nicklas 680         </para>
3715 11 Sep 07 nicklas 681         
3715 11 Sep 07 nicklas 682         <para>
3715 11 Sep 07 nicklas 683           When combining permission for a single item the permission codes for the different 
3715 11 Sep 07 nicklas 684           paths are OR-ed together. For example a user has a role key with <constant>READ</constant>
3715 11 Sep 07 nicklas 685           permission for <constant>SAMPLES</constant>, but also an item key with <constant>USE</constant>
3715 11 Sep 07 nicklas 686           permission for a specific sample. Of course, the resulting permission for that
3715 11 Sep 07 nicklas 687           sample is <constant>USE</constant>. For other samples the resulting permission is
3715 11 Sep 07 nicklas 688           <constant>READ</constant>.
3715 11 Sep 07 nicklas 689         </para>
3715 11 Sep 07 nicklas 690         
3715 11 Sep 07 nicklas 691         <para>
3715 11 Sep 07 nicklas 692           If the user is also a member of a project which has <constant>WRITE</constant>
3715 11 Sep 07 nicklas 693           permission for the same sample, the user will have <constant>WRITE</constant>
3715 11 Sep 07 nicklas 694           permission when working with that project.
3715 11 Sep 07 nicklas 695         </para>
3715 11 Sep 07 nicklas 696         
3715 11 Sep 07 nicklas 697         <para>
3715 11 Sep 07 nicklas 698           The <constant>RESTRICTED_WRITE</constant> permission is in most cases the same 
3715 11 Sep 07 nicklas 699           as the <constant>WRITE</constant> permission. So far the <constant>RESTRICTED_WRITE</constant>
3947 12 Nov 07 nicklas 700           permission is only given to users to their own <classname docapi="net.sf.basedb.core.data">UserData</classname>
3715 11 Sep 07 nicklas 701           object so they can change their address and other contact information, 
3715 11 Sep 07 nicklas 702           but not quota, expiration date and other administrative information.
3715 11 Sep 07 nicklas 703         </para>
3757 20 Sep 07 nicklas 704
3715 11 Sep 07 nicklas 705       </sect3>
3715 11 Sep 07 nicklas 706     </sect2>
3715 11 Sep 07 nicklas 707
3715 11 Sep 07 nicklas 708     <sect2 id="data_api.reporters">
3715 11 Sep 07 nicklas 709       <title>Reporters</title>
3891 30 Oct 07 nicklas 710       <para>
5780 04 Oct 11 nicklas 711          This section gives an overview of reporters in BASE.
3891 30 Oct 07 nicklas 712       </para>
3891 30 Oct 07 nicklas 713       
3891 30 Oct 07 nicklas 714         <figure id="data_api.figures.reporters">
3891 30 Oct 07 nicklas 715           <title>Reporters</title>
3891 30 Oct 07 nicklas 716           <screenshot>
3891 30 Oct 07 nicklas 717             <mediaobject>
3891 30 Oct 07 nicklas 718               <imageobject>
3891 30 Oct 07 nicklas 719                 <imagedata 
3943 09 Nov 07 nicklas 720                   align="center"
3891 30 Oct 07 nicklas 721                   fileref="figures/uml/datalayer.reporters.png" format="PNG" />
3891 30 Oct 07 nicklas 722               </imageobject>
3891 30 Oct 07 nicklas 723             </mediaobject>
3891 30 Oct 07 nicklas 724           </screenshot>
3891 30 Oct 07 nicklas 725         </figure>
3891 30 Oct 07 nicklas 726       
3891 30 Oct 07 nicklas 727       <sect3 id="data_api.reporters.description">
3891 30 Oct 07 nicklas 728         <title>Reporters</title>
3891 30 Oct 07 nicklas 729         <para>
3947 12 Nov 07 nicklas 730           The <classname docapi="net.sf.basedb.core.data">ReporterData</classname> class holds information about reporters.
3891 30 Oct 07 nicklas 731           The <property>externalId</property> is a required property that must be unique
3891 30 Oct 07 nicklas 732           among all reporters. The external ID is the value BASE uses to match 
3891 30 Oct 07 nicklas 733           reporters when importing data from files.
3891 30 Oct 07 nicklas 734         </para>
3891 30 Oct 07 nicklas 735         
3891 30 Oct 07 nicklas 736         <para>
3891 30 Oct 07 nicklas 737           The <classname>ReporterData</classname> is an <emphasis>extendable</emphasis>
3891 30 Oct 07 nicklas 738           class, which means that the server administrator can define additional
3891 30 Oct 07 nicklas 739           columns (=annotations) in the reporters table. These are accessed with
3891 30 Oct 07 nicklas 740           the <methodname>ReporterData.getExtended()</methodname> and
3891 30 Oct 07 nicklas 741           <methodname>ReporterData.setExtended()</methodname> methods.
3891 30 Oct 07 nicklas 742           See <xref linkend="appendix.extendedproperties" /> for more information about 
3891 30 Oct 07 nicklas 743           this.
3891 30 Oct 07 nicklas 744         </para>
3891 30 Oct 07 nicklas 745         
3891 30 Oct 07 nicklas 746         <para>
3891 30 Oct 07 nicklas 747           The <classname>ReporterData</classname> is also a <emphasis>batchable</emphasis>
3891 30 Oct 07 nicklas 748           class which means that there is no corresponding class in the core
3891 30 Oct 07 nicklas 749           layer. Client applications and plug-ins should work directly with 
3891 30 Oct 07 nicklas 750           the <classname>ReporterData</classname> class. To help manage the reporters
3947 12 Nov 07 nicklas 751           there is the <classname docapi="net.sf.basedb.core">Reporter</classname> and <classname docapi="net.sf.basedb.core">ReporterBatcher</classname>
3891 30 Oct 07 nicklas 752           classes. The main reason for this
3891 30 Oct 07 nicklas 753           is to increase the performance and lower the memory usage by bypassing
3891 30 Oct 07 nicklas 754           internal caching in the core and Hibernate. Performance is also
3891 30 Oct 07 nicklas 755           increased by the batchers which uses more efficient SQL against the
3891 30 Oct 07 nicklas 756           database than Hibernate.
3891 30 Oct 07 nicklas 757         </para>
3891 30 Oct 07 nicklas 758         
3891 30 Oct 07 nicklas 759         <para>
4093 18 Jan 08 enell 760           The
4093 18 Jan 08 enell 761           <property>lastUpdate</property>
4093 18 Jan 08 enell 762           property holds the data and time the reporter information was last updated. The
4093 18 Jan 08 enell 763           value is managed automatically by the
4093 18 Jan 08 enell 764           <classname>ReporterBatcher</classname>
4093 18 Jan 08 enell 765           class. That goes for
4093 18 Jan 08 enell 766           <property>lastSource</property>
4093 18 Jan 08 enell 767           property too, which holds information about where the last update comes from. By
4093 18 Jan 08 enell 768           default this is set to the name of the logged in user, but it can be changed by
4093 18 Jan 08 enell 769           calling
4093 18 Jan 08 enell 770           <methodname>ReporterBatcher.setUpdateSource(String source)</methodname>
4093 18 Jan 08 enell 771           before the batcher commits the updates to the database. The source-string 
4093 18 Jan 08 enell 772           should have the format:  <synopsis>[ITEM_TYPE]:[ITEM_NAME]</synopsis> where,in 
4093 18 Jan 08 enell 773           the file-case, ITEM_TYPE is File and ITEM_NAME is the file's name.
3891 30 Oct 07 nicklas 774         </para>
3891 30 Oct 07 nicklas 775       </sect3>
3891 30 Oct 07 nicklas 776       
3891 30 Oct 07 nicklas 777       <sect3 id="data_api.reporters.lists">
3891 30 Oct 07 nicklas 778         <title>Reporter lists</title>
3891 30 Oct 07 nicklas 779         
3891 30 Oct 07 nicklas 780         <para>
3891 30 Oct 07 nicklas 781           Reporter lists can be used to group reporters that are somehow related
3891 30 Oct 07 nicklas 782           to each other. This could for example be a list of interesting reporters
3891 30 Oct 07 nicklas 783           found in the analysis of an experiment. Each reporter in the list may
3891 30 Oct 07 nicklas 784           optionally be assigned a score. The meaning of the score value is not
3891 30 Oct 07 nicklas 785           interpreted by BASE.
3891 30 Oct 07 nicklas 786         </para>
3891 30 Oct 07 nicklas 787         
3891 30 Oct 07 nicklas 788       </sect3>
3891 30 Oct 07 nicklas 789       
3891 30 Oct 07 nicklas 790       
3715 11 Sep 07 nicklas 791     </sect2>
3715 11 Sep 07 nicklas 792
3715 11 Sep 07 nicklas 793     <sect2 id="data_api.quota">
3715 11 Sep 07 nicklas 794       <title>Quota and disk usage</title>
3891 30 Oct 07 nicklas 795       <para>
3891 30 Oct 07 nicklas 796          This section gives an overview of quota system in BASE
3891 30 Oct 07 nicklas 797          and how the disk usage is kept track of.
3891 30 Oct 07 nicklas 798       </para>
3891 30 Oct 07 nicklas 799       
3891 30 Oct 07 nicklas 800         <figure id="data_api.figures.quota">
3891 30 Oct 07 nicklas 801           <title>Quota and disk usage</title>
3891 30 Oct 07 nicklas 802           <screenshot>
3891 30 Oct 07 nicklas 803             <mediaobject>
3891 30 Oct 07 nicklas 804               <imageobject>
3891 30 Oct 07 nicklas 805                 <imagedata 
3943 09 Nov 07 nicklas 806                   align="center"
3891 30 Oct 07 nicklas 807                   fileref="figures/uml/datalayer.quota.png" format="PNG" />
3891 30 Oct 07 nicklas 808               </imageobject>
3891 30 Oct 07 nicklas 809             </mediaobject>
3891 30 Oct 07 nicklas 810           </screenshot>
3891 30 Oct 07 nicklas 811         </figure>
3891 30 Oct 07 nicklas 812       
3891 30 Oct 07 nicklas 813       <sect3 id="data_api.quota.description">
3891 30 Oct 07 nicklas 814         <title>Quota</title>
3891 30 Oct 07 nicklas 815         
3891 30 Oct 07 nicklas 816         <para>
3947 12 Nov 07 nicklas 817           The <classname docapi="net.sf.basedb.core.data">QuotaData</classname> holds information about a 
3891 30 Oct 07 nicklas 818           single quota registration. The same quota may be used by many different users
3891 30 Oct 07 nicklas 819           and groups. This object encapsulates allowed
3891 30 Oct 07 nicklas 820           quota values for different types of quota types and locations. 
3891 30 Oct 07 nicklas 821           BASE defines several quota types (file, raw data and experiment),
7598 22 Feb 19 nicklas 822           and locations (primary, external and offline).
3891 30 Oct 07 nicklas 823         </para>
3891 30 Oct 07 nicklas 824         
3891 30 Oct 07 nicklas 825         <para>
6468 10 Jun 14 nicklas 826           The <property>quotaValues</property> property is a set containing 
6468 10 Jun 14 nicklas 827           <classname docapi="net.sf.basedb.core.data">QuotaIndex</classname> which hold the 
6468 10 Jun 14 nicklas 828           maximum byte values for a specified quota type and location. The set must contain at 
6468 10 Jun 14 nicklas 829           least one entry for the total quota at the primary location.
3891 30 Oct 07 nicklas 830         </para>
3891 30 Oct 07 nicklas 831         
3891 30 Oct 07 nicklas 832       </sect3>
3891 30 Oct 07 nicklas 833       
3891 30 Oct 07 nicklas 834       <sect3 id="data_api.quota.diskusage">
3891 30 Oct 07 nicklas 835         <title>Disk usage</title>
3891 30 Oct 07 nicklas 836         
3891 30 Oct 07 nicklas 837         <para>
3947 12 Nov 07 nicklas 838           A <interfacename docapi="net.sf.basedb.core.data">DiskConsumableData</interfacename> (for example a file)
3947 12 Nov 07 nicklas 839           item is automatically linked to a <classname docapi="net.sf.basedb.core.data">DiskUsageData</classname>
3891 30 Oct 07 nicklas 840           item. This holds information about the number of bytes,
3891 30 Oct 07 nicklas 841           the location and quota type the item uses. It also holds information
3891 30 Oct 07 nicklas 842           about which user and group (optional) that should be charged for the disk usage.
3891 30 Oct 07 nicklas 843           The user is always the owner of the item.
3891 30 Oct 07 nicklas 844         </para>
3891 30 Oct 07 nicklas 845
3891 30 Oct 07 nicklas 846       </sect3>
3891 30 Oct 07 nicklas 847       
3715 11 Sep 07 nicklas 848     </sect2>
3715 11 Sep 07 nicklas 849
3896 31 Oct 07 nicklas 850     <sect2 id="data_api.clients">
3715 11 Sep 07 nicklas 851       <title>Client, session and settings</title>
3896 31 Oct 07 nicklas 852       <para>
5818 21 Oct 11 nicklas 853          This section gives an overview of client applications, sessions and settings.
3896 31 Oct 07 nicklas 854       </para>
3896 31 Oct 07 nicklas 855       
3896 31 Oct 07 nicklas 856         <figure id="data_api.figures.clients">
3896 31 Oct 07 nicklas 857           <title>Client, sessions and settings</title>
3896 31 Oct 07 nicklas 858           <screenshot>
3896 31 Oct 07 nicklas 859             <mediaobject>
3896 31 Oct 07 nicklas 860               <imageobject>
3896 31 Oct 07 nicklas 861                 <imagedata 
3943 09 Nov 07 nicklas 862                   align="center"
3943 09 Nov 07 nicklas 863                   scalefit="1" width="100%"
3896 31 Oct 07 nicklas 864                   fileref="figures/uml/datalayer.clients.png" format="PNG" />
3896 31 Oct 07 nicklas 865               </imageobject>
3896 31 Oct 07 nicklas 866             </mediaobject>
3896 31 Oct 07 nicklas 867           </screenshot>
3896 31 Oct 07 nicklas 868         </figure>
5780 04 Oct 11 nicklas 869
3896 31 Oct 07 nicklas 870       <sect3 id="data_api.clients.description">
3896 31 Oct 07 nicklas 871         <title>Clients</title>
3896 31 Oct 07 nicklas 872         <para>
3947 12 Nov 07 nicklas 873           The <classname docapi="net.sf.basedb.core.data">ClientData</classname> class holds information
3896 31 Oct 07 nicklas 874           about a client application. The <property>externalId</property>
3896 31 Oct 07 nicklas 875           property is a unique identifier for the application. To avoid ID clashes the ID
3896 31 Oct 07 nicklas 876           should be constructed in the same way as Java packages, for example 
3896 31 Oct 07 nicklas 877           <constant>net.sf.basedb.clients.web</constant> is the ID for the
3896 31 Oct 07 nicklas 878           web client application. 
3896 31 Oct 07 nicklas 879         </para>
3896 31 Oct 07 nicklas 880         
3896 31 Oct 07 nicklas 881         <para>
3896 31 Oct 07 nicklas 882           A client application doesn't have to be registered with BASE
3896 31 Oct 07 nicklas 883           to be able to use it. But we recommend it since:
3896 31 Oct 07 nicklas 884         </para>
3896 31 Oct 07 nicklas 885         
3896 31 Oct 07 nicklas 886         <itemizedlist>
3896 31 Oct 07 nicklas 887         <listitem>
3896 31 Oct 07 nicklas 888           <para>
3896 31 Oct 07 nicklas 889             The permission system allows an admin to specify exactly
3896 31 Oct 07 nicklas 890             which users that may use a specific application.
3896 31 Oct 07 nicklas 891           </para>
3896 31 Oct 07 nicklas 892         </listitem>
3896 31 Oct 07 nicklas 893         
3896 31 Oct 07 nicklas 894         <listitem>
3896 31 Oct 07 nicklas 895           <para>
3896 31 Oct 07 nicklas 896           The application can't store any context-sensitive or application-specific
3896 31 Oct 07 nicklas 897           settings unless it is registered.
3896 31 Oct 07 nicklas 898           </para>
3896 31 Oct 07 nicklas 899         </listitem>
3896 31 Oct 07 nicklas 900         
3896 31 Oct 07 nicklas 901         <listitem>
3896 31 Oct 07 nicklas 902           <para>
3896 31 Oct 07 nicklas 903           The application can store context-sensitive help in the BASE
3896 31 Oct 07 nicklas 904           database.
3896 31 Oct 07 nicklas 905           </para>
3896 31 Oct 07 nicklas 906         </listitem>
3896 31 Oct 07 nicklas 907         </itemizedlist>
3896 31 Oct 07 nicklas 908       </sect3>
3896 31 Oct 07 nicklas 909       
3896 31 Oct 07 nicklas 910       <sect3 id="data_api.clients.sessions">
3896 31 Oct 07 nicklas 911         <title>Sessions</title>
3896 31 Oct 07 nicklas 912         
3896 31 Oct 07 nicklas 913         <para>
3896 31 Oct 07 nicklas 914           A session represents the time between login and logout for a single
3947 12 Nov 07 nicklas 915           user. The <classname docapi="net.sf.basedb.core.data">SessionData</classname> object is entirely
3896 31 Oct 07 nicklas 916           managed by the BASE core, and should be considered read-only
3896 31 Oct 07 nicklas 917           for client applications.
3896 31 Oct 07 nicklas 918         </para>
3896 31 Oct 07 nicklas 919             
3896 31 Oct 07 nicklas 920       </sect3>
3896 31 Oct 07 nicklas 921       
3896 31 Oct 07 nicklas 922       <sect3 id="data_api.clients.settings">
3896 31 Oct 07 nicklas 923         <title>Settings</title>
3896 31 Oct 07 nicklas 924         
3896 31 Oct 07 nicklas 925         <para>
3896 31 Oct 07 nicklas 926           There are two types of settings: context-sensitive settings and regular 
3896 31 Oct 07 nicklas 927           settings. The regular settings are simple key-value pairs of strings
3896 31 Oct 07 nicklas 928           and can be used for almost anything. There are four subtypes:
3896 31 Oct 07 nicklas 929         </para>
3896 31 Oct 07 nicklas 930         
3896 31 Oct 07 nicklas 931         <itemizedlist>
3896 31 Oct 07 nicklas 932         <listitem>
3896 31 Oct 07 nicklas 933           <para>
3896 31 Oct 07 nicklas 934           Global default settings: Settings that are used by all users
3896 31 Oct 07 nicklas 935           and client applications on the BASE server. These settings
3896 31 Oct 07 nicklas 936           are read-only except for administrators. BASE has not yet defined
3896 31 Oct 07 nicklas 937           any settings of this type.
3896 31 Oct 07 nicklas 938           </para>
3896 31 Oct 07 nicklas 939         </listitem>
3896 31 Oct 07 nicklas 940         
3896 31 Oct 07 nicklas 941         <listitem>
3896 31 Oct 07 nicklas 942           <para>
3896 31 Oct 07 nicklas 943           User default settings: Settings that are valid for a single user
3896 31 Oct 07 nicklas 944           for any client application. BASE has not yet defined
3896 31 Oct 07 nicklas 945           any settings of this type.
3896 31 Oct 07 nicklas 946           </para>
3896 31 Oct 07 nicklas 947         </listitem>
3896 31 Oct 07 nicklas 948         
3896 31 Oct 07 nicklas 949         <listitem>
3896 31 Oct 07 nicklas 950           <para>
3896 31 Oct 07 nicklas 951           Client default settings: Settings that are valid for all users using
3896 31 Oct 07 nicklas 952           a specific client application. Each client application is responsible
3896 31 Oct 07 nicklas 953           for defining it's own settings. Settings are read-only except
3896 31 Oct 07 nicklas 954           for administrators.
3896 31 Oct 07 nicklas 955           </para>
3896 31 Oct 07 nicklas 956         </listitem>
3896 31 Oct 07 nicklas 957         
3896 31 Oct 07 nicklas 958         <listitem>
3896 31 Oct 07 nicklas 959           <para>
3896 31 Oct 07 nicklas 960           User client settings: Settings that are valid for a single user using
3896 31 Oct 07 nicklas 961           a specific client application. Each client application is responsible
3896 31 Oct 07 nicklas 962           for defining it's own settings.
3896 31 Oct 07 nicklas 963           </para>
3896 31 Oct 07 nicklas 964         </listitem>
3896 31 Oct 07 nicklas 965         
3896 31 Oct 07 nicklas 966         </itemizedlist>
3896 31 Oct 07 nicklas 967         
3896 31 Oct 07 nicklas 968         <para>
3896 31 Oct 07 nicklas 969           The context-sensitive settings are designed to hold information 
3896 31 Oct 07 nicklas 970           about the current status of options related to the listing of items
3896 31 Oct 07 nicklas 971           of a specific type. This includes:
3896 31 Oct 07 nicklas 972         </para>
3896 31 Oct 07 nicklas 973         
3896 31 Oct 07 nicklas 974         <itemizedlist>
3896 31 Oct 07 nicklas 975         <listitem>
3896 31 Oct 07 nicklas 976           <para>
3947 12 Nov 07 nicklas 977           Current filtering options (as 1 or more <classname docapi="net.sf.basedb.core.data">PropertyFilterData</classname>
3896 31 Oct 07 nicklas 978           objects).
3896 31 Oct 07 nicklas 979           </para>
3896 31 Oct 07 nicklas 980         </listitem>
3896 31 Oct 07 nicklas 981         
3896 31 Oct 07 nicklas 982         <listitem>
3896 31 Oct 07 nicklas 983           <para>
3896 31 Oct 07 nicklas 984           Which columns and direction to use for sorting. 
3896 31 Oct 07 nicklas 985           </para>
3896 31 Oct 07 nicklas 986         </listitem>
3896 31 Oct 07 nicklas 987         
3896 31 Oct 07 nicklas 988         <listitem>
3896 31 Oct 07 nicklas 989           <para>
3896 31 Oct 07 nicklas 990           The number of items to display on each page, and which page that
3896 31 Oct 07 nicklas 991           is the current page.
3896 31 Oct 07 nicklas 992           </para>
3896 31 Oct 07 nicklas 993         </listitem>
3896 31 Oct 07 nicklas 994         
3896 31 Oct 07 nicklas 995         <listitem>
3896 31 Oct 07 nicklas 996           <para>
3896 31 Oct 07 nicklas 997           Simple key-value settings related to a given context.
3896 31 Oct 07 nicklas 998           </para>
3896 31 Oct 07 nicklas 999         </listitem>
3896 31 Oct 07 nicklas 1000         </itemizedlist>
3896 31 Oct 07 nicklas 1001         
3896 31 Oct 07 nicklas 1002         <para>
3896 31 Oct 07 nicklas 1003           Context-sensitive settings are only accessible if a client
3896 31 Oct 07 nicklas 1004           application has been registered. The settings may be
3896 31 Oct 07 nicklas 1005           named to make it possible to store several presets and to
3896 31 Oct 07 nicklas 1006           quickly switch between them. In any case, BASE maintains a
3896 31 Oct 07 nicklas 1007           current default setting with an empty name. An administrator
3896 31 Oct 07 nicklas 1008           may mark a named setting as public to allow other users to 
3896 31 Oct 07 nicklas 1009           use it.
3896 31 Oct 07 nicklas 1010         </para>
3896 31 Oct 07 nicklas 1011         
3896 31 Oct 07 nicklas 1012       </sect3>
3896 31 Oct 07 nicklas 1013       
3896 31 Oct 07 nicklas 1014       
3715 11 Sep 07 nicklas 1015     </sect2>
3715 11 Sep 07 nicklas 1016
3715 11 Sep 07 nicklas 1017     <sect2 id="data_api.files">
3715 11 Sep 07 nicklas 1018       <title>Files and directories</title>
3762 21 Sep 07 nicklas 1019
3762 21 Sep 07 nicklas 1020       <para>
3762 21 Sep 07 nicklas 1021         This section covers the details of the BASE file
3762 21 Sep 07 nicklas 1022         system.
3762 21 Sep 07 nicklas 1023       </para>
3762 21 Sep 07 nicklas 1024
3762 21 Sep 07 nicklas 1025         <figure id="data_api.figures.files">
3762 21 Sep 07 nicklas 1026           <title>Files and directories</title>
3762 21 Sep 07 nicklas 1027           <screenshot>
3762 21 Sep 07 nicklas 1028             <mediaobject>
3762 21 Sep 07 nicklas 1029               <imageobject>
3762 21 Sep 07 nicklas 1030                 <imagedata 
3943 09 Nov 07 nicklas 1031                   align="center"
3762 21 Sep 07 nicklas 1032                   fileref="figures/uml/datalayer.files.png" format="PNG" />
3762 21 Sep 07 nicklas 1033               </imageobject>
3762 21 Sep 07 nicklas 1034             </mediaobject>
3762 21 Sep 07 nicklas 1035           </screenshot>
3762 21 Sep 07 nicklas 1036         </figure>
3762 21 Sep 07 nicklas 1037       
3762 21 Sep 07 nicklas 1038         <para>
3947 12 Nov 07 nicklas 1039           The <classname docapi="net.sf.basedb.core.data">DirectoryData</classname> class holds
3762 21 Sep 07 nicklas 1040           information about directories. Directories are organised in the
3762 21 Sep 07 nicklas 1041           ususal way as as tree structure. All directories must have
3762 21 Sep 07 nicklas 1042           a parent directory, except the system-defined root directory.
3762 21 Sep 07 nicklas 1043         </para>
3762 21 Sep 07 nicklas 1044         
3762 21 Sep 07 nicklas 1045         <para>
3947 12 Nov 07 nicklas 1046           The <classname docapi="net.sf.basedb.core.data">FileData</classname> class holds information about
3762 21 Sep 07 nicklas 1047           a file. The actual file contents is stored on disk in the directory
3762 21 Sep 07 nicklas 1048           specified by the <varname>userfiles</varname> setting in 
3762 21 Sep 07 nicklas 1049           <filename>base.config</filename>. The <varname>internalName</varname>
3762 21 Sep 07 nicklas 1050           property is the name of the file on disk, but this is never exposed to 
3762 21 Sep 07 nicklas 1051           client applications. The filenames and directories
3762 21 Sep 07 nicklas 1052           on the disk doesn't correspond to the the filenames and directories in 
3762 21 Sep 07 nicklas 1053           BASE.
3762 21 Sep 07 nicklas 1054         </para>
3762 21 Sep 07 nicklas 1055         
3762 21 Sep 07 nicklas 1056         <para>
5408 13 Sep 10 nicklas 1057           The <varname>url</varname> property is used for file items which are stored in
5408 13 Sep 10 nicklas 1058           an external location. In this case there is no local file data on the
5408 13 Sep 10 nicklas 1059           BASE server.
5408 13 Sep 10 nicklas 1060         </para>
5408 13 Sep 10 nicklas 1061         
5408 13 Sep 10 nicklas 1062         <para>
3762 21 Sep 07 nicklas 1063           The <varname>location</varname> property can take three values:
3762 21 Sep 07 nicklas 1064         </para>
3762 21 Sep 07 nicklas 1065         
3762 21 Sep 07 nicklas 1066         <itemizedlist>
3762 21 Sep 07 nicklas 1067         <listitem>
3762 21 Sep 07 nicklas 1068           <para>
3762 21 Sep 07 nicklas 1069           0 = The file is offline, ie. there is no file on the disk
3762 21 Sep 07 nicklas 1070           </para>
3762 21 Sep 07 nicklas 1071         </listitem>
3762 21 Sep 07 nicklas 1072         <listitem>
3762 21 Sep 07 nicklas 1073           <para>
3762 21 Sep 07 nicklas 1074           1 = The file is in primary storage, ie. it is located on the disk
3762 21 Sep 07 nicklas 1075           and can be used by BASE
3762 21 Sep 07 nicklas 1076           </para>
3762 21 Sep 07 nicklas 1077         </listitem>
3762 21 Sep 07 nicklas 1078         <listitem>
3762 21 Sep 07 nicklas 1079           <para>
5408 13 Sep 10 nicklas 1080           3 = The file is an external file whose location is referenced by the 
5408 13 Sep 10 nicklas 1081           <varname>url</varname> property. If the file is protected by passwords
5408 13 Sep 10 nicklas 1082           or certificates the file item may reference a 
5408 13 Sep 10 nicklas 1083           <classname docapi="net.sf.basedb.core.data">FileServerData</classname>
5408 13 Sep 10 nicklas 1084           object. Note that an external file in most cases can be used by client
5408 13 Sep 10 nicklas 1085           applications/plug-ins as if the file was stored locally on the BASE 
5408 13 Sep 10 nicklas 1086           server.
5408 13 Sep 10 nicklas 1087           </para>
5408 13 Sep 10 nicklas 1088         </listitem>
3762 21 Sep 07 nicklas 1089         </itemizedlist>
7598 22 Feb 19 nicklas 1090
3762 21 Sep 07 nicklas 1091         <para>
3762 21 Sep 07 nicklas 1092           The <varname>md5</varname> property can be used to check for file
7598 22 Feb 19 nicklas 1093           corruption when a user re-uploads a file that has been offline.
3762 21 Sep 07 nicklas 1094         </para>
3762 21 Sep 07 nicklas 1095         
3762 21 Sep 07 nicklas 1096         <para>
3762 21 Sep 07 nicklas 1097           BASE can store files in a compressed format. This is handled internally
3762 21 Sep 07 nicklas 1098           and is not visible to client applications. The <varname>compressed</varname>
5408 13 Sep 10 nicklas 1099           and <varname>compressedSize</varname> properties are used to store information
3762 21 Sep 07 nicklas 1100           about this. A file may always be compressed if the users says so, but
3762 21 Sep 07 nicklas 1101           BASE can also do this automatically if the file is uploaded
3762 21 Sep 07 nicklas 1102           to a directory with the <varname>autoCompress</varname> flag set
3762 21 Sep 07 nicklas 1103           or if the file has MIME type with the <varname>autoCompress</varname>
3762 21 Sep 07 nicklas 1104           flag set.
3762 21 Sep 07 nicklas 1105         </para>
3762 21 Sep 07 nicklas 1106         
3762 21 Sep 07 nicklas 1107         <para>
5408 13 Sep 10 nicklas 1108           The <classname docapi="net.sf.basedb.core.data">FileServerData</classname> class 
5780 04 Oct 11 nicklas 1109           holds information about an external file server. If the <varname>connectionManagerFactory</varname>
5780 04 Oct 11 nicklas 1110           isn't set BASE automatically selects a factory based on the URL of the file. There is
5780 04 Oct 11 nicklas 1111           built-in support for HTTP and HTTPS, but it is possible to install extensions for
5780 04 Oct 11 nicklas 1112           support for other protocols. The <varname>host</varname> property can be set
5780 04 Oct 11 nicklas 1113           to override the host part of the URL from the file. See <xref 
5780 04 Oct 11 nicklas 1114           linkend="extensions_developer.connection_manager" /> for more
5780 04 Oct 11 nicklas 1115           information about connection managers.
5780 04 Oct 11 nicklas 1116         </para>
5780 04 Oct 11 nicklas 1117         
5780 04 Oct 11 nicklas 1118         <para>
5780 04 Oct 11 nicklas 1119           The <varname>username</varname> and <varname>password</varname> properties are used if 
5780 04 Oct 11 nicklas 1120           the server requires the user to be logged in. BASE has built-in support for Basic and 
5780 04 Oct 11 nicklas 1121           Digest authentication. The <varname>serverCertificate</varname> can be used with HTTPS 
5780 04 Oct 11 nicklas 1122           servers that uses a non-trusted certificate to tell BASE to trust the server anyway. 
5780 04 Oct 11 nicklas 1123           In most cases, this is only needed if the server uses a self-signed certificate, but could, for 
5408 13 Sep 10 nicklas 1124           example, also be used if a trusted site has forgot to renew an expired certificate. 
5408 13 Sep 10 nicklas 1125           The server certificate should be an X.509 certificate in either binary or text format.
5408 13 Sep 10 nicklas 1126           The <varname>clientCertificate</varname> and <varname>clientPassword</varname>
5408 13 Sep 10 nicklas 1127           properties are used for servers that require that users present a valid client
5408 13 Sep 10 nicklas 1128           certificate before they are allowed access. The client certificate is usually issued
5408 13 Sep 10 nicklas 1129           by the server operator and must be in PKCS #12 format.
5408 13 Sep 10 nicklas 1130         </para>
5408 13 Sep 10 nicklas 1131         
5408 13 Sep 10 nicklas 1132         <para>
3947 12 Nov 07 nicklas 1133           The <classname docapi="net.sf.basedb.core.data">FileTypeData</classname> class holds information about 
3762 21 Sep 07 nicklas 1134           file types. It is used only to make it easier for users to organise 
3762 21 Sep 07 nicklas 1135           their files.
3762 21 Sep 07 nicklas 1136         </para>
3762 21 Sep 07 nicklas 1137         
3762 21 Sep 07 nicklas 1138         <para>
3947 12 Nov 07 nicklas 1139           The <classname docapi="net.sf.basedb.core.data">MimeTypeData</classname> is used to register mime types and
3762 21 Sep 07 nicklas 1140           map them to file extensions. The information is only used to lookup values 
3762 21 Sep 07 nicklas 1141           when needed. Given the filename we can set the <varname>File.mimeType</varname>
3762 21 Sep 07 nicklas 1142           and <varname>File.fileType</varname> properties. The MIME type is also
3762 21 Sep 07 nicklas 1143           used to decide if a file should be stored in a compressed format or not.
3762 21 Sep 07 nicklas 1144           The extension of a MIME type must be unique. Extensions should be registered 
3762 21 Sep 07 nicklas 1145           without a dot, ie <emphasis>html</emphasis>, not <emphasis>.html</emphasis>.  
5780 04 Oct 11 nicklas 1146         </para>  
3762 21 Sep 07 nicklas 1147       
3715 11 Sep 07 nicklas 1148     </sect2>
3757 20 Sep 07 nicklas 1149     
3757 20 Sep 07 nicklas 1150     <sect2 id="data_api.platforms">
5780 04 Oct 11 nicklas 1151       <title>Experimental platforms and item subtypes</title>
3715 11 Sep 07 nicklas 1152
3757 20 Sep 07 nicklas 1153       <para>
3757 20 Sep 07 nicklas 1154          This section gives an overview of experimental platforms
3757 20 Sep 07 nicklas 1155          and how they are used to enable data storage in files
5780 04 Oct 11 nicklas 1156          instead of in the database. In some senses item subtypes
5780 04 Oct 11 nicklas 1157          are related to platforms so they are also included here.
3757 20 Sep 07 nicklas 1158       </para>
3757 20 Sep 07 nicklas 1159       
3835 15 Oct 07 nicklas 1160       <itemizedlist>
3835 15 Oct 07 nicklas 1161         <title>See also</title>
3835 15 Oct 07 nicklas 1162         <listitem><xref linkend="core_api.data_in_files" /></listitem>
3835 15 Oct 07 nicklas 1163         <listitem><xref linkend="appendix.rawdatatypes.platforms" /></listitem>
5780 04 Oct 11 nicklas 1164         <listitem><xref linkend="extensions_developer.fileset_validator" /></listitem>
3835 15 Oct 07 nicklas 1165       </itemizedlist>
3835 15 Oct 07 nicklas 1166           
3757 20 Sep 07 nicklas 1167         <figure id="data_api.figures.platforms">
5780 04 Oct 11 nicklas 1168           <title>Experimental platforms and item subtypes</title>
3757 20 Sep 07 nicklas 1169           <screenshot>
3757 20 Sep 07 nicklas 1170             <mediaobject>
3757 20 Sep 07 nicklas 1171               <imageobject>
3757 20 Sep 07 nicklas 1172                 <imagedata 
3943 09 Nov 07 nicklas 1173                   align="center"
3757 20 Sep 07 nicklas 1174                   fileref="figures/uml/datalayer.platforms.png" format="PNG" />
3757 20 Sep 07 nicklas 1175               </imageobject>
3757 20 Sep 07 nicklas 1176             </mediaobject>
3757 20 Sep 07 nicklas 1177           </screenshot>
3757 20 Sep 07 nicklas 1178         </figure>
5780 04 Oct 11 nicklas 1179
3757 20 Sep 07 nicklas 1180       <sect3 id="data_api.platforms.platforms">
3757 20 Sep 07 nicklas 1181         <title>Platforms</title>
3757 20 Sep 07 nicklas 1182         
3757 20 Sep 07 nicklas 1183         <para>
3947 12 Nov 07 nicklas 1184           The <classname docapi="net.sf.basedb.core.data">PlatformData</classname> holds information about a
3947 12 Nov 07 nicklas 1185           platform. A platform can have one or more <classname docapi="net.sf.basedb.core.data">PlatformVariant</classname>:s.
3795 27 Sep 07 nicklas 1186           Both the platform and variant are identified by an external ID that
3757 20 Sep 07 nicklas 1187           is fixed and can't be changed. <emphasis>Affymetrix</emphasis>
3872 23 Oct 07 nicklas 1188           is an example of a platform.
3757 20 Sep 07 nicklas 1189           If the <varname>fileOnly</varname> flag is set data for the platform
3757 20 Sep 07 nicklas 1190           can only be stored in files and not imported into the database. If
3757 20 Sep 07 nicklas 1191           the flag is not set data can be imported into the database.
3872 23 Oct 07 nicklas 1192           In the latter case, the <varname>rawDataType</varname> property
3872 23 Oct 07 nicklas 1193           can be used to lock the platform
3757 20 Sep 07 nicklas 1194           to a specific raw data type. If the value is <constant>null</constant>
3757 20 Sep 07 nicklas 1195           the platform can use any raw data type. 
3757 20 Sep 07 nicklas 1196         </para>
3757 20 Sep 07 nicklas 1197         
3757 20 Sep 07 nicklas 1198         <para>
3757 20 Sep 07 nicklas 1199           Each platform and it's variant can be connected to one or more
3947 12 Nov 07 nicklas 1200           <classname docapi="net.sf.basedb.core.data">DataFileTypeData</classname> items. This item 
3757 20 Sep 07 nicklas 1201           describes the kind of files that are used to hold data for
3757 20 Sep 07 nicklas 1202           the platform and/or variant. The file types are re-usable between
3757 20 Sep 07 nicklas 1203           different platforms and variants. Note that a file type may be attached
3757 20 Sep 07 nicklas 1204           to either only a platform or to a platform with a variant. File 
3757 20 Sep 07 nicklas 1205           types attached to platforms are inherited by the variants. The variants
3757 20 Sep 07 nicklas 1206           can only define additional file types, not remove or redefine file types
3757 20 Sep 07 nicklas 1207           that has been attached to the platform.
3757 20 Sep 07 nicklas 1208         </para>
3757 20 Sep 07 nicklas 1209         <para>
3757 20 Sep 07 nicklas 1210           The file type is also identified
3795 27 Sep 07 nicklas 1211           by a fixed, non-changable external ID. The <varname>itemType</varname>
3757 20 Sep 07 nicklas 1212           property tells us what type of item the file holds data for (ie. 
5780 04 Oct 11 nicklas 1213           array design or raw bioassay). It also links to a <classname 
5780 04 Oct 11 nicklas 1214           docapi="net.sf.basedb.core.data">ItemSubtype</classname>
3872 23 Oct 07 nicklas 1215           which is the generic type of data in the file. This allows us to query
3872 23 Oct 07 nicklas 1216           the database for, as an example, files with the generic type
3757 20 Sep 07 nicklas 1217           <constant>FileType.RAW_DATA</constant>. If we are in an Affymetrix 
3757 20 Sep 07 nicklas 1218           experiment we will get the CEL file, for another platform we will
3757 20 Sep 07 nicklas 1219           get another file.
3757 20 Sep 07 nicklas 1220         </para>
3795 27 Sep 07 nicklas 1221         <para>
3947 12 Nov 07 nicklas 1222           The <varname>required</varname> flag in <classname docapi="net.sf.basedb.core.data">PlatformFileTypeData</classname>
3872 23 Oct 07 nicklas 1223           is used to signal that the file is a required file. This is not 
5780 04 Oct 11 nicklas 1224           enforced by the core. It is intended to be used by client applications
3872 23 Oct 07 nicklas 1225           for creating a better GUI and for validation of an experiment.
3795 27 Sep 07 nicklas 1226         </para>
5780 04 Oct 11 nicklas 1227         <para>
5780 04 Oct 11 nicklas 1228           The <varname>allowMultiple</varname> flag in <classname 
5780 04 Oct 11 nicklas 1229           docapi="net.sf.basedb.core.data">PlatformFileTypeData</classname>
5780 04 Oct 11 nicklas 1230           controls if it should be possible to store more than one file of
5780 04 Oct 11 nicklas 1231           the given type in file type. Again, this is not enforced by the core,
5780 04 Oct 11 nicklas 1232           but only a recommendation to client applications. The setting is
5780 04 Oct 11 nicklas 1233           also used for validation of an experiment.
5780 04 Oct 11 nicklas 1234         </para>
3757 20 Sep 07 nicklas 1235
3757 20 Sep 07 nicklas 1236       </sect3>
3757 20 Sep 07 nicklas 1237       
5780 04 Oct 11 nicklas 1238       <sect3 id="data_api.platforms.subtypes">
5780 04 Oct 11 nicklas 1239         <title>Item subtypes</title>
5780 04 Oct 11 nicklas 1240         
5780 04 Oct 11 nicklas 1241         <para>
5780 04 Oct 11 nicklas 1242           The <classname docapi="net.sf.basedb.core.data">ItemSubtypeData</classname> 
5780 04 Oct 11 nicklas 1243           class describes a subtype for a main <varname>itemType</varname>. In the simplest 
5780 04 Oct 11 nicklas 1244           form the subtype is a kind of annotation that is used mainly for creating a 
5780 04 Oct 11 nicklas 1245           better user experience. If the main item type is also implementing the
5780 04 Oct 11 nicklas 1246           <interfacename docapi="net.sf.basedb.core.data">FileStoreEnabledData</interfacename> 
5780 04 Oct 11 nicklas 1247           interface, it is possible to
5780 04 Oct 11 nicklas 1248           register associations to the file types that can be used together with a given
5780 04 Oct 11 nicklas 1249           item subtype. The <varname>required</varname> and <varname>allowMultiple</varname>
5780 04 Oct 11 nicklas 1250           have are used in the same way as in the <classname>PlatformFileTypeData</classname>
5780 04 Oct 11 nicklas 1251           class.
5780 04 Oct 11 nicklas 1252         </para>
5780 04 Oct 11 nicklas 1253         
5780 04 Oct 11 nicklas 1254         <para>
5780 04 Oct 11 nicklas 1255           A subtype can be related to other subtypes. This is used to "chain" together 
5780 04 Oct 11 nicklas 1256           groups of item subtypes. For example, <constant>Hybridization</constant>
5780 04 Oct 11 nicklas 1257           is a subtype for <constant>PHYSICALBIOASSAY</constant>, which is related to
5780 04 Oct 11 nicklas 1258           the <constant>Labeled extract (EXTRACT)</constant> subtype which is related to 
5780 04 Oct 11 nicklas 1259           the <constant>Label (TAG)</constant> subtype. In addition, there are also
5780 04 Oct 11 nicklas 1260           several protocol and hardware subetypes mixed into this. The relationship between
5780 04 Oct 11 nicklas 1261           subtypes makes it possible for client applications to filter out unrelated stuff,
5780 04 Oct 11 nicklas 1262           and to validate experiments.
5780 04 Oct 11 nicklas 1263         </para>
5780 04 Oct 11 nicklas 1264         
5780 04 Oct 11 nicklas 1265       </sect3>
5780 04 Oct 11 nicklas 1266       
3757 20 Sep 07 nicklas 1267       <sect3 id="data_api.platforms.files">
3835 15 Oct 07 nicklas 1268         <title>FileStoreEnabled items and data files</title>
3757 20 Sep 07 nicklas 1269         
3757 20 Sep 07 nicklas 1270         <para>
5780 04 Oct 11 nicklas 1271           An item must implement the <interfacename docapi="net.sf.basedb.core.data">FileStoreEnabledData</interfacename>
3757 20 Sep 07 nicklas 1272           interface to be able to store data in files instead of in the database.
3947 12 Nov 07 nicklas 1273           The interface creates a link to a <classname docapi="net.sf.basedb.core.data">FileSetData</classname> object,
3947 12 Nov 07 nicklas 1274           which can hold several <classname docapi="net.sf.basedb.core.data">FileSetMemberData</classname> items.
3947 12 Nov 07 nicklas 1275           Each member points to specific <classname docapi="net.sf.basedb.core.data">FileData</classname> item.
3757 20 Sep 07 nicklas 1276         </para>
3757 20 Sep 07 nicklas 1277         
3757 20 Sep 07 nicklas 1278       </sect3>
3757 20 Sep 07 nicklas 1279     </sect2>
3757 20 Sep 07 nicklas 1280
3715 11 Sep 07 nicklas 1281     <sect2 id="data_api.parameters">
3715 11 Sep 07 nicklas 1282       <title>Parameters</title>
3904 02 Nov 07 nicklas 1283       
3904 02 Nov 07 nicklas 1284       <para>
3904 02 Nov 07 nicklas 1285         This section gives an overview the generic parameter
3904 02 Nov 07 nicklas 1286         system in BASE that is used to store annotation values,
3904 02 Nov 07 nicklas 1287         plugin configuration values, job parameter values, etc.
3904 02 Nov 07 nicklas 1288       </para>
3904 02 Nov 07 nicklas 1289       
3904 02 Nov 07 nicklas 1290         <figure id="data_api.figures.parameters">
3904 02 Nov 07 nicklas 1291           <title>Parameters</title>
3904 02 Nov 07 nicklas 1292           <screenshot>
3904 02 Nov 07 nicklas 1293             <mediaobject>
3904 02 Nov 07 nicklas 1294               <imageobject>
3904 02 Nov 07 nicklas 1295                 <imagedata 
3943 09 Nov 07 nicklas 1296                   align="center"
3904 02 Nov 07 nicklas 1297                   fileref="figures/uml/datalayer.parameters.png" format="PNG" />
3904 02 Nov 07 nicklas 1298               </imageobject>
3904 02 Nov 07 nicklas 1299             </mediaobject>
3904 02 Nov 07 nicklas 1300           </screenshot>
3904 02 Nov 07 nicklas 1301         </figure>
3904 02 Nov 07 nicklas 1302       
3916 06 Nov 07 nicklas 1303         <para>
3916 06 Nov 07 nicklas 1304           The parameter system is a generic system that can store almost
3916 06 Nov 07 nicklas 1305           any kind of simple values (string, numbers, dates, etc.) and
5780 04 Oct 11 nicklas 1306           also links to other items. It is, for example, used to store configuration
5780 04 Oct 11 nicklas 1307           parameters to plug-ins and jobs as well as annotation values to annotatable items.
5780 04 Oct 11 nicklas 1308           The <classname docapi="net.sf.basedb.core.data">ParameterValueData</classname> 
3916 06 Nov 07 nicklas 1309           class is an abstract base class that can hold multiple values (all must be of the
3916 06 Nov 07 nicklas 1310           same type). Unless only a specific type of values should be stored, this is 
3916 06 Nov 07 nicklas 1311           the class that should be used when creating references for storing parameter
5780 04 Oct 11 nicklas 1312           values. It makes it possible for a single relation to use any kind of
3916 06 Nov 07 nicklas 1313           values or for a collection reference to mix multiple types of values.
3916 06 Nov 07 nicklas 1314           A typical use case maps a <classname>Map</classname> with the 
3916 06 Nov 07 nicklas 1315           parameter name as the key:
3916 06 Nov 07 nicklas 1316         </para>
3916 06 Nov 07 nicklas 1317         
3916 06 Nov 07 nicklas 1318         <programlisting language="java">
3916 06 Nov 07 nicklas 1319 private Map&lt;String, ParameterValueData&lt;?&gt;&gt; configurationValues;
3916 06 Nov 07 nicklas 1320 /**
3916 06 Nov 07 nicklas 1321    Link parameter name with it's values.
3916 06 Nov 07 nicklas 1322    @hibernate.map table="`PluginConfigurationValues`" lazy="true" cascade="all"
3916 06 Nov 07 nicklas 1323    @hibernate.collection-key column="`pluginconfiguration_id`"
3916 06 Nov 07 nicklas 1324    @hibernate.collection-index column="`name`" type="string" length="255"
3916 06 Nov 07 nicklas 1325    @hibernate.collection-many-to-many column="`value_id`" 
3916 06 Nov 07 nicklas 1326       class="net.sf.basedb.core.data.ParameterValueData"
3916 06 Nov 07 nicklas 1327 */
3916 06 Nov 07 nicklas 1328 public Map&lt;String, ParameterValueData&lt;?&gt;&gt; getConfigurationValues()
3916 06 Nov 07 nicklas 1329 {
3916 06 Nov 07 nicklas 1330    return configurationValues;
3916 06 Nov 07 nicklas 1331 }
3916 06 Nov 07 nicklas 1332 void setConfigurationValues(Map&lt;String, ParameterValueData&lt;?&gt;&gt; configurationValues)
3916 06 Nov 07 nicklas 1333 {
3916 06 Nov 07 nicklas 1334    this.configurationValues = configurationValues;
3916 06 Nov 07 nicklas 1335 }
3916 06 Nov 07 nicklas 1336 </programlisting>
3916 06 Nov 07 nicklas 1337         
3904 02 Nov 07 nicklas 1338       <para>
3916 06 Nov 07 nicklas 1339       Now it is possible for the collection to store all types of values:
3904 02 Nov 07 nicklas 1340       </para>
3904 02 Nov 07 nicklas 1341       
3916 06 Nov 07 nicklas 1342       <programlisting language="java">
3916 06 Nov 07 nicklas 1343 Map&lt;String, ParameterValueData&lt;?&gt;&gt; config = ...
3916 06 Nov 07 nicklas 1344 config.put("names", new StringParameterValueData("A", "B", "C"));
3916 06 Nov 07 nicklas 1345 config.put("sizes", new IntegerParameterValueData(10, 20, 30));
3916 06 Nov 07 nicklas 1346
3916 06 Nov 07 nicklas 1347 // When you later load those values again you have to cast 
3916 06 Nov 07 nicklas 1348 // them to the correct class.
3916 06 Nov 07 nicklas 1349 List&lt;String&gt; names = (List&lt;String&gt;)config.get("names").getValues();
3916 06 Nov 07 nicklas 1350 List&lt;Integer&gt; sizes = (List&lt;Integer&gt;)config.get("sizes").getValues();
3916 06 Nov 07 nicklas 1351 </programlisting>
3916 06 Nov 07 nicklas 1352
3715 11 Sep 07 nicklas 1353     </sect2>
3715 11 Sep 07 nicklas 1354
3715 11 Sep 07 nicklas 1355     <sect2 id="data_api.annotations">
3715 11 Sep 07 nicklas 1356       <title>Annotations</title>
3904 02 Nov 07 nicklas 1357       
3904 02 Nov 07 nicklas 1358       <para>
3904 02 Nov 07 nicklas 1359         This section gives an overview of how the BASE annotation
3904 02 Nov 07 nicklas 1360         system works.
3904 02 Nov 07 nicklas 1361       </para>
3904 02 Nov 07 nicklas 1362       
3904 02 Nov 07 nicklas 1363         <figure id="data_api.figures.annotations">
3904 02 Nov 07 nicklas 1364           <title>Annotations</title>
3904 02 Nov 07 nicklas 1365           <screenshot>
3904 02 Nov 07 nicklas 1366             <mediaobject>
3904 02 Nov 07 nicklas 1367               <imageobject>
3904 02 Nov 07 nicklas 1368                 <imagedata 
3943 09 Nov 07 nicklas 1369                   align="center"
3904 02 Nov 07 nicklas 1370                   fileref="figures/uml/datalayer.annotations.png" format="PNG" />
3904 02 Nov 07 nicklas 1371               </imageobject>
3904 02 Nov 07 nicklas 1372             </mediaobject>
3904 02 Nov 07 nicklas 1373           </screenshot>
3904 02 Nov 07 nicklas 1374         </figure>
3904 02 Nov 07 nicklas 1375       
3904 02 Nov 07 nicklas 1376       <sect3 id="data_api.annotations.description">
3904 02 Nov 07 nicklas 1377         <title>Annotations</title>
3904 02 Nov 07 nicklas 1378         
3904 02 Nov 07 nicklas 1379         <para>
3947 12 Nov 07 nicklas 1380         An item must implement the <interfacename docapi="net.sf.basedb.core.data">AnnotatableData</interfacename>
3904 02 Nov 07 nicklas 1381         interface to be able to use the annotation system. This interface gives
3947 12 Nov 07 nicklas 1382         a link to a <classname docapi="net.sf.basedb.core.data">AnnotationSetData</classname> item. This class
3904 02 Nov 07 nicklas 1383         encapsulates all annotations for the item. There are two types of
3904 02 Nov 07 nicklas 1384         annotations:
3904 02 Nov 07 nicklas 1385         </para>
3904 02 Nov 07 nicklas 1386         
3904 02 Nov 07 nicklas 1387         <itemizedlist>
3904 02 Nov 07 nicklas 1388         <listitem>
3904 02 Nov 07 nicklas 1389           <para>
3904 02 Nov 07 nicklas 1390           <emphasis>Primary annotations</emphasis> are annotations that
3904 02 Nov 07 nicklas 1391           explicitely belong to the item. An annotation set can contain
3904 02 Nov 07 nicklas 1392           only one primary annotation of each annotation type. The primary
3904 02 Nov 07 nicklas 1393           annotation are linked with the <property>annotations</property>
3904 02 Nov 07 nicklas 1394           property. This property is a map with an 
3947 12 Nov 07 nicklas 1395           <classname docapi="net.sf.basedb.core.data">AnnotationTypeData</classname>  as the key.
3904 02 Nov 07 nicklas 1396           </para>
3904 02 Nov 07 nicklas 1397         </listitem>
3904 02 Nov 07 nicklas 1398         
3904 02 Nov 07 nicklas 1399         <listitem>
3904 02 Nov 07 nicklas 1400           <para>
3904 02 Nov 07 nicklas 1401           <emphasis>Inherited annotations</emphasis> are annotations
3904 02 Nov 07 nicklas 1402           that belong to a parent item, but that we want to use on 
3904 02 Nov 07 nicklas 1403           another item as well. Inherited annotations are saved as
3904 02 Nov 07 nicklas 1404           references to either a single annotation or to another
3904 02 Nov 07 nicklas 1405           annotation set. Thus, it is possible for an item to inherit
3904 02 Nov 07 nicklas 1406           multiple annotations of the same annotation type.
3904 02 Nov 07 nicklas 1407           </para>
3904 02 Nov 07 nicklas 1408         </listitem>
3904 02 Nov 07 nicklas 1409         </itemizedlist>
3904 02 Nov 07 nicklas 1410         
3904 02 Nov 07 nicklas 1411         <para>
3947 12 Nov 07 nicklas 1412           The <classname docapi="net.sf.basedb.core.data">AnnotationData</classname> class is also
3904 02 Nov 07 nicklas 1413           just a placeholder. It connects the annotation set and
3947 12 Nov 07 nicklas 1414           annotation type with a <classname docapi="net.sf.basedb.core.data">ParameterValueData</classname>
3904 02 Nov 07 nicklas 1415           object. This is the object that holds the actual annotation
3904 02 Nov 07 nicklas 1416           values.
3904 02 Nov 07 nicklas 1417         </para>
3904 02 Nov 07 nicklas 1418         
3904 02 Nov 07 nicklas 1419       </sect3>
3904 02 Nov 07 nicklas 1420       
3904 02 Nov 07 nicklas 1421       <sect3 id="data_api.annotations.types">
3904 02 Nov 07 nicklas 1422         <title>Annotation types</title>
3904 02 Nov 07 nicklas 1423         
3904 02 Nov 07 nicklas 1424         <para>
3947 12 Nov 07 nicklas 1425         Instances of the <classname docapi="net.sf.basedb.core.data">AnnotationTypeData</classname> class
3904 02 Nov 07 nicklas 1426         defines the various annotations. It must have a <property>valueType</property> 
3904 02 Nov 07 nicklas 1427         property which cannot be changed. The value of this property controls 
3947 12 Nov 07 nicklas 1428         which <classname docapi="net.sf.basedb.core.data">ParameterValueData</classname> subclass is used to store 
3947 12 Nov 07 nicklas 1429         the annotation values, ie. <classname docapi="net.sf.basedb.core.data">IntegerParameterValueData</classname>, 
3947 12 Nov 07 nicklas 1430         <classname docapi="net.sf.basedb.core.data">StringParameterValueData</classname>, etc. 
3904 02 Nov 07 nicklas 1431         The <property>multiplicity</property> property holds the maximum allowed 
3904 02 Nov 07 nicklas 1432         number of values for an annotation, or 0 if an unlimited number is 
3904 02 Nov 07 nicklas 1433         allowed.
3904 02 Nov 07 nicklas 1434         </para>
3904 02 Nov 07 nicklas 1435         
3904 02 Nov 07 nicklas 1436         <para>
3904 02 Nov 07 nicklas 1437         The <property>itemTypes</property> collection holds the codes for 
3904 02 Nov 07 nicklas 1438         the types of items the annotation type can be used on. This is 
3904 02 Nov 07 nicklas 1439         checked when new annotations are created but already existing 
3904 02 Nov 07 nicklas 1440         annotations are not affected if the collection is modified.
3904 02 Nov 07 nicklas 1441         </para>
3904 02 Nov 07 nicklas 1442         
3904 02 Nov 07 nicklas 1443         <para>
3904 02 Nov 07 nicklas 1444         Annotation types with the <property>protocolParameter</property> flag set 
3904 02 Nov 07 nicklas 1445         are treated a bit differently. They will not show up as annotations 
3904 02 Nov 07 nicklas 1446         to items with a type found in the <property>itemTypes</property> collection.
5780 04 Oct 11 nicklas 1447         Instead, a protocol parameter should be attached to a protocol. Then, when an item 
3904 02 Nov 07 nicklas 1448         is using that protocol it becomes possible to add annotation values for 
3904 02 Nov 07 nicklas 1449         the annotation types specified as protocol parameters. It doesn't matter 
3904 02 Nov 07 nicklas 1450         if the item's type is found in the <property>itemTypes</property> 
3904 02 Nov 07 nicklas 1451         collection or not.
3904 02 Nov 07 nicklas 1452         </para>
3904 02 Nov 07 nicklas 1453         
3904 02 Nov 07 nicklas 1454         <para>
3904 02 Nov 07 nicklas 1455         The <property>options</property> collection is used to store additional 
3904 02 Nov 07 nicklas 1456         options required by some of the value types, for example a max string 
3904 02 Nov 07 nicklas 1457         length for string annotations or the max and min allowed value for 
3904 02 Nov 07 nicklas 1458         integer annotations.
3904 02 Nov 07 nicklas 1459         </para>
3904 02 Nov 07 nicklas 1460         
3904 02 Nov 07 nicklas 1461         <para>
3904 02 Nov 07 nicklas 1462         The <property>enumeration</property> property is a boolean flag 
3904 02 Nov 07 nicklas 1463         indicating if the allowed values are predefined as an enumeration. 
3904 02 Nov 07 nicklas 1464         In that case those values are found in the <property>enumerationValues</property>
3904 02 Nov 07 nicklas 1465         property. The actual subclass is determined by the <property>valueType</property>
3904 02 Nov 07 nicklas 1466         property.
3904 02 Nov 07 nicklas 1467         </para>
3904 02 Nov 07 nicklas 1468         
3904 02 Nov 07 nicklas 1469         <para>
3904 02 Nov 07 nicklas 1470         Most of the other properties are hints to client applications how 
3904 02 Nov 07 nicklas 1471         to render the input field for the annotation. 
3904 02 Nov 07 nicklas 1472         </para>
3904 02 Nov 07 nicklas 1473         
3904 02 Nov 07 nicklas 1474       </sect3>
3904 02 Nov 07 nicklas 1475       
4538 18 Sep 08 nicklas 1476       <sect3 id="data_api.annotations.units">
4538 18 Sep 08 nicklas 1477         <title>Units</title>
4538 18 Sep 08 nicklas 1478         <para>
4538 18 Sep 08 nicklas 1479         Numerical annotation values can have units. A unit is described by 
4538 18 Sep 08 nicklas 1480         a <classname docapi="net.sf.basedb.core.data">UnitData</classname> object. 
4538 18 Sep 08 nicklas 1481         Each unit belongs to a <classname docapi="net.sf.basedb.core.data">QuantityData</classname> 
4538 18 Sep 08 nicklas 1482         object which defines the class of units. For example, if the quantity is 
4538 18 Sep 08 nicklas 1483         <emphasis>weight</emphasis>, we can have units, <emphasis>kg</emphasis>, 
4538 18 Sep 08 nicklas 1484         <emphasis>mg</emphasis>, <emphasis>µg</emphasis>, etc. The <classname>UnitData</classname>
4542 22 Sep 08 nicklas 1485         contains a factor and offset that relates all units to a common reference
4538 18 Sep 08 nicklas 1486         defined by the <classname>QuantityData</classname> class. For example,
4542 22 Sep 08 nicklas 1487         <emphasis>1 meter</emphasis> is the reference unit for distance, and we
4542 22 Sep 08 nicklas 1488         have <code>1 meter * 0.001 = 1 millimeter</code>. In this case, the factor is 
4542 22 Sep 08 nicklas 1489         <emphasis>0.001</emphasis> and the offset 0. Another example is the relationship between 
4542 22 Sep 08 nicklas 1490         kelvin and Celsius, which is <code>1 kelvin + 273.15 = 1 °Celsius</code>.
4542 22 Sep 08 nicklas 1491         Here, the factor is 1 and the offset is <emphasis>+273.15</emphasis>.
4542 22 Sep 08 nicklas 1492         The <classname
4538 18 Sep 08 nicklas 1493         docapi="net.sf.basedb.core.data">UnitSymbolData</classname>
4538 18 Sep 08 nicklas 1494         is used to make it possible to assign alternative symbols to a single unit.
4538 18 Sep 08 nicklas 1495         This is needed to simplify input where it may be hard to know what to
4542 22 Sep 08 nicklas 1496         type to get <emphasis>m²</emphasis> or <emphasis>°C</emphasis>. Instead, 
4542 22 Sep 08 nicklas 1497         <emphasis>m2</emphasis> and <emphasis>C</emphasis> can be used as 
4542 22 Sep 08 nicklas 1498         alternative symbols.
4538 18 Sep 08 nicklas 1499         </para>
4538 18 Sep 08 nicklas 1500         
4538 18 Sep 08 nicklas 1501         <para>
4538 18 Sep 08 nicklas 1502         The creator of an annotation type may select a 
4538 18 Sep 08 nicklas 1503         <classname>QuantityData</classname>, which can't be changed later, and
4538 18 Sep 08 nicklas 1504         a default <classname>UnitData</classname>. When entering annotation values
4538 18 Sep 08 nicklas 1505         a user may select any unit for the selected quantity (unless annotation type
4538 18 Sep 08 nicklas 1506         owner has limited this by selecting <varname>usableUnits</varname>). Before
4538 18 Sep 08 nicklas 1507         the values are stored in the database, they are converted to the default
4538 18 Sep 08 nicklas 1508         unit. This makes it possible to compare and filter on annotation values
4538 18 Sep 08 nicklas 1509         using different units. For example, filtering with <emphasis>&gt;5mg</emphasis> 
4538 18 Sep 08 nicklas 1510         also finds items that are annotated with <emphasis>2g</emphasis>.
4538 18 Sep 08 nicklas 1511         </para>
4538 18 Sep 08 nicklas 1512         
4538 18 Sep 08 nicklas 1513         <para>
4538 18 Sep 08 nicklas 1514         The core should automatically update the stored annotation values if
4538 18 Sep 08 nicklas 1515         the default unit is changed for an annotation type, or if the reference
4538 18 Sep 08 nicklas 1516         factor for a unit is changed.
4538 18 Sep 08 nicklas 1517         </para>
4538 18 Sep 08 nicklas 1518       </sect3>
4538 18 Sep 08 nicklas 1519       
3904 02 Nov 07 nicklas 1520       <sect3 id="data_api.annotations.categories">
3904 02 Nov 07 nicklas 1521         <title>Categories</title>
3904 02 Nov 07 nicklas 1522         
3904 02 Nov 07 nicklas 1523         <para>
3947 12 Nov 07 nicklas 1524         The <classname docapi="net.sf.basedb.core.data">AnnotationTypeCategoryData</classname> class defines
3904 02 Nov 07 nicklas 1525         categories that are used to group annotation types that are related to 
3904 02 Nov 07 nicklas 1526         each other. This information is mainly useful for client applications 
3904 02 Nov 07 nicklas 1527         when displaying forms for annotating items, that wish to provide a 
3904 02 Nov 07 nicklas 1528         clearer interface when there are many (say 50+) annotations type for 
3904 02 Nov 07 nicklas 1529         an item. An annotation type can belong to more than one category. 
3904 02 Nov 07 nicklas 1530         </para>
3904 02 Nov 07 nicklas 1531         
3904 02 Nov 07 nicklas 1532       </sect3>
3904 02 Nov 07 nicklas 1533       
3715 11 Sep 07 nicklas 1534     </sect2>
3715 11 Sep 07 nicklas 1535
3904 02 Nov 07 nicklas 1536     <sect2 id="data_api.protocols">
5780 04 Oct 11 nicklas 1537       <title>Protocols, hardware and software</title>
3904 02 Nov 07 nicklas 1538
3904 02 Nov 07 nicklas 1539       <para>
3904 02 Nov 07 nicklas 1540         This section gives an overview of how protocols that describe various
3904 02 Nov 07 nicklas 1541         processes, such as sampling, extraction and scanning, are used in BASE.
3904 02 Nov 07 nicklas 1542       </para>
3904 02 Nov 07 nicklas 1543       
3904 02 Nov 07 nicklas 1544         <figure id="data_api.figures.protocols">
5780 04 Oct 11 nicklas 1545           <title>Protocols, hardware and software</title>
3904 02 Nov 07 nicklas 1546           <screenshot>
3904 02 Nov 07 nicklas 1547             <mediaobject>
3904 02 Nov 07 nicklas 1548               <imageobject>
3904 02 Nov 07 nicklas 1549                 <imagedata 
3943 09 Nov 07 nicklas 1550                   align="center"
3904 02 Nov 07 nicklas 1551                   fileref="figures/uml/datalayer.protocols.png" format="PNG" />
3904 02 Nov 07 nicklas 1552               </imageobject>
3904 02 Nov 07 nicklas 1553             </mediaobject>
3904 02 Nov 07 nicklas 1554           </screenshot>
3904 02 Nov 07 nicklas 1555         </figure>
3904 02 Nov 07 nicklas 1556       
3904 02 Nov 07 nicklas 1557       <sect3 id="data_api.protocols.description">
3904 02 Nov 07 nicklas 1558         <title>Protocols</title>
3904 02 Nov 07 nicklas 1559         
3904 02 Nov 07 nicklas 1560         <para>
3904 02 Nov 07 nicklas 1561         A protocol is something that defines a procedure or recipe for some
5780 04 Oct 11 nicklas 1562         kind of action, such as sampling, extraction and scanning. The subtype
5780 04 Oct 11 nicklas 1563         of the protocol is used to determine what the protocol is used for. 
5780 04 Oct 11 nicklas 1564         In BASE we only store a short name and description. It is possible to 
5780 04 Oct 11 nicklas 1565         attach a file that provides a longer description of the procedure.
3904 02 Nov 07 nicklas 1566         </para>
3904 02 Nov 07 nicklas 1567       
3904 02 Nov 07 nicklas 1568       </sect3>
3904 02 Nov 07 nicklas 1569       
3904 02 Nov 07 nicklas 1570       <sect3 id="data_api.protocols.parameters">
3904 02 Nov 07 nicklas 1571         <title>Parameters</title>
3904 02 Nov 07 nicklas 1572         
3904 02 Nov 07 nicklas 1573         <para>
3904 02 Nov 07 nicklas 1574         The procedure described by the protocol may have parameters
3904 02 Nov 07 nicklas 1575         that are set indepentently each time the protocol is used. It
3904 02 Nov 07 nicklas 1576         could for example be a temperature, a time or something else.
3904 02 Nov 07 nicklas 1577         The definition of parameters is done by creating annotation
3904 02 Nov 07 nicklas 1578         types and attaching them to the protocol. It is only possible
3904 02 Nov 07 nicklas 1579         to attach annotation types which has the <property>protocolParameter</property>
3904 02 Nov 07 nicklas 1580         property set to <constant>true</constant>. The same annotation type
3904 02 Nov 07 nicklas 1581         can be used for more than one protocol, but only do this if the 
3904 02 Nov 07 nicklas 1582         parameters actually has the same meaning.
3904 02 Nov 07 nicklas 1583         </para>
3904 02 Nov 07 nicklas 1584       
3904 02 Nov 07 nicklas 1585       </sect3>
5780 04 Oct 11 nicklas 1586
5780 04 Oct 11 nicklas 1587       <sect3 id="data_api.wares.description">
5780 04 Oct 11 nicklas 1588         <title>Hardware and software</title>
5780 04 Oct 11 nicklas 1589         <para>
5780 04 Oct 11 nicklas 1590           BASE is pre-installed with a set of subtypes for hardware and software. 
5780 04 Oct 11 nicklas 1591           They are typically used to filter the registered hardware and software
5780 04 Oct 11 nicklas 1592           depending on what a user is doing. For example, when adding raw data
5780 04 Oct 11 nicklas 1593           to BASE a user can select a scanner. The GUI will display the hardware
5780 04 Oct 11 nicklas 1594           that has been registered as <emphasis>scanner</emphasis> subtype.
5780 04 Oct 11 nicklas 1595           Other subtypes are <emphasis>hybridization station</emphasis>
5780 04 Oct 11 nicklas 1596           and <emphasis>print robot</emphasis>. An administrator may register more
5780 04 Oct 11 nicklas 1597           subtypes. 
5780 04 Oct 11 nicklas 1598         </para>
5780 04 Oct 11 nicklas 1599       </sect3>
3904 02 Nov 07 nicklas 1600       
3904 02 Nov 07 nicklas 1601     </sect2>
3904 02 Nov 07 nicklas 1602
3715 11 Sep 07 nicklas 1603     <sect2 id="data_api.plugins">
3715 11 Sep 07 nicklas 1604       <title>Plug-ins, jobs and job agents</title>
3871 22 Oct 07 nicklas 1605       
3871 22 Oct 07 nicklas 1606       <para>
3871 22 Oct 07 nicklas 1607          This section gives an overview of plug-ins, jobs and job agents.
3871 22 Oct 07 nicklas 1608       </para>
3871 22 Oct 07 nicklas 1609       
3871 22 Oct 07 nicklas 1610       <itemizedlist>
3871 22 Oct 07 nicklas 1611         <title>See also</title>
3871 22 Oct 07 nicklas 1612         <listitem><xref linkend="plugins.installation" /></listitem>
5738 15 Sep 11 nicklas 1613         <listitem><xref linkend="installation.jobagents" /></listitem>
3871 22 Oct 07 nicklas 1614       </itemizedlist>
3871 22 Oct 07 nicklas 1615       
3871 22 Oct 07 nicklas 1616         <figure id="data_api.figures.plugins">
3871 22 Oct 07 nicklas 1617           <title>Plug-ins, jobs and job agents</title>
3871 22 Oct 07 nicklas 1618           <screenshot>
3871 22 Oct 07 nicklas 1619             <mediaobject>
3871 22 Oct 07 nicklas 1620               <imageobject>
3871 22 Oct 07 nicklas 1621                 <imagedata 
3943 09 Nov 07 nicklas 1622                   align="center"
3943 09 Nov 07 nicklas 1623                   scalefit="1" width="100%"
3871 22 Oct 07 nicklas 1624                   fileref="figures/uml/datalayer.plugins.png" format="PNG" />
3871 22 Oct 07 nicklas 1625               </imageobject>
3871 22 Oct 07 nicklas 1626             </mediaobject>
3871 22 Oct 07 nicklas 1627           </screenshot>
3871 22 Oct 07 nicklas 1628         </figure>
3871 22 Oct 07 nicklas 1629
3871 22 Oct 07 nicklas 1630       <sect3 id="data_api.plugins.plugins">
3871 22 Oct 07 nicklas 1631         <title>Plug-ins</title>
3871 22 Oct 07 nicklas 1632         
3871 22 Oct 07 nicklas 1633         <para>
3947 12 Nov 07 nicklas 1634           The <classname docapi="net.sf.basedb.core.data">PluginDefinitionData</classname> holds information of the 
3871 22 Oct 07 nicklas 1635           installed plugin classes. Much of the information is copied from the
3947 12 Nov 07 nicklas 1636           plug-in itself from the <classname docapi="net.sf.basedb.core.plugin">About</classname> object and by checking
3871 22 Oct 07 nicklas 1637           which interfaces it implements.
3871 22 Oct 07 nicklas 1638         </para>
3871 22 Oct 07 nicklas 1639         
3871 22 Oct 07 nicklas 1640         <para>
3871 22 Oct 07 nicklas 1641           There are five main types of plug-ins:
3871 22 Oct 07 nicklas 1642         </para>
3871 22 Oct 07 nicklas 1643         
3871 22 Oct 07 nicklas 1644         <itemizedlist>
3871 22 Oct 07 nicklas 1645         <listitem>
3871 22 Oct 07 nicklas 1646           <para>
3871 22 Oct 07 nicklas 1647           IMPORT (mainType = 1): A plug-in that imports data to BASE.
3871 22 Oct 07 nicklas 1648           </para>
3871 22 Oct 07 nicklas 1649         </listitem>
3871 22 Oct 07 nicklas 1650         <listitem>
3871 22 Oct 07 nicklas 1651           <para>
3871 22 Oct 07 nicklas 1652           EXPORT (mainType = 2): A plug-in that exports data from BASE.
3871 22 Oct 07 nicklas 1653           </para>
3871 22 Oct 07 nicklas 1654         </listitem>
3871 22 Oct 07 nicklas 1655         <listitem>
3871 22 Oct 07 nicklas 1656           <para>
3871 22 Oct 07 nicklas 1657           INTENSITY (mainType = 3): A plug-in that calculates intensity values
3871 22 Oct 07 nicklas 1658           from raw data.
3871 22 Oct 07 nicklas 1659           </para>
3871 22 Oct 07 nicklas 1660         </listitem>
3871 22 Oct 07 nicklas 1661         <listitem>
3871 22 Oct 07 nicklas 1662           <para>
3871 22 Oct 07 nicklas 1663           ANALYZE (mainType = 4): A plug-in that analyses data.
3871 22 Oct 07 nicklas 1664           </para>
3871 22 Oct 07 nicklas 1665         </listitem>
3871 22 Oct 07 nicklas 1666         <listitem>
3871 22 Oct 07 nicklas 1667           <para>
3871 22 Oct 07 nicklas 1668           OTHER (mainType = 5): Any other plug-in.
3871 22 Oct 07 nicklas 1669           </para>
3871 22 Oct 07 nicklas 1670         </listitem>
3871 22 Oct 07 nicklas 1671         </itemizedlist>
3871 22 Oct 07 nicklas 1672         
3871 22 Oct 07 nicklas 1673         <para>
3871 22 Oct 07 nicklas 1674           A plug-in may have different configurations. The flags <property>supportsConfigurations</property>
3871 22 Oct 07 nicklas 1675           and <property>requiresConfiguration</property> are used to specify if a plug-in 
3871 22 Oct 07 nicklas 1676           must have or can't have any configurations. Configuration parameter values are 
3871 22 Oct 07 nicklas 1677           versioned. Each time anyone updates a configuration the version number 
3871 22 Oct 07 nicklas 1678           is increased and the parameter values are stored as a new entity. 
3871 22 Oct 07 nicklas 1679           This is required because we want to be able to know exactly which
3871 22 Oct 07 nicklas 1680           parameters a job were using when it was executed. When a job is 
3871 22 Oct 07 nicklas 1681           created we also store the parameter version number 
3871 22 Oct 07 nicklas 1682           (<property>JobData.parameterVersion</property>). This means that even if 
3871 22 Oct 07 nicklas 1683           someone changes the configuration later we will always know which 
3871 22 Oct 07 nicklas 1684           parameters the job used. 
3871 22 Oct 07 nicklas 1685         </para>
3871 22 Oct 07 nicklas 1686         
3871 22 Oct 07 nicklas 1687         <para>
3947 12 Nov 07 nicklas 1688           The <classname docapi="net.sf.basedb.core.data">PluginTypeData</classname> class is ued to group
3871 22 Oct 07 nicklas 1689           plug-ins that share some common functionality, by implementing
3871 22 Oct 07 nicklas 1690           additional (optional) interfaces. For example, the 
3947 12 Nov 07 nicklas 1691           <interfacename docapi="net.sf.basedb.core.plugin">AutoDetectingImporter</interfacename> should be implemented
3871 22 Oct 07 nicklas 1692           by import plug-ins that supports automatic detection of file formats.
3947 12 Nov 07 nicklas 1693           Another example is the <interfacename docapi="net.sf.basedb.core.plugin">AnalysisFilterPlugin</interfacename>
3871 22 Oct 07 nicklas 1694           interface which should be implemented by all analysis plug-ins that
3871 22 Oct 07 nicklas 1695           only filters data.
3871 22 Oct 07 nicklas 1696         </para>
3871 22 Oct 07 nicklas 1697
3871 22 Oct 07 nicklas 1698       </sect3>
3871 22 Oct 07 nicklas 1699       
3871 22 Oct 07 nicklas 1700       <sect3 id="data_api.plugins.jobs">
3871 22 Oct 07 nicklas 1701         <title>Jobs</title>
3871 22 Oct 07 nicklas 1702         
3871 22 Oct 07 nicklas 1703         <para>
3871 22 Oct 07 nicklas 1704           A job represents a single invokation of a plug-in to do some work.
3947 12 Nov 07 nicklas 1705           The <classname docapi="net.sf.basedb.core.data">JobData</classname> class holds information about this.
3871 22 Oct 07 nicklas 1706           A job is usuallu executed by a plug-in, but doesn't have to be. The
3871 22 Oct 07 nicklas 1707           <property>status</property> property holds the current state of a job.
3871 22 Oct 07 nicklas 1708         </para>
3871 22 Oct 07 nicklas 1709         
3871 22 Oct 07 nicklas 1710         <itemizedlist>
3871 22 Oct 07 nicklas 1711         <listitem>
3871 22 Oct 07 nicklas 1712           <para>
3871 22 Oct 07 nicklas 1713             UNCONFIGURED (status = 0): The job is not yet ready to be executed.
3871 22 Oct 07 nicklas 1714           </para>
3871 22 Oct 07 nicklas 1715         </listitem>
3871 22 Oct 07 nicklas 1716         <listitem>
3871 22 Oct 07 nicklas 1717           <para>
3871 22 Oct 07 nicklas 1718             WAITING (status = 1): The job is waiting to be executed.
3871 22 Oct 07 nicklas 1719           </para>
3871 22 Oct 07 nicklas 1720         </listitem>
3871 22 Oct 07 nicklas 1721         <listitem>
3871 22 Oct 07 nicklas 1722           <para>
3871 22 Oct 07 nicklas 1723             PREPARING (status = 5): The job is about to be executed but hasn't started yet.
3871 22 Oct 07 nicklas 1724           </para>
3871 22 Oct 07 nicklas 1725         </listitem>
3871 22 Oct 07 nicklas 1726         <listitem>
3871 22 Oct 07 nicklas 1727           <para>
3871 22 Oct 07 nicklas 1728             EXECUTING (status = 2): The job is currently executing.
3871 22 Oct 07 nicklas 1729           </para>
3871 22 Oct 07 nicklas 1730         </listitem>
3871 22 Oct 07 nicklas 1731         <listitem>
3871 22 Oct 07 nicklas 1732           <para>
5780 04 Oct 11 nicklas 1733             ABORTING (status = 6): The job is executing but an ABORT signal has been sent
5780 04 Oct 11 nicklas 1734             requesting it to abort and finish.
5780 04 Oct 11 nicklas 1735           </para>
5780 04 Oct 11 nicklas 1736         </listitem>
5780 04 Oct 11 nicklas 1737         <listitem>
5780 04 Oct 11 nicklas 1738           <para>
3871 22 Oct 07 nicklas 1739             DONE (status = 3): The job finished successfully.
3871 22 Oct 07 nicklas 1740           </para>
3871 22 Oct 07 nicklas 1741         </listitem>
3871 22 Oct 07 nicklas 1742         <listitem>
3871 22 Oct 07 nicklas 1743           <para>
3871 22 Oct 07 nicklas 1744             ERROR (status = 4): The job finished with an error.
3871 22 Oct 07 nicklas 1745           </para>
3871 22 Oct 07 nicklas 1746         </listitem>
3871 22 Oct 07 nicklas 1747         </itemizedlist>
3871 22 Oct 07 nicklas 1748       </sect3>
3871 22 Oct 07 nicklas 1749
3871 22 Oct 07 nicklas 1750       <sect3 id="data_api.plugins.agents">
3871 22 Oct 07 nicklas 1751         <title>Job agents</title>
3871 22 Oct 07 nicklas 1752         
3871 22 Oct 07 nicklas 1753         <para>
3871 22 Oct 07 nicklas 1754           A job agent is a program running on the same or a different server that 
3871 22 Oct 07 nicklas 1755           is regularly checking for jobs that are waiting to be executed. The
3947 12 Nov 07 nicklas 1756           <classname docapi="net.sf.basedb.core.data">JobAgentData</classname> holds information about a job agent
3947 12 Nov 07 nicklas 1757           and the <classname docapi="net.sf.basedb.core.data">JobAgentSettingsData</classname> links the agent
3871 22 Oct 07 nicklas 1758           with the plug-ins the agent is able to execute. The job agent will only 
5780 04 Oct 11 nicklas 1759           execute jobs that are owned by users or projects that the job agent has 
3871 22 Oct 07 nicklas 1760           been shared to with at least use permission. The <property>priorityBoost</property>
3871 22 Oct 07 nicklas 1761           property can be used to give specific plug-ins higher priority.
3871 22 Oct 07 nicklas 1762           Thus, for a job agent it is possible to:
3871 22 Oct 07 nicklas 1763         </para>
3871 22 Oct 07 nicklas 1764         
3871 22 Oct 07 nicklas 1765         <itemizedlist>
3871 22 Oct 07 nicklas 1766         <listitem>
3871 22 Oct 07 nicklas 1767           <para>
3871 22 Oct 07 nicklas 1768           Specify exactly which plug-ins it will execute. For example, it is possible
3871 22 Oct 07 nicklas 1769           to dedicate one agent to only run one plug-in.
3871 22 Oct 07 nicklas 1770           </para>
3871 22 Oct 07 nicklas 1771         </listitem>
3871 22 Oct 07 nicklas 1772         <listitem>
3871 22 Oct 07 nicklas 1773           <para>
3871 22 Oct 07 nicklas 1774           Give some plug-ins higher priority. For example a job agent that is mainly 
3871 22 Oct 07 nicklas 1775           used for importing data should give higher priority to all import plug-ins.
3871 22 Oct 07 nicklas 1776           Other types of jobs will have to wait until there are no more data to be 
3871 22 Oct 07 nicklas 1777           imported.
3871 22 Oct 07 nicklas 1778           </para>
3871 22 Oct 07 nicklas 1779         </listitem>
3871 22 Oct 07 nicklas 1780         <listitem>
3871 22 Oct 07 nicklas 1781           <para>
3871 22 Oct 07 nicklas 1782           Specify exactly which users/groups/projects that may use the agent. For 
3871 22 Oct 07 nicklas 1783           example, it is possible to dedicate one agent to only run jobs for a certain 
3871 22 Oct 07 nicklas 1784           project.
3871 22 Oct 07 nicklas 1785           </para>
3871 22 Oct 07 nicklas 1786         </listitem>
3871 22 Oct 07 nicklas 1787         </itemizedlist>
3871 22 Oct 07 nicklas 1788         
3871 22 Oct 07 nicklas 1789       </sect3>
3871 22 Oct 07 nicklas 1790
3871 22 Oct 07 nicklas 1791
3715 11 Sep 07 nicklas 1792     </sect2>
3715 11 Sep 07 nicklas 1793     
3715 11 Sep 07 nicklas 1794     <sect2 id="data_api.biomaterials">
5457 28 Oct 10 nicklas 1795       <title>Biomaterial LIMS</title>
3916 06 Nov 07 nicklas 1796       
3916 06 Nov 07 nicklas 1797         <figure id="data_api.figures.biomaterials">
5100 15 Sep 09 nicklas 1798           <title>Biomaterial LIMS</title>
3916 06 Nov 07 nicklas 1799           <screenshot>
3916 06 Nov 07 nicklas 1800             <mediaobject>
3916 06 Nov 07 nicklas 1801               <imageobject>
3916 06 Nov 07 nicklas 1802                 <imagedata 
3943 09 Nov 07 nicklas 1803                   align="center"
3916 06 Nov 07 nicklas 1804                   fileref="figures/uml/datalayer.biomaterials.png" format="PNG" />
3916 06 Nov 07 nicklas 1805               </imageobject>
3916 06 Nov 07 nicklas 1806             </mediaobject>
3916 06 Nov 07 nicklas 1807           </screenshot>
3916 06 Nov 07 nicklas 1808         </figure>
3916 06 Nov 07 nicklas 1809       
3916 06 Nov 07 nicklas 1810       <sect3 id="data_api.biomaterials.description">
5780 04 Oct 11 nicklas 1811         <title>Biomaterials</title>
3916 06 Nov 07 nicklas 1812         
3916 06 Nov 07 nicklas 1813         <para>
5780 04 Oct 11 nicklas 1814           There are three main types of biomaterials: <classname docapi="net.sf.basedb.core.data">BioSourceData</classname>, 
5780 04 Oct 11 nicklas 1815           <classname docapi="net.sf.basedb.core.data">SampleData</classname> and 
5780 04 Oct 11 nicklas 1816           <classname docapi="net.sf.basedb.core.data">ExtractData</classname>.
5780 04 Oct 11 nicklas 1817           All types of are derived from the base class <classname docapi="net.sf.basedb.core.data">BioMaterialData</classname>. 
3916 06 Nov 07 nicklas 1818           The reason for this is that they all share common functionality such as pooling 
3916 06 Nov 07 nicklas 1819           and events. By using a common base class we do not have to create duplicate 
3916 06 Nov 07 nicklas 1820           classes for keeping track of events and parents.
3916 06 Nov 07 nicklas 1821         </para>
3916 06 Nov 07 nicklas 1822         
3916 06 Nov 07 nicklas 1823         <para>
3947 12 Nov 07 nicklas 1824           The <classname docapi="net.sf.basedb.core.data">BioSourceData</classname> is the simplest of the biomaterials. 
3916 06 Nov 07 nicklas 1825           It cannot have parents and can't participate in events. It's only used as a 
3916 06 Nov 07 nicklas 1826           (non-required) parent for samples.
3916 06 Nov 07 nicklas 1827         </para>
3916 06 Nov 07 nicklas 1828         
3916 06 Nov 07 nicklas 1829         <para>
3947 12 Nov 07 nicklas 1830           The <classname docapi="net.sf.basedb.core.data">MeasuredBioMaterialData</classname> class is used as a base 
5780 04 Oct 11 nicklas 1831           class for the other biomaterial types. It introduces quantity 
3916 06 Nov 07 nicklas 1832           measurements and can store original and remaining quantities. They are 
3916 06 Nov 07 nicklas 1833           both optional. If an original quantity has been specified the core 
3916 06 Nov 07 nicklas 1834           automatically calculates the remaining quantity based on the events a 
3916 06 Nov 07 nicklas 1835           biomaterial participates in.
3916 06 Nov 07 nicklas 1836         </para>
3916 06 Nov 07 nicklas 1837         
3916 06 Nov 07 nicklas 1838         <para>
3916 06 Nov 07 nicklas 1839           All measured biomaterial have at least one event associated with them, 
5780 04 Oct 11 nicklas 1840           the <emphasis>creation event</emphasis>, which holds information about the creation of the 
3916 06 Nov 07 nicklas 1841           biomaterial. A measured biomaterial can be created in three ways:
3916 06 Nov 07 nicklas 1842         </para>
3916 06 Nov 07 nicklas 1843         
3916 06 Nov 07 nicklas 1844         <itemizedlist>
3916 06 Nov 07 nicklas 1845         <listitem>
3916 06 Nov 07 nicklas 1846           <para>
5780 04 Oct 11 nicklas 1847           From a single item of the same type or the parent type. Biosource is the parent type of 
5780 04 Oct 11 nicklas 1848           samples and sample is the parent type of extracts. The <property>parentType</property> 
5780 04 Oct 11 nicklas 1849           property must be set to the correct parent type and the <property>parent</property> property
5780 04 Oct 11 nicklas 1850           is set to point to the parent item. The parent information
5780 04 Oct 11 nicklas 1851           is also always duplicated in the <property>sources</property> collection of the <classname docapi="net.sf.basedb.core.data">BioMaterialEventData</classname>
3916 06 Nov 07 nicklas 1852           object representing the creation event. It is the responsibility of the 
3916 06 Nov 07 nicklas 1853           core to make sure that everything is properly synchronized and that 
3916 06 Nov 07 nicklas 1854           remaining quantities are calculated.
3916 06 Nov 07 nicklas 1855           </para>
3916 06 Nov 07 nicklas 1856         </listitem>
3916 06 Nov 07 nicklas 1857         
3916 06 Nov 07 nicklas 1858         <listitem>
3916 06 Nov 07 nicklas 1859           <para>
5780 04 Oct 11 nicklas 1860           From multiple items of the same type, i.e pooling.
5780 04 Oct 11 nicklas 1861           In this case the <property>parentType</property> property is set, but
5780 04 Oct 11 nicklas 1862           the <property>parent</property> property is null. All source 
3916 06 Nov 07 nicklas 1863           biomaterials are contained in the <property>sources</property> collection. 
3916 06 Nov 07 nicklas 1864           The core is still responsible for keeping everything synchronized and to
3916 06 Nov 07 nicklas 1865           update remaining quantities.
3916 06 Nov 07 nicklas 1866           </para>
3916 06 Nov 07 nicklas 1867         </listitem>
3916 06 Nov 07 nicklas 1868         
3916 06 Nov 07 nicklas 1869         <listitem>
3916 06 Nov 07 nicklas 1870           <para>
5780 04 Oct 11 nicklas 1871           As a standalone biomaterial without parents. The <property>parentType</property>
5780 04 Oct 11 nicklas 1872           property should be null, as should the <property>parent</property> property
5780 04 Oct 11 nicklas 1873           and the <property>sources</property> collection.
3916 06 Nov 07 nicklas 1874           </para>
3916 06 Nov 07 nicklas 1875         </listitem>
3916 06 Nov 07 nicklas 1876         </itemizedlist>
3916 06 Nov 07 nicklas 1877
3916 06 Nov 07 nicklas 1878       </sect3>
3916 06 Nov 07 nicklas 1879       
5457 28 Oct 10 nicklas 1880       <sect3 id="data_api.biomaterials.plates">
5457 28 Oct 10 nicklas 1881         <title>Bioplates and plate types</title>
5457 28 Oct 10 nicklas 1882         
5457 28 Oct 10 nicklas 1883         <para>
5457 28 Oct 10 nicklas 1884           Biomaterial (except biosource) may optionally be placed on <classname 
5457 28 Oct 10 nicklas 1885           docapi="net.sf.basedb.core.data">BioPlateData</classname>:s. A bioplate is something
5457 28 Oct 10 nicklas 1886           that collects multiple biomaterial as a unit. A bioplate typically has a
5457 28 Oct 10 nicklas 1887           <classname docapi="net.sf.basedb.core.data">PlateGeometryData</classname> that
5457 28 Oct 10 nicklas 1888           determines the number of locations on the plate (<classname docapi="net.sf.basedb.core.data">BioWellData</classname>).
5457 28 Oct 10 nicklas 1889           A single well can hold a single biomaterial at a time.
5457 28 Oct 10 nicklas 1890         </para>
5457 28 Oct 10 nicklas 1891         
5457 28 Oct 10 nicklas 1892         <para>
5457 28 Oct 10 nicklas 1893           The bioplate must be of a specific <classname docapi="net.sf.basedb.core.data">BioPlateTypeData</classname>.
5457 28 Oct 10 nicklas 1894           The type can be used to put limitations on how the plate can be used. For example,
5457 28 Oct 10 nicklas 1895           it can be limited to a single type of biomaterial. It is also possible to lock wells
5457 28 Oct 10 nicklas 1896           so that the biomaterial in them can't be changed. Supported lock modes are:
5457 28 Oct 10 nicklas 1897         </para>
5457 28 Oct 10 nicklas 1898         
5457 28 Oct 10 nicklas 1899         <itemizedlist>
5457 28 Oct 10 nicklas 1900         <listitem>
5457 28 Oct 10 nicklas 1901           <para>
5457 28 Oct 10 nicklas 1902           <emphasis>Unlocked</emphasis>: Wells are unlocked and the biomaterial may be changed
5457 28 Oct 10 nicklas 1903           any number of times.
5457 28 Oct 10 nicklas 1904           </para>
5457 28 Oct 10 nicklas 1905         </listitem>
5457 28 Oct 10 nicklas 1906         <listitem>
5457 28 Oct 10 nicklas 1907           <para>
5457 28 Oct 10 nicklas 1908           <emphasis>Locked-after-move</emphasis>: The well is locked after it has been used one 
5457 28 Oct 10 nicklas 1909           time and the biomaterial that was put in it has been moved to another plate. 
5457 28 Oct 10 nicklas 1910           </para>
5457 28 Oct 10 nicklas 1911         </listitem>
5457 28 Oct 10 nicklas 1912         <listitem>
5457 28 Oct 10 nicklas 1913           <para>
5457 28 Oct 10 nicklas 1914           <emphasis>Locked-after-add</emphasis>: The well is locked after biomaterial has been
5457 28 Oct 10 nicklas 1915           put into it. It is not possible to remove the biomaterial.
5457 28 Oct 10 nicklas 1916           </para>
5457 28 Oct 10 nicklas 1917         </listitem>
5457 28 Oct 10 nicklas 1918         <listitem>
5457 28 Oct 10 nicklas 1919           <para>
5457 28 Oct 10 nicklas 1920           <emphasis>Locked-after-create</emphasis>: The well is locked once it has been created.
5457 28 Oct 10 nicklas 1921           Biomaterial must be put into wells before the plate is saved to the database.
5457 28 Oct 10 nicklas 1922           </para>
5457 28 Oct 10 nicklas 1923         </listitem>
5457 28 Oct 10 nicklas 1924         </itemizedlist>
5457 28 Oct 10 nicklas 1925         
5457 28 Oct 10 nicklas 1926       </sect3>
5457 28 Oct 10 nicklas 1927   
5525 06 Dec 10 nicklas 1928       <sect3 id="data_api.biomaterials.events">
5525 06 Dec 10 nicklas 1929         <title>Biomaterial and plate events</title>
5525 06 Dec 10 nicklas 1930         
5525 06 Dec 10 nicklas 1931         <para>
5525 06 Dec 10 nicklas 1932           An event represents something that happened to one or more biomaterials, for example 
5525 06 Dec 10 nicklas 1933           the creation of another biomaterial. The <classname docapi="net.sf.basedb.core.data">BioMaterialEventData</classname>
5525 06 Dec 10 nicklas 1934           holds information about entry and event dates, protocols used, the user who is 
5525 06 Dec 10 nicklas 1935           responsible, etc. There are three types of events represented by the <property>eventType</property>
5525 06 Dec 10 nicklas 1936           property.
5525 06 Dec 10 nicklas 1937         </para>
5525 06 Dec 10 nicklas 1938         
5525 06 Dec 10 nicklas 1939         <orderedlist>
5525 06 Dec 10 nicklas 1940         <listitem>
5525 06 Dec 10 nicklas 1941           <para>
5525 06 Dec 10 nicklas 1942           <emphasis>Creation event</emphasis>: This event represents the creation of a (measured) 
5525 06 Dec 10 nicklas 1943           biomaterial. The <property>sources</property> collection contains 
5525 06 Dec 10 nicklas 1944           information about the biomaterials that were used to create the new 
5780 04 Oct 11 nicklas 1945           biomaterial. All sources must be of the same type. There can only be one 
5780 04 Oct 11 nicklas 1946           source of the parent type. These rules are maintained by the core.
5525 06 Dec 10 nicklas 1947           </para>
5525 06 Dec 10 nicklas 1948         </listitem>
5525 06 Dec 10 nicklas 1949         
5525 06 Dec 10 nicklas 1950         <listitem>
5525 06 Dec 10 nicklas 1951           <para>
5780 04 Oct 11 nicklas 1952           <emphasis>Bioassay event</emphasis>: This event represents the creation 
5780 04 Oct 11 nicklas 1953           of a bioassay. This event type is needed because we want to keep track
5780 04 Oct 11 nicklas 1954           of quantities for extracts. This event has a <classname docapi="net.sf.basedb.core.data">PhysicalBioAssayData</classname> 
5780 04 Oct 11 nicklas 1955           as a product instead of a biomaterial. The sources collection can only contain 
5780 04 Oct 11 nicklas 1956           extracts. If the bioassay can hold extracts in multiple positions the
5780 04 Oct 11 nicklas 1957           <property>position</property> property in <classname docapi="net.sf.basedb.core.data">BioMaterialEventSourceData</classname> 
5780 04 Oct 11 nicklas 1958           can be used to track which extract that was put in each position. It is allowed
5780 04 Oct 11 nicklas 1959           to put multiple extracts in the same position, but then the usually need
5780 04 Oct 11 nicklas 1960           to use different <classname docapi="net.sf.basedb.core.data">TagData</classname> 
5780 04 Oct 11 nicklas 1961           items. However, this is not enforced by the core.
5525 06 Dec 10 nicklas 1962           </para>
5525 06 Dec 10 nicklas 1963         </listitem>
5525 06 Dec 10 nicklas 1964
5525 06 Dec 10 nicklas 1965         <listitem>
5525 06 Dec 10 nicklas 1966           <para>
5525 06 Dec 10 nicklas 1967           <emphasis>Other event</emphasis>: This event represents some other important
5525 06 Dec 10 nicklas 1968           information about a single biomaterial that affected the remaining quantity. 
5525 06 Dec 10 nicklas 1969           This event type doesn't have any sources.
5525 06 Dec 10 nicklas 1970           </para>
5525 06 Dec 10 nicklas 1971         </listitem>
5525 06 Dec 10 nicklas 1972         </orderedlist>
5525 06 Dec 10 nicklas 1973         
5525 06 Dec 10 nicklas 1974         <para>
5525 06 Dec 10 nicklas 1975           It is also possible to register events that applies to one or more
5525 06 Dec 10 nicklas 1976           bioplates using the <classname docapi="net.sf.basedb.core.data">BioPlateEventData</classname>
5525 06 Dec 10 nicklas 1977           class. The <classname docapi="net.sf.basedb.core.data">BioPlateEventParticipantData</classname>
5525 06 Dec 10 nicklas 1978           class holds information about each plate that is part of the event. The <property>role</property>
5525 06 Dec 10 nicklas 1979           property is a textual description of what happened to the plate. Eg. a move event, may have one
5525 06 Dec 10 nicklas 1980           <emphasis>source</emphasis> plate and one <emphasis>destination</emphasis> plate. It is
5525 06 Dec 10 nicklas 1981           recommended (but not required) that all biomaterial that are affected by the plate event
5525 06 Dec 10 nicklas 1982           are linked via a <code>BioMaterialEventData</code> to a <code>BioPlateEventParticipantData</code>. 
5525 06 Dec 10 nicklas 1983           This will make it easier to keep track of the history of individual biomaterial items.
5525 06 Dec 10 nicklas 1984           Biomaterial events that are linked in this way are also automatically updated if the
5525 06 Dec 10 nicklas 1985           bioplate event is modified (eg. selecting a protocol, event date, etc.).
5525 06 Dec 10 nicklas 1986         </para>
5525 06 Dec 10 nicklas 1987         
5525 06 Dec 10 nicklas 1988       </sect3>  
3715 11 Sep 07 nicklas 1989     </sect2>
3715 11 Sep 07 nicklas 1990
3715 11 Sep 07 nicklas 1991     <sect2 id="data_api.plates">
3715 11 Sep 07 nicklas 1992       <title>Array LIMS - plates</title>
3926 07 Nov 07 nicklas 1993
3926 07 Nov 07 nicklas 1994         <figure id="data_api.figures.plates">
3926 07 Nov 07 nicklas 1995           <title>Array LIMS - plates</title>
3926 07 Nov 07 nicklas 1996           <screenshot>
3926 07 Nov 07 nicklas 1997             <mediaobject>
3926 07 Nov 07 nicklas 1998               <imageobject>
3926 07 Nov 07 nicklas 1999                 <imagedata 
3943 09 Nov 07 nicklas 2000                   align="center"
3943 09 Nov 07 nicklas 2001                   scalefit="1" width="100%"
3926 07 Nov 07 nicklas 2002                   fileref="figures/uml/datalayer.plates.png" format="PNG" />
3926 07 Nov 07 nicklas 2003               </imageobject>
3926 07 Nov 07 nicklas 2004             </mediaobject>
3926 07 Nov 07 nicklas 2005           </screenshot>
3926 07 Nov 07 nicklas 2006         </figure>
3926 07 Nov 07 nicklas 2007
3942 08 Nov 07 nicklas 2008       <sect3 id="data_api.plates.description">
3942 08 Nov 07 nicklas 2009         <title>Plates</title>
3942 08 Nov 07 nicklas 2010         
3942 08 Nov 07 nicklas 2011         <para>
3947 12 Nov 07 nicklas 2012           The <classname docapi="net.sf.basedb.core.data">PlateData</classname> is the main class holding information 
3947 12 Nov 07 nicklas 2013           about a single plate. The associated <classname docapi="net.sf.basedb.core.data">PlateGeometryData</classname>
3942 08 Nov 07 nicklas 2014           defines how many rows and columns there are on a plate. Since this 
3942 08 Nov 07 nicklas 2015           information is used to create wells, and for various other checks it is 
3942 08 Nov 07 nicklas 2016           not possible to change the number of rows or columns once a geometry has 
3942 08 Nov 07 nicklas 2017           been created. 
3942 08 Nov 07 nicklas 2018         </para>
3942 08 Nov 07 nicklas 2019           
3942 08 Nov 07 nicklas 2020         <para>
3947 12 Nov 07 nicklas 2021           All plates must have a <classname docapi="net.sf.basedb.core.data">PlateTypeData</classname> which defines 
3942 08 Nov 07 nicklas 2022           the geometry and a set of event types (see below).
3942 08 Nov 07 nicklas 2023         </para>
3942 08 Nov 07 nicklas 2024         
3942 08 Nov 07 nicklas 2025         <para>
3942 08 Nov 07 nicklas 2026           If the destroyed flag of a plate is set it is not allowed to use the 
3942 08 Nov 07 nicklas 2027           plate for a plate mapping or to create array designs. However, it 
3942 08 Nov 07 nicklas 2028           is possible to change the flag to not destroyed.
3942 08 Nov 07 nicklas 2029         </para>
3942 08 Nov 07 nicklas 2030
3942 08 Nov 07 nicklas 2031         <para>
3942 08 Nov 07 nicklas 2032           The barcode is intended to be used as an external identifier of the plate. 
3942 08 Nov 07 nicklas 2033           But, the core doesn't care about the value or if it is unique or not. 
3942 08 Nov 07 nicklas 2034         </para>
3942 08 Nov 07 nicklas 2035       </sect3>
3942 08 Nov 07 nicklas 2036       
3942 08 Nov 07 nicklas 2037       <sect3 id="data_api.plates.events">
3942 08 Nov 07 nicklas 2038         <title>Plate events</title>
3942 08 Nov 07 nicklas 2039
3942 08 Nov 07 nicklas 2040         <para>
3947 12 Nov 07 nicklas 2041           The plate type defines a set of <classname docapi="net.sf.basedb.core.data">PlateEventTypeData</classname>
3942 08 Nov 07 nicklas 2042           objects, each one represening a particular event a plate of this type
3942 08 Nov 07 nicklas 2043           usually goes trough. For a plate of a certain type, it is possible to 
3942 08 Nov 07 nicklas 2044           attach exactly one event of each event type. The event type defines an 
3942 08 Nov 07 nicklas 2045           optional protocol type, which can be used by client applications to 
3942 08 Nov 07 nicklas 2046           filter a list of protocols for the event. The core doesn't check that 
3942 08 Nov 07 nicklas 2047           the selected protocol for an event is of the same protocol type as 
3942 08 Nov 07 nicklas 2048           defined by the event type.
3942 08 Nov 07 nicklas 2049         </para>
3942 08 Nov 07 nicklas 2050
3942 08 Nov 07 nicklas 2051         <para>
3942 08 Nov 07 nicklas 2052           The ordinal value can be used as a hint to client applications in 
3942 08 Nov 07 nicklas 2053           which order the events actually are performed in the lab. The core doesn't 
3942 08 Nov 07 nicklas 2054           care about this value or if several event types have the same value. 
3942 08 Nov 07 nicklas 2055         </para>
3942 08 Nov 07 nicklas 2056       </sect3>
3942 08 Nov 07 nicklas 2057
3942 08 Nov 07 nicklas 2058       <sect3 id="data_api.plates.mappings">
3942 08 Nov 07 nicklas 2059         <title>Plate mappings</title>
3942 08 Nov 07 nicklas 2060         
3942 08 Nov 07 nicklas 2061         <para>
3942 08 Nov 07 nicklas 2062           A plate can be created either from scratch, with the help of the information
3947 12 Nov 07 nicklas 2063           in a <classname docapi="net.sf.basedb.core.data">PlateMappingData</classname>, from a set of parent plates.
3942 08 Nov 07 nicklas 2064           In the first case it is possible to specify a reporter for each well on the 
3942 08 Nov 07 nicklas 2065           plate. In the second case the mapping code creates all the wells and links 
3942 08 Nov 07 nicklas 2066           them to the parent wells on the parent plates. Once the plate has been saved
3942 08 Nov 07 nicklas 2067           to the database, the wells cannot be modified (because they are used 
3942 08 Nov 07 nicklas 2068           downstream for various validation, etc.)
3942 08 Nov 07 nicklas 2069         </para>
3942 08 Nov 07 nicklas 2070         
3942 08 Nov 07 nicklas 2071         <para>
3942 08 Nov 07 nicklas 2072           The details in a plate mapping are simply coordinates that for each
3942 08 Nov 07 nicklas 2073           destination plate, row and column define a source plate, row and column.
3942 08 Nov 07 nicklas 2074           It is possible for a single source well to be mapped to multiple destination
3942 08 Nov 07 nicklas 2075           wells, but for each destination well only a single source well can be 
3942 08 Nov 07 nicklas 2076           used.
3942 08 Nov 07 nicklas 2077         </para>
3942 08 Nov 07 nicklas 2078         
3942 08 Nov 07 nicklas 2079       </sect3>
3942 08 Nov 07 nicklas 2080
3715 11 Sep 07 nicklas 2081     </sect2>
3715 11 Sep 07 nicklas 2082
3715 11 Sep 07 nicklas 2083     <sect2 id="data_api.arrays">
3715 11 Sep 07 nicklas 2084       <title>Array LIMS - arrays</title>
3926 07 Nov 07 nicklas 2085       
3926 07 Nov 07 nicklas 2086         <figure id="data_api.figures.arrays">
3926 07 Nov 07 nicklas 2087           <title>Array LIMS - arrays</title>
3926 07 Nov 07 nicklas 2088           <screenshot>
3926 07 Nov 07 nicklas 2089             <mediaobject>
3926 07 Nov 07 nicklas 2090               <imageobject>
3926 07 Nov 07 nicklas 2091                 <imagedata 
3943 09 Nov 07 nicklas 2092                   align="center"
3926 07 Nov 07 nicklas 2093                   fileref="figures/uml/datalayer.arrays.png" format="PNG" />
3926 07 Nov 07 nicklas 2094               </imageobject>
3926 07 Nov 07 nicklas 2095             </mediaobject>
3926 07 Nov 07 nicklas 2096           </screenshot>
3926 07 Nov 07 nicklas 2097         </figure>
3926 07 Nov 07 nicklas 2098       
3942 08 Nov 07 nicklas 2099       <sect3 id="data_api.arrays.designs">
3942 08 Nov 07 nicklas 2100         <title>Array designs</title>
3942 08 Nov 07 nicklas 2101         
3942 08 Nov 07 nicklas 2102         <para>
3947 12 Nov 07 nicklas 2103           Array designs are stored in <classname docapi="net.sf.basedb.core.data">ArrayDesignData</classname> objects
3942 08 Nov 07 nicklas 2104           and can be created either as standalone designs or
3942 08 Nov 07 nicklas 2105           from plates. In the first case the features on an array design
3942 08 Nov 07 nicklas 2106           are described by a reporter map. A reporter map is a file
4093 18 Jan 08 enell 2107           that maps a coordinate (block, meta-grid, row, column), 
4093 18 Jan 08 enell 2108           position or an external ID on an array design to a 
4093 18 Jan 08 enell 2109           reporter. Which method to use is given by the 
4093 18 Jan 08 enell 2110           <property>ArrayDesign.featureIdentificationMethod</property> property. 
3942 08 Nov 07 nicklas 2111           The coordinate system on an array design is divided into blocks.
3942 08 Nov 07 nicklas 2112           Each block can be identified either by a <property>blockNumber</property>
3942 08 Nov 07 nicklas 2113           or by meta coordinates. This information is stored in
3947 12 Nov 07 nicklas 2114           <classname docapi="net.sf.basedb.core.data">ArrayDesignBlockData</classname> items. Each block
3947 12 Nov 07 nicklas 2115           contains several <classname docapi="net.sf.basedb.core.data">FeatureData</classname> items, each
3942 08 Nov 07 nicklas 2116           one identified by a row and column coordinate. Platforms that doesn't
4093 18 Jan 08 enell 2117           divide the array design into blocks or doesn't use the coordinate system at all
4093 18 Jan 08 enell 2118           must still create a single super-block that holds all features. 
3942 08 Nov 07 nicklas 2119         </para>
3942 08 Nov 07 nicklas 2120         
3942 08 Nov 07 nicklas 2121         <para>
3942 08 Nov 07 nicklas 2122           Array designs that are created from plates use a print map file
3942 08 Nov 07 nicklas 2123           instead of a reporter map. A print map is similar to a plate mapping
3942 08 Nov 07 nicklas 2124           but maps features (instead of wells) to wells. The file should
3942 08 Nov 07 nicklas 2125           specifify which plate and well a feature is created from. Reporter
3942 08 Nov 07 nicklas 2126           information will automatically be copied by BASE from the well.
3942 08 Nov 07 nicklas 2127         </para>
3942 08 Nov 07 nicklas 2128         
3942 08 Nov 07 nicklas 2129         <para>
3942 08 Nov 07 nicklas 2130           It is also possible to skip the importing of features into the 
3942 08 Nov 07 nicklas 2131           database and just keep the data in the orginal files instead.
3942 08 Nov 07 nicklas 2132           This is typically done for Affymetrix CDF files.
3942 08 Nov 07 nicklas 2133         </para>
3942 08 Nov 07 nicklas 2134         
3942 08 Nov 07 nicklas 2135       </sect3>
3926 07 Nov 07 nicklas 2136       
3942 08 Nov 07 nicklas 2137       <sect3 id="data_api.arrays.slides">
3942 08 Nov 07 nicklas 2138         <title>Array slides</title>
3942 08 Nov 07 nicklas 2139         
3942 08 Nov 07 nicklas 2140         <para>
3947 12 Nov 07 nicklas 2141           The <classname docapi="net.sf.basedb.core.data">ArraySlideData</classname> represents a single
3942 08 Nov 07 nicklas 2142           array. Arrays are usually printed several hundreds in a batch, 
3947 12 Nov 07 nicklas 2143           represented by a <classname docapi="net.sf.basedb.core.data">ArrayBatchData</classname> item.
3942 08 Nov 07 nicklas 2144           The <property>batchIndex</property> is the ordinal number of the
3942 08 Nov 07 nicklas 2145           array in the batch. The <property>barcode</property> can be used
3942 08 Nov 07 nicklas 2146           as a means for external programs to identify the array. BASE doesn't
3942 08 Nov 07 nicklas 2147           care if a value is given or if they are unique or not. If the
3942 08 Nov 07 nicklas 2148           <property>destroyed</property> flag is set it prevents a slide from
3942 08 Nov 07 nicklas 2149           beeing used by a hybridization.
3942 08 Nov 07 nicklas 2150         </para>
3942 08 Nov 07 nicklas 2151
3942 08 Nov 07 nicklas 2152       </sect3>
3715 11 Sep 07 nicklas 2153     </sect2>
3715 11 Sep 07 nicklas 2154
5780 04 Oct 11 nicklas 2155     <sect2 id="data_api.bioassays">
5780 04 Oct 11 nicklas 2156       <title>Bioassays and raw data</title>
3918 06 Nov 07 nicklas 2157       
3918 06 Nov 07 nicklas 2158         <figure id="data_api.figures.rawdata">
5780 04 Oct 11 nicklas 2159           <title>Bioassays and raw data</title>
3918 06 Nov 07 nicklas 2160           <screenshot>
3918 06 Nov 07 nicklas 2161             <mediaobject>
3918 06 Nov 07 nicklas 2162               <imageobject>
3918 06 Nov 07 nicklas 2163                 <imagedata 
3943 09 Nov 07 nicklas 2164                   align="center"
3943 09 Nov 07 nicklas 2165                   scalefit="1" width="100%"
5780 04 Oct 11 nicklas 2166                   fileref="figures/uml/datalayer.bioassays.png" format="PNG" />
3918 06 Nov 07 nicklas 2167               </imageobject>
3918 06 Nov 07 nicklas 2168             </mediaobject>
3918 06 Nov 07 nicklas 2169           </screenshot>
3918 06 Nov 07 nicklas 2170         </figure>
3918 06 Nov 07 nicklas 2171       
5780 04 Oct 11 nicklas 2172       <sect3 id="data_api.bioassays.physical">
5780 04 Oct 11 nicklas 2173         <title>Physical bioassays</title>
3926 07 Nov 07 nicklas 2174         
3926 07 Nov 07 nicklas 2175         <para>
5780 04 Oct 11 nicklas 2176         A <classname docapi="net.sf.basedb.core.data">PhysicalBioAssayData</classname>
5780 04 Oct 11 nicklas 2177         item connect the array slides from the Array LIMS part
5780 04 Oct 11 nicklas 2178         with extracts from the biomaterials part. The <property>creationEvent</property>
5780 04 Oct 11 nicklas 2179         is used to register which extracts that were used on the bioassay.
3926 07 Nov 07 nicklas 2180         The relation to slides is a one-to-one relation. A slide can only be used on 
5780 04 Oct 11 nicklas 2181         a single physical bioassay and a bioassay can only use a single slide. The relation
3926 07 Nov 07 nicklas 2182         is optional from both sides.
3926 07 Nov 07 nicklas 2183         </para>
3926 07 Nov 07 nicklas 2184
3926 07 Nov 07 nicklas 2185         <para>
5780 04 Oct 11 nicklas 2186         Further processing of the bioassay is registered as a series
5780 04 Oct 11 nicklas 2187         of <classname docapi="net.sf.basedb.core.data">DerivedBioAssayData</classname>
5780 04 Oct 11 nicklas 2188         items. For microarray experiments the first step is typically a scanning
5780 04 Oct 11 nicklas 2189         of the hybridization. Information about the software/hardware and protocol
5780 04 Oct 11 nicklas 2190         used can be registered. Any data files generated by the process can be
5780 04 Oct 11 nicklas 2191         registered with the <classname docapi="net.sf.basedb.core.data">FileSetData</classname>
5780 04 Oct 11 nicklas 2192         item. If more than one processsing step is required child derived
5780 04 Oct 11 nicklas 2193         bioassays can be created that descrive each additional step.  
3926 07 Nov 07 nicklas 2194         </para>
3926 07 Nov 07 nicklas 2195         
5780 04 Oct 11 nicklas 2196         <para>
5780 04 Oct 11 nicklas 2197         If the root physical bioassay has multiple extracts in multiple positions, the
5780 04 Oct 11 nicklas 2198         <property>extract</property> property of a derived bioassay is used to link
5780 04 Oct 11 nicklas 2199         with the extract that the specific derived bioassay represents. If the
5780 04 Oct 11 nicklas 2200         link is null the derived bioassay represents all extracts on the
5780 04 Oct 11 nicklas 2201         physical bioassay.
5780 04 Oct 11 nicklas 2202         </para>
5780 04 Oct 11 nicklas 2203         
3926 07 Nov 07 nicklas 2204       </sect3>
3918 06 Nov 07 nicklas 2205       
5780 04 Oct 11 nicklas 2206       <sect3 id="data_api.bioassays.rawdata">
3926 07 Nov 07 nicklas 2207         <title>Raw data</title>
3926 07 Nov 07 nicklas 2208         
3926 07 Nov 07 nicklas 2209         <para>
5780 04 Oct 11 nicklas 2210         A <classname docapi="net.sf.basedb.core.data">RawBioAssayData</classname> object 
5780 04 Oct 11 nicklas 2211         represents the raw data that is produced by analysing the data from the physical
5780 04 Oct 11 nicklas 2212         bioassay. You may register which software that was used, the
3926 07 Nov 07 nicklas 2213         protocol and any parameters (through the annotation system).
3926 07 Nov 07 nicklas 2214         </para>
3926 07 Nov 07 nicklas 2215
3926 07 Nov 07 nicklas 2216         <para>
3926 07 Nov 07 nicklas 2217         Files with the analysed data values can be attached to the 
5780 04 Oct 11 nicklas 2218         associated <classname docapi="net.sf.basedb.core.data">FileSetData</classname> object. 
5780 04 Oct 11 nicklas 2219         The platform and, optionally, the variant has information about the file types
3926 07 Nov 07 nicklas 2220         that can be used for that platform. If the platform file types support 
3926 07 Nov 07 nicklas 2221         metadata extraction, headers, the number of spots, and other 
3926 07 Nov 07 nicklas 2222         information may be automatically extracted from the raw data file(s).
3926 07 Nov 07 nicklas 2223         </para>
3926 07 Nov 07 nicklas 2224         
3926 07 Nov 07 nicklas 2225         <para>
3926 07 Nov 07 nicklas 2226         If the platform support it, raw data can also be imported into the database.
3947 12 Nov 07 nicklas 2227         This is handled by batchers and <classname docapi="net.sf.basedb.core.data">RawData</classname> objects.
3947 12 Nov 07 nicklas 2228         Which table to store the data in depends on the <property>rawDataType</property>
3926 07 Nov 07 nicklas 2229         property. The properties shown for the <classname>RawData</classname> class
3926 07 Nov 07 nicklas 2230         in the diagram are the mandatory properties. Each raw data type defines additional
3926 07 Nov 07 nicklas 2231         properties that are specific to that raw data type.
3926 07 Nov 07 nicklas 2232         </para>
3926 07 Nov 07 nicklas 2233         
3926 07 Nov 07 nicklas 2234       </sect3>
3926 07 Nov 07 nicklas 2235         
3715 11 Sep 07 nicklas 2236     </sect2>
3715 11 Sep 07 nicklas 2237
3715 11 Sep 07 nicklas 2238     <sect2 id="data_api.experiments">
3715 11 Sep 07 nicklas 2239       <title>Experiments and analysis</title>
3943 09 Nov 07 nicklas 2240       
3943 09 Nov 07 nicklas 2241       
3943 09 Nov 07 nicklas 2242         <figure id="data_api.figures.experiments">
3943 09 Nov 07 nicklas 2243           <title>Experiments</title>
3943 09 Nov 07 nicklas 2244           <screenshot>
3943 09 Nov 07 nicklas 2245             <mediaobject>
3943 09 Nov 07 nicklas 2246               <imageobject>
3943 09 Nov 07 nicklas 2247                 <imagedata 
3943 09 Nov 07 nicklas 2248                   align="center"
3943 09 Nov 07 nicklas 2249                   scalefit="1" width="75%"
3943 09 Nov 07 nicklas 2250                   fileref="figures/uml/datalayer.experiments.png" format="PNG" />
3943 09 Nov 07 nicklas 2251               </imageobject>
3943 09 Nov 07 nicklas 2252             </mediaobject>
3943 09 Nov 07 nicklas 2253           </screenshot>
3943 09 Nov 07 nicklas 2254         </figure>
3943 09 Nov 07 nicklas 2255       
3943 09 Nov 07 nicklas 2256       <sect3 id="data_api.experiments.description">
3943 09 Nov 07 nicklas 2257         <title>Experiments</title>
3943 09 Nov 07 nicklas 2258         
3943 09 Nov 07 nicklas 2259         <para>
3943 09 Nov 07 nicklas 2260           The <classname docapi="net.sf.basedb.core.data">ExperimentData</classname> 
3943 09 Nov 07 nicklas 2261           class is used to collect information about a single experiment. It 
3943 09 Nov 07 nicklas 2262           links to any number of <classname docapi="net.sf.basedb.core.data">RawBioAssayData</classname>
3943 09 Nov 07 nicklas 2263           items, which must all be of the same <classname 
3943 09 Nov 07 nicklas 2264           docapi="net.sf.basedb.core">RawDataType</classname>.
3943 09 Nov 07 nicklas 2265         </para>
3943 09 Nov 07 nicklas 2266         
3943 09 Nov 07 nicklas 2267         <para>
3943 09 Nov 07 nicklas 2268           Annotation types that are needed in the analysis must connected to
3943 09 Nov 07 nicklas 2269           the experiment as experimental factors and the annotation values should 
3943 09 Nov 07 nicklas 2270           be set on or inherited by each raw bioassay that is part of the 
3943 09 Nov 07 nicklas 2271           experiment.
3943 09 Nov 07 nicklas 2272         </para>
3943 09 Nov 07 nicklas 2273         
3943 09 Nov 07 nicklas 2274         <para>
3943 09 Nov 07 nicklas 2275           The directory connected to the experiment is the default directory
3943 09 Nov 07 nicklas 2276           where plugins that generate files should store them.
3943 09 Nov 07 nicklas 2277         </para>
3943 09 Nov 07 nicklas 2278       </sect3>
3943 09 Nov 07 nicklas 2279             
3943 09 Nov 07 nicklas 2280       <sect3 id="data_api.experiments.bioassays">
3943 09 Nov 07 nicklas 2281         <title>Bioassay sets, bioassays and transformations</title>
3943 09 Nov 07 nicklas 2282         
3943 09 Nov 07 nicklas 2283         <para>
3943 09 Nov 07 nicklas 2284           Each line of analysis starts with the creation of a <emphasis>root</emphasis>
3943 09 Nov 07 nicklas 2285           <classname docapi="net.sf.basedb.core.data">BioAssaySetData</classname>, 
3943 09 Nov 07 nicklas 2286           which holds the intensities calculated from the raw data. 
3943 09 Nov 07 nicklas 2287           A bioassayset can hold one intensity for each channel. The number of 
3943 09 Nov 07 nicklas 2288           channels is defined by the raw data type. For each raw bioassay used a 
3943 09 Nov 07 nicklas 2289           <classname docapi="net.sf.basedb.core.data">BioAssayData</classname>
3943 09 Nov 07 nicklas 2290           is created.
3943 09 Nov 07 nicklas 2291         </para>
3943 09 Nov 07 nicklas 2292         
3943 09 Nov 07 nicklas 2293         <para>
3943 09 Nov 07 nicklas 2294           Information about the process that calculated the intensities are 
3943 09 Nov 07 nicklas 2295           stored in a <classname docapi="net.sf.basedb.core.data">TransformationData</classname>
3943 09 Nov 07 nicklas 2296           object. The root transformation links with the raw bioassays that are used 
3943 09 Nov 07 nicklas 2297           in this line of analysis and to a <classname 
3943 09 Nov 07 nicklas 2298           docapi="net.sf.basedb.core.data">JobData</classname> which has information
3943 09 Nov 07 nicklas 2299           about which plug-in and parameters that was used in the calculation.
3943 09 Nov 07 nicklas 2300         </para>
3943 09 Nov 07 nicklas 2301       
3943 09 Nov 07 nicklas 2302         <para>
3943 09 Nov 07 nicklas 2303           Once the root bioassayset has been created it is possible to 
3943 09 Nov 07 nicklas 2304           again apply a transformation to it. This time the transformation
3943 09 Nov 07 nicklas 2305           links to a single source bioassayset instead of the raw bioassays. 
3943 09 Nov 07 nicklas 2306           As before, it still links to a job with information about the plug-in and
3943 09 Nov 07 nicklas 2307           parameters that does the actual work. The transformation must make sure 
3943 09 Nov 07 nicklas 2308           that new bioassays are created and linked to the bioassays in the 
3943 09 Nov 07 nicklas 2309           source bioassayset. This above process may be repeated as many times 
3943 09 Nov 07 nicklas 2310           as needed.
3943 09 Nov 07 nicklas 2311         </para>
3943 09 Nov 07 nicklas 2312         
3943 09 Nov 07 nicklas 2313         <para>
3943 09 Nov 07 nicklas 2314           Data to a bioassay set can only be added to it before it has been
3943 09 Nov 07 nicklas 2315           committed to the database. Once the transaction has been committed
3943 09 Nov 07 nicklas 2316           it is no longed possible to add more data or to modify existing
3943 09 Nov 07 nicklas 2317           data.
3943 09 Nov 07 nicklas 2318         </para>
3943 09 Nov 07 nicklas 2319       
3943 09 Nov 07 nicklas 2320       </sect3>
3943 09 Nov 07 nicklas 2321
3943 09 Nov 07 nicklas 2322       <sect3 id="data_api.experiments.virtualdb">
3943 09 Nov 07 nicklas 2323         <title>Virtual databases, datacubes, etc.</title>
3943 09 Nov 07 nicklas 2324         
3943 09 Nov 07 nicklas 2325         <para>
3943 09 Nov 07 nicklas 2326           The above processes requires a flexible storage solution for the data. 
3943 09 Nov 07 nicklas 2327           Each experiment is related to a <classname docapi="net.sf.basedb.core.data">VirtualDb</classname>
3943 09 Nov 07 nicklas 2328           object. This object represents the set of tables that are needed to store
3943 09 Nov 07 nicklas 2329           data for the experiment. All tables are created in a special part of the
3943 09 Nov 07 nicklas 2330           BASE database that we call the <emphasis>dynamic database</emphasis>.
3943 09 Nov 07 nicklas 2331           In MySQL the dynamic database is a separate database, in Postgres it is
3943 09 Nov 07 nicklas 2332           a separate schema.
3943 09 Nov 07 nicklas 2333         </para>
3943 09 Nov 07 nicklas 2334         
3943 09 Nov 07 nicklas 2335         <para>
3943 09 Nov 07 nicklas 2336           A virual database is divided into data cubes. A data cube can be seen 
3943 09 Nov 07 nicklas 2337           as a three-dimensional object where each point can hold data that in
3943 09 Nov 07 nicklas 2338           most cases can be interpreted as data for a single spot from an
3943 09 Nov 07 nicklas 2339           array. The coordinates to a point is given by <emphasis>layer</emphasis>,
3943 09 Nov 07 nicklas 2340           <emphasis>column</emphasis> and <emphasis>position</emphasis>. The
3943 09 Nov 07 nicklas 2341           layer and column coordinates are represented by the 
3943 09 Nov 07 nicklas 2342           <classname docapi="net.sf.basedb.core.data">DataCubeLayerData</classname>
3943 09 Nov 07 nicklas 2343           and <classname docapi="net.sf.basedb.core.data">DataCubeColumnData</classname>
3943 09 Nov 07 nicklas 2344           objects. The position coordinate has no separate object associated with
3943 09 Nov 07 nicklas 2345           it.
3943 09 Nov 07 nicklas 2346         </para>
3943 09 Nov 07 nicklas 2347         
3943 09 Nov 07 nicklas 2348         <para>
3943 09 Nov 07 nicklas 2349           Data for a single bioassay set is always stored in a single layer. It
3943 09 Nov 07 nicklas 2350           is possible for more than one bioassay set to use the same layer. This
3943 09 Nov 07 nicklas 2351           usually happens for filtering transformations that doesn't modify the 
3943 09 Nov 07 nicklas 2352           data.  The filtered bioassay set is then linked to a 
3943 09 Nov 07 nicklas 2353           <classname docapi="net.sf.basedb.core.data">DataCubeFilterData</classname>
3943 09 Nov 07 nicklas 2354           object, which has information about which data points that
3943 09 Nov 07 nicklas 2355           passed the filter.
3943 09 Nov 07 nicklas 2356         </para>
3943 09 Nov 07 nicklas 2357         
3943 09 Nov 07 nicklas 2358         <para>
3943 09 Nov 07 nicklas 2359           All data for a bioassay is stored in a single column.
3943 09 Nov 07 nicklas 2360           Two bioassays in different bioassaysets (layers) can only have the same
3943 09 Nov 07 nicklas 2361           column if one is the parent of the other.
3943 09 Nov 07 nicklas 2362         </para>
3943 09 Nov 07 nicklas 2363         
3943 09 Nov 07 nicklas 2364         <para>
3943 09 Nov 07 nicklas 2365           The position coordinate is tied to a reporter.
3943 09 Nov 07 nicklas 2366         </para>
3943 09 Nov 07 nicklas 2367         
3943 09 Nov 07 nicklas 2368         <para>
3943 09 Nov 07 nicklas 2369           A child bioassay set may use the same data cube as it's parent
3943 09 Nov 07 nicklas 2370           bioassay set if all of the following conditions are true:
3943 09 Nov 07 nicklas 2371         </para>
3943 09 Nov 07 nicklas 2372         
3943 09 Nov 07 nicklas 2373         <itemizedlist>
3943 09 Nov 07 nicklas 2374         <listitem>
3943 09 Nov 07 nicklas 2375           <para>
3943 09 Nov 07 nicklas 2376           All positions are linked to the same reporter as the positions
3943 09 Nov 07 nicklas 2377           in the parent bioassay set.
3943 09 Nov 07 nicklas 2378           </para>
3943 09 Nov 07 nicklas 2379         </listitem>
3943 09 Nov 07 nicklas 2380         
3943 09 Nov 07 nicklas 2381         <listitem>
3943 09 Nov 07 nicklas 2382           <para>
3943 09 Nov 07 nicklas 2383           All data points are linked to the same (possible many) raw data
3943 09 Nov 07 nicklas 2384           spots as the corresponding data points in the parent bioassay set.
3943 09 Nov 07 nicklas 2385           </para>
3943 09 Nov 07 nicklas 2386         </listitem>
3943 09 Nov 07 nicklas 2387         
3943 09 Nov 07 nicklas 2388         <listitem>
3943 09 Nov 07 nicklas 2389           <para>
3943 09 Nov 07 nicklas 2390           The bioassays in the child bioassay set each have exactly one
3943 09 Nov 07 nicklas 2391           parent in the parent bioassay set. No parent bioassay may be the
3943 09 Nov 07 nicklas 2392           parent of more than one child bioassay.
3943 09 Nov 07 nicklas 2393           </para>
3943 09 Nov 07 nicklas 2394         </listitem>
3943 09 Nov 07 nicklas 2395         </itemizedlist>
3943 09 Nov 07 nicklas 2396         
3943 09 Nov 07 nicklas 2397         <para>
3943 09 Nov 07 nicklas 2398           If any of the above conditions are not true, a new data cube
3943 09 Nov 07 nicklas 2399           must be created for the child bioassay set. 
3943 09 Nov 07 nicklas 2400         </para>
3943 09 Nov 07 nicklas 2401       </sect3>
3943 09 Nov 07 nicklas 2402       
3943 09 Nov 07 nicklas 2403       <sect3 id="data_api.dynamic.description">
3943 09 Nov 07 nicklas 2404         <title>The dynamic database</title>
3943 09 Nov 07 nicklas 2405
3943 09 Nov 07 nicklas 2406         <figure id="data_api.figures.dynamic">
3943 09 Nov 07 nicklas 2407           <title>The dynamic database</title>
3943 09 Nov 07 nicklas 2408           <screenshot>
3943 09 Nov 07 nicklas 2409             <mediaobject>
3943 09 Nov 07 nicklas 2410               <imageobject>
3943 09 Nov 07 nicklas 2411                 <imagedata 
3943 09 Nov 07 nicklas 2412                   align="center"
3943 09 Nov 07 nicklas 2413                   fileref="figures/uml/datalayer.dynamic.png" format="PNG" />
3943 09 Nov 07 nicklas 2414               </imageobject>
3943 09 Nov 07 nicklas 2415             </mediaobject>
3943 09 Nov 07 nicklas 2416           </screenshot>
3943 09 Nov 07 nicklas 2417         </figure>
3943 09 Nov 07 nicklas 2418         
3943 09 Nov 07 nicklas 2419         <para>
3943 09 Nov 07 nicklas 2420           Each virtual database consists of several tables. The tables
3943 09 Nov 07 nicklas 2421           are dynamically created when needed. For each table shown in the diagram 
3943 09 Nov 07 nicklas 2422           the # sign is replaced by the id of the virtual database object at run
3943 09 Nov 07 nicklas 2423           time.
3943 09 Nov 07 nicklas 2424         </para>
3943 09 Nov 07 nicklas 2425         
3943 09 Nov 07 nicklas 2426         <para>
3943 09 Nov 07 nicklas 2427           There are no classes in the data layer for these tables and they 
3943 09 Nov 07 nicklas 2428           are not mapped with Hibernate. When we work with these tables we 
3943 09 Nov 07 nicklas 2429           are always using batcher classes and queries that works with integer, 
3943 09 Nov 07 nicklas 2430           floats and strings.
3943 09 Nov 07 nicklas 2431         </para>
3943 09 Nov 07 nicklas 2432         
3943 09 Nov 07 nicklas 2433         <bridgehead>The D#Spot table</bridgehead>
3943 09 Nov 07 nicklas 2434         <para>
3943 09 Nov 07 nicklas 2435           This is the main table which keeps the intensities for a single spot 
3943 09 Nov 07 nicklas 2436           in the data cube. Extra values attached to the spot are kept in separate 
3943 09 Nov 07 nicklas 2437           tables, one for each type of value (D#SpotInt, D#SpotFloat and D#SpotString).
3943 09 Nov 07 nicklas 2438         </para>
3943 09 Nov 07 nicklas 2439         
3943 09 Nov 07 nicklas 2440         <bridgehead>The D#Pos table</bridgehead>
3943 09 Nov 07 nicklas 2441         <para>
3943 09 Nov 07 nicklas 2442           This table stores the reporter id for each position in a cube. 
3943 09 Nov 07 nicklas 2443           Extra values attached to the position are kept in separate tables, 
3943 09 Nov 07 nicklas 2444           one for each type of value (D#PosInt, D#PosFloat and D#PosString).
3943 09 Nov 07 nicklas 2445         </para>
3943 09 Nov 07 nicklas 2446         
3943 09 Nov 07 nicklas 2447         <bridgehead>The D#Filter table</bridgehead>
3943 09 Nov 07 nicklas 2448         <para>
3943 09 Nov 07 nicklas 2449           This table stores the coordinates for the spots that remain after 
3943 09 Nov 07 nicklas 2450           filtering. Note that each filter is related to a bioassayset which 
3943 09 Nov 07 nicklas 2451           gives the cube and layer values. Each row in the filter table then 
3943 09 Nov 07 nicklas 2452           adds the column and position allowing us to find the spots in the 
3943 09 Nov 07 nicklas 2453           D#Spot table.
3943 09 Nov 07 nicklas 2454         </para>
3943 09 Nov 07 nicklas 2455         
3943 09 Nov 07 nicklas 2456         <bridgehead>The D#RawParents table</bridgehead>
3943 09 Nov 07 nicklas 2457         <para>
3943 09 Nov 07 nicklas 2458           This table holds mappings for a spot to the raw data it is calculated 
3943 09 Nov 07 nicklas 2459           from. We don't need the layer coordinate since all layers in a cube 
3943 09 Nov 07 nicklas 2460           must have the same mapping to raw data.
3943 09 Nov 07 nicklas 2461         </para>
3943 09 Nov 07 nicklas 2462         
3943 09 Nov 07 nicklas 2463       </sect3>      
3943 09 Nov 07 nicklas 2464
3943 09 Nov 07 nicklas 2465       
3715 11 Sep 07 nicklas 2466     </sect2>
3715 11 Sep 07 nicklas 2467     
3715 11 Sep 07 nicklas 2468     <sect2 id="data_api.misc">
3715 11 Sep 07 nicklas 2469       <title>Other classes</title>
3943 09 Nov 07 nicklas 2470       
3943 09 Nov 07 nicklas 2471         <figure id="data_api.figures.misc">
3943 09 Nov 07 nicklas 2472           <title>Other classes</title>
3943 09 Nov 07 nicklas 2473           <screenshot>
3943 09 Nov 07 nicklas 2474             <mediaobject>
3943 09 Nov 07 nicklas 2475               <imageobject>
3943 09 Nov 07 nicklas 2476                 <imagedata 
3943 09 Nov 07 nicklas 2477                   align="center"
3943 09 Nov 07 nicklas 2478                   fileref="figures/uml/datalayer.misc.png" format="PNG" />
3943 09 Nov 07 nicklas 2479               </imageobject>
3943 09 Nov 07 nicklas 2480             </mediaobject>
3943 09 Nov 07 nicklas 2481           </screenshot>
3943 09 Nov 07 nicklas 2482         </figure>
3943 09 Nov 07 nicklas 2483       
3715 11 Sep 07 nicklas 2484     </sect2>
3715 11 Sep 07 nicklas 2485
3315 09 May 07 nicklas 2486   </sect1>
3315 09 May 07 nicklas 2487   
5781 04 Oct 11 nicklas 2488   <sect1 id="base_api.core" chunked="1">
5782 04 Oct 11 nicklas 2489     <?dbhtml filename="core_api.html" ?>
3315 09 May 07 nicklas 2490     <title>The Core API</title>
3757 20 Sep 07 nicklas 2491     
3315 09 May 07 nicklas 2492     <para>
3757 20 Sep 07 nicklas 2493       This section gives an overview of various parts of the core API.
3315 09 May 07 nicklas 2494     </para>
3757 20 Sep 07 nicklas 2495     
5781 04 Oct 11 nicklas 2496     <sect2 id="core_api.authentication">
5781 04 Oct 11 nicklas 2497       <title>Authentication and sessions</title>
5781 04 Oct 11 nicklas 2498       <para>
5781 04 Oct 11 nicklas 2499         This documentation is only available in the old format which may not be up-to-date with
5781 04 Oct 11 nicklas 2500         the current implementation.
7982 14 Jun 21 nicklas 2501         See <ulink url="https://base.thep.lu.se/chrome/site/doc/historical/development/overview/core/authentication.html"
7982 14 Jun 21 nicklas 2502           >https://base.thep.lu.se/chrome/site/doc/historical/development/overview/core/authentication.html</ulink>
5781 04 Oct 11 nicklas 2503       </para>
5781 04 Oct 11 nicklas 2504     </sect2>    
5781 04 Oct 11 nicklas 2505     
5781 04 Oct 11 nicklas 2506     <sect2 id="core_api.accesspermissions">
5781 04 Oct 11 nicklas 2507       <title>Access permissions</title>
5781 04 Oct 11 nicklas 2508       <para>
5781 04 Oct 11 nicklas 2509         This documentation is only available in the old format which may not be up-to-date with
5781 04 Oct 11 nicklas 2510         the current implementation.
7982 14 Jun 21 nicklas 2511         See <ulink url="https://base.thep.lu.se/chrome/site/doc/historical/development/overview/core/accesspermissions.html"
7982 14 Jun 21 nicklas 2512           >https://base.thep.lu.se/chrome/site/doc/historical/development/overview/core/accesspermissions.html</ulink>
5781 04 Oct 11 nicklas 2513       </para>
5781 04 Oct 11 nicklas 2514     </sect2>
5781 04 Oct 11 nicklas 2515     
5781 04 Oct 11 nicklas 2516     <sect2 id="core_api.datavalidation">
5781 04 Oct 11 nicklas 2517       <title>Data validation</title>
5781 04 Oct 11 nicklas 2518       <para>
5781 04 Oct 11 nicklas 2519         TODO
5781 04 Oct 11 nicklas 2520       </para>
5781 04 Oct 11 nicklas 2521     </sect2>    
5781 04 Oct 11 nicklas 2522     <sect2 id="core_api.transactions">
5781 04 Oct 11 nicklas 2523       <title>Transaction handling</title>
5781 04 Oct 11 nicklas 2524       <para>
5781 04 Oct 11 nicklas 2525         TODO
5781 04 Oct 11 nicklas 2526       </para>
5781 04 Oct 11 nicklas 2527     </sect2>    
5781 04 Oct 11 nicklas 2528     <sect2 id="core_api.crwd">
5781 04 Oct 11 nicklas 2529       <title>Create/read/write/delete operations</title>
5781 04 Oct 11 nicklas 2530       <para>
5781 04 Oct 11 nicklas 2531         This documentation is only available in the old format which may not be up-to-date with
5781 04 Oct 11 nicklas 2532         the current implementation.
7982 14 Jun 21 nicklas 2533         See <ulink url="https://base.thep.lu.se/chrome/site/doc/historical/development/overview/core/itemhandling.html"
7982 14 Jun 21 nicklas 2534           >https://base.thep.lu.se/chrome/site/doc/historical/development/overview/core/itemhandling.html</ulink>
5781 04 Oct 11 nicklas 2535       </para>
5781 04 Oct 11 nicklas 2536     </sect2>    
5781 04 Oct 11 nicklas 2537     <sect2 id="core_api.batch">
5781 04 Oct 11 nicklas 2538       <title>Batch operations</title>
5781 04 Oct 11 nicklas 2539       <para>
5781 04 Oct 11 nicklas 2540         This documentation is only available in the old format which may not be up-to-date with
5781 04 Oct 11 nicklas 2541         the current implementation.
7982 14 Jun 21 nicklas 2542         See <ulink url="https://base.thep.lu.se/chrome/site/doc/historical/development/overview/core/batchprocessing.html"
7982 14 Jun 21 nicklas 2543           >https://base.thep.lu.se/chrome/site/doc/historical/development/overview/core/batchprocessing.html</ulink>
5781 04 Oct 11 nicklas 2544       </para>
5781 04 Oct 11 nicklas 2545     </sect2>    
5781 04 Oct 11 nicklas 2546     
5781 04 Oct 11 nicklas 2547     <sect2 id="core_api.quota">
5781 04 Oct 11 nicklas 2548       <title>Quota</title>
5781 04 Oct 11 nicklas 2549       <para>
5781 04 Oct 11 nicklas 2550         TODO
5781 04 Oct 11 nicklas 2551       </para>
5781 04 Oct 11 nicklas 2552     </sect2>    
5781 04 Oct 11 nicklas 2553     <sect2 id="core_api.pluginexecution">
5781 04 Oct 11 nicklas 2554       <title>Plugin execution / job queue</title>
5781 04 Oct 11 nicklas 2555       <para>
5781 04 Oct 11 nicklas 2556         This documentation is only available in the old format which may not be up-to-date with
5781 04 Oct 11 nicklas 2557         the current implementation.
7982 14 Jun 21 nicklas 2558         See <ulink url="https://base.thep.lu.se/chrome/site/doc/historical/development/overview/core/plugins.html"
7982 14 Jun 21 nicklas 2559           >https://base.thep.lu.se/chrome/site/doc/historical/development/overview/core/plugins.html</ulink>
5781 04 Oct 11 nicklas 2560       </para>
5781 04 Oct 11 nicklas 2561     </sect2>    
5781 04 Oct 11 nicklas 2562     
3757 20 Sep 07 nicklas 2563     <sect2 id="core_api.data_in_files">
3757 20 Sep 07 nicklas 2564       <title>Using files to store data</title>
3757 20 Sep 07 nicklas 2565       
3757 20 Sep 07 nicklas 2566       <para>
5818 21 Oct 11 nicklas 2567         BASE has support for storing data in files instead of importing it into the database. 
5818 21 Oct 11 nicklas 2568         Files can be attached to any item that implements the <interfacename 
5818 21 Oct 11 nicklas 2569         docapi="net.sf.basedb.core">FileStoreEnabled</interfacename>
5818 21 Oct 11 nicklas 2570         interface. For example, <classname docapi="net.sf.basedb.core">RawBioAssay</classname>,
5818 21 Oct 11 nicklas 2571         and <classname docapi="net.sf.basedb.core">ArrayDesign</classname> and a few other
5818 21 Oct 11 nicklas 2572         classes. The ability to store data in files is not a replacement for storing data in the
3757 20 Sep 07 nicklas 2573         database. It is possible (for some platforms/raw data types) to have data in 
5818 21 Oct 11 nicklas 2574         files and in the database at the same time. There are three cases:
3757 20 Sep 07 nicklas 2575       </para>
3757 20 Sep 07 nicklas 2576       
3757 20 Sep 07 nicklas 2577       <itemizedlist>
3757 20 Sep 07 nicklas 2578       <listitem>
3757 20 Sep 07 nicklas 2579         <para>
3757 20 Sep 07 nicklas 2580         Data in files only
3757 20 Sep 07 nicklas 2581         </para>
3757 20 Sep 07 nicklas 2582       </listitem>
3757 20 Sep 07 nicklas 2583       <listitem>
3757 20 Sep 07 nicklas 2584         <para>
3757 20 Sep 07 nicklas 2585         Data in the database only
3757 20 Sep 07 nicklas 2586         </para>
3757 20 Sep 07 nicklas 2587       </listitem>
3757 20 Sep 07 nicklas 2588       <listitem>
3757 20 Sep 07 nicklas 2589         <para>
3757 20 Sep 07 nicklas 2590         Data in both files and in the database
3757 20 Sep 07 nicklas 2591         </para>
3757 20 Sep 07 nicklas 2592       </listitem>
3757 20 Sep 07 nicklas 2593       </itemizedlist>
3757 20 Sep 07 nicklas 2594       
3757 20 Sep 07 nicklas 2595       <para>
3757 20 Sep 07 nicklas 2596         Not all three cases are supported for all types of data. This is controlled
3947 12 Nov 07 nicklas 2597         by the <classname docapi="net.sf.basedb.core">Platform</classname> class, which may disallow 
3835 15 Oct 07 nicklas 2598         that data is stored in the database. To check this call
3835 15 Oct 07 nicklas 2599         <methodname>Platform.isFileOnly()</methodname> and/or
3835 15 Oct 07 nicklas 2600         <methodname>Platform.getRawDataType()</methodname>. If the <methodname>isFileOnly()</methodname>
3835 15 Oct 07 nicklas 2601         method returns <constant>true</constant>, the platform can't store data in 
3835 15 Oct 07 nicklas 2602         the database. If the value is <constant>false</constant> more information
3835 15 Oct 07 nicklas 2603         can be obtained by calling <methodname>getRawDataType()</methodname>,
3835 15 Oct 07 nicklas 2604         which may return:
3757 20 Sep 07 nicklas 2605       </para>
3757 20 Sep 07 nicklas 2606       
3757 20 Sep 07 nicklas 2607       <itemizedlist>
3757 20 Sep 07 nicklas 2608       <listitem>
3757 20 Sep 07 nicklas 2609         <para>
3757 20 Sep 07 nicklas 2610           <constant>null</constant>: The platform can store data with any
3757 20 Sep 07 nicklas 2611           raw data type in the database. 
3757 20 Sep 07 nicklas 2612         </para>
3757 20 Sep 07 nicklas 2613       </listitem>
3757 20 Sep 07 nicklas 2614       <listitem>
3757 20 Sep 07 nicklas 2615         <para>
3947 12 Nov 07 nicklas 2616         A <classname docapi="net.sf.basedb.core">RawDataType</classname> that has <code>isStoredInDb() == true</code>:
3757 20 Sep 07 nicklas 2617         The platform can store data in the database but only data with the specified raw
3757 20 Sep 07 nicklas 2618         data type.
3757 20 Sep 07 nicklas 2619         </para>
3757 20 Sep 07 nicklas 2620       </listitem>
3757 20 Sep 07 nicklas 2621       <listitem>
3757 20 Sep 07 nicklas 2622         <para>
3947 12 Nov 07 nicklas 2623         A <classname docapi="net.sf.basedb.core">RawDataType</classname> that has <code>isStoredInDb() == false</code>:
3757 20 Sep 07 nicklas 2624         The platform can't store data in the database.
3757 20 Sep 07 nicklas 2625         </para>
3757 20 Sep 07 nicklas 2626       </listitem>
3757 20 Sep 07 nicklas 2627       </itemizedlist>
3757 20 Sep 07 nicklas 2628
3757 20 Sep 07 nicklas 2629       <para>
5818 21 Oct 11 nicklas 2630         Some <classname docapi="net.sf.basedb.core">FileStoreEnabled</classname> items doesn't 
5818 21 Oct 11 nicklas 2631         have a platform (for example, <classname docapi="net.sf.basedb.core">DerivedBioAssay</classname>).
5818 21 Oct 11 nicklas 2632         In this case, the file storage ability is controlled by the subtype of the item.
5818 21 Oct 11 nicklas 2633         See <methodname>getDataFileTypes()</methodname> method in the
5818 21 Oct 11 nicklas 2634         <classname docapi="net.sf.basedb.core">ItemSubtype</classname> class.
3757 20 Sep 07 nicklas 2635       </para>
5818 21 Oct 11 nicklas 2636
3835 15 Oct 07 nicklas 2637       <para>
3947 12 Nov 07 nicklas 2638         For backwards compatibility reasons, each <classname docapi="net.sf.basedb.core">Platform</classname>
3835 15 Oct 07 nicklas 2639         that can only store data in files will create "virtual" raw data type
3835 15 Oct 07 nicklas 2640         objects internally. These raw data types all return <constant>false</constant>
3872 23 Oct 07 nicklas 2641         from the <methodname>RawDataType.isStoredInDb()</methodname>
3872 23 Oct 07 nicklas 2642         method. They also have a back-link to the platform/variant that
3835 15 Oct 07 nicklas 2643         created it: <methodname>RawDataType.getPlatform()</methodname>
3872 23 Oct 07 nicklas 2644         and <methodname>RawDataType.getVariant()</methodname>. These two methods
3872 23 Oct 07 nicklas 2645         will always return <constant>null</constant> when called on a raw data type 
3872 23 Oct 07 nicklas 2646         that can be stored in the database.
3835 15 Oct 07 nicklas 2647       </para>
3835 15 Oct 07 nicklas 2648       
3835 15 Oct 07 nicklas 2649       <itemizedlist>
3835 15 Oct 07 nicklas 2650         <title>See also</title>
3835 15 Oct 07 nicklas 2651         <listitem><xref linkend="data_api.platforms" /></listitem>
5818 21 Oct 11 nicklas 2652         <listitem><xref linkend="extensions_developer.fileset_validator" /></listitem>
3835 15 Oct 07 nicklas 2653         <listitem><xref linkend="appendix.rawdatatypes.platforms" /></listitem>
3835 15 Oct 07 nicklas 2654       </itemizedlist>
3835 15 Oct 07 nicklas 2655       
3757 20 Sep 07 nicklas 2656       <sect3 id="core_api.data_in_files.diagram">
3757 20 Sep 07 nicklas 2657         <title>Diagram of classes and methods</title>
3757 20 Sep 07 nicklas 2658         <figure id="core_api.figures.data_in_files">
3757 20 Sep 07 nicklas 2659           <title>Store data in files</title>
3757 20 Sep 07 nicklas 2660           <screenshot>
3757 20 Sep 07 nicklas 2661             <mediaobject>
3757 20 Sep 07 nicklas 2662               <imageobject>
3757 20 Sep 07 nicklas 2663                 <imagedata 
3943 09 Nov 07 nicklas 2664                   align="center"
3943 09 Nov 07 nicklas 2665                   scalefit="1" width="100%"
3757 20 Sep 07 nicklas 2666                   fileref="figures/uml/corelayer.datainfiles.png" format="PNG" />
3757 20 Sep 07 nicklas 2667               </imageobject>
3757 20 Sep 07 nicklas 2668             </mediaobject>
3757 20 Sep 07 nicklas 2669           </screenshot>
3757 20 Sep 07 nicklas 2670         </figure>
3872 23 Oct 07 nicklas 2671         
3872 23 Oct 07 nicklas 2672         <para>
3872 23 Oct 07 nicklas 2673           This is rather large set of classes and methods. The ultimate goal
5818 21 Oct 11 nicklas 2674           is to be able to create links between a <classname docapi="net.sf.basedb.core">FileStoreEnabled</classname>
5818 21 Oct 11 nicklas 2675           item and <classname docapi="net.sf.basedb.core">File</classname>
3872 23 Oct 07 nicklas 2676           items and to provide some metadata about the files. 
3947 12 Nov 07 nicklas 2677           The <classname docapi="net.sf.basedb.core">FileStoreUtil</classname> class is one of the most
3872 23 Oct 07 nicklas 2678           important ones. It is intended to make it easy for plug-in (and other)
3872 23 Oct 07 nicklas 2679           developers to access the files without having to mess with platform
3872 23 Oct 07 nicklas 2680           or file type objects. The API is best described
3872 23 Oct 07 nicklas 2681           by a set of use-case examples.
3872 23 Oct 07 nicklas 2682         </para>
3872 23 Oct 07 nicklas 2683         
3757 20 Sep 07 nicklas 2684       </sect3>
3757 20 Sep 07 nicklas 2685       
3757 20 Sep 07 nicklas 2686       <sect3 id="core_api.data_in_files.ask">
3872 23 Oct 07 nicklas 2687         <title>Use case: Asking the user for files for a given item</title>
3757 20 Sep 07 nicklas 2688
3757 20 Sep 07 nicklas 2689         <para>
3757 20 Sep 07 nicklas 2690           A client application must know what types of files it makes sense 
3757 20 Sep 07 nicklas 2691           to ask the user for. In some cases, data may be split into more than 
3757 20 Sep 07 nicklas 2692           one file so we need a generic way to select files.
3757 20 Sep 07 nicklas 2693         </para>
3757 20 Sep 07 nicklas 2694         
3757 20 Sep 07 nicklas 2695         <para>
3947 12 Nov 07 nicklas 2696           Given that we have a <interfacename docapi="net.sf.basedb.core">FileStoreEnabled</interfacename>
3947 12 Nov 07 nicklas 2697           item we want to find out which <classname docapi="net.sf.basedb.core">DataFileType</classname>
3835 15 Oct 07 nicklas 2698           items that can be used for that item. The 
5818 21 Oct 11 nicklas 2699           <methodname>Base.getDataFileTypes()</methodname>
5818 21 Oct 11 nicklas 2700           can be used for this. You'll need to supply information about the platform,
5818 21 Oct 11 nicklas 2701           variant and subtype of the item. The method will create a query that returns
5818 21 Oct 11 nicklas 2702           a list of <classname>DataFileType</classname> items, each one representing a 
3835 15 Oct 07 nicklas 2703           specific file type that we should ask the user about. Examples:
3757 20 Sep 07 nicklas 2704         </para>
3757 20 Sep 07 nicklas 2705
3757 20 Sep 07 nicklas 2706         <orderedlist>
3757 20 Sep 07 nicklas 2707         <listitem>
3757 20 Sep 07 nicklas 2708           <para>
3757 20 Sep 07 nicklas 2709           The <constant>Affymetrix</constant> platform defines <constant>CEL</constant>
3872 23 Oct 07 nicklas 2710           as a raw data file and <constant>CDF</constant> as an array design (reporter map)
5818 21 Oct 11 nicklas 2711           file. If we have a <classname docapi="net.sf.basedb.core">RawBioAssay</classname> 
5818 21 Oct 11 nicklas 2712           the query will only return
3757 20 Sep 07 nicklas 2713           the CEL file type and the client can ask the user for a CEL file.
3757 20 Sep 07 nicklas 2714           </para>
3757 20 Sep 07 nicklas 2715         </listitem>
3757 20 Sep 07 nicklas 2716         <listitem>
3757 20 Sep 07 nicklas 2717           <para>
3835 15 Oct 07 nicklas 2718           The <constant>Generic</constant> platform defines <constant>PRINT_MAP</constant>
3835 15 Oct 07 nicklas 2719           and <constant>REPORTER_MAP</constant> for array designs. If we have
3947 12 Nov 07 nicklas 2720           an <classname docapi="net.sf.basedb.core">ArrayDesign</classname> the query will return those two
3835 15 Oct 07 nicklas 2721           items.
3757 20 Sep 07 nicklas 2722           </para>
3757 20 Sep 07 nicklas 2723         </listitem>
5818 21 Oct 11 nicklas 2724         <listitem>
5818 21 Oct 11 nicklas 2725           <para>
5818 21 Oct 11 nicklas 2726           The <constant>Scan</constant> subtype defines <constant>MICROARRAY_IMAGE</constant>
5818 21 Oct 11 nicklas 2727           for derived bioassays.
5818 21 Oct 11 nicklas 2728           </para>
5818 21 Oct 11 nicklas 2729         </listitem>
3757 20 Sep 07 nicklas 2730         </orderedlist>
3757 20 Sep 07 nicklas 2731       
3757 20 Sep 07 nicklas 2732         <para>
3835 15 Oct 07 nicklas 2733           It might also be interesting to know the currently selected file
5818 21 Oct 11 nicklas 2734           for each file type and if the file is <varname>required</varname>
5818 21 Oct 11 nicklas 2735           and if <varname>multiple</varname> files are allowed.
5818 21 Oct 11 nicklas 2736           Here is a simple code example
3835 15 Oct 07 nicklas 2737           that may be useful to start from:
3757 20 Sep 07 nicklas 2738         </para>
3835 15 Oct 07 nicklas 2739       
3838 16 Oct 07 nicklas 2740         <programlisting language="java">
3757 20 Sep 07 nicklas 2741 DbControl dc = ...
3757 20 Sep 07 nicklas 2742 FileStoreEnabled item = ...
3835 15 Oct 07 nicklas 2743 Platform platform = item.getPlatform();
3835 15 Oct 07 nicklas 2744 PlatformVariant variant = item.getVariant();
5818 21 Oct 11 nicklas 2745 Itemsubtype subtype = item instanceof Subtypable ?
5818 21 Oct 11 nicklas 2746    ((Subtypable)item).getItemSubtype() : null;
3835 15 Oct 07 nicklas 2747
3835 15 Oct 07 nicklas 2748 // Get list of DataFileTypes used by the platform
3795 27 Sep 07 nicklas 2749 ItemQuery&lt;DataFileType&gt; query =
5818 21 Oct 11 nicklas 2750    Base.getDataFileTypes(item.getType(), item, platform, variant, subtype);
3795 27 Sep 07 nicklas 2751 List&lt;DataFileType&gt; types = query.list(dc);
3835 15 Oct 07 nicklas 2752
3835 15 Oct 07 nicklas 2753 // Always check hasFileSet() method first to avoid
3835 15 Oct 07 nicklas 2754 // creating the file set if it doesn't exists
3835 15 Oct 07 nicklas 2755 FileSet fileSet = item.hasFileSet() ? 
3835 15 Oct 07 nicklas 2756    null : item.getFileSet();
3835 15 Oct 07 nicklas 2757    
3835 15 Oct 07 nicklas 2758 for (DataFileType type : types)
3835 15 Oct 07 nicklas 2759 {
3835 15 Oct 07 nicklas 2760    // Get the current file, if any
3835 15 Oct 07 nicklas 2761    FileSetMember member = fileSet == null || !fileSet.hasMember(type) ?
3835 15 Oct 07 nicklas 2762       null : fileSet.getMember(type);
3835 15 Oct 07 nicklas 2763    File current = member == null ? 
3835 15 Oct 07 nicklas 2764       null : member.getFile();
3835 15 Oct 07 nicklas 2765    
5818 21 Oct 11 nicklas 2766    // Check if a file is required by the platform/subtype
3835 15 Oct 07 nicklas 2767    PlatformFileType pft = platform == null ? 
5818 21 Oct 11 nicklas 2768       null : platform.getFileType(type, variant, false);
5818 21 Oct 11 nicklas 2769    ItemSubtypeFileType ift = subtype == null ?
5818 21 Oct 11 nicklas 2770       null : subtype.getAssociatedDataFileType(type, false);
3835 15 Oct 07 nicklas 2771    boolean isRequired = pft == null ? 
3835 15 Oct 07 nicklas 2772       false : pft.isRequired();
5818 21 Oct 11 nicklas 2773    isRequired |= ift == null ?
5818 21 Oct 11 nicklas 2774       false : ift.isRequired();
3835 15 Oct 07 nicklas 2775       
3835 15 Oct 07 nicklas 2776    // Now we can do something with this information to
3835 15 Oct 07 nicklas 2777    // let the user select a file ...
3835 15 Oct 07 nicklas 2778 }
3757 20 Sep 07 nicklas 2779 </programlisting>
3757 20 Sep 07 nicklas 2780       
3835 15 Oct 07 nicklas 2781         <note>
3835 15 Oct 07 nicklas 2782           <title>Also remember to catch PermissionDeniedException</title>
3835 15 Oct 07 nicklas 2783           <para>
3835 15 Oct 07 nicklas 2784             The above code may look complicated, but this is mostly because
3835 15 Oct 07 nicklas 2785             of all checks for <constant>null</constant> values. Remember
3835 15 Oct 07 nicklas 2786             that many things are optional and may return <constant>null</constant>.
3835 15 Oct 07 nicklas 2787             Another thing to look out for is 
3835 15 Oct 07 nicklas 2788             <exceptionname>PermissionDeniedException</exceptionname>:s. The logged in
3835 15 Oct 07 nicklas 2789             user may not have access to all items. The above example doesn't include
3835 15 Oct 07 nicklas 2790             any code for this since it would have made it too complex.
3835 15 Oct 07 nicklas 2791           </para>
3835 15 Oct 07 nicklas 2792         </note>
3757 20 Sep 07 nicklas 2793       </sect3>
3757 20 Sep 07 nicklas 2794       
3757 20 Sep 07 nicklas 2795       <sect3 id="core_api.data_in_files.link">
3872 23 Oct 07 nicklas 2796         <title>Use case: Link, validate and extract metadata from the selected files</title>
3757 20 Sep 07 nicklas 2797         <para>
3757 20 Sep 07 nicklas 2798           When the user has selected the file(s) we must store the links
3947 12 Nov 07 nicklas 2799           to them in the database. This is done with a <classname docapi="net.sf.basedb.core">FileSet</classname>
5818 21 Oct 11 nicklas 2800           object. A file set can contain any number of files. 
5818 21 Oct 11 nicklas 2801           Call <methodname>FileSet.setMember()</methodname> or <methodname>FileSet.addMember()</methodname>
5818 21 Oct 11 nicklas 2802           to store a file in the file set. If a file already exists for the given file type
5818 21 Oct 11 nicklas 2803           it is replaced if the <methodname>setMember</methodname> method is called. 
5818 21 Oct 11 nicklas 2804           The following
3947 12 Nov 07 nicklas 2805           program example assumes that we have a map where <classname docapi="net.sf.basedb.core">File</classname>:s
3947 12 Nov 07 nicklas 2806           are related to <classname docapi="net.sf.basedb.core">DataFileType</classname>:s. When all files
3872 23 Oct 07 nicklas 2807           have been added we call <methodname>FileSet.validate()</methodname>
3872 23 Oct 07 nicklas 2808           to validate the files and extract metadata.
3757 20 Sep 07 nicklas 2809         </para>
3835 15 Oct 07 nicklas 2810         
3838 16 Oct 07 nicklas 2811         <programlisting language="java">
3835 15 Oct 07 nicklas 2812 DbControl dc = ...
3835 15 Oct 07 nicklas 2813 FileStoreEnabled item = ...
3835 15 Oct 07 nicklas 2814 Map&lt;DataFileType, File&gt; files = ...
3835 15 Oct 07 nicklas 2815
3835 15 Oct 07 nicklas 2816 // Store the selected files in the fileset
3835 15 Oct 07 nicklas 2817 FileSet fileSet = item.getFileSet();
3835 15 Oct 07 nicklas 2818 for (Map.Entry&lt;DataFileType, File&gt; entry : files)
3835 15 Oct 07 nicklas 2819 {
3835 15 Oct 07 nicklas 2820    DataFileType type = entry.getKey();
3835 15 Oct 07 nicklas 2821    File file = entry.getValue();
3835 15 Oct 07 nicklas 2822    fileSet.setMember(type, file);
3835 15 Oct 07 nicklas 2823 }
3835 15 Oct 07 nicklas 2824
3835 15 Oct 07 nicklas 2825 // Validate the files and extract metadata
5818 21 Oct 11 nicklas 2826 fileSet.validate(dc);
3835 15 Oct 07 nicklas 2827 </programlisting>
3872 23 Oct 07 nicklas 2828
3757 20 Sep 07 nicklas 2829         <para>
3757 20 Sep 07 nicklas 2830           Validation and extraction of metadata is important since we want
3757 20 Sep 07 nicklas 2831           data in files to be equivalent to data in the database. The validation
5818 21 Oct 11 nicklas 2832           and metadata extraction is initiated by the core when the 
3872 23 Oct 07 nicklas 2833           <methodname>FileSet.validate()</methodname> is called. 
5818 21 Oct 11 nicklas 2834           The validation and metadata extraction is handled by extensions
5818 21 Oct 11 nicklas 2835           so the actual outcome depends on what has been installed on the 
5818 21 Oct 11 nicklas 2836           BASE server.
3757 20 Sep 07 nicklas 2837         </para>
3872 23 Oct 07 nicklas 2838
3872 23 Oct 07 nicklas 2839         <note>
3872 23 Oct 07 nicklas 2840           <para>
5818 21 Oct 11 nicklas 2841           The <methodname>FileSet.validate()</methodname> method doesn't
3872 23 Oct 07 nicklas 2842           throw any exceptions. Instead, all validation errors
3872 23 Oct 07 nicklas 2843           are returned a list of <classname>Throwable</classname>:s. The
3872 23 Oct 07 nicklas 2844           validation result is also stored for each file and can be access
3872 23 Oct 07 nicklas 2845           with <methodname>FileSetMember.isValid()</methodname> and
3872 23 Oct 07 nicklas 2846           <methodname>FileSetMember.getErrorMessage()</methodname>.
3872 23 Oct 07 nicklas 2847           </para>
3872 23 Oct 07 nicklas 2848         </note>
3872 23 Oct 07 nicklas 2849
3872 23 Oct 07 nicklas 2850         <para>
3872 23 Oct 07 nicklas 2851           Here is the general outline of what is going on in the core:
3872 23 Oct 07 nicklas 2852         </para>
3872 23 Oct 07 nicklas 2853
3835 15 Oct 07 nicklas 2854         <orderedlist>
3835 15 Oct 07 nicklas 2855         <listitem>
3835 15 Oct 07 nicklas 2856           <para>
5818 21 Oct 11 nicklas 2857           The core calls the main <classname 
5818 21 Oct 11 nicklas 2858           docapi="net.sf.basedb.util.extensions.manager">ExtensionsManager</classname>
5818 21 Oct 11 nicklas 2859           and initiates the action factory for all file set validator extensions.
3835 15 Oct 07 nicklas 2860           </para>
3835 15 Oct 07 nicklas 2861         </listitem>
3835 15 Oct 07 nicklas 2862         
3835 15 Oct 07 nicklas 2863         <listitem>
3835 15 Oct 07 nicklas 2864           <para>
5818 21 Oct 11 nicklas 2865           After inspecting the current item and file set, the factories create
5818 21 Oct 11 nicklas 2866           one or more <interfacename 
5818 21 Oct 11 nicklas 2867           docapi="net.sf.basedb.util.fileset">ValidationAction</interfacename>:s.
3835 15 Oct 07 nicklas 2868           </para>
3835 15 Oct 07 nicklas 2869         </listitem>
3835 15 Oct 07 nicklas 2870         
3835 15 Oct 07 nicklas 2871         <listitem>
3835 15 Oct 07 nicklas 2872           <para>
5818 21 Oct 11 nicklas 2873           For each file in the file set, the <methodname>ValidationAction.acceptFile()</methodname> 
5818 21 Oct 11 nicklas 2874           method is called on each action, which is supposed to either accept or deny 
5818 21 Oct 11 nicklas 2875           validation of the file.
3835 15 Oct 07 nicklas 2876           </para>
3835 15 Oct 07 nicklas 2877         </listitem>
3835 15 Oct 07 nicklas 2878         
3835 15 Oct 07 nicklas 2879         <listitem>
3835 15 Oct 07 nicklas 2880           <para>
5818 21 Oct 11 nicklas 2881           If the file is accepted the <methodname>ValidationAction.validateAndExtractMetadata()</methodname>
5818 21 Oct 11 nicklas 2882           method is called.
3835 15 Oct 07 nicklas 2883           </para>
3835 15 Oct 07 nicklas 2884         </listitem>
3835 15 Oct 07 nicklas 2885         </orderedlist>
3757 20 Sep 07 nicklas 2886
3757 20 Sep 07 nicklas 2887         <note>
3757 20 Sep 07 nicklas 2888           <title>Only one instance of each validator class is created</title>
3757 20 Sep 07 nicklas 2889           <para>
5818 21 Oct 11 nicklas 2890           The validation is not done until all files have been 
5818 21 Oct 11 nicklas 2891           added to the fileset. If the same validator is
5818 21 Oct 11 nicklas 2892           used for more than one file, the same instance is reused. Eg. 
5818 21 Oct 11 nicklas 2893           the <methodname>acceptFile()</methodname> is called one time
5818 21 Oct 11 nicklas 2894           for each file. Depending on the return value, the 
5818 21 Oct 11 nicklas 2895           <methodname>validateAndExtractMetadata()</methodname> may be called either 
5818 21 Oct 11 nicklas 2896           immediately or not until all files have been processed.
3757 20 Sep 07 nicklas 2897           </para>
3757 20 Sep 07 nicklas 2898         </note>
3757 20 Sep 07 nicklas 2899         
3757 20 Sep 07 nicklas 2900       </sect3>
3757 20 Sep 07 nicklas 2901       
3757 20 Sep 07 nicklas 2902       <sect3 id="core_api.data_in_files.import">
3872 23 Oct 07 nicklas 2903         <title>Use case: Import data into the database</title>
3757 20 Sep 07 nicklas 2904         
3757 20 Sep 07 nicklas 2905         <para>
3757 20 Sep 07 nicklas 2906           This should be done by existing plug-ins in the same way as before.
3757 20 Sep 07 nicklas 2907           A slight modification is needed since it is good if the importers
3947 12 Nov 07 nicklas 2908           are made aware of already selected files in the <classname docapi="net.sf.basedb.core">FileSet</classname>
3947 12 Nov 07 nicklas 2909           to provide good default values. The <classname docapi="net.sf.basedb.core">FileStoreUtil</classname>
3872 23 Oct 07 nicklas 2910           class is very useful in cases like this:
3757 20 Sep 07 nicklas 2911         </para>
3757 20 Sep 07 nicklas 2912         
3838 16 Oct 07 nicklas 2913         <programlisting language="java">
3835 15 Oct 07 nicklas 2914 RawBioAssay rba = ...
3835 15 Oct 07 nicklas 2915 DbControl dc = ...
3835 15 Oct 07 nicklas 2916
3835 15 Oct 07 nicklas 2917 // Get the current raw data file, if any
3872 23 Oct 07 nicklas 2918 List&lt;File&gt; rawDataFiles = 
3872 23 Oct 07 nicklas 2919    FileStoreUtil.getGenericDataFiles(dc, rba, FileType.RAW_DATA);
3835 15 Oct 07 nicklas 2920 File defaultFile = rawDataFiles.size() > 0 ?
3835 15 Oct 07 nicklas 2921    rawDataFiles.get(0) : null;
3835 15 Oct 07 nicklas 2922    
3835 15 Oct 07 nicklas 2923 // Create parameter asking for input file - use current as default
3835 15 Oct 07 nicklas 2924 PluginParameter&lt;File&gt; fileParameter = new PluginParameter&lt;File&gt;(
3835 15 Oct 07 nicklas 2925    "file",
3835 15 Oct 07 nicklas 2926    "Raw data file",
3835 15 Oct 07 nicklas 2927    "The file that contains the raw data that you want to import",
3835 15 Oct 07 nicklas 2928    new FileParameterType(defaultFile, true, 1)
3835 15 Oct 07 nicklas 2929 );
3757 20 Sep 07 nicklas 2930 </programlisting>
3835 15 Oct 07 nicklas 2931
3835 15 Oct 07 nicklas 2932       <para>
3835 15 Oct 07 nicklas 2933         An import plug-in should also save the file that was used to the file set:
3835 15 Oct 07 nicklas 2934       </para>
3835 15 Oct 07 nicklas 2935       
3838 16 Oct 07 nicklas 2936       <programlisting language="java">
3835 15 Oct 07 nicklas 2937 RawBioassay rba = ...
3835 15 Oct 07 nicklas 2938 // The file the user selected to import from
3835 15 Oct 07 nicklas 2939 File rawDataFile = (File)job.getValue("file");
3835 15 Oct 07 nicklas 2940
3835 15 Oct 07 nicklas 2941 // Save the file to the fileset. The method will check which file 
3835 15 Oct 07 nicklas 2942 // type the platform uses as the raw data type. As a fallback the
3835 15 Oct 07 nicklas 2943 // GENERIC_RAW_DATA type is used
3835 15 Oct 07 nicklas 2944 FileStoreUtil.setGenericDataFile(dc, rba, FileType.RAW_DATA, 
3835 15 Oct 07 nicklas 2945    DataFileType.GENERIC_RAW_DATA, rawDataFile);
3835 15 Oct 07 nicklas 2946 </programlisting>
3835 15 Oct 07 nicklas 2947
3757 20 Sep 07 nicklas 2948       </sect3>
3757 20 Sep 07 nicklas 2949       
3757 20 Sep 07 nicklas 2950       <sect3 id="core_api.data_in_files.experiments">
3872 23 Oct 07 nicklas 2951         <title>Use case: Using raw data from files in an experiment</title>
3757 20 Sep 07 nicklas 2952         
3757 20 Sep 07 nicklas 2953         <para>
3757 20 Sep 07 nicklas 2954           Just as before, an experiment is still locked to a single
3947 12 Nov 07 nicklas 2955           <classname docapi="net.sf.basedb.core">RawDataType</classname>. This is a design issue that
3757 20 Sep 07 nicklas 2956           would break too many things if changed. If data is stored in files
3947 12 Nov 07 nicklas 2957           the experiment is also locked to a single <classname docapi="net.sf.basedb.core">Platform</classname>.
3757 20 Sep 07 nicklas 2958           This has been designed to have as little impact on existing
3757 20 Sep 07 nicklas 2959           plug-ins as possible. In most cases, the plug-ins will continue
3757 20 Sep 07 nicklas 2960           to work as before.
3757 20 Sep 07 nicklas 2961         </para>
3757 20 Sep 07 nicklas 2962         
3757 20 Sep 07 nicklas 2963         <para>
3757 20 Sep 07 nicklas 2964           A plug-in (using data from the database that needs to check if it can
3757 20 Sep 07 nicklas 2965           be used within an experiment can still do:
3757 20 Sep 07 nicklas 2966         </para>
3757 20 Sep 07 nicklas 2967         
3838 16 Oct 07 nicklas 2968         <programlisting language="java">
3757 20 Sep 07 nicklas 2969 Experiment e = ...
3757 20 Sep 07 nicklas 2970 RawDataType rdt = e.getRawDataType();
3757 20 Sep 07 nicklas 2971 if (rdt.isStoredInDb())
3757 20 Sep 07 nicklas 2972 {
3757 20 Sep 07 nicklas 2973    // Check number of channels, etc...
3757 20 Sep 07 nicklas 2974    // ... run plug-in code ...
3757 20 Sep 07 nicklas 2975 }
3757 20 Sep 07 nicklas 2976 </programlisting>
3757 20 Sep 07 nicklas 2977         
3757 20 Sep 07 nicklas 2978         <para>
3757 20 Sep 07 nicklas 2979           A newer plug-in which uses data from files should do:
3757 20 Sep 07 nicklas 2980         </para>
3757 20 Sep 07 nicklas 2981         
3838 16 Oct 07 nicklas 2982         <programlisting language="java">
3757 20 Sep 07 nicklas 2983 Experiment e = ...
3835 15 Oct 07 nicklas 2984 DbControl dc = ...
3757 20 Sep 07 nicklas 2985 RawDataType rdt = e.getRawDataType();
3757 20 Sep 07 nicklas 2986 if (!rdt.isStoredInDb())
3757 20 Sep 07 nicklas 2987 {
3872 23 Oct 07 nicklas 2988    // Check that platform/variant is supported
3835 15 Oct 07 nicklas 2989    Platform p = rdt.getPlatform(dc);
3835 15 Oct 07 nicklas 2990    PlatformVariant v = rdt.getVariant(dc);
3872 23 Oct 07 nicklas 2991    // ...
3872 23 Oct 07 nicklas 2992
3872 23 Oct 07 nicklas 2993    // Get data files
3872 23 Oct 07 nicklas 2994    File aFile = FileStoreUtil.getDataFile(dc, ...);
3872 23 Oct 07 nicklas 2995    
3757 20 Sep 07 nicklas 2996    // ... run plug-in code ...
3757 20 Sep 07 nicklas 2997 }
3757 20 Sep 07 nicklas 2998 </programlisting>
3757 20 Sep 07 nicklas 2999         
3757 20 Sep 07 nicklas 3000       </sect3>
3757 20 Sep 07 nicklas 3001       
3757 20 Sep 07 nicklas 3002     </sect2>
4093 18 Jan 08 enell 3003     
4093 18 Jan 08 enell 3004     <sect2 id="core_api.signals">
4093 18 Jan 08 enell 3005       <title>Sending signals (to plug-ins)</title>
4093 18 Jan 08 enell 3006     
4093 18 Jan 08 enell 3007       <para>
4093 18 Jan 08 enell 3008         BASE has a simple system for sending signals between different parts of
4093 18 Jan 08 enell 3009         a system. This signalling system was initially developed to be able to
4093 18 Jan 08 enell 3010         kill plug-ins that a user for some reason wanted to abort. The signalling
4093 18 Jan 08 enell 3011         system as such is not limited to this and it can be used for other purposes 
4093 18 Jan 08 enell 3012         as well. Signals can of course be handled internally in a single JVM but
4093 18 Jan 08 enell 3013         also sent externally to other JVM:s running on the same or a different 
4093 18 Jan 08 enell 3014         computer. The transport mechanism for signals is decoupled from the actual
4093 18 Jan 08 enell 3015         handling of them. If you want to, you could implement a signal transporter
4093 18 Jan 08 enell 3016         that sends signal as emails and the target plug-in would never know.
4093 18 Jan 08 enell 3017       </para>
4093 18 Jan 08 enell 3018       
4093 18 Jan 08 enell 3019       <para>
4093 18 Jan 08 enell 3020         The remainder of this section will focus mainly on the sending and
4093 18 Jan 08 enell 3021         transportation of signals. For more information about handling signals
4093 18 Jan 08 enell 3022         on the receiving end, see <xref linkend="plugin_developer.signals" />.
4093 18 Jan 08 enell 3023       </para>
4093 18 Jan 08 enell 3024       
4093 18 Jan 08 enell 3025       <sect3 id="core_api.signals.diagram">
4093 18 Jan 08 enell 3026         <title>Diagram of classes and methods</title>
4093 18 Jan 08 enell 3027         <figure id="core_api.figures.signals">
4093 18 Jan 08 enell 3028           <title>The signalling system</title>
4093 18 Jan 08 enell 3029           <screenshot>
4093 18 Jan 08 enell 3030             <mediaobject>
4093 18 Jan 08 enell 3031               <imageobject>
4093 18 Jan 08 enell 3032                 <imagedata 
4093 18 Jan 08 enell 3033                   align="center"
4093 18 Jan 08 enell 3034                   scalefit="1" width="100%"
4093 18 Jan 08 enell 3035                   fileref="figures/uml/corelayer.signals.png" format="PNG" />
4093 18 Jan 08 enell 3036               </imageobject>
4093 18 Jan 08 enell 3037             </mediaobject>
4093 18 Jan 08 enell 3038           </screenshot>
4093 18 Jan 08 enell 3039         </figure>
4093 18 Jan 08 enell 3040       
4093 18 Jan 08 enell 3041         <para>
4093 18 Jan 08 enell 3042           The signalling system is rather simple. An object that wish
4093 18 Jan 08 enell 3043           to receieve signals must implement the 
4093 18 Jan 08 enell 3044           <interfacename docapi="net.sf.basedb.core.signal"
4093 18 Jan 08 enell 3045           >SignalTarget</interfacename>. It's only method 
4093 18 Jan 08 enell 3046           is <methodname>getSignalHandler()</methodname>. A 
4093 18 Jan 08 enell 3047           <interfacename docapi="net.sf.basedb.core.signal"
4093 18 Jan 08 enell 3048           >SignalHandler</interfacename> is an object that 
4093 18 Jan 08 enell 3049           knows what to do when a signal is delivered to it. The target object
4093 18 Jan 08 enell 3050           may implement the <interfacename>SignalHandler</interfacename> itself
4093 18 Jan 08 enell 3051           or use one of the existing handlers. 
4093 18 Jan 08 enell 3052         </para>
4093 18 Jan 08 enell 3053         
4093 18 Jan 08 enell 3054         <para>
4093 18 Jan 08 enell 3055           The difficult part here is to be aware that a signal is usually
4093 18 Jan 08 enell 3056           delivered by a separate thread. The target object must be aware
4093 18 Jan 08 enell 3057           of this and know how to handle multiple threads. As an example we
4093 18 Jan 08 enell 3058           can use the <classname docapi="net.sf.basedb.core.signal"
4093 18 Jan 08 enell 3059           >ThreadSignalHandler</classname> which simply
4093 18 Jan 08 enell 3060           calls <code>Thread.interrupt()</code> to deliver a signal. The target 
5818 21 Oct 11 nicklas 3061           object that uses this signal handler must know that it should check
5818 21 Oct 11 nicklas 3062           <code>Thread.interrupted()</code> at regular intervals from the worker
4093 18 Jan 08 enell 3063           thread. If that method returns true, it means that the <constant>ABORT</constant>
4093 18 Jan 08 enell 3064           signal has been delivered and the main thread should clean up and exit as
4093 18 Jan 08 enell 3065           soon as possible.
4093 18 Jan 08 enell 3066         </para>
4093 18 Jan 08 enell 3067         
4093 18 Jan 08 enell 3068         <para>
4093 18 Jan 08 enell 3069           Even if a signal handler could be given directly to the party
4093 18 Jan 08 enell 3070           that may be interested in sending a signal to the target this
4093 18 Jan 08 enell 3071           is not recommended. This would only work when sending signals
4093 18 Jan 08 enell 3072           within the same virtual machine. The signalling system includes
4093 18 Jan 08 enell 3073           <interfacename docapi="net.sf.basedb.core.signal"
4093 18 Jan 08 enell 3074           >SignalTransporter</interfacename> and
4093 18 Jan 08 enell 3075           <interfacename docapi="net.sf.basedb.core.signal"
4093 18 Jan 08 enell 3076           >SignalReceiver</interfacename> objects that are used
4093 18 Jan 08 enell 3077           to decouple the sending of signals with the handling of signals. The
4093 18 Jan 08 enell 3078           implementation usually comes in pairs, for example 
4093 18 Jan 08 enell 3079           <classname docapi="net.sf.basedb.core.signal"
4093 18 Jan 08 enell 3080           >SocketSignalTransporters</classname> and <classname 
4093 18 Jan 08 enell 3081           docapi="net.sf.basedb.core.signal">SocketSignalReceiver</classname>.
4093 18 Jan 08 enell 3082         </para>
4093 18 Jan 08 enell 3083         
4093 18 Jan 08 enell 3084         <para>
4093 18 Jan 08 enell 3085           Setting up the transport mechanism is usually a system responsibility.
4093 18 Jan 08 enell 3086           Only the system know what kind of transport that is appropriate for it's current 
4093 18 Jan 08 enell 3087           setup. Ie. should signals be delievered by TCP/IP sockets, only internally, or 
4093 18 Jan 08 enell 3088           should a delivery mechanism based on web services be implemented? 
4093 18 Jan 08 enell 3089           If a system wants to receive signals it must create an appropriate
4093 18 Jan 08 enell 3090           <interfacename>SignalReceiver</interfacename> object. Within BASE the 
4093 18 Jan 08 enell 3091           internal job queue set up it's own signalling system that can be used to
4093 18 Jan 08 enell 3092           send signals (eg. kill) running jobs. The job agents do the same but uses
4093 18 Jan 08 enell 3093           a different implementation. See <xref linkend="appendix.base.config.jobqueue" />
4093 18 Jan 08 enell 3094           for more information about how to configure the internal job queue's 
4093 18 Jan 08 enell 3095           signal receiver. In both cases, there is only one signal receiver instance
4093 18 Jan 08 enell 3096           active in the system.
4093 18 Jan 08 enell 3097         </para>
4093 18 Jan 08 enell 3098         
4093 18 Jan 08 enell 3099         <para>
4093 18 Jan 08 enell 3100           Let's take the internal job queue as an example. Here is how it works:
4093 18 Jan 08 enell 3101         </para>
4093 18 Jan 08 enell 3102         
4093 18 Jan 08 enell 3103         <itemizedlist>
4093 18 Jan 08 enell 3104         <listitem>
4093 18 Jan 08 enell 3105           <para>
4093 18 Jan 08 enell 3106           When the internal job queue is started, it will also create a signal
4093 18 Jan 08 enell 3107           receiver instance according to the settings in <filename>base.config</filename>.
4093 18 Jan 08 enell 3108           The default is to create <classname docapi="net.sf.basedb.core.signal"
4093 18 Jan 08 enell 3109           >LocalSignalReceiver</classname>
4093 18 Jan 08 enell 3110           which can only be used inside the same JVM. If needed, this can
4093 18 Jan 08 enell 3111           be changed to a <classname docapi="net.sf.basedb.core.signal"
4093 18 Jan 08 enell 3112           >SocketSignalReceiver</classname> or any other
4093 18 Jan 08 enell 3113           user-provided implementation.
4093 18 Jan 08 enell 3114           </para>
4093 18 Jan 08 enell 3115         </listitem>
4093 18 Jan 08 enell 3116         
4093 18 Jan 08 enell 3117         <listitem>
4093 18 Jan 08 enell 3118           <para>
4093 18 Jan 08 enell 3119           When the job queue has found a plug-in to execute it will check if
4093 18 Jan 08 enell 3120           it also implements the <interfacename docapi="net.sf.basedb.core.signal"
4093 18 Jan 08 enell 3121           >SignalTarget</interfacename>
4093 18 Jan 08 enell 3122           interface. If it does, a signal handler is created and registered
4093 18 Jan 08 enell 3123           with the signal receiver. This is actually done by the BASE core 
4093 18 Jan 08 enell 3124           by calling <methodname>PluginExecutionRequest.registerSignalReceiver()</methodname>
4093 18 Jan 08 enell 3125           which also makes sure that the the ID returned from the registration is
4093 18 Jan 08 enell 3126           stored in the database together with the job item representing the 
4093 18 Jan 08 enell 3127           plug-in to execute.
4093 18 Jan 08 enell 3128           </para>
4093 18 Jan 08 enell 3129         </listitem>
4093 18 Jan 08 enell 3130         
4093 18 Jan 08 enell 3131         <listitem>
4093 18 Jan 08 enell 3132           <para>
4093 18 Jan 08 enell 3133           Now, when the web client see's a running job which has a non-empty 
4093 18 Jan 08 enell 3134           signal transporter property, the <guilabel>Abort</guilabel>
4093 18 Jan 08 enell 3135           button is activated. If the user clicks this button the BASE core
4093 18 Jan 08 enell 3136           uses the information in the database to create 
4093 18 Jan 08 enell 3137           <interfacename docapi="net.sf.basedb.core.signal"
4093 18 Jan 08 enell 3138           >SignalTransporter</interfacename> object. This
4093 18 Jan 08 enell 3139           is simply done by calling <code>Job.getSignalTransporter()</code>.
4093 18 Jan 08 enell 3140           The created signal transporter knows how to send a signal 
4093 18 Jan 08 enell 3141           to the signal receiver it was first registered with. When the
4093 18 Jan 08 enell 3142           signal arrives at the receiver it will find the handler for it
4093 18 Jan 08 enell 3143           and call <code>SignalHandler.handleSignal()</code>. This will in it's turn
4093 18 Jan 08 enell 3144           trigger some action in the signal target which soon will abort what
4093 18 Jan 08 enell 3145           it is doing and exit.
4093 18 Jan 08 enell 3146           </para>
4093 18 Jan 08 enell 3147         </listitem>
4093 18 Jan 08 enell 3148         </itemizedlist>
4093 18 Jan 08 enell 3149         
4093 18 Jan 08 enell 3150         
4093 18 Jan 08 enell 3151       </sect3>
4093 18 Jan 08 enell 3152     
4093 18 Jan 08 enell 3153     </sect2>
4093 18 Jan 08 enell 3154     
3315 09 May 07 nicklas 3155   </sect1>
3315 09 May 07 nicklas 3156
5781 04 Oct 11 nicklas 3157   <sect1 id="core_api.query">
5782 04 Oct 11 nicklas 3158     <?dbhtml filename="query_api.html" ?>
3315 09 May 07 nicklas 3159     <title>The Query API</title>
3315 09 May 07 nicklas 3160     <para>
5818 21 Oct 11 nicklas 3161       This documentation is only available in the old format which may not be up-to-date with
5818 21 Oct 11 nicklas 3162       the current implementation.
7982 14 Jun 21 nicklas 3163       See <ulink url="https://base.thep.lu.se/chrome/site/doc/historical/development/overview/query/index.html"
7982 14 Jun 21 nicklas 3164         >https://base.thep.lu.se/chrome/site/doc/historical/development/overview/query/index.html</ulink>
3315 09 May 07 nicklas 3165     </para>
3315 09 May 07 nicklas 3166     
3315 09 May 07 nicklas 3167   </sect1>
3315 09 May 07 nicklas 3168   
5781 04 Oct 11 nicklas 3169   <sect1 id="core_api.dynamic">
5782 04 Oct 11 nicklas 3170     <?dbhtml filename="dynamic_api.html" ?>
5781 04 Oct 11 nicklas 3171     <title>The Dynamic API</title>
3315 09 May 07 nicklas 3172     <para>
5818 21 Oct 11 nicklas 3173       This documentation is only available in the old format which may not be up-to-date with
5818 21 Oct 11 nicklas 3174       the current implementation.
7982 14 Jun 21 nicklas 3175       See <ulink url="https://base.thep.lu.se/chrome/site/doc/historical/development/overview/dynamic/index.html"
7982 14 Jun 21 nicklas 3176         >https://base.thep.lu.se/chrome/site/doc/historical/development/overview/dynamic/index.html</ulink>
3315 09 May 07 nicklas 3177     </para>
3315 09 May 07 nicklas 3178   </sect1>
3315 09 May 07 nicklas 3179
5781 04 Oct 11 nicklas 3180   <sect1 id="core_api.extensions">
5782 04 Oct 11 nicklas 3181     <?dbhtml filename="extensions_api.html" ?>
5781 04 Oct 11 nicklas 3182     <title>The Extensions API</title>
4206 04 Apr 08 nicklas 3183     
5781 04 Oct 11 nicklas 3184     <sect2 id="extensions_api.core">
4206 04 Apr 08 nicklas 3185       <title>The core part</title>
4206 04 Apr 08 nicklas 3186     
4206 04 Apr 08 nicklas 3187       <para>
4206 04 Apr 08 nicklas 3188         The <emphasis>Extensions API</emphasis> is divided into two parts. A core
4206 04 Apr 08 nicklas 3189         part and a web client specific part. The core part can be found in the
4223 15 Apr 08 nicklas 3190         <package>net.sf.basedb.util.extensions</package> package and it's sub-packages,
5826 26 Oct 11 nicklas 3191         and consists of two sub-parts:
4206 04 Apr 08 nicklas 3192       </para>
4206 04 Apr 08 nicklas 3193       
4206 04 Apr 08 nicklas 3194       <itemizedlist>
4206 04 Apr 08 nicklas 3195       <listitem>
4206 04 Apr 08 nicklas 3196         <para>
5826 26 Oct 11 nicklas 3197         An <classname docapi="net.sf.basedb.util.extensions.manager">ExtensionsManager</classname>
5826 26 Oct 11 nicklas 3198         that keeps track of the JAR files on the file system containing extensions code.
5826 26 Oct 11 nicklas 3199         The manager can detect new, updated and deleted files and is used to 
5826 26 Oct 11 nicklas 3200         load metadata information about the extensions and register them in the <classname 
5826 26 Oct 11 nicklas 3201         docapi="net.sf.basedb.util.extensions">Registry</classname> so that they can be used.
5826 26 Oct 11 nicklas 3202         The manager is also used to install plug-ins.
4206 04 Apr 08 nicklas 3203         </para>
4206 04 Apr 08 nicklas 3204       </listitem>
5826 26 Oct 11 nicklas 3205
4206 04 Apr 08 nicklas 3206       <listitem>
4206 04 Apr 08 nicklas 3207         <para>
5826 26 Oct 11 nicklas 3208         A set of interface definitions which forms the core of the Extensions API.
5826 26 Oct 11 nicklas 3209         The interfaces defines, for example, what an <interfacename 
5826 26 Oct 11 nicklas 3210         docapi="net.sf.basedb.util.extensions">Extension</interfacename> is,
5826 26 Oct 11 nicklas 3211         what an <interfacename 
5826 26 Oct 11 nicklas 3212         docapi="net.sf.basedb.util.extensions">ActionFactory</interfacename> should do
5826 26 Oct 11 nicklas 3213         and a few other things.
4206 04 Apr 08 nicklas 3214         </para>
4206 04 Apr 08 nicklas 3215       </listitem>
5826 26 Oct 11 nicklas 3216       </itemizedlist>
4206 04 Apr 08 nicklas 3217       
5826 26 Oct 11 nicklas 3218       <para>
5826 26 Oct 11 nicklas 3219         Let's start by looking at the extensions manager and related classes.
5826 26 Oct 11 nicklas 3220       </para>
5826 26 Oct 11 nicklas 3221       
5826 26 Oct 11 nicklas 3222       <figure id="extensions_api.figures.manager">
5826 26 Oct 11 nicklas 3223         <title>The extensions manager</title>
5826 26 Oct 11 nicklas 3224         <screenshot>
5826 26 Oct 11 nicklas 3225           <mediaobject>
5826 26 Oct 11 nicklas 3226             <imageobject>
5826 26 Oct 11 nicklas 3227               <imagedata 
5826 26 Oct 11 nicklas 3228                 align="center"
5826 26 Oct 11 nicklas 3229                 fileref="figures/uml/corelayer.extensions_manager.png" format="PNG" />
5826 26 Oct 11 nicklas 3230             </imageobject>
5826 26 Oct 11 nicklas 3231           </mediaobject>
5826 26 Oct 11 nicklas 3232         </screenshot>
5826 26 Oct 11 nicklas 3233       </figure>
5826 26 Oct 11 nicklas 3234       
5826 26 Oct 11 nicklas 3235       <para>
5826 26 Oct 11 nicklas 3236       The BASE application is using a single manager and a single registry (handled by the 
5826 26 Oct 11 nicklas 3237       <classname docapi="net.sf.basedb.core">Application</classname>) class. 
5826 26 Oct 11 nicklas 3238       The manager has been configured to look for extensions and plug-ins in the directory 
5826 26 Oct 11 nicklas 3239       specified by the <property>plugins.dir</property> setting in 
5826 26 Oct 11 nicklas 3240       <filename>base.config</filename>. Theoretically, a single manager can handle
5826 26 Oct 11 nicklas 3241       multiple directories, but we do not use that feature. The BASE core also
5826 26 Oct 11 nicklas 3242       include some special files that are added with the <methodname>addURI()</methodname>
5826 26 Oct 11 nicklas 3243       method. They contain definitions for the core extensions and core plug-ins
5826 26 Oct 11 nicklas 3244       and are shipped as XML files that reside inside the BASE core JAR files.
5826 26 Oct 11 nicklas 3245       </para>
5826 26 Oct 11 nicklas 3246       
5826 26 Oct 11 nicklas 3247       <para>
5826 26 Oct 11 nicklas 3248       The <methodname>ExtensionsManager.scanForChanges()</methodname>
5826 26 Oct 11 nicklas 3249       method is called to initiate a check for new, updated and deleted files. The
5826 26 Oct 11 nicklas 3250       manager uses the <classname docapi="net.sf.basedb.util.extensions.xml">XmlLoader</classname>
5826 26 Oct 11 nicklas 3251       to find information about each JAR or XML file it find in the directory.
5826 26 Oct 11 nicklas 3252       After the scan, the <methodname>ExtensionsManager.getFiles()</methodname> 
5826 26 Oct 11 nicklas 3253       method can be used to find more information about each individual file, for example,
5826 26 Oct 11 nicklas 3254       if it is a new or modified file, if it contains valid extension definitions and
5826 26 Oct 11 nicklas 3255       information about the author, etc. This information is used by the installation 
5826 26 Oct 11 nicklas 3256       wizard in the web client to display a dialog were the user can select which extensions 
5826 26 Oct 11 nicklas 3257       to intall. See <xref linkend="plugins.figures.installwizard" />.
5826 26 Oct 11 nicklas 3258       Note that no installation or other actions take place at this stage.
5826 26 Oct 11 nicklas 3259       </para>
5826 26 Oct 11 nicklas 3260       
5826 26 Oct 11 nicklas 3261       <para>
5826 26 Oct 11 nicklas 3262       The <methodname>ExtensionsManager.processFiles()</methodname> method is called to actually do
5826 26 Oct 11 nicklas 3263       something. It needs an <interfacename docapi="net.sf.basedb.util.extensions.manager"
5826 26 Oct 11 nicklas 3264       >ExtensionsFileProcessor</interfacename> implementation as an argument. As you can see
5826 26 Oct 11 nicklas 3265       in the diagram above there are multiple implementations (all are not
5826 26 Oct 11 nicklas 3266       shown in the diagram), each with a very specific task.  A processor is usually
5826 26 Oct 11 nicklas 3267       also paired with a filter to target it at files that fulfil some criteria, for example,
5826 26 Oct 11 nicklas 3268       only at valid extension files that has been updated. Typically, the 
5826 26 Oct 11 nicklas 3269       <methodname>ExtensionsManager.processFiles()</methodname> method need to be 
5826 26 Oct 11 nicklas 3270       called multiple times with different processor implementations to perform a full 
5826 26 Oct 11 nicklas 3271       installation of an extension or plug-in. Here is a list of the various processors
5826 26 Oct 11 nicklas 3272       currently in use in BASE.
5826 26 Oct 11 nicklas 3273       </para>
5826 26 Oct 11 nicklas 3274       
5826 26 Oct 11 nicklas 3275       <variablelist>
5826 26 Oct 11 nicklas 3276         <varlistentry>
5826 26 Oct 11 nicklas 3277           <term><classname docapi="net.sf.basedb.util.extensions.manager.processor"
5826 26 Oct 11 nicklas 3278             >RegisterExtensionsProcessor</classname></term>
5826 26 Oct 11 nicklas 3279           <listitem>
5826 26 Oct 11 nicklas 3280           <para>
5826 26 Oct 11 nicklas 3281             Is used to register
5826 26 Oct 11 nicklas 3282             extensions with the registry. Can be paired with different filters
5826 26 Oct 11 nicklas 3283             depending on when it is used. At BASE startup an <classname 
5826 26 Oct 11 nicklas 3284             docapi="net.sf.basedb.util.extensions.manager.filter">InstalledFilter</classname>
5826 26 Oct 11 nicklas 3285             is used so that only installed extensions are registered.
5826 26 Oct 11 nicklas 3286           </para>
5826 26 Oct 11 nicklas 3287           </listitem>
5826 26 Oct 11 nicklas 3288         </varlistentry>
5826 26 Oct 11 nicklas 3289
5826 26 Oct 11 nicklas 3290         <varlistentry>
5826 26 Oct 11 nicklas 3291           <term><classname docapi="net.sf.basedb.util.extensions.manager.processor"
5826 26 Oct 11 nicklas 3292             >UnregisterExtensionsProcessor</classname></term>
5826 26 Oct 11 nicklas 3293           <listitem>
5826 26 Oct 11 nicklas 3294           <para>
5826 26 Oct 11 nicklas 3295             Is used to unregister
5826 26 Oct 11 nicklas 3296             extensions when a file has been deleted. This should always be paired with
5826 26 Oct 11 nicklas 3297             for example, a <classname docapi="net.sf.basedb.util.extensions.manager.filter"
5826 26 Oct 11 nicklas 3298             >DeletedFilter</classname>.
5826 26 Oct 11 nicklas 3299           </para>
5826 26 Oct 11 nicklas 3300           </listitem>
5826 26 Oct 11 nicklas 3301         </varlistentry>
5826 26 Oct 11 nicklas 3302
5826 26 Oct 11 nicklas 3303         <varlistentry>
5826 26 Oct 11 nicklas 3304           <term><classname docapi="net.sf.basedb.util.extensions.manager.processor"
5826 26 Oct 11 nicklas 3305             >UnregisterExtensionsProcessor</classname></term>
5826 26 Oct 11 nicklas 3306           <listitem>
5826 26 Oct 11 nicklas 3307           <para>
5826 26 Oct 11 nicklas 3308             Is used to unregister
5826 26 Oct 11 nicklas 3309             extensions when a file has been deleted. This should always be paired with
5826 26 Oct 11 nicklas 3310             for example, a <classname docapi="net.sf.basedb.util.extensions.manager.filter"
5826 26 Oct 11 nicklas 3311             >DeletedFilter</classname>.
5826 26 Oct 11 nicklas 3312           </para>
5826 26 Oct 11 nicklas 3313           </listitem>
5826 26 Oct 11 nicklas 3314         </varlistentry>
5826 26 Oct 11 nicklas 3315
5826 26 Oct 11 nicklas 3316         <varlistentry>
5826 26 Oct 11 nicklas 3317           <term><classname docapi="net.sf.basedb.util.extensions.manager.processor"
5826 26 Oct 11 nicklas 3318             >ExtractResourcesProcessor</classname></term>
5826 26 Oct 11 nicklas 3319           <listitem>
5826 26 Oct 11 nicklas 3320           <para>
5826 26 Oct 11 nicklas 3321             Is used to extract
5826 26 Oct 11 nicklas 3322             files from the JAR file to a local directory. This is currently used
5826 26 Oct 11 nicklas 3323             by the web client to extract JSP files, images, etc. that are
5826 26 Oct 11 nicklas 3324             needed by web client extensions.
5826 26 Oct 11 nicklas 3325           </para>
5826 26 Oct 11 nicklas 3326           </listitem>
5826 26 Oct 11 nicklas 3327         </varlistentry>
5826 26 Oct 11 nicklas 3328
5826 26 Oct 11 nicklas 3329         <varlistentry>
5826 26 Oct 11 nicklas 3330           <term><classname docapi="net.sf.basedb.util.extensions.manager.processor"
5826 26 Oct 11 nicklas 3331             >DeleteResourcesProcessor</classname></term>
5826 26 Oct 11 nicklas 3332           <listitem>
5826 26 Oct 11 nicklas 3333           <para>
5826 26 Oct 11 nicklas 3334             The opposite of
5826 26 Oct 11 nicklas 3335             <classname>ExtractResourcesProcessor</classname>.
5826 26 Oct 11 nicklas 3336           </para>
5826 26 Oct 11 nicklas 3337           </listitem>
5826 26 Oct 11 nicklas 3338         </varlistentry>
5826 26 Oct 11 nicklas 3339
5826 26 Oct 11 nicklas 3340         <varlistentry>
5826 26 Oct 11 nicklas 3341           <term><classname docapi="net.sf.basedb.util.extensions.manager.processor"
5826 26 Oct 11 nicklas 3342             >PluginInstallationProcessor</classname></term>
5826 26 Oct 11 nicklas 3343           <listitem>
5826 26 Oct 11 nicklas 3344           <para>
5826 26 Oct 11 nicklas 3345             Is used to install and register plug-ins.
5826 26 Oct 11 nicklas 3346           </para>
5826 26 Oct 11 nicklas 3347           </listitem>
5826 26 Oct 11 nicklas 3348         </varlistentry>
5826 26 Oct 11 nicklas 3349         
5826 26 Oct 11 nicklas 3350         <varlistentry>
5826 26 Oct 11 nicklas 3351           <term><classname docapi="net.sf.basedb.util.extensions.manager.processor"
5826 26 Oct 11 nicklas 3352             >DisablePluginsProcessor</classname></term>
5826 26 Oct 11 nicklas 3353           <listitem>
5826 26 Oct 11 nicklas 3354           <para>
5826 26 Oct 11 nicklas 3355             Is used to disable plug-ins
5826 26 Oct 11 nicklas 3356             from extensions that have been removed.
5826 26 Oct 11 nicklas 3357           </para>
5826 26 Oct 11 nicklas 3358           </listitem>
5826 26 Oct 11 nicklas 3359         </varlistentry>
5826 26 Oct 11 nicklas 3360         
5826 26 Oct 11 nicklas 3361         <varlistentry>
5826 26 Oct 11 nicklas 3362           <term><classname docapi="net.sf.basedb.util.extensions.manager.processor"
5826 26 Oct 11 nicklas 3363             >MarkAsProcessedProcessor</classname></term>
5826 26 Oct 11 nicklas 3364         
5826 26 Oct 11 nicklas 3365           <listitem>
5826 26 Oct 11 nicklas 3366           <para>
5826 26 Oct 11 nicklas 3367             This is usually the final
5826 26 Oct 11 nicklas 3368             processor that is called and reset the timestamp on all processed files
5826 26 Oct 11 nicklas 3369             so that the next time <methodname>ExtensionsManger.scanForChanges()</methodname> 
5826 26 Oct 11 nicklas 3370             is called it will know what has been modified.
5826 26 Oct 11 nicklas 3371           </para>
5826 26 Oct 11 nicklas 3372           </listitem>
5826 26 Oct 11 nicklas 3373         </varlistentry>
5826 26 Oct 11 nicklas 3374       </variablelist>
5826 26 Oct 11 nicklas 3375       
5826 26 Oct 11 nicklas 3376       <note>
4206 04 Apr 08 nicklas 3377         <para>
5826 26 Oct 11 nicklas 3378         This list contains the core processors only. The web client part
5826 26 Oct 11 nicklas 3379         is using some additional processors to perform, for example, servlet
5826 26 Oct 11 nicklas 3380         registration.
4206 04 Apr 08 nicklas 3381         </para>
5826 26 Oct 11 nicklas 3382       </note>
4206 04 Apr 08 nicklas 3383       
5826 26 Oct 11 nicklas 3384       <para>
5826 26 Oct 11 nicklas 3385       The result of the processing can be collected with a <classname 
5826 26 Oct 11 nicklas 3386       docapi="net.sf.basedb.util.extensions.manager">ProcessResults</classname> object
5826 26 Oct 11 nicklas 3387       and is then displayed to the user as in <xref linkend="plugins.figures.installresults" />.
5826 26 Oct 11 nicklas 3388       All of the above is only used when BASE is starting up and initializing the extensions
5826 26 Oct 11 nicklas 3389       system or when the server administrator is performing a manual installation or update.
5826 26 Oct 11 nicklas 3390       The next diagram shows the part of the extensions system that is used when
5826 26 Oct 11 nicklas 3391       actually using the extensions for what they are intended to do (the web client adds some
5826 26 Oct 11 nicklas 3392       extra features to this as well, but that is discussed later).
5826 26 Oct 11 nicklas 3393       </para>
5826 26 Oct 11 nicklas 3394       
5826 26 Oct 11 nicklas 3395       
5781 04 Oct 11 nicklas 3396       <figure id="extensions_api.figures.core">
5826 26 Oct 11 nicklas 3397         <title>The main Extensions API</title>
4206 04 Apr 08 nicklas 3398         <screenshot>
4206 04 Apr 08 nicklas 3399           <mediaobject>
4206 04 Apr 08 nicklas 3400             <imageobject>
4206 04 Apr 08 nicklas 3401               <imagedata 
4206 04 Apr 08 nicklas 3402                 align="center"
4206 04 Apr 08 nicklas 3403                 fileref="figures/uml/corelayer.extensions_core.png" format="PNG" />
4206 04 Apr 08 nicklas 3404             </imageobject>
4206 04 Apr 08 nicklas 3405           </mediaobject>
4206 04 Apr 08 nicklas 3406         </screenshot>
4206 04 Apr 08 nicklas 3407       </figure>
4206 04 Apr 08 nicklas 3408       
4206 04 Apr 08 nicklas 3409       <para>
4206 04 Apr 08 nicklas 3410         The <classname docapi="net.sf.basedb.util.extensions">Registry</classname> 
4206 04 Apr 08 nicklas 3411         is one of the main classes in the extension system. All extension points and
4206 04 Apr 08 nicklas 3412         extensions must be registered before they can be used. Typically, you will
4206 04 Apr 08 nicklas 3413         first register extension points and then extensions, beacuse an extension
4206 04 Apr 08 nicklas 3414         can't be registered until the extension point it is extending has been
4206 04 Apr 08 nicklas 3415         registered.
4206 04 Apr 08 nicklas 3416       </para>
4206 04 Apr 08 nicklas 3417       
4206 04 Apr 08 nicklas 3418       <para>
4206 04 Apr 08 nicklas 3419         An <interfacename docapi="net.sf.basedb.util.extensions">ExtensionPoint</interfacename>
4206 04 Apr 08 nicklas 3420         is an ID and a definition of an <interfacename docapi="net.sf.basedb.util.extensions">Action</interfacename>
4206 04 Apr 08 nicklas 3421         class. The other options (name, description, renderer factory, etc.) are optional.
4206 04 Apr 08 nicklas 3422         An <interfacename docapi="net.sf.basedb.util.extensions">Extension</interfacename>
4206 04 Apr 08 nicklas 3423         that extends a specific extension point must provide an 
4206 04 Apr 08 nicklas 3424         <interfacename docapi="net.sf.basedb.util.extensions">ActionFactory</interfacename>
4206 04 Apr 08 nicklas 3425         instance that can create actions of the type the extension point requires.
4206 04 Apr 08 nicklas 3426       </para>
4206 04 Apr 08 nicklas 3427       
5781 04 Oct 11 nicklas 3428       <example id="extensions_api.example.menu">
4206 04 Apr 08 nicklas 3429         <title>The menu extensions point</title>
4206 04 Apr 08 nicklas 3430         <para>
4206 04 Apr 08 nicklas 3431         The <code>net.sf.basedb.clients.web.menu.extensions</code> extension point 
4206 04 Apr 08 nicklas 3432         requires <interfacename 
4206 04 Apr 08 nicklas 3433         docapi="net.sf.basedb.clients.web.extensions.menu">MenuItemAction</interfacename>
4206 04 Apr 08 nicklas 3434         objects. An extension for this extension point must provide a factory that
4206 04 Apr 08 nicklas 3435         can create <classname>MenuItemAction</classname>:s. BASE ships with default
4206 04 Apr 08 nicklas 3436         factory implementations, for example the <classname 
4206 04 Apr 08 nicklas 3437         docapi="net.sf.basedb.clients.web.extensions.menu">FixedMenuItemFactory</classname>
4206 04 Apr 08 nicklas 3438         class, but an extension may provide it's own factory implementation if it wants to.
4206 04 Apr 08 nicklas 3439         </para>
4206 04 Apr 08 nicklas 3440       </example>
4206 04 Apr 08 nicklas 3441       
4206 04 Apr 08 nicklas 3442       <para>
4206 04 Apr 08 nicklas 3443         Call the <methodname>Registry.useExtensions()</methodname> method
4206 04 Apr 08 nicklas 3444         to use extensions from one or several extension points. This method will
4206 04 Apr 08 nicklas 3445         find all extensions for the given extension points. If a filter is given,
4206 04 Apr 08 nicklas 3446         it checks if any of the extensions or extension points has been disabled.
4206 04 Apr 08 nicklas 3447         It will then call <methodname>ActionFactory.prepareContext()</methodname>
4206 04 Apr 08 nicklas 3448         for all remaining extensions. This gives the action factory a chance to
4206 04 Apr 08 nicklas 3449         also disable the extension, for example, if the logged in user doesn't
4223 15 Apr 08 nicklas 3450         have a required permission. The action factory may also set attributes
4206 04 Apr 08 nicklas 3451         on the context. The attributes can be anything that the extension point 
4206 04 Apr 08 nicklas 3452         may make use of. Check the documentation for the specific extension point
4206 04 Apr 08 nicklas 3453         for information about which attributes it supports. If there are
4206 04 Apr 08 nicklas 3454         any renderer factories, their <methodname>RendererFactory.prepareContext()</methodname>
4206 04 Apr 08 nicklas 3455         is also called. They have the same possibility of setting attributes
4206 04 Apr 08 nicklas 3456         on the context, but can't disable an extension.
4206 04 Apr 08 nicklas 3457       </para>
4206 04 Apr 08 nicklas 3458       
4206 04 Apr 08 nicklas 3459       <para>
4206 04 Apr 08 nicklas 3460         After this, an <classname 
4206 04 Apr 08 nicklas 3461         docapi="net.sf.basedb.util.extensions">ExtensionsInvoker</classname>
4206 04 Apr 08 nicklas 3462         object is created and returned to the extension point. Note that
4206 04 Apr 08 nicklas 3463         the <methodname>ActionFactory.getActions()</methodname> has not been 
4206 04 Apr 08 nicklas 3464         called yet, so we don't know if the extensions are actually
4206 04 Apr 08 nicklas 3465         going to generate any actions. The <methodname>ActionFactory.getActions()</methodname>
4206 04 Apr 08 nicklas 3466         is not called until we have got ourselves an 
4206 04 Apr 08 nicklas 3467         <classname docapi="net.sf.basedb.util.extensions">ActionIterator</classname>
4206 04 Apr 08 nicklas 3468         from the <methodname>ExtensionsInvoker.iterate()</methodname> method and
4206 04 Apr 08 nicklas 3469         starts to iterate. The call to <methodname>ActionIterator.hasNext()</methodname>
4206 04 Apr 08 nicklas 3470         will propagate down to <methodname>ActionFactory.getActions()</methodname>
4206 04 Apr 08 nicklas 3471         and the generated actions are then available with the 
4206 04 Apr 08 nicklas 3472         <methodname>ActionIterator.next()</methodname> method.
4206 04 Apr 08 nicklas 3473       </para>
4206 04 Apr 08 nicklas 3474       
4206 04 Apr 08 nicklas 3475       <para>
4206 04 Apr 08 nicklas 3476         The <methodname>ExtensionsInvoker.renderDefault()</methodname>
4206 04 Apr 08 nicklas 3477         and <methodname>ExtensionsInvoker.render()</methodname> are 
4206 04 Apr 08 nicklas 3478         just convenience methods that will make it easer to render
4206 04 Apr 08 nicklas 3479         the actions. The first method will of course only work if the
4206 04 Apr 08 nicklas 3480         extension point is providing a renderer factory, that can
4206 04 Apr 08 nicklas 3481         create the default renderer.
4206 04 Apr 08 nicklas 3482       </para>
4206 04 Apr 08 nicklas 3483       
4206 04 Apr 08 nicklas 3484       <note>
4206 04 Apr 08 nicklas 3485         <title>Be aware of multi-threading issues</title>
4206 04 Apr 08 nicklas 3486         <para>
4206 04 Apr 08 nicklas 3487           When you are creating extensions you must be aware that
4206 04 Apr 08 nicklas 3488           multiple threads may access the same objects at the same time.
4206 04 Apr 08 nicklas 3489           In particular, any action factory or renderer factory has to be
4206 04 Apr 08 nicklas 3490           thread-safe, since only one exists for each extension. 
4206 04 Apr 08 nicklas 3491           Action and renderer objects should be thread-safe if the
4206 04 Apr 08 nicklas 3492           factories re-use the same objects.
4206 04 Apr 08 nicklas 3493         </para>
4206 04 Apr 08 nicklas 3494       </note>
4206 04 Apr 08 nicklas 3495     
5520 23 Nov 10 nicklas 3496       <para>
5520 23 Nov 10 nicklas 3497         Any errors that happen during usage of an extension is handled by an 
5520 23 Nov 10 nicklas 3498         <interfacename docapi="net.sf.basedb.util.extensions">ErrorHandler</interfacename>. 
5520 23 Nov 10 nicklas 3499         The core provides two implementations. We usually don't want the
5520 23 Nov 10 nicklas 3500         errors to show up in the gui so the <classname 
5520 23 Nov 10 nicklas 3501         docapi="net.sf.basedb.util.extensions">LoggingErrorHandlerFactory</classname> 
5520 23 Nov 10 nicklas 3502         is the default implementation that only writes to the log file. The
5520 23 Nov 10 nicklas 3503         <classname 
5520 23 Nov 10 nicklas 3504         docapi="net.sf.basedb.util.extensions">RethrowErrorHandlerFactory</classname>
5520 23 Nov 10 nicklas 3505         error handler can be used to re-throw exceptions which usually means that
5520 23 Nov 10 nicklas 3506         they trickle up to the gui and are shown to the user. It is also
5520 23 Nov 10 nicklas 3507         possible for an extension point to provide its own implementation of 
5520 23 Nov 10 nicklas 3508         an <interfacename docapi="net.sf.basedb.util.extensions">ErrorHandlerFactory</interfacename>.
5520 23 Nov 10 nicklas 3509       </para>
5520 23 Nov 10 nicklas 3510     
4206 04 Apr 08 nicklas 3511     </sect2>
4206 04 Apr 08 nicklas 3512     
5781 04 Oct 11 nicklas 3513     <sect2 id="extensions_api.web">
4206 04 Apr 08 nicklas 3514       <title>The web client part</title>
4206 04 Apr 08 nicklas 3515     
4206 04 Apr 08 nicklas 3516       <para>
4206 04 Apr 08 nicklas 3517         The web client specific parts of the Extensions API can be found
4206 04 Apr 08 nicklas 3518         in the <package>net.sf.basedb.client.web.extensions</package> package
5826 26 Oct 11 nicklas 3519         and it's subpackages. The top-level package contains the 
5826 26 Oct 11 nicklas 3520         <classname docapi="net.sf.basedb.client.web.extensions">ExtensionsControl</classname>
5826 26 Oct 11 nicklas 3521         class which is used to administrate the extension system. It is more or
5826 26 Oct 11 nicklas 3522         less a wrapper around the <classname 
5826 26 Oct 11 nicklas 3523         docapi="net.sf.basedb.util.extensions.manager">ExtensionsManager</classname>
5826 26 Oct 11 nicklas 3524         provided by the core, but adds permission control and a few other things.
4206 04 Apr 08 nicklas 3525       </para>
4206 04 Apr 08 nicklas 3526       
4206 04 Apr 08 nicklas 3527       <para>
4206 04 Apr 08 nicklas 3528         In the top-level package there are also some abstract classes that may
4206 04 Apr 08 nicklas 3529         be useful to extend for developers creating their own extensions.
4206 04 Apr 08 nicklas 3530         For example, we recommend that all action factories extend the <classname 
4206 04 Apr 08 nicklas 3531         docapi="net.sf.basedb.client.web.extensions">AbstractJspActionFactory</classname>
5826 26 Oct 11 nicklas 3532         class. All web client extension points use the <classname 
5826 26 Oct 11 nicklas 3533         docapi="net.sf.basedb.client.web.extensions">JspContext</classname> class instead of
5826 26 Oct 11 nicklas 3534         <classname docapi="net.sf.basedb.util.extensions">ClientContext</classname>. 
5826 26 Oct 11 nicklas 3535         The JSP context provides some extra information about the current request.
4206 04 Apr 08 nicklas 3536       </para>
4206 04 Apr 08 nicklas 3537       
4206 04 Apr 08 nicklas 3538       <para>
4206 04 Apr 08 nicklas 3539         The sub-packages to <package>net.sf.basedb.client.web.extensions</package>
4206 04 Apr 08 nicklas 3540         are mostly specific to a single extension point or to a specific type of
4206 04 Apr 08 nicklas 3541         extension point. The <package>net.sf.basedb.client.web.extensions.menu</package>
4206 04 Apr 08 nicklas 3542         package, for example, contains classes that are/can be used for extensions 
4206 04 Apr 08 nicklas 3543         adding menu items to the <menuchoice><guimenu>Extensions</guimenu></menuchoice>
5826 26 Oct 11 nicklas 3544         menu. See <xref linkend="extensions_developer.base_extension_points" />
5826 26 Oct 11 nicklas 3545         for more information about the extension points defined by BASE.
4206 04 Apr 08 nicklas 3546       </para>
4206 04 Apr 08 nicklas 3547       
5781 04 Oct 11 nicklas 3548       <figure id="extensions_api.figures.web">
4206 04 Apr 08 nicklas 3549         <title>The web client part of the Extensions API</title>
4206 04 Apr 08 nicklas 3550         <screenshot>
4206 04 Apr 08 nicklas 3551           <mediaobject>
4206 04 Apr 08 nicklas 3552             <imageobject>
4206 04 Apr 08 nicklas 3553               <imagedata 
4206 04 Apr 08 nicklas 3554                 align="center"
4206 04 Apr 08 nicklas 3555                 fileref="figures/uml/corelayer.extensions_web.png" format="PNG" />
4206 04 Apr 08 nicklas 3556             </imageobject>
4206 04 Apr 08 nicklas 3557           </mediaobject>
4206 04 Apr 08 nicklas 3558         </screenshot>
4206 04 Apr 08 nicklas 3559       </figure>
4206 04 Apr 08 nicklas 3560     
4206 04 Apr 08 nicklas 3561       <para>
4223 15 Apr 08 nicklas 3562         When the Tomcat web server is starting up, the <classname 
4223 15 Apr 08 nicklas 3563         docapi="net.sf.basedb.client.web.extensions">ExtensionsServlet</classname>
4223 15 Apr 08 nicklas 3564         is automatically loaded. This servlet has as two purposes:
4223 15 Apr 08 nicklas 3565       </para>
4223 15 Apr 08 nicklas 3566       
4223 15 Apr 08 nicklas 3567       <itemizedlist>
4223 15 Apr 08 nicklas 3568       <listitem>
4223 15 Apr 08 nicklas 3569         <para>
4223 15 Apr 08 nicklas 3570         Initialise the extensions system by calling 
4206 04 Apr 08 nicklas 3571         <methodname>ExtensionsControl.init()</methodname>. This will result in
5826 26 Oct 11 nicklas 3572         an initial scan for installed extensions. This means that
4206 04 Apr 08 nicklas 3573         the extension system is up an running as soon as the first user log's
5826 26 Oct 11 nicklas 3574         in to BASE. The processing scheme is slightly different from what is done
5826 26 Oct 11 nicklas 3575         when the core is setting up the initial manager. The major additions are:
4223 15 Apr 08 nicklas 3576         </para>
5826 26 Oct 11 nicklas 3577         
5826 26 Oct 11 nicklas 3578         <itemizedlist>
5826 26 Oct 11 nicklas 3579           <listitem>
5826 26 Oct 11 nicklas 3580             <para>
5826 26 Oct 11 nicklas 3581             The <classname docapi="net.sf.basedb.client.web.extensions"
5826 26 Oct 11 nicklas 3582             >LoadServletsProcessor</classname> is used to load servlets that 
5826 26 Oct 11 nicklas 3583             has been defined in <filename>META-INF/servlets.xml</filename>.
5826 26 Oct 11 nicklas 3584             </para>
5826 26 Oct 11 nicklas 3585           </listitem>
5826 26 Oct 11 nicklas 3586           <listitem>
5826 26 Oct 11 nicklas 3587             <para>
5826 26 Oct 11 nicklas 3588             The <classname docapi="net.sf.basedb.util.extensions.manager.processor"
5826 26 Oct 11 nicklas 3589             >ExtractResourcesProcessor</classname> is used to extract all files
5826 26 Oct 11 nicklas 3590             from <filename>resources/*</filename> in the JAR file to 
5826 26 Oct 11 nicklas 3591             <filename>www/extensions/jar-name.jar/</filename>
5826 26 Oct 11 nicklas 3592             in Tomcat's web application directory.
5826 26 Oct 11 nicklas 3593             </para>
5826 26 Oct 11 nicklas 3594           </listitem>
5826 26 Oct 11 nicklas 3595         </itemizedlist>
5826 26 Oct 11 nicklas 3596         
4223 15 Apr 08 nicklas 3597       </listitem>
4206 04 Apr 08 nicklas 3598       
4223 15 Apr 08 nicklas 3599       <listitem>
4223 15 Apr 08 nicklas 3600         <para>
4223 15 Apr 08 nicklas 3601         Act as a proxy for custom servlets defined by the extensions. URL:s
4223 15 Apr 08 nicklas 3602         ending with <code>.servlet</code> has been mapped to the 
4223 15 Apr 08 nicklas 3603         <classname>ExtensionsServlet</classname>. When a request is made it
4223 15 Apr 08 nicklas 3604         will extract the name of the extension's JAR file from the
4223 15 Apr 08 nicklas 3605         URL, get the corresponding <classname 
5826 26 Oct 11 nicklas 3606         docapi="net.sf.basedb.client.web.extensions">ServletWrapper</classname>
4223 15 Apr 08 nicklas 3607         and then invoke the custom servlet. More information can be found in
4223 15 Apr 08 nicklas 3608         <xref linkend="extensions_developer.servlets" />.
4223 15 Apr 08 nicklas 3609         </para>
4223 15 Apr 08 nicklas 3610       </listitem>
4223 15 Apr 08 nicklas 3611       
4223 15 Apr 08 nicklas 3612       </itemizedlist>
4223 15 Apr 08 nicklas 3613       
4206 04 Apr 08 nicklas 3614       <para>
4206 04 Apr 08 nicklas 3615         Using extensions only involves calling the 
4206 04 Apr 08 nicklas 3616         <methodname>ExtensionsControl.createContext()</methodname> and
4206 04 Apr 08 nicklas 3617         <methodname>ExtensionsControl.useExtensions()</methodname> methods. This
4206 04 Apr 08 nicklas 3618         returns an <classname docapi="net.sf.basedb.util.extensions">ExtensionsInvoker</classname> 
4206 04 Apr 08 nicklas 3619         object as described in the previous section.
4206 04 Apr 08 nicklas 3620       </para>
4206 04 Apr 08 nicklas 3621       
4206 04 Apr 08 nicklas 3622       <para>
4206 04 Apr 08 nicklas 3623         To render the actions it is possible to either use the 
4206 04 Apr 08 nicklas 3624         <methodname>ExtensionsInvoker.iterate()</methodname> method
4206 04 Apr 08 nicklas 3625         and generate HTML from the information in each action. Or 
4223 15 Apr 08 nicklas 3626         (the better way) is to use a renderer together with the
4206 04 Apr 08 nicklas 3627         <classname docapi="net.sf.basedb.clients.web.taglib.extensions">Render</classname>
4206 04 Apr 08 nicklas 3628         taglib.
4206 04 Apr 08 nicklas 3629       </para>
4206 04 Apr 08 nicklas 3630       
4206 04 Apr 08 nicklas 3631       <para>
4206 04 Apr 08 nicklas 3632         To get information about the installed extensions,  
4206 04 Apr 08 nicklas 3633         change settings, enabled/disable extensions, performing a manual
5826 26 Oct 11 nicklas 3634         installation, etc. use the <methodname>ExtensionsControl.get()</methodname>
4206 04 Apr 08 nicklas 3635         method. This will create a permission-controlled object. All
4206 04 Apr 08 nicklas 3636         users has read permission, administrators has write permission.
4206 04 Apr 08 nicklas 3637       </para>
4206 04 Apr 08 nicklas 3638       
4206 04 Apr 08 nicklas 3639       <note>
4206 04 Apr 08 nicklas 3640         <para>
4206 04 Apr 08 nicklas 3641           The permission we check for is WRITE permission on the
4206 04 Apr 08 nicklas 3642           web client item. This means it is possible to give a user
4206 04 Apr 08 nicklas 3643           permissions to manage the extension system by assigning
4206 04 Apr 08 nicklas 3644           WRITE permission to the web client entry in the database.
4206 04 Apr 08 nicklas 3645           Do this from <menuchoice>
4206 04 Apr 08 nicklas 3646             <guimenu>Administrate</guimenu>
4206 04 Apr 08 nicklas 3647             <guimenuitem>Clients</guimenuitem>
4206 04 Apr 08 nicklas 3648           </menuchoice>.
4206 04 Apr 08 nicklas 3649         </para>
4206 04 Apr 08 nicklas 3650       </note>
4206 04 Apr 08 nicklas 3651     
4223 15 Apr 08 nicklas 3652       <para>
4223 15 Apr 08 nicklas 3653         The <classname docapi="net.sf.basedb.clients.web.extensions">XJspCompiler</classname>
4223 15 Apr 08 nicklas 3654         is mapped to handle the compilation <code>.xjsp</code> files
5826 26 Oct 11 nicklas 3655         which are regular JSP files with a different extension. The difference is that
5826 26 Oct 11 nicklas 3656         the XJSP compiler include the extension's JAR file on the class path, which
5826 26 Oct 11 nicklas 3657         means that the JSP file can use classes that would otherwise be impossible.
5826 26 Oct 11 nicklas 3658         This feature is experimental and requires installing an extra JAR into Tomcat's lib
5737 14 Sep 11 nicklas 3659         directory. See <xref linkend="plugins.installation.xjspcompiler" /> for 
4223 15 Apr 08 nicklas 3660         more information.
4223 15 Apr 08 nicklas 3661       </para>
4223 15 Apr 08 nicklas 3662     
4206 04 Apr 08 nicklas 3663     </sect2>
4206 04 Apr 08 nicklas 3664     
4206 04 Apr 08 nicklas 3665   </sect1>
4206 04 Apr 08 nicklas 3666
5782 04 Oct 11 nicklas 3667   <sect1 id="base_api.other">
3315 09 May 07 nicklas 3668     <title>Other useful classes and methods</title>
3315 09 May 07 nicklas 3669     <para>
3315 09 May 07 nicklas 3670       TODO
3315 09 May 07 nicklas 3671     </para>
3315 09 May 07 nicklas 3672   </sect1>
3315 09 May 07 nicklas 3673   
3675 16 Aug 07 jari 3674 </chapter>

Generated on Sat Oct  7 02:27:15 2023 (UTC) by svndigest 0.11.2pre (dev build 1672)