Changeset 5780

Timestamp:

Oct 4, 2011, 1:01:20 PM (11 years ago)

Author:

Nicklas Nordborg

Message:

References #1590: Documentation cleanup

Updated developer documentation "API overview". The chapter has been renamed to "The BASE API" and I intend to merge some information from the "Core developer reference" with this chapter.

Location:

trunk/doc/src

Files:

• docbook/appendix/incompatible.xml (modified) (1 diff)
• docbook/appendix/raw_data_types.xml (modified) (1 diff)
• docbook/developer/base_api.xml (moved) (moved from trunk/doc/src/docbook/developer/api_overview.xml) (64 diffs)
• docbook/developer/core_ref.xml (modified) (4 diffs)
• docbook/developer/index.xml (modified) (1 diff)
• docbook/figures/uml/datalayer.annotations.png (modified) (previous)
• docbook/figures/uml/datalayer.arrays.png (modified) (previous)
• docbook/figures/uml/datalayer.authentication.png (modified) (previous)
• docbook/figures/uml/datalayer.basic.png (modified) (previous)
• docbook/figures/uml/datalayer.bioassays.png (moved) (moved from trunk/doc/src/docbook/figures/uml/datalayer.rawdata.png)
• docbook/figures/uml/datalayer.parameters.png (modified) (previous)
• docbook/figures/uml/datalayer.plates.png (modified) (previous)
• docbook/figures/uml/datalayer.platforms.png (modified) (previous)
• docbook/figures/uml/datalayer.plugins.png (modified) (previous)
• docbook/figures/uml/datalayer.subtypes.png (deleted)
• uml/baseuml.mdzip (modified) (previous)

trunk/doc/src/docbook/appendix/incompatible.xml

@@ -30 +30 @@
     In this document we list all changes to code in the <emphasis>Public API</emphasis>
     that may be backwards incompatible with existing client applications
-    and or plug-ins. See <xref linkend="api_overview.public_api" /> for more
+    and or plug-ins. See <xref linkend="base_api.public" /> for more
     information about what we mean with the <emphasis>Public API</emphasis>
     and backwards compatible.

trunk/doc/src/docbook/appendix/raw_data_types.xml

@@ -96 +96 @@
             <entry>CEL file</entry>
             <entry>affymetrix.cel</entry>
+          </row>
+          <row>
+            <entry morerows="1">Sequencing</entry>
+            <entry morerows="1">sequencing</entry>
+            <entry morerows="1">Expression-like</entry>
+            <entry morerows="1">sequencing.expression</entry>
+            <entry>Array design</entry>
+            <entry>GTF ref-seq file</entry>
+            <entry>refseq.gtf</entry>
+          </row>
+          <row>
+            <entry>Raw bioassay</entry>
+            <entry>FPKM tracking file</entry>
+            <entry> sequencing.fpkm_tracking</entry>
           </row>
         </tbody>

trunk/doc/src/docbook/developer/base_api.xml

@@ -25 +25 @@
 -->
 
-<chapter id="api_overview">
-  <title>API overview (how to use and code examples)</title>
-
-  <sect1 id="api_overview.public_api">
+<chapter id="base_api">
+  <title>The BASE API</title>
+
+  <sect1 id="base_api.public">
     <title>The Public API of BASE</title>
     
     <para>
-      Not all public classes and methods in the <filename>BASE2Core.jar</filename>
-      and other JAR files shipped with BASE are considered as
+      Not all public classes and methods in the <filename>base-*.jar</filename>
+      files and other JAR files shipped with BASE are considered as
       <emphasis>Public API</emphasis>. This is important knowledge
       since we will always try to maintain backwards compatibility
@@ -42 +42 @@
     
     <note>
-      <title>Only use the public API when developing plug-ins</title>
-      <para>
-        This will maximize the chance that you plug-in will continue
+      <title>Only use the public API when developing plug-ins and extensions</title>
+      <para>
+        This will maximize the chance that your code will continue
         to work with the next BASE release. If you use the non-public API
         you do so at your own risk.
@@ -51 +51 @@
     
     <para>
-      See the <ulink url="http://base.thep.lu.se/chrome/site/doc/api/index.html"
-        >javadoc</ulink> for information about
+      See the <ulink url="../../api/index.html"
+        >BASE API javadoc</ulink> for information about
       what parts of the API that contributes to the public API.
       Methods, classes and other elements that have been tagged as 
@@ -60 +60 @@
     
     <para>
-      See <xref linkend="appendix.incompatible" /> to read more about
-      changes that have been introduced by each release.
+      Keeping the backwards compatibility is an aim only. It may not
+      always be possible. See <xref linkend="appendix.incompatible" /> to 
+      read more about changes that have been introduced by each release
+      that may affect existing code.
     </para>
 
-    <sect2 id="api_overview.compatibility">
+    <sect2 id="base_api.compatibility">
       <title>What is backwards compatibility?</title>
       
@@ -76 +78 @@
       
       
-      <sect3 id="api_overview.compatibility.binary">
+      <sect3 id="core_api.compatibility.binary">
         <title>Binary compatibility</title>
         <para>
@@ -102 +104 @@
       </sect3>
       
-      <sect3 id="api_overview.compatibility.contract">
+      <sect3 id="base_api.compatibility.contract">
         <title>Contract compatibility</title>
         <para>
@@ -134 +136 @@
       </sect3>
       
-      <sect3 id="api_overview.compatibility.source">
+      <sect3 id="base_api.compatibility.source">
         <title>Source code compatibility</title>
         <para>
@@ -155 +157 @@
   </sect1>
 
-  <sect1 id="api_overview.data_api" chunked="1">
-    <title>The database schema and the Data Layer API</title>
+  <sect1 id="base_api.data" chunked="1">
+    <title>The Data Layer API</title>
 
     <para>
@@ -190 +192 @@
       </para>
       
-      <sect3 id="data_api.basic.uml">
-        <title>UML diagram</title>
-        
         <figure id="data_api.figures.basic">
           <title>Basic classes and interfaces</title>
@@ -205 +204 @@
           </screenshot>
         </figure>
-      </sect3>
       
       <sect3 id="data_api.basic.classes">
@@ -399 +397 @@
         
         <varlistentry>
-          <term><classname docapi="net.sf.basedb.core.data">RegisteredData</classname></term>
+          <term><interfacename docapi="net.sf.basedb.core.data">RegisteredData</interfacename></term>
           <listitem>
             <para>
@@ -423 +421 @@
           </listitem>
         </varlistentry>
+
+        <varlistentry>
+          <term><interfacename docapi="net.sf.basedb.core.data">FileStoreEnabledData</interfacename></term>
+          <listitem>
+            <para>
+            This interface is implemented by all items that can have files with related data
+            attached to them. The file types that can be used for a specific item are usually
+            determined by the main type, the subtype or platform.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><interfacename docapi="net.sf.basedb.core.data">SubtypableData</interfacename></term>
+          <listitem>
+            <para>
+            This interface should be implemented by all items that can be subtyped.
+            Unless otherwise noted the subtype is always an optional link to
+            a <classname docapi="net.sf.basedb.core.data">ItemSubtypeData</classname>.
+            item. In the simplest form, the subtype is a kind of an annotation, but
+            for items that also implements the <interfacename 
+            docapi="net.sf.basedb.core.data">FileStoreEnabledData</interfacename>
+            interface, the subtype can be used to specify the file types that
+            are applicable for each item.
+            </para>
+          </listitem>
+        </varlistentry>
         </variablelist>
 
@@ -437 +462 @@
       </para>
       
-      <sect3 id="data_api.authentication.uml">
-        <title>UML diagram</title>
-        
         <figure id="data_api.figures.authentication">
           <title>User authentication and access control</title>
@@ -453 +475 @@
           </screenshot>
         </figure>
-      </sect3>
       
       <sect3 id="data_api.authentication.users">
@@ -473 +494 @@
       
         <para>
-          The <classname docapi="net.sf.basedb.core.data">GroupData</classname>, <classname docapi="net.sf.basedb.core.data">RoleData</classname> and 
-          <classname docapi="net.sf.basedb.core.data">ProjectData</classname> classes holds information about groups, roles 
+          The <classname docapi="net.sf.basedb.core.data">GroupData</classname>, 
+          <classname docapi="net.sf.basedb.core.data">RoleData</classname> and 
+          <classname docapi="net.sf.basedb.core.data">ProjectData</classname> classes holds 
+          information about groups, roles 
           and projects respectively. A user may be a member of any number of groups,
-          roles and/or projects. The membership in a project comes with an attached
+          roles and/or projects. New users are automatically added as members of all 
+          groups and roles that has the <varname>default</varname> property set.
+        </para>
+          
+        <para>
+          The membership in a project comes with an attached
           permission values. This is the highest permission the user has in the
           project. No matter what permission an item has been shared with the
@@ -675 +703 @@
     </sect2>
 
-    <sect2 id="data_api.wares">
-      <title>Hardware and software</title>
-      <para>
-         This section gives an overview of hardware and software in BASE.
-      </para>
-      
-      <sect3 id="data_api.wares.uml">
-        <title>UML diagram</title>
-        
-        <figure id="data_api.figures.wares">
-          <title>Hardware and software</title>
-          <screenshot>
-            <mediaobject>
-              <imageobject>
-                <imagedata 
-                  align="center"
-                  fileref="figures/uml/datalayer.wares.png" format="PNG" />
-              </imageobject>
-            </mediaobject>
-          </screenshot>
-        </figure>
-      </sect3>
-      
-      <sect3 id="data_api.wares.description">
-        <title>Hardware and software</title>
-        <para>
-          BASE is pre-installed with a set of hardware and software types. 
-          They are typically used to filter the registered hardware and software
-          depending on what a user is doing. For example, when adding raw data
-          to BASE a user can select a scanner. The GUI will display the hardware
-          that has been registered as <emphasis>scanner</emphasis> hardware types.
-          Other hardware types are <emphasis>hybridization station</emphasis>
-          and <emphasis>print robot</emphasis>. An administrator may register more
-          hardware and software types. 
-        </para>
-      </sect3>
-    </sect2>
-    
     <sect2 id="data_api.reporters">
       <title>Reporters</title>
       <para>
-         This section gives an overview of hardware and software in BASE.
-      </para>
-      
-      <sect3 id="data_api.reporters.uml">
-        <title>UML diagram</title>
-        
+         This section gives an overview of reporters in BASE.
+      </para>
+      
         <figure id="data_api.figures.reporters">
           <title>Reporters</title>
@@ -734 +721 @@
           </screenshot>
         </figure>
-      </sect3>
       
       <sect3 id="data_api.reporters.description">
@@ -809 +795 @@
       </para>
       
-      <sect3 id="data_api.quota.uml">
-        <title>UML diagram</title>
-        
         <figure id="data_api.figures.quota">
           <title>Quota and disk usage</title>
@@ -824 +807 @@
           </screenshot>
         </figure>
-      </sect3>
       
       <sect3 id="data_api.quota.description">
@@ -869 +851 @@
       </para>
       
-      <sect3 id="data_api.clients.uml">
-        <title>UML diagram</title>
-        
         <figure id="data_api.figures.clients">
           <title>Client, sessions and settings</title>
@@ -885 +864 @@
           </screenshot>
         </figure>
-      </sect3>
-      
+
       <sect3 id="data_api.clients.description">
         <title>Clients</title>
@@ -1042 +1020 @@
       </para>
 
-      <sect3 id="data_api.files.uml">
-      <title>UML diagram</title>
-      
         <figure id="data_api.figures.files">
           <title>Files and directories</title>
@@ -1057 +1032 @@
           </screenshot>
         </figure>
-      </sect3>
-      
-      <sect3 id="data_api.files.description">
-        <title>Description</title>
-        
+      
         <para>
           The <classname docapi="net.sf.basedb.core.data">DirectoryData</classname> class holds
@@ -1171 +1142 @@
         <para>
           The <classname docapi="net.sf.basedb.core.data">FileServerData</classname> class 
-          holds information about an external file server. The <varname>username</varname>
-          and <varname>password</varname> properties are used if the server requires the
-          user to be logged in. BASE supports Basic and Digest authentication.
-          The <varname>serverCertificate</varname> can be used with HTTPS servers that uses
-          a non-trusted certificate to tell BASE to trust the server anyway. In most cases,
-          this is only needed if the server uses a self-signed certificate, but could, for 
+          holds information about an external file server. If the <varname>connectionManagerFactory</varname>
+          isn't set BASE automatically selects a factory based on the URL of the file. There is
+          built-in support for HTTP and HTTPS, but it is possible to install extensions for
+          support for other protocols. The <varname>host</varname> property can be set
+          to override the host part of the URL from the file. See <xref 
+          linkend="extensions_developer.connection_manager" /> for more
+          information about connection managers.
+        </para>
+        
+        <para>
+          The <varname>username</varname> and <varname>password</varname> properties are used if 
+          the server requires the user to be logged in. BASE has built-in support for Basic and 
+          Digest authentication. The <varname>serverCertificate</varname> can be used with HTTPS 
+          servers that uses a non-trusted certificate to tell BASE to trust the server anyway. 
+          In most cases, this is only needed if the server uses a self-signed certificate, but could, for 
           example, also be used if a trusted site has forgot to renew an expired certificate. 
           The server certificate should be an X.509 certificate in either binary or text format.
@@ -1199 +1179 @@
           The extension of a MIME type must be unique. Extensions should be registered 
           without a dot, ie <emphasis>html</emphasis>, not <emphasis>.html</emphasis>.  
-        </para>
-        
-      </sect3>
-      
+        </para> 
       
     </sect2>
     
     <sect2 id="data_api.platforms">
-      <title>Experimental platforms</title>
+      <title>Experimental platforms and item subtypes</title>
 
       <para>
          This section gives an overview of experimental platforms
          and how they are used to enable data storage in files
-         instead of in the database.
+         instead of in the database. In some senses item subtypes
+         are related to platforms so they are also included here.
       </para>
       
@@ -1219 +1197 @@
         <listitem><xref linkend="core_api.data_in_files" /></listitem>
         <listitem><xref linkend="appendix.rawdatatypes.platforms" /></listitem>
-        <listitem><xref linkend="plugin_developer.other.datafiles" /></listitem>
+        <listitem><xref linkend="extensions_developer.fileset_validator" /></listitem>
       </itemizedlist>
           
-      <sect3 id="data_api.platforms.uml">
-        <title>UML diagram</title>
-        
         <figure id="data_api.figures.platforms">
-          <title>Experimental platforms</title>
+          <title>Experimental platforms and item subtypes</title>
           <screenshot>
             <mediaobject>
@@ -1237 +1212 @@
           </screenshot>
         </figure>
-      </sect3>
-      
+
       <sect3 id="data_api.platforms.platforms">
         <title>Platforms</title>
@@ -1272 +1246 @@
           by a fixed, non-changable external ID. The <varname>itemType</varname>
           property tells us what type of item the file holds data for (ie. 
-          array design or raw bioassay). It also links to a <classname docapi="net.sf.basedb.core.data">FileType</classname>
+          array design or raw bioassay). It also links to a <classname 
+          docapi="net.sf.basedb.core.data">ItemSubtype</classname>
           which is the generic type of data in the file. This allows us to query
           the database for, as an example, files with the generic type
@@ -1282 +1257 @@
           The <varname>required</varname> flag in <classname docapi="net.sf.basedb.core.data">PlatformFileTypeData</classname>
           is used to signal that the file is a required file. This is not 
-          enforeced by the core. It is intended to be used by client applications
+          enforced by the core. It is intended to be used by client applications
           for creating a better GUI and for validation of an experiment.
         </para>
-
+        <para>
+          The <varname>allowMultiple</varname> flag in <classname 
+          docapi="net.sf.basedb.core.data">PlatformFileTypeData</classname>
+          controls if it should be possible to store more than one file of
+          the given type in file type. Again, this is not enforced by the core,
+          but only a recommendation to client applications. The setting is
+          also used for validation of an experiment.
+        </para>
+
+      </sect3>
+      
+      <sect3 id="data_api.platforms.subtypes">
+        <title>Item subtypes</title>
+        
+        <para>
+          The <classname docapi="net.sf.basedb.core.data">ItemSubtypeData</classname> 
+          class describes a subtype for a main <varname>itemType</varname>. In the simplest 
+          form the subtype is a kind of annotation that is used mainly for creating a 
+          better user experience. If the main item type is also implementing the
+          <interfacename docapi="net.sf.basedb.core.data">FileStoreEnabledData</interfacename> 
+          interface, it is possible to
+          register associations to the file types that can be used together with a given
+          item subtype. The <varname>required</varname> and <varname>allowMultiple</varname>
+          have are used in the same way as in the <classname>PlatformFileTypeData</classname>
+          class.
+        </para>
+        
+        <para>
+          A subtype can be related to other subtypes. This is used to "chain" together 
+          groups of item subtypes. For example, <constant>Hybridization</constant>
+          is a subtype for <constant>PHYSICALBIOASSAY</constant>, which is related to
+          the <constant>Labeled extract (EXTRACT)</constant> subtype which is related to 
+          the <constant>Label (TAG)</constant> subtype. In addition, there are also
+          several protocol and hardware subetypes mixed into this. The relationship between
+          subtypes makes it possible for client applications to filter out unrelated stuff,
+          and to validate experiments.
+        </para>
+        
       </sect3>
       
@@ -1292 +1304 @@
         
         <para>
-          An item must implement the <interfacename docapi="net.sf.basedb.core">FileStoreEnabledData</interfacename>
+          An item must implement the <interfacename docapi="net.sf.basedb.core.data">FileStoreEnabledData</interfacename>
           interface to be able to store data in files instead of in the database.
           The interface creates a link to a <classname docapi="net.sf.basedb.core.data">FileSetData</classname> object,
           which can hold several <classname docapi="net.sf.basedb.core.data">FileSetMemberData</classname> items.
           Each member points to specific <classname docapi="net.sf.basedb.core.data">FileData</classname> item.
-          A file set can only store one file of each <classname docapi="net.sf.basedb.core.data">DataFileTypeData</classname>.
         </para>
         
@@ -1312 +1323 @@
       </para>
       
-      <sect3 id="data_api.parameters.uml">
-        <title>UML diagram</title>
-        
         <figure id="data_api.figures.parameters">
           <title>Parameters</title>
@@ -1327 +1335 @@
           </screenshot>
         </figure>
-      </sect3>
-      
-      <sect3 id="data_api.parameters.description">
-        <title>Parameters</title>
-        
+      
         <para>
           The parameter system is a generic system that can store almost
           any kind of simple values (string, numbers, dates, etc.) and
-          also links to other items. The <classname docapi="net.sf.basedb.core.data">ParameterValueData</classname> 
+          also links to other items. It is, for example, used to store configuration
+          parameters to plug-ins and jobs as well as annotation values to annotatable items.
+          The <classname docapi="net.sf.basedb.core.data">ParameterValueData</classname> 
           class is an abstract base class that can hold multiple values (all must be of the
           same type). Unless only a specific type of values should be stored, this is 
           the class that should be used when creating references for storing parameter
-          values. It makes it possible for a single relaltion to use any kind of
+          values. It makes it possible for a single relation to use any kind of
           values or for a collection reference to mix multiple types of values.
           A typical use case maps a <classname>Map</classname> with the 
@@ -1380 +1386 @@
 </programlisting>
 
-      </sect3>
-      
     </sect2>
 
@@ -1392 +1396 @@
       </para>
       
-      <sect3 id="data_api.annotations.uml">
-        <title>UML diagram</title>
-        
         <figure id="data_api.figures.annotations">
           <title>Annotations</title>
@@ -1407 +1408 @@
           </screenshot>
         </figure>
-      </sect3>
       
       <sect3 id="data_api.annotations.description">
@@ -1480 +1480 @@
         are treated a bit differently. They will not show up as annotations 
         to items with a type found in the <property>itemTypes</property> collection.
-        A protocol parameter should be attached to a protocol. Then, when an item 
+        Instead, a protocol parameter should be attached to a protocol. Then, when an item 
         is using that protocol it becomes possible to add annotation values for 
         the annotation types specified as protocol parameters. It doesn't matter 
@@ -1570 +1570 @@
 
     <sect2 id="data_api.protocols">
-      <title>Protocols</title>
+      <title>Protocols, hardware and software</title>
 
       <para>
@@ -1577 +1577 @@
       </para>
       
-      <sect3 id="data_api.protocols.uml">
-        <title>UML diagram</title>
-        
         <figure id="data_api.figures.protocols">
-          <title>Protocols</title>
+          <title>Protocols, hardware and software</title>
           <screenshot>
             <mediaobject>
@@ -1592 +1589 @@
           </screenshot>
         </figure>
-      </sect3>
       
       <sect3 id="data_api.protocols.description">
@@ -1599 +1595 @@
         <para>
         A protocol is something that defines a procedure or recipe for some
-        kind of action, such as sampling, extraction and scanning. In BASE we only
-        store a short name and description. It is possible to attach a file
-        that provides a longer description of the procedure.
+        kind of action, such as sampling, extraction and scanning. The subtype
+        of the protocol is used to determine what the protocol is used for. 
+        In BASE we only store a short name and description. It is possible to 
+        attach a file that provides a longer description of the procedure.
         </para>
       
@@ -1622 +1619 @@
       
       </sect3>
+
+      <sect3 id="data_api.wares.description">
+        <title>Hardware and software</title>
+        <para>
+          BASE is pre-installed with a set of subtypes for hardware and software. 
+          They are typically used to filter the registered hardware and software
+          depending on what a user is doing. For example, when adding raw data
+          to BASE a user can select a scanner. The GUI will display the hardware
+          that has been registered as <emphasis>scanner</emphasis> subtype.
+          Other subtypes are <emphasis>hybridization station</emphasis>
+          and <emphasis>print robot</emphasis>. An administrator may register more
+          subtypes. 
+        </para>
+      </sect3>
       
     </sect2>
@@ -1638 +1649 @@
       </itemizedlist>
       
-      <sect3 id="data_api.plugins.uml">
-        <title>UML diagram</title>
-        
         <figure id="data_api.figures.plugins">
           <title>Plug-ins, jobs and job agents</title>
@@ -1654 +1662 @@
           </screenshot>
         </figure>
-      </sect3>
 
       <sect3 id="data_api.plugins.plugins">
@@ -1759 +1766 @@
         <listitem>
           <para>
+            ABORTING (status = 6): The job is executing but an ABORT signal has been sent
+            requesting it to abort and finish.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
             DONE (status = 3): The job finished successfully.
           </para>
@@ -1779 +1792 @@
           and the <classname docapi="net.sf.basedb.core.data">JobAgentSettingsData</classname> links the agent
           with the plug-ins the agent is able to execute. The job agent will only 
-          execute jobs that are owner by users or projects that the job agent has 
+          execute jobs that are owned by users or projects that the job agent has 
           been shared to with at least use permission. The <property>priorityBoost</property>
           property can be used to give specific plug-ins higher priority.
@@ -1817 +1830 @@
       <title>Biomaterial LIMS</title>
       
-      <sect3 id="data_api.biomaterials.uml">
-        <title>UML diagram</title>
-        
         <figure id="data_api.figures.biomaterials">
           <title>Biomaterial LIMS</title>
@@ -1832 +1842 @@
           </screenshot>
         </figure>
-      </sect3>
       
       <sect3 id="data_api.biomaterials.description">
-        <title>Biomaterial LIMS</title>
-        
-        <para>
-          There are four types of biomaterials: <classname docapi="net.sf.basedb.core.data">BioSourceData</classname>, 
-          <classname docapi="net.sf.basedb.core.data">SampleData</classname>, <classname docapi="net.sf.basedb.core.data">ExtractData</classname> and 
-          <classname docapi="net.sf.basedb.core.data">LabeledExtractData</classname>.
-          All four types of are derived from the base class <classname docapi="net.sf.basedb.core.data">BioMaterialData</classname>. 
+        <title>Biomaterials</title>
+        
+        <para>
+          There are three main types of biomaterials: <classname docapi="net.sf.basedb.core.data">BioSourceData</classname>, 
+          <classname docapi="net.sf.basedb.core.data">SampleData</classname> and 
+          <classname docapi="net.sf.basedb.core.data">ExtractData</classname>.
+          All types of are derived from the base class <classname docapi="net.sf.basedb.core.data">BioMaterialData</classname>. 
           The reason for this is that they all share common functionality such as pooling 
           and events. By using a common base class we do not have to create duplicate 
@@ -1855 +1864 @@
         <para>
           The <classname docapi="net.sf.basedb.core.data">MeasuredBioMaterialData</classname> class is used as a base 
-          class for the other three biomaterial types. It introduces quantity 
+          class for the other biomaterial types. It introduces quantity 
           measurements and can store original and remaining quantities. They are 
           both optional. If an original quantity has been specified the core 
@@ -1864 +1873 @@
         <para>
           All measured biomaterial have at least one event associated with them, 
-          the creation event, which holds information about the creation of the 
+          the <emphasis>creation event</emphasis>, which holds information about the creation of the 
           biomaterial. A measured biomaterial can be created in three ways:
         </para>
@@ -1871 +1880 @@
         <listitem>
           <para>
-          From a single item of the parent type. Biosource is the parent type of 
-          samples, sample is the parent type of extracts, and extract is the
-          parent type of labeled extracts. In this case the 
-          <property>pooled</property> property is <constant>false</constant>
-          and the parent is specified in the <property>parent</property> property. 
-          If the parent is not a <classname docapi="net.sf.basedb.core.data">BioSourceData</classname> this information 
-          is duplicated, with the addition of an optional used quantity value, in the 
-          <property>sources</property> collection of the <classname docapi="net.sf.basedb.core.data">BioMaterialEventData</classname>
+          From a single item of the same type or the parent type. Biosource is the parent type of 
+          samples and sample is the parent type of extracts. The <property>parentType</property> 
+          property must be set to the correct parent type and the <property>parent</property> property
+          is set to point to the parent item. The parent information
+          is also always duplicated in the <property>sources</property> collection of the <classname docapi="net.sf.basedb.core.data">BioMaterialEventData</classname>
           object representing the creation event. It is the responsibility of the 
           core to make sure that everything is properly synchronized and that 
@@ -1887 +1893 @@
         <listitem>
           <para>
-          From one or more items of the same type, i.e pooling.
-          In this case the <property>pooled</property> property is <constant>true</constant> 
-          and the <property>parent</property> property is null. All source 
+          From multiple items of the same type, i.e pooling.
+          In this case the <property>parentType</property> property is set, but
+          the <property>parent</property> property is null. All source 
           biomaterials are contained in the <property>sources</property> collection. 
           The core is still responsible for keeping everything synchronized and to
@@ -1898 +1904 @@
         <listitem>
           <para>
-          As a standalone biomaterial without parents.
+          As a standalone biomaterial without parents. The <property>parentType</property>
+          property should be null, as should the <property>parent</property> property
+          and the <property>sources</property> collection.
           </para>
         </listitem>
@@ -1970 +1978 @@
           biomaterial. The <property>sources</property> collection contains 
           information about the biomaterials that were used to create the new 
-          biomaterial. If the biomaterial is a pooled biomaterial all sources must 
-          be of the same type. Otherwise there can only be one source of the parent 
-          type. These rules are maintained by the core.
-          </para>
-        </listitem>
-        
-        <listitem>
-          <para>
-          <emphasis>Hybridization event</emphasis>: This event represents the creation 
-          of a hybridization. This event type is needed because we want to keep track
-          of quantities for labeled extracts. This event has a hybridization as a 
-          product instead of a biomaterial. The sources collection can only contain 
-          labeled extracts.
+          biomaterial. All sources must be of the same type. There can only be one 
+          source of the parent type. These rules are maintained by the core.
+          </para>
+        </listitem>
+        
+        <listitem>
+          <para>
+          <emphasis>Bioassay event</emphasis>: This event represents the creation 
+          of a bioassay. This event type is needed because we want to keep track
+          of quantities for extracts. This event has a <classname docapi="net.sf.basedb.core.data">PhysicalBioAssayData</classname> 
+          as a product instead of a biomaterial. The sources collection can only contain 
+          extracts. If the bioassay can hold extracts in multiple positions the
+          <property>position</property> property in <classname docapi="net.sf.basedb.core.data">BioMaterialEventSourceData</classname> 
+          can be used to track which extract that was put in each position. It is allowed
+          to put multiple extracts in the same position, but then the usually need
+          to use different <classname docapi="net.sf.basedb.core.data">TagData</classname> 
+          items. However, this is not enforced by the core.
           </para>
         </listitem>
@@ -2015 +2027 @@
       <title>Array LIMS - plates</title>
 
-      <sect3 id="data_api.plates.uml">
-        <title>UML diagram</title>
-        
         <figure id="data_api.figures.plates">
           <title>Array LIMS - plates</title>
@@ -2031 +2040 @@
           </screenshot>
         </figure>
-      </sect3>
 
       <sect3 id="data_api.plates.description">
@@ -2111 +2119 @@
       <title>Array LIMS - arrays</title>
       
-      <sect3 id="data_api.arrays.uml">
-        <title>UML diagram</title>
-        
         <figure id="data_api.figures.arrays">
           <title>Array LIMS - arrays</title>
@@ -2126 +2131 @@
           </screenshot>
         </figure>
-      </sect3>
       
       <sect3 id="data_api.arrays.designs">
@@ -2184 +2188 @@
     </sect2>
 
-    <sect2 id="data_api.rawdata">
-      <title>Hybridizations and raw data</title>
-      
-      <sect3 id="data_api.rawdata.uml">
-        <title>UML diagram</title>
-        
+    <sect2 id="data_api.bioassays">
+      <title>Bioassays and raw data</title>
+      
         <figure id="data_api.figures.rawdata">
-          <title>Hybridizations and raw data</title>
+          <title>Bioassays and raw data</title>
           <screenshot>
             <mediaobject>
@@ -2198 +2199 @@
                   align="center"
                   scalefit="1" width="100%"
-                  fileref="figures/uml/datalayer.rawdata.png" format="PNG" />
+                  fileref="figures/uml/datalayer.bioassays.png" format="PNG" />
               </imageobject>
             </mediaobject>
           </screenshot>
         </figure>
-      </sect3>
-      
-      <sect3 id="data_api.rawdata.hybridizations">
-        <title>Hybridizations</title>
-        
-        <para>
-        Hybridizations connects the slides from the Array LIMS part
-        with labeled extracts from the biomaterials part. The <property>creationEvent</property>
-        is used to register which labeled extracts that were used on the hybridization.
+      
+      <sect3 id="data_api.bioassays.physical">
+        <title>Physical bioassays</title>
+        
+        <para>
+        A <classname docapi="net.sf.basedb.core.data">PhysicalBioAssayData</classname>
+        item connect the array slides from the Array LIMS part
+        with extracts from the biomaterials part. The <property>creationEvent</property>
+        is used to register which extracts that were used on the bioassay.
         The relation to slides is a one-to-one relation. A slide can only be used on 
-        a single hybridization and a hybridization can only use a single slide. The relation
+        a single physical bioassay and a bioassay can only use a single slide. The relation
         is optional from both sides.
         </para>
 
         <para>
-        The scanning of the hybridized slide is registered as separate scan events.
-        One or more images can optionally be attached to each scan. 
-        The images are not used by BASE.
-        </para>
-        
-      </sect3>
-      
-      <sect3 id="data_api.rawdata.description">
+        Further processing of the bioassay is registered as a series
+        of <classname docapi="net.sf.basedb.core.data">DerivedBioAssayData</classname>
+        items. For microarray experiments the first step is typically a scanning
+        of the hybridization. Information about the software/hardware and protocol
+        used can be registered. Any data files generated by the process can be
+        registered with the <classname docapi="net.sf.basedb.core.data">FileSetData</classname>
+        item. If more than one processsing step is required child derived
+        bioassays can be created that descrive each additional step.  
+        </para>
+        
+        <para>
+        If the root physical bioassay has multiple extracts in multiple positions, the
+        <property>extract</property> property of a derived bioassay is used to link
+        with the extract that the specific derived bioassay represents. If the
+        link is null the derived bioassay represents all extracts on the
+        physical bioassay.
+        </para>
+        
+      </sect3>
+      
+      <sect3 id="data_api.bioassays.rawdata">
         <title>Raw data</title>
         
         <para>
-        A <classname docapi="net.sf.basedb.core.data">RawBioAssayData</classname> object represents
-        the raw data that is produced by analysing the image(s) from a
-        single scan. You may register which software that was used, the
+        A <classname docapi="net.sf.basedb.core.data">RawBioAssayData</classname> object 
+        represents the raw data that is produced by analysing the data from the physical
+        bioassay. You may register which software that was used, the
         protocol and any parameters (through the annotation system).
         </para>
@@ -2237 +2251 @@
         <para>
         Files with the analysed data values can be attached to the 
-        associated <classname docapi="net.sf.basedb.core.data">FileSetData</classname> object. The platform
-        and, optionally, the variant has information about the file types
+        associated <classname docapi="net.sf.basedb.core.data">FileSetData</classname> object. 
+        The platform and, optionally, the variant has information about the file types
         that can be used for that platform. If the platform file types support 
         metadata extraction, headers, the number of spots, and other 
@@ -2277 +2291 @@
       
       
-      <sect3 id="data_api.experiments.uml">
-        <title>UML diagram</title>
-        
         <figure id="data_api.figures.experiments">
           <title>Experiments</title>
@@ -2293 +2304 @@
           </screenshot>
         </figure>
-      </sect3>
       
       <sect3 id="data_api.experiments.description">
@@ -2510 +2520 @@
       <title>Other classes</title>
       
-      <sect3 id="data_api.misc.uml">
-        <title>UML diagram</title>
-        
         <figure id="data_api.figures.misc">
           <title>Other classes</title>
@@ -2525 +2532 @@
           </screenshot>
         </figure>
-      </sect3>
       
     </sect2>

trunk/doc/src/docbook/developer/core_ref.xml

@@ -102 +102 @@
         <para>
         Identify things that may affect backwards compatibility. For more 
-        information about such things read <xref linkend="api_overview.public_api" />
+        information about such things read <xref linkend="base_api.public" />
         and <xref linkend="core_ref.rules.compatibility" />.
         </para>
@@ -508 +508 @@
             documentation to mark that part of the code as an internal API that should
             not be used by plug-ins and other client code. See
-            <xref linkend="api_overview.public_api" />.
+            <xref linkend="base_api.public" />.
             </para>
           </listitem>
@@ -844 +844 @@
             <para>
             Not all code in BASE is considered to be part of the public
-            API. See <xref linkend="api_overview.public_api" /> and
+            API. See <xref linkend="base_api.public" /> and
             <ulink url="../../../api/index.html">the javadoc</ulink> 
             for information about the public API. Changes made to
@@ -2371 +2371 @@
           and may implement any of the interfaces if needed. The strucure is similar to the 
           structure found in the <code>net.sf.basedb.core.data</code> package 
-          (See <xref linkend="api_overview.data_api" />). 
+          (See <xref linkend="base_api.data" />). 
         </para>
 

trunk/doc/src/docbook/developer/index.xml

@@ -32 +32 @@
   <include file="extensions.xml" />
   <include file="webservices.xml"/>
-  <include file="api_overview.xml"/>
+  <include file="base_api.xml"/>
   <include file="documentation.xml"/>
   <include file="core_ref.xml"/>