Changeset 5780


Ignore:
Timestamp:
Oct 4, 2011, 1:01:20 PM (10 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:
1 deleted
13 edited
2 moved

Legend:

Unmodified
Added
Removed
  • trunk/doc/src/docbook/appendix/incompatible.xml

    r5677 r5780  
    3030    In this document we list all changes to code in the <emphasis>Public API</emphasis>
    3131    that may be backwards incompatible with existing client applications
    32     and or plug-ins. See <xref linkend="api_overview.public_api" /> for more
     32    and or plug-ins. See <xref linkend="base_api.public" /> for more
    3333    information about what we mean with the <emphasis>Public API</emphasis>
    3434    and backwards compatible.
  • trunk/doc/src/docbook/appendix/raw_data_types.xml

    r5678 r5780  
    9696            <entry>CEL file</entry>
    9797            <entry>affymetrix.cel</entry>
     98          </row>
     99          <row>
     100            <entry morerows="1">Sequencing</entry>
     101            <entry morerows="1">sequencing</entry>
     102            <entry morerows="1">Expression-like</entry>
     103            <entry morerows="1">sequencing.expression</entry>
     104            <entry>Array design</entry>
     105            <entry>GTF ref-seq file</entry>
     106            <entry>refseq.gtf</entry>
     107          </row>
     108          <row>
     109            <entry>Raw bioassay</entry>
     110            <entry>FPKM tracking file</entry>
     111            <entry> sequencing.fpkm_tracking</entry>
    98112          </row>
    99113        </tbody>
  • trunk/doc/src/docbook/developer/base_api.xml

    r5774 r5780  
    2525-->
    2626
    27 <chapter id="api_overview">
    28   <title>API overview (how to use and code examples)</title>
    29 
    30   <sect1 id="api_overview.public_api">
     27<chapter id="base_api">
     28  <title>The BASE API</title>
     29
     30  <sect1 id="base_api.public">
    3131    <title>The Public API of BASE</title>
    3232   
    3333    <para>
    34       Not all public classes and methods in the <filename>BASE2Core.jar</filename>
    35       and other JAR files shipped with BASE are considered as
     34      Not all public classes and methods in the <filename>base-*.jar</filename>
     35      files and other JAR files shipped with BASE are considered as
    3636      <emphasis>Public API</emphasis>. This is important knowledge
    3737      since we will always try to maintain backwards compatibility
     
    4242   
    4343    <note>
    44       <title>Only use the public API when developing plug-ins</title>
    45       <para>
    46         This will maximize the chance that you plug-in will continue
     44      <title>Only use the public API when developing plug-ins and extensions</title>
     45      <para>
     46        This will maximize the chance that your code will continue
    4747        to work with the next BASE release. If you use the non-public API
    4848        you do so at your own risk.
     
    5151   
    5252    <para>
    53       See the <ulink url="http://base.thep.lu.se/chrome/site/doc/api/index.html"
    54         >javadoc</ulink> for information about
     53      See the <ulink url="../../api/index.html"
     54        >BASE API javadoc</ulink> for information about
    5555      what parts of the API that contributes to the public API.
    5656      Methods, classes and other elements that have been tagged as
     
    6060   
    6161    <para>
    62       See <xref linkend="appendix.incompatible" /> to read more about
    63       changes that have been introduced by each release.
     62      Keeping the backwards compatibility is an aim only. It may not
     63      always be possible. See <xref linkend="appendix.incompatible" /> to
     64      read more about changes that have been introduced by each release
     65      that may affect existing code.
    6466    </para>
    6567
    66     <sect2 id="api_overview.compatibility">
     68    <sect2 id="base_api.compatibility">
    6769      <title>What is backwards compatibility?</title>
    6870     
     
    7678     
    7779     
    78       <sect3 id="api_overview.compatibility.binary">
     80      <sect3 id="core_api.compatibility.binary">
    7981        <title>Binary compatibility</title>
    8082        <para>
     
    102104      </sect3>
    103105     
    104       <sect3 id="api_overview.compatibility.contract">
     106      <sect3 id="base_api.compatibility.contract">
    105107        <title>Contract compatibility</title>
    106108        <para>
     
    134136      </sect3>
    135137     
    136       <sect3 id="api_overview.compatibility.source">
     138      <sect3 id="base_api.compatibility.source">
    137139        <title>Source code compatibility</title>
    138140        <para>
     
    155157  </sect1>
    156158
    157   <sect1 id="api_overview.data_api" chunked="1">
    158     <title>The database schema and the Data Layer API</title>
     159  <sect1 id="base_api.data" chunked="1">
     160    <title>The Data Layer API</title>
    159161
    160162    <para>
     
    190192      </para>
    191193     
    192       <sect3 id="data_api.basic.uml">
    193         <title>UML diagram</title>
    194        
    195194        <figure id="data_api.figures.basic">
    196195          <title>Basic classes and interfaces</title>
     
    205204          </screenshot>
    206205        </figure>
    207       </sect3>
    208206     
    209207      <sect3 id="data_api.basic.classes">
     
    399397       
    400398        <varlistentry>
    401           <term><classname docapi="net.sf.basedb.core.data">RegisteredData</classname></term>
     399          <term><interfacename docapi="net.sf.basedb.core.data">RegisteredData</interfacename></term>
    402400          <listitem>
    403401            <para>
     
    423421          </listitem>
    424422        </varlistentry>
     423
     424        <varlistentry>
     425          <term><interfacename docapi="net.sf.basedb.core.data">FileStoreEnabledData</interfacename></term>
     426          <listitem>
     427            <para>
     428            This interface is implemented by all items that can have files with related data
     429            attached to them. The file types that can be used for a specific item are usually
     430            determined by the main type, the subtype or platform.
     431            </para>
     432          </listitem>
     433        </varlistentry>
     434
     435        <varlistentry>
     436          <term><interfacename docapi="net.sf.basedb.core.data">SubtypableData</interfacename></term>
     437          <listitem>
     438            <para>
     439            This interface should be implemented by all items that can be subtyped.
     440            Unless otherwise noted the subtype is always an optional link to
     441            a <classname docapi="net.sf.basedb.core.data">ItemSubtypeData</classname>.
     442            item. In the simplest form, the subtype is a kind of an annotation, but
     443            for items that also implements the <interfacename
     444            docapi="net.sf.basedb.core.data">FileStoreEnabledData</interfacename>
     445            interface, the subtype can be used to specify the file types that
     446            are applicable for each item.
     447            </para>
     448          </listitem>
     449        </varlistentry>
    425450        </variablelist>
    426451
     
    437462      </para>
    438463     
    439       <sect3 id="data_api.authentication.uml">
    440         <title>UML diagram</title>
    441        
    442464        <figure id="data_api.figures.authentication">
    443465          <title>User authentication and access control</title>
     
    453475          </screenshot>
    454476        </figure>
    455       </sect3>
    456477     
    457478      <sect3 id="data_api.authentication.users">
     
    473494     
    474495        <para>
    475           The <classname docapi="net.sf.basedb.core.data">GroupData</classname>, <classname docapi="net.sf.basedb.core.data">RoleData</classname> and
    476           <classname docapi="net.sf.basedb.core.data">ProjectData</classname> classes holds information about groups, roles
     496          The <classname docapi="net.sf.basedb.core.data">GroupData</classname>,
     497          <classname docapi="net.sf.basedb.core.data">RoleData</classname> and
     498          <classname docapi="net.sf.basedb.core.data">ProjectData</classname> classes holds
     499          information about groups, roles
    477500          and projects respectively. A user may be a member of any number of groups,
    478           roles and/or projects. The membership in a project comes with an attached
     501          roles and/or projects. New users are automatically added as members of all
     502          groups and roles that has the <varname>default</varname> property set.
     503        </para>
     504         
     505        <para>
     506          The membership in a project comes with an attached
    479507          permission values. This is the highest permission the user has in the
    480508          project. No matter what permission an item has been shared with the
     
    675703    </sect2>
    676704
    677     <sect2 id="data_api.wares">
    678       <title>Hardware and software</title>
    679       <para>
    680          This section gives an overview of hardware and software in BASE.
    681       </para>
    682      
    683       <sect3 id="data_api.wares.uml">
    684         <title>UML diagram</title>
    685        
    686         <figure id="data_api.figures.wares">
    687           <title>Hardware and software</title>
    688           <screenshot>
    689             <mediaobject>
    690               <imageobject>
    691                 <imagedata
    692                   align="center"
    693                   fileref="figures/uml/datalayer.wares.png" format="PNG" />
    694               </imageobject>
    695             </mediaobject>
    696           </screenshot>
    697         </figure>
    698       </sect3>
    699      
    700       <sect3 id="data_api.wares.description">
    701         <title>Hardware and software</title>
    702         <para>
    703           BASE is pre-installed with a set of hardware and software types.
    704           They are typically used to filter the registered hardware and software
    705           depending on what a user is doing. For example, when adding raw data
    706           to BASE a user can select a scanner. The GUI will display the hardware
    707           that has been registered as <emphasis>scanner</emphasis> hardware types.
    708           Other hardware types are <emphasis>hybridization station</emphasis>
    709           and <emphasis>print robot</emphasis>. An administrator may register more
    710           hardware and software types.
    711         </para>
    712       </sect3>
    713     </sect2>
    714    
    715705    <sect2 id="data_api.reporters">
    716706      <title>Reporters</title>
    717707      <para>
    718          This section gives an overview of hardware and software in BASE.
    719       </para>
    720      
    721       <sect3 id="data_api.reporters.uml">
    722         <title>UML diagram</title>
    723        
     708         This section gives an overview of reporters in BASE.
     709      </para>
     710     
    724711        <figure id="data_api.figures.reporters">
    725712          <title>Reporters</title>
     
    734721          </screenshot>
    735722        </figure>
    736       </sect3>
    737723     
    738724      <sect3 id="data_api.reporters.description">
     
    809795      </para>
    810796     
    811       <sect3 id="data_api.quota.uml">
    812         <title>UML diagram</title>
    813        
    814797        <figure id="data_api.figures.quota">
    815798          <title>Quota and disk usage</title>
     
    824807          </screenshot>
    825808        </figure>
    826       </sect3>
    827809     
    828810      <sect3 id="data_api.quota.description">
     
    869851      </para>
    870852     
    871       <sect3 id="data_api.clients.uml">
    872         <title>UML diagram</title>
    873        
    874853        <figure id="data_api.figures.clients">
    875854          <title>Client, sessions and settings</title>
     
    885864          </screenshot>
    886865        </figure>
    887       </sect3>
    888      
     866
    889867      <sect3 id="data_api.clients.description">
    890868        <title>Clients</title>
     
    10421020      </para>
    10431021
    1044       <sect3 id="data_api.files.uml">
    1045       <title>UML diagram</title>
    1046      
    10471022        <figure id="data_api.figures.files">
    10481023          <title>Files and directories</title>
     
    10571032          </screenshot>
    10581033        </figure>
    1059       </sect3>
    1060      
    1061       <sect3 id="data_api.files.description">
    1062         <title>Description</title>
    1063        
     1034     
    10641035        <para>
    10651036          The <classname docapi="net.sf.basedb.core.data">DirectoryData</classname> class holds
     
    11711142        <para>
    11721143          The <classname docapi="net.sf.basedb.core.data">FileServerData</classname> class
    1173           holds information about an external file server. The <varname>username</varname>
    1174           and <varname>password</varname> properties are used if the server requires the
    1175           user to be logged in. BASE supports Basic and Digest authentication.
    1176           The <varname>serverCertificate</varname> can be used with HTTPS servers that uses
    1177           a non-trusted certificate to tell BASE to trust the server anyway. In most cases,
    1178           this is only needed if the server uses a self-signed certificate, but could, for
     1144          holds information about an external file server. If the <varname>connectionManagerFactory</varname>
     1145          isn't set BASE automatically selects a factory based on the URL of the file. There is
     1146          built-in support for HTTP and HTTPS, but it is possible to install extensions for
     1147          support for other protocols. The <varname>host</varname> property can be set
     1148          to override the host part of the URL from the file. See <xref
     1149          linkend="extensions_developer.connection_manager" /> for more
     1150          information about connection managers.
     1151        </para>
     1152       
     1153        <para>
     1154          The <varname>username</varname> and <varname>password</varname> properties are used if
     1155          the server requires the user to be logged in. BASE has built-in support for Basic and
     1156          Digest authentication. The <varname>serverCertificate</varname> can be used with HTTPS
     1157          servers that uses a non-trusted certificate to tell BASE to trust the server anyway.
     1158          In most cases, this is only needed if the server uses a self-signed certificate, but could, for
    11791159          example, also be used if a trusted site has forgot to renew an expired certificate.
    11801160          The server certificate should be an X.509 certificate in either binary or text format.
     
    11991179          The extension of a MIME type must be unique. Extensions should be registered
    12001180          without a dot, ie <emphasis>html</emphasis>, not <emphasis>.html</emphasis>. 
    1201         </para>
    1202        
    1203       </sect3>
    1204      
     1181        </para>
    12051182     
    12061183    </sect2>
    12071184   
    12081185    <sect2 id="data_api.platforms">
    1209       <title>Experimental platforms</title>
     1186      <title>Experimental platforms and item subtypes</title>
    12101187
    12111188      <para>
    12121189         This section gives an overview of experimental platforms
    12131190         and how they are used to enable data storage in files
    1214          instead of in the database.
     1191         instead of in the database. In some senses item subtypes
     1192         are related to platforms so they are also included here.
    12151193      </para>
    12161194     
     
    12191197        <listitem><xref linkend="core_api.data_in_files" /></listitem>
    12201198        <listitem><xref linkend="appendix.rawdatatypes.platforms" /></listitem>
    1221         <listitem><xref linkend="plugin_developer.other.datafiles" /></listitem>
     1199        <listitem><xref linkend="extensions_developer.fileset_validator" /></listitem>
    12221200      </itemizedlist>
    12231201         
    1224       <sect3 id="data_api.platforms.uml">
    1225         <title>UML diagram</title>
    1226        
    12271202        <figure id="data_api.figures.platforms">
    1228           <title>Experimental platforms</title>
     1203          <title>Experimental platforms and item subtypes</title>
    12291204          <screenshot>
    12301205            <mediaobject>
     
    12371212          </screenshot>
    12381213        </figure>
    1239       </sect3>
    1240      
     1214
    12411215      <sect3 id="data_api.platforms.platforms">
    12421216        <title>Platforms</title>
     
    12721246          by a fixed, non-changable external ID. The <varname>itemType</varname>
    12731247          property tells us what type of item the file holds data for (ie.
    1274           array design or raw bioassay). It also links to a <classname docapi="net.sf.basedb.core.data">FileType</classname>
     1248          array design or raw bioassay). It also links to a <classname
     1249          docapi="net.sf.basedb.core.data">ItemSubtype</classname>
    12751250          which is the generic type of data in the file. This allows us to query
    12761251          the database for, as an example, files with the generic type
     
    12821257          The <varname>required</varname> flag in <classname docapi="net.sf.basedb.core.data">PlatformFileTypeData</classname>
    12831258          is used to signal that the file is a required file. This is not
    1284           enforeced by the core. It is intended to be used by client applications
     1259          enforced by the core. It is intended to be used by client applications
    12851260          for creating a better GUI and for validation of an experiment.
    12861261        </para>
    1287 
     1262        <para>
     1263          The <varname>allowMultiple</varname> flag in <classname
     1264          docapi="net.sf.basedb.core.data">PlatformFileTypeData</classname>
     1265          controls if it should be possible to store more than one file of
     1266          the given type in file type. Again, this is not enforced by the core,
     1267          but only a recommendation to client applications. The setting is
     1268          also used for validation of an experiment.
     1269        </para>
     1270
     1271      </sect3>
     1272     
     1273      <sect3 id="data_api.platforms.subtypes">
     1274        <title>Item subtypes</title>
     1275       
     1276        <para>
     1277          The <classname docapi="net.sf.basedb.core.data">ItemSubtypeData</classname>
     1278          class describes a subtype for a main <varname>itemType</varname>. In the simplest
     1279          form the subtype is a kind of annotation that is used mainly for creating a
     1280          better user experience. If the main item type is also implementing the
     1281          <interfacename docapi="net.sf.basedb.core.data">FileStoreEnabledData</interfacename>
     1282          interface, it is possible to
     1283          register associations to the file types that can be used together with a given
     1284          item subtype. The <varname>required</varname> and <varname>allowMultiple</varname>
     1285          have are used in the same way as in the <classname>PlatformFileTypeData</classname>
     1286          class.
     1287        </para>
     1288       
     1289        <para>
     1290          A subtype can be related to other subtypes. This is used to "chain" together
     1291          groups of item subtypes. For example, <constant>Hybridization</constant>
     1292          is a subtype for <constant>PHYSICALBIOASSAY</constant>, which is related to
     1293          the <constant>Labeled extract (EXTRACT)</constant> subtype which is related to
     1294          the <constant>Label (TAG)</constant> subtype. In addition, there are also
     1295          several protocol and hardware subetypes mixed into this. The relationship between
     1296          subtypes makes it possible for client applications to filter out unrelated stuff,
     1297          and to validate experiments.
     1298        </para>
     1299       
    12881300      </sect3>
    12891301     
     
    12921304       
    12931305        <para>
    1294           An item must implement the <interfacename docapi="net.sf.basedb.core">FileStoreEnabledData</interfacename>
     1306          An item must implement the <interfacename docapi="net.sf.basedb.core.data">FileStoreEnabledData</interfacename>
    12951307          interface to be able to store data in files instead of in the database.
    12961308          The interface creates a link to a <classname docapi="net.sf.basedb.core.data">FileSetData</classname> object,
    12971309          which can hold several <classname docapi="net.sf.basedb.core.data">FileSetMemberData</classname> items.
    12981310          Each member points to specific <classname docapi="net.sf.basedb.core.data">FileData</classname> item.
    1299           A file set can only store one file of each <classname docapi="net.sf.basedb.core.data">DataFileTypeData</classname>.
    13001311        </para>
    13011312       
     
    13121323      </para>
    13131324     
    1314       <sect3 id="data_api.parameters.uml">
    1315         <title>UML diagram</title>
    1316        
    13171325        <figure id="data_api.figures.parameters">
    13181326          <title>Parameters</title>
     
    13271335          </screenshot>
    13281336        </figure>
    1329       </sect3>
    1330      
    1331       <sect3 id="data_api.parameters.description">
    1332         <title>Parameters</title>
    1333        
     1337     
    13341338        <para>
    13351339          The parameter system is a generic system that can store almost
    13361340          any kind of simple values (string, numbers, dates, etc.) and
    1337           also links to other items. The <classname docapi="net.sf.basedb.core.data">ParameterValueData</classname>
     1341          also links to other items. It is, for example, used to store configuration
     1342          parameters to plug-ins and jobs as well as annotation values to annotatable items.
     1343          The <classname docapi="net.sf.basedb.core.data">ParameterValueData</classname>
    13381344          class is an abstract base class that can hold multiple values (all must be of the
    13391345          same type). Unless only a specific type of values should be stored, this is
    13401346          the class that should be used when creating references for storing parameter
    1341           values. It makes it possible for a single relaltion to use any kind of
     1347          values. It makes it possible for a single relation to use any kind of
    13421348          values or for a collection reference to mix multiple types of values.
    13431349          A typical use case maps a <classname>Map</classname> with the
     
    13801386</programlisting>
    13811387
    1382       </sect3>
    1383      
    13841388    </sect2>
    13851389
     
    13921396      </para>
    13931397     
    1394       <sect3 id="data_api.annotations.uml">
    1395         <title>UML diagram</title>
    1396        
    13971398        <figure id="data_api.figures.annotations">
    13981399          <title>Annotations</title>
     
    14071408          </screenshot>
    14081409        </figure>
    1409       </sect3>
    14101410     
    14111411      <sect3 id="data_api.annotations.description">
     
    14801480        are treated a bit differently. They will not show up as annotations
    14811481        to items with a type found in the <property>itemTypes</property> collection.
    1482         A protocol parameter should be attached to a protocol. Then, when an item
     1482        Instead, a protocol parameter should be attached to a protocol. Then, when an item
    14831483        is using that protocol it becomes possible to add annotation values for
    14841484        the annotation types specified as protocol parameters. It doesn't matter
     
    15701570
    15711571    <sect2 id="data_api.protocols">
    1572       <title>Protocols</title>
     1572      <title>Protocols, hardware and software</title>
    15731573
    15741574      <para>
     
    15771577      </para>
    15781578     
    1579       <sect3 id="data_api.protocols.uml">
    1580         <title>UML diagram</title>
    1581        
    15821579        <figure id="data_api.figures.protocols">
    1583           <title>Protocols</title>
     1580          <title>Protocols, hardware and software</title>
    15841581          <screenshot>
    15851582            <mediaobject>
     
    15921589          </screenshot>
    15931590        </figure>
    1594       </sect3>
    15951591     
    15961592      <sect3 id="data_api.protocols.description">
     
    15991595        <para>
    16001596        A protocol is something that defines a procedure or recipe for some
    1601         kind of action, such as sampling, extraction and scanning. In BASE we only
    1602         store a short name and description. It is possible to attach a file
    1603         that provides a longer description of the procedure.
     1597        kind of action, such as sampling, extraction and scanning. The subtype
     1598        of the protocol is used to determine what the protocol is used for.
     1599        In BASE we only store a short name and description. It is possible to
     1600        attach a file that provides a longer description of the procedure.
    16041601        </para>
    16051602     
     
    16221619     
    16231620      </sect3>
     1621
     1622      <sect3 id="data_api.wares.description">
     1623        <title>Hardware and software</title>
     1624        <para>
     1625          BASE is pre-installed with a set of subtypes for hardware and software.
     1626          They are typically used to filter the registered hardware and software
     1627          depending on what a user is doing. For example, when adding raw data
     1628          to BASE a user can select a scanner. The GUI will display the hardware
     1629          that has been registered as <emphasis>scanner</emphasis> subtype.
     1630          Other subtypes are <emphasis>hybridization station</emphasis>
     1631          and <emphasis>print robot</emphasis>. An administrator may register more
     1632          subtypes.
     1633        </para>
     1634      </sect3>
    16241635     
    16251636    </sect2>
     
    16381649      </itemizedlist>
    16391650     
    1640       <sect3 id="data_api.plugins.uml">
    1641         <title>UML diagram</title>
    1642        
    16431651        <figure id="data_api.figures.plugins">
    16441652          <title>Plug-ins, jobs and job agents</title>
     
    16541662          </screenshot>
    16551663        </figure>
    1656       </sect3>
    16571664
    16581665      <sect3 id="data_api.plugins.plugins">
     
    17591766        <listitem>
    17601767          <para>
     1768            ABORTING (status = 6): The job is executing but an ABORT signal has been sent
     1769            requesting it to abort and finish.
     1770          </para>
     1771        </listitem>
     1772        <listitem>
     1773          <para>
    17611774            DONE (status = 3): The job finished successfully.
    17621775          </para>
     
    17791792          and the <classname docapi="net.sf.basedb.core.data">JobAgentSettingsData</classname> links the agent
    17801793          with the plug-ins the agent is able to execute. The job agent will only
    1781           execute jobs that are owner by users or projects that the job agent has
     1794          execute jobs that are owned by users or projects that the job agent has
    17821795          been shared to with at least use permission. The <property>priorityBoost</property>
    17831796          property can be used to give specific plug-ins higher priority.
     
    18171830      <title>Biomaterial LIMS</title>
    18181831     
    1819       <sect3 id="data_api.biomaterials.uml">
    1820         <title>UML diagram</title>
    1821        
    18221832        <figure id="data_api.figures.biomaterials">
    18231833          <title>Biomaterial LIMS</title>
     
    18321842          </screenshot>
    18331843        </figure>
    1834       </sect3>
    18351844     
    18361845      <sect3 id="data_api.biomaterials.description">
    1837         <title>Biomaterial LIMS</title>
    1838        
    1839         <para>
    1840           There are four types of biomaterials: <classname docapi="net.sf.basedb.core.data">BioSourceData</classname>,
    1841           <classname docapi="net.sf.basedb.core.data">SampleData</classname>, <classname docapi="net.sf.basedb.core.data">ExtractData</classname> and
    1842           <classname docapi="net.sf.basedb.core.data">LabeledExtractData</classname>.
    1843           All four types of are derived from the base class <classname docapi="net.sf.basedb.core.data">BioMaterialData</classname>.
     1846        <title>Biomaterials</title>
     1847       
     1848        <para>
     1849          There are three main types of biomaterials: <classname docapi="net.sf.basedb.core.data">BioSourceData</classname>,
     1850          <classname docapi="net.sf.basedb.core.data">SampleData</classname> and
     1851          <classname docapi="net.sf.basedb.core.data">ExtractData</classname>.
     1852          All types of are derived from the base class <classname docapi="net.sf.basedb.core.data">BioMaterialData</classname>.
    18441853          The reason for this is that they all share common functionality such as pooling
    18451854          and events. By using a common base class we do not have to create duplicate
     
    18551864        <para>
    18561865          The <classname docapi="net.sf.basedb.core.data">MeasuredBioMaterialData</classname> class is used as a base
    1857           class for the other three biomaterial types. It introduces quantity
     1866          class for the other biomaterial types. It introduces quantity
    18581867          measurements and can store original and remaining quantities. They are
    18591868          both optional. If an original quantity has been specified the core
     
    18641873        <para>
    18651874          All measured biomaterial have at least one event associated with them,
    1866           the creation event, which holds information about the creation of the
     1875          the <emphasis>creation event</emphasis>, which holds information about the creation of the
    18671876          biomaterial. A measured biomaterial can be created in three ways:
    18681877        </para>
     
    18711880        <listitem>
    18721881          <para>
    1873           From a single item of the parent type. Biosource is the parent type of
    1874           samples, sample is the parent type of extracts, and extract is the
    1875           parent type of labeled extracts. In this case the
    1876           <property>pooled</property> property is <constant>false</constant>
    1877           and the parent is specified in the <property>parent</property> property.
    1878           If the parent is not a <classname docapi="net.sf.basedb.core.data">BioSourceData</classname> this information
    1879           is duplicated, with the addition of an optional used quantity value, in the
    1880           <property>sources</property> collection of the <classname docapi="net.sf.basedb.core.data">BioMaterialEventData</classname>
     1882          From a single item of the same type or the parent type. Biosource is the parent type of
     1883          samples and sample is the parent type of extracts. The <property>parentType</property>
     1884          property must be set to the correct parent type and the <property>parent</property> property
     1885          is set to point to the parent item. The parent information
     1886          is also always duplicated in the <property>sources</property> collection of the <classname docapi="net.sf.basedb.core.data">BioMaterialEventData</classname>
    18811887          object representing the creation event. It is the responsibility of the
    18821888          core to make sure that everything is properly synchronized and that
     
    18871893        <listitem>
    18881894          <para>
    1889           From one or more items of the same type, i.e pooling.
    1890           In this case the <property>pooled</property> property is <constant>true</constant>
    1891           and the <property>parent</property> property is null. All source
     1895          From multiple items of the same type, i.e pooling.
     1896          In this case the <property>parentType</property> property is set, but
     1897          the <property>parent</property> property is null. All source
    18921898          biomaterials are contained in the <property>sources</property> collection.
    18931899          The core is still responsible for keeping everything synchronized and to
     
    18981904        <listitem>
    18991905          <para>
    1900           As a standalone biomaterial without parents.
     1906          As a standalone biomaterial without parents. The <property>parentType</property>
     1907          property should be null, as should the <property>parent</property> property
     1908          and the <property>sources</property> collection.
    19011909          </para>
    19021910        </listitem>
     
    19701978          biomaterial. The <property>sources</property> collection contains
    19711979          information about the biomaterials that were used to create the new
    1972           biomaterial. If the biomaterial is a pooled biomaterial all sources must
    1973           be of the same type. Otherwise there can only be one source of the parent
    1974           type. These rules are maintained by the core.
    1975           </para>
    1976         </listitem>
    1977        
    1978         <listitem>
    1979           <para>
    1980           <emphasis>Hybridization event</emphasis>: This event represents the creation
    1981           of a hybridization. This event type is needed because we want to keep track
    1982           of quantities for labeled extracts. This event has a hybridization as a
    1983           product instead of a biomaterial. The sources collection can only contain
    1984           labeled extracts.
     1980          biomaterial. All sources must be of the same type. There can only be one
     1981          source of the parent type. These rules are maintained by the core.
     1982          </para>
     1983        </listitem>
     1984       
     1985        <listitem>
     1986          <para>
     1987          <emphasis>Bioassay event</emphasis>: This event represents the creation
     1988          of a bioassay. This event type is needed because we want to keep track
     1989          of quantities for extracts. This event has a <classname docapi="net.sf.basedb.core.data">PhysicalBioAssayData</classname>
     1990          as a product instead of a biomaterial. The sources collection can only contain
     1991          extracts. If the bioassay can hold extracts in multiple positions the
     1992          <property>position</property> property in <classname docapi="net.sf.basedb.core.data">BioMaterialEventSourceData</classname>
     1993          can be used to track which extract that was put in each position. It is allowed
     1994          to put multiple extracts in the same position, but then the usually need
     1995          to use different <classname docapi="net.sf.basedb.core.data">TagData</classname>
     1996          items. However, this is not enforced by the core.
    19851997          </para>
    19861998        </listitem>
     
    20152027      <title>Array LIMS - plates</title>
    20162028
    2017       <sect3 id="data_api.plates.uml">
    2018         <title>UML diagram</title>
    2019        
    20202029        <figure id="data_api.figures.plates">
    20212030          <title>Array LIMS - plates</title>
     
    20312040          </screenshot>
    20322041        </figure>
    2033       </sect3>
    20342042
    20352043      <sect3 id="data_api.plates.description">
     
    21112119      <title>Array LIMS - arrays</title>
    21122120     
    2113       <sect3 id="data_api.arrays.uml">
    2114         <title>UML diagram</title>
    2115        
    21162121        <figure id="data_api.figures.arrays">
    21172122          <title>Array LIMS - arrays</title>
     
    21262131          </screenshot>
    21272132        </figure>
    2128       </sect3>
    21292133     
    21302134      <sect3 id="data_api.arrays.designs">
     
    21842188    </sect2>
    21852189
    2186     <sect2 id="data_api.rawdata">
    2187       <title>Hybridizations and raw data</title>
    2188      
    2189       <sect3 id="data_api.rawdata.uml">
    2190         <title>UML diagram</title>
    2191        
     2190    <sect2 id="data_api.bioassays">
     2191      <title>Bioassays and raw data</title>
     2192     
    21922193        <figure id="data_api.figures.rawdata">
    2193           <title>Hybridizations and raw data</title>
     2194          <title>Bioassays and raw data</title>
    21942195          <screenshot>
    21952196            <mediaobject>
     
    21982199                  align="center"
    21992200                  scalefit="1" width="100%"
    2200                   fileref="figures/uml/datalayer.rawdata.png" format="PNG" />
     2201                  fileref="figures/uml/datalayer.bioassays.png" format="PNG" />
    22012202              </imageobject>
    22022203            </mediaobject>
    22032204          </screenshot>
    22042205        </figure>
    2205       </sect3>
    2206      
    2207       <sect3 id="data_api.rawdata.hybridizations">
    2208         <title>Hybridizations</title>
    2209        
    2210         <para>
    2211         Hybridizations connects the slides from the Array LIMS part
    2212         with labeled extracts from the biomaterials part. The <property>creationEvent</property>
    2213         is used to register which labeled extracts that were used on the hybridization.
     2206     
     2207      <sect3 id="data_api.bioassays.physical">
     2208        <title>Physical bioassays</title>
     2209       
     2210        <para>
     2211        A <classname docapi="net.sf.basedb.core.data">PhysicalBioAssayData</classname>
     2212        item connect the array slides from the Array LIMS part
     2213        with extracts from the biomaterials part. The <property>creationEvent</property>
     2214        is used to register which extracts that were used on the bioassay.
    22142215        The relation to slides is a one-to-one relation. A slide can only be used on
    2215         a single hybridization and a hybridization can only use a single slide. The relation
     2216        a single physical bioassay and a bioassay can only use a single slide. The relation
    22162217        is optional from both sides.
    22172218        </para>
    22182219
    22192220        <para>
    2220         The scanning of the hybridized slide is registered as separate scan events.
    2221         One or more images can optionally be attached to each scan.
    2222         The images are not used by BASE.
    2223         </para>
    2224        
    2225       </sect3>
    2226      
    2227       <sect3 id="data_api.rawdata.description">
     2221        Further processing of the bioassay is registered as a series
     2222        of <classname docapi="net.sf.basedb.core.data">DerivedBioAssayData</classname>
     2223        items. For microarray experiments the first step is typically a scanning
     2224        of the hybridization. Information about the software/hardware and protocol
     2225        used can be registered. Any data files generated by the process can be
     2226        registered with the <classname docapi="net.sf.basedb.core.data">FileSetData</classname>
     2227        item. If more than one processsing step is required child derived
     2228        bioassays can be created that descrive each additional step. 
     2229        </para>
     2230       
     2231        <para>
     2232        If the root physical bioassay has multiple extracts in multiple positions, the
     2233        <property>extract</property> property of a derived bioassay is used to link
     2234        with the extract that the specific derived bioassay represents. If the
     2235        link is null the derived bioassay represents all extracts on the
     2236        physical bioassay.
     2237        </para>
     2238       
     2239      </sect3>
     2240     
     2241      <sect3 id="data_api.bioassays.rawdata">
    22282242        <title>Raw data</title>
    22292243       
    22302244        <para>
    2231         A <classname docapi="net.sf.basedb.core.data">RawBioAssayData</classname> object represents
    2232         the raw data that is produced by analysing the image(s) from a
    2233         single scan. You may register which software that was used, the
     2245        A <classname docapi="net.sf.basedb.core.data">RawBioAssayData</classname> object
     2246        represents the raw data that is produced by analysing the data from the physical
     2247        bioassay. You may register which software that was used, the
    22342248        protocol and any parameters (through the annotation system).
    22352249        </para>
     
    22372251        <para>
    22382252        Files with the analysed data values can be attached to the
    2239         associated <classname docapi="net.sf.basedb.core.data">FileSetData</classname> object. The platform
    2240         and, optionally, the variant has information about the file types
     2253        associated <classname docapi="net.sf.basedb.core.data">FileSetData</classname> object.
     2254        The platform and, optionally, the variant has information about the file types
    22412255        that can be used for that platform. If the platform file types support
    22422256        metadata extraction, headers, the number of spots, and other
     
    22772291     
    22782292     
    2279       <sect3 id="data_api.experiments.uml">
    2280         <title>UML diagram</title>
    2281        
    22822293        <figure id="data_api.figures.experiments">
    22832294          <title>Experiments</title>
     
    22932304          </screenshot>
    22942305        </figure>
    2295       </sect3>
    22962306     
    22972307      <sect3 id="data_api.experiments.description">
     
    25102520      <title>Other classes</title>
    25112521     
    2512       <sect3 id="data_api.misc.uml">
    2513         <title>UML diagram</title>
    2514        
    25152522        <figure id="data_api.figures.misc">
    25162523          <title>Other classes</title>
     
    25252532          </screenshot>
    25262533        </figure>
    2527       </sect3>
    25282534     
    25292535    </sect2>
  • trunk/doc/src/docbook/developer/core_ref.xml

    r5738 r5780  
    102102        <para>
    103103        Identify things that may affect backwards compatibility. For more
    104         information about such things read <xref linkend="api_overview.public_api" />
     104        information about such things read <xref linkend="base_api.public" />
    105105        and <xref linkend="core_ref.rules.compatibility" />.
    106106        </para>
     
    508508            documentation to mark that part of the code as an internal API that should
    509509            not be used by plug-ins and other client code. See
    510             <xref linkend="api_overview.public_api" />.
     510            <xref linkend="base_api.public" />.
    511511            </para>
    512512          </listitem>
     
    844844            <para>
    845845            Not all code in BASE is considered to be part of the public
    846             API. See <xref linkend="api_overview.public_api" /> and
     846            API. See <xref linkend="base_api.public" /> and
    847847            <ulink url="../../../api/index.html">the javadoc</ulink>
    848848            for information about the public API. Changes made to
     
    23712371          and may implement any of the interfaces if needed. The strucure is similar to the
    23722372          structure found in the <code>net.sf.basedb.core.data</code> package
    2373           (See <xref linkend="api_overview.data_api" />).
     2373          (See <xref linkend="base_api.data" />).
    23742374        </para>
    23752375
  • trunk/doc/src/docbook/developer/index.xml

    r5738 r5780  
    3232  <include file="extensions.xml" />
    3333  <include file="webservices.xml"/>
    34   <include file="api_overview.xml"/>
     34  <include file="base_api.xml"/>
    3535  <include file="documentation.xml"/>
    3636  <include file="core_ref.xml"/>
Note: See TracChangeset for help on using the changeset viewer.