source: trunk/doc/src/docbook/developerdoc/base_overview.xml @ 4902

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC 
    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" 
    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
<!--
  $Id: base_overview.xml 4902 2009-04-24 10:56:19Z nicklas $

  Copyright (C) 2007 Nicklas Nordborg, Martin Svensson

  This file is part of BASE - BioArray Software Environment.
  Available at http://base.thep.lu.se/

  BASE is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License
  as published by the Free Software Foundation; either version 3
  of the License, or (at your option) any later version.

  BASE is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with BASE. If not, see <http://www.gnu.org/licenses/>.
-->

<chapter id="base_develop_overview" chunked="0">
  <?dbhtml dir="develop_overview"?>
  <title>Developer overview of BASE</title>

  <para>
    This section gives a brief overview of the architechture used
    in  BASE. This is a good starting point if you need to know how
    various parts of BASE are glued together. The figure below should
    display most of the importants parts in BASE. The following
    sections will briefly describe some parts of the figure 
    and give you pointers for further reading if you are interested in
    the details.
  </para>
  
    <figure id="develop.figures.overview">
      <title>Overview of the BASE application</title>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata 
              align="center"
              scalefit="1" width="100%"
              fileref="figures/uml/base.overview.png" format="PNG" />
          </imageobject>
        </mediaobject>
      </screenshot>
    </figure>
    
    <sect1 id="base_develop_overview.database">
      <title>Fixed vs. dynamic database</title>

      <para>
        BASE stores most of it's data in a database. The database is divided into
        two parts, one fixed and one dynamic part.
      </para>
    
      <para>
        The fixed part contains tables that corresponds
        to the various items found in BASE. There is, for example, one table
        for users, one table for groups and one table for reporters. Some items
        share the same table. Biosources, samples, extracts and labeled extracts are
        all biomaterials and share the <code>BioMaterials</code> table. The access
        to the fixed part of the database goes through Hibernate in most cases 
        or through the the Batch API in some cases (for example, access to reporters).
      </para>
      
      <para>
        The dynamic part of the database contains tables for storing analyzed data.  
        Each experiment has it's own set of tables and it is not possible to mix data 
        from two experiments. The dynamic part of the database can only be accessed 
        by the Batch API and the Query API using SQL and JDBC.
      </para>

      <note>
        The actual location of the two parts depends on the database that is used.
        MySQL uses two separate databases while PostgreSQL uses one database with two schemas.
      </note>

      <bridgehead>More information</bridgehead>
      <itemizedlist>
        <listitem>
          <para>
          <xref linkend="api_overview.dynamic_and_batch_api" />
          </para>
        </listitem>
      </itemizedlist>
    
    </sect1>

    <sect1 id="base_develop_overview.hibernate">
      <title>Hibernate and the DbEngine</title>
    
      <para>
        Hibernate (<ulink url="http://www.hibernate.org">www.hibernate.org</ulink>) is an 
        object/relational mapping software package. It takes plain Java objects
        and stores them in a database. All we have to do is to set the properties
        on the objects (for example: <code>user.setName("A name")</code>). Hibernate
        will take care of the SQL generation and database communication for us.
        This is not a magic or automatic process. We have to provide mapping 
        information about what objects goes into which tables and what properties 
        goes into which columns, and other stuff like caching and proxy settings, etc.
        This is done by annotating the code with Javadoc comments. The classes 
        that are mapped to the database are found in the <code>net.sf.basedb.core.data</code> 
        package, which is shown as the <guilabel>Data classes</guilabel> box in the image above.
        The <classname docapi="net.sf.basedb.core">HibernateUtil</classname> class contains a 
        lot of functionality for interacting with Hibernate.
      </para>
    
      <para>
        Hibernate supports many different database systems. In theory, this means 
        that BASE should work with all those databases. However, in practice we have
        found that this is not the case. For example, Oracle converts empty strings
        to <code>null</code> values, which breaks some parts of our code that
        expects non-null values. Another difficulty is that our Batch API and some parts of 
        the Query API:s generates native SQL as well. We try to use database dialect information 
        from Hibernate, but it is not always possible. The <interfacename 
        docapi="net.sf.basedb.core.dbengine">DbEngine</interfacename> contains code
        for generating the SQL that Hibernate can't help us with. We have implemented
        a generic <classname docapi="net.sf.basedb.core.dbengine">DefaultDbEngine</classname>
        which follows ANSI specifications and special drivers for MySQL 
        (<classname docapi="net.sf.basedb.core.dbengine">MySQLEngine</classname>) and 
        PostgreSQL (<classname docapi="net.sf.basedb.core.dbengine">PostgresDbEngine</classname>). 
        We don't expect BASE to work with other databases without modifications.
      </para> 
        
      <bridgehead>More information</bridgehead>
      <itemizedlist>
        <listitem>
          <para>
          <xref linkend="core_ref.rules.datalayer" />
          </para>
        </listitem>
        <listitem>
          <para>
          <ulink url="http://www.hibernate.org">www.hibernate.org</ulink>
          </para>
        </listitem>
      </itemizedlist>

    </sect1>

    <sect1 id="base_develop_overview.batchapi">
      <title>The Batch API</title>
    
      <para>
        Hibernate comes with a price. It affects performance and uses a lot
        of memory. This means that those parts of BASE that often handles
        lots of items at the same time doesn't work well with Hibernate. This
        is for example reporters, array design features and raw data. We
        have created the Batch API to solve these problems.
      </para>

      <para>
        The Batch API uses JDBC and SQL directly against the database. However, we
        still use metadata and database dialect information available from Hibernate 
        to generate most of the SQL we need. In theory, this should make the Batch API 
        just as database-independent as Hibernate is. In practice there is some information
        that we can't extract from Hibernate so we have implemented a simple 
        <interfacename docapi="net.sf.basedb.core.dbengine">DbEngine</interfacename>
        to account for missing pieces. The Batch API can be used for any
        <classname docapi="net.sf.basedb.core.data">BatchableData</classname> class in the 
        fixed part of the database and is the only way for adding data to the dynamic part.
      </para>
  
      <note>
        The main reason for the Batch API is to avoid the internal caching
        of Hibernate which eats lots of memory when handling thousands of items.
        Hibernate 3.1 introduced a new stateless API which among other things doesn't
        do any caching. This version was released after we had created the Batch API. 
        We made a few tests to check if it would be better for us to switch back to Hibernate 
        but found that it didn't perform as well as our own Batch API (it was about 2 times slower).
        In any case, we can never get Hibernate to work with the dynamic database, 
        so the Batch API is needed.
      </note>
      
      <bridgehead>More information</bridgehead>
      <itemizedlist>
        <listitem>
          <para>
          <xref linkend="api_overview.dynamic_and_batch_api" />
          </para>
        </listitem>
        <listitem>
          <para>
          <xref linkend="core_ref.rules.batchclass" />
          </para>
        </listitem>
        <listitem>
          <para>
          <xref linkend="core_ref.batch" />
          </para>
        </listitem>
      </itemizedlist>
    </sect1>
    
    <sect1 id="base_develop_overview.classes">
      <title>Data classes vs. item classes</title>
    
      <para>
        The data classes are, with few exceptions, for internal use. These are the classes
        that are mapped to the database with Hibernate mapping files. They are very simple
        and contains no logic at all. They don't do any permission checks or any data
        validation.
      </para>
  
      <para>
        Most of the data classes has a corresponding item class. For example: 
        <classname docapi="net.sf.basedb.core.data">UserData</classname>
        and <classname docapi="net.sf.basedb.core">User</classname>, 
        <classname docapi="net.sf.basedb.core.data">GroupData</classname> and 
        <classname docapi="net.sf.basedb.core">Group</classname>. 
        The item classes are what the client applications can see and use. They contain 
        logic for permission checking (for example if the logged in user has WRITE permission) 
        and data validation (for example setting a required property to null).
      </para>
      
      <para>
        The exception to the above scheme are the batchable classes, which are
        all subclasses of the <classname docapi="net.sf.basedb.core.data">BatchableData</classname>
        class. For example, there is a <classname docapi="net.sf.basedb.core.data">ReporterData</classname>
        class but no corresponding item class. Instead there is a  
        batcher implementation, <classname docapi="net.sf.basedb.core">ReporterBatcher</classname>,
        which takes care of the more or less the same things that an item class does,
        but it also takes care of it's own SQL generation and JDBC calls that
        bypasses Hibernate and the caching system.
      </para>
  
      <bridgehead>More information</bridgehead>
      <itemizedlist>
        <listitem>
          <para>
          <xref linkend="core_ref.rules.datalayer" />
          </para>
        </listitem>
        <listitem>
          <para>
          <xref linkend="core_ref.rules.itemclass" />
          </para>
        </listitem>
        <listitem>
          <para>
          <xref linkend="core_ref.rules.batchclass" />
          </para>
        </listitem>
        <listitem>
          <para>
          <xref linkend="core_ref.accesspermissions" />
          </para>
        </listitem>
        <listitem>
          <para>
          <xref linkend="core_ref.datavalidation" />
          </para>
        </listitem>
        <listitem>
          <para>
          <xref linkend="core_ref.batch" />
          </para>
        </listitem>
      </itemizedlist>
    </sect1>

    <sect1 id="base_develop_overview.queryapi">
      <title>The Query API</title>
      <para>
        The Query API is used to build and execute queries against the data in the 
        database. It builds a query by using objects that represents certain
        operations. For example, there is an <classname 
        docapi="net.sf.basedb.core.query">EqRestriction</classname> object
        which tests if two expressions are equal and there is an <classname 
        docapi="net.sf.basedb.core.query">AddExpression</classname>
        object which adds two expressions. In this way it is possible to build
        very complex queries without using SQL or HQL.
      </para>
      
      <para>
        The Query API knows how to work both via Hibernate and via SQL. In the first case it
        generates HQL (Hibernate Query Language) statements which Hibernate then
        translates into SQL. In the second case SQL is generated directly. 
        In most cases HQL and SQL are identical, but not
        always. Some situations are solved by having the Query API generate
        slightly different query strings (with the help of information from
        Hibernate and the DbEngine). Some query elements can only be used
        with one of the query types.
      </para>
      
      <note>
        The object-based approach makes it a bit difficult to store 
        a query for later reuse. The <code>net.sf.basedb.util.jep</code> 
        package contains an expression parser that can be used to convert
        a string to <interfacename 
        docapi="net.sf.basedb.core.query">Restriction</interfacename>:s and 
        <interfacename 
        docapi="net.sf.basedb.core.query">Expression</interfacename>:s for 
        the Query API. While it doesn't cover 100% of the cases it should be
        useful for the <code>WHERE</code> part of a query.
      </note>
      
      <bridgehead>More information</bridgehead>
      <itemizedlist>
        <listitem>
          <para>
          <xref linkend="api_overview.query_api" />
          </para>
        </listitem>
      </itemizedlist>
    </sect1>

    <sect1 id="base_develop_overview.controllerapi">
      <title>The Controller API</title>
      <para>
        The Controller API is the very heart of the Base 2 system. This part
        of the core is used for boring but essential details, such as
        user authentication, database connection management, transaction 
        management, data validation, and more. We don't write more about this 
        part here, but recommends reading the documents below.
      </para>
      
      <bridgehead>More information</bridgehead>
      <itemizedlist>
        <listitem>
          <para>
          <xref linkend="core_ref.coreinternals" />
          </para>
        </listitem>
      </itemizedlist>
    </sect1>

    <sect1 id="base_develop_overview.plugins">
      <title>Plug-ins</title>
    
      <para>
        From the core code's point of view a plug-in is just another client 
        application. A plug-in doesn't have more powers and doesn't have
        access to some special API that allows it to do cool stuff that other
        clients can't.
      </para>

      <para>
        However, the core must be able to control when and where a plug-in is 
        executed. Some plug-ins may take a long time doing their calculations
        and may use a lot of memory. It would be bad if a several users started
        to execute a resource-demanding plug-in at the same time. This problem is
        solved by adding a job queue. Each plug-in that should be executed is
        registered as <classname 
        docapi="net.sf.basedb.core">Job</classname> in the database. A job controller is 
        checking the job queue at regular intervals. The job controller can then
        choose if it should execute the plug-in or wait depending on the current
        load on the server.
      </para>
  
      <note>
        BASE ships with two types of job controllers. One internal that runs
        inside the web application, and one external that is designed to run
        on separate servers, so called job agents. The internal job controller
        should work fine in most cases. The drawback with this controller is 
        that a badly written plug-in may crash the entire web server. For example, 
        a call to <code>System.exit()</code> in the plug-in code shuts down Tomcat 
        as well. 
      </note>

      <bridgehead>More information</bridgehead>
      <itemizedlist>
        <listitem>
          <para>
          <xref linkend="plugin_developer" />
          </para>
        </listitem>
        <listitem>
          <para>
          <xref linkend="core_ref.pluginexecution" />
          </para>
        </listitem>
      </itemizedlist>
    </sect1>

    <sect1 id="base_develop_overview.clients">
      <title>Client applications</title>
      <para>
        Client applications are application that use the BASE Core API. The current web 
        application is built with Java Server Pages (JSP). It is supported by several 
        application servers but we have only tested it with Tomcat. Other client 
        applications are the external job agents that executes plug-ins on separate 
        servers, and the migration tool that migrates data from a BASE 1.2.x installation
        to BASE 2.
      </para>
      
      <para>
        Although it is possible to develop a completely new client appliction from
        scratch we don't see this as a likely thing to happen. Instead, there are
        some other possibilites to access data in BASE and to extend the functionality
        in BASE. 
      </para>
      
      <para>
        The first possibility is to use the Web Service API. This allows you to access
        some of the data in the BASE database and download it for further use. The
        Web Service API is currently very limited but it is not hard to extend it
        to cover more use cases.
      </para>
      
      <para>
        A second possibility is to use the Extension API. This allows a developer to
        add functionality that appears directly in the web interface. For example,
        additional menu items and toolbar buttons. This API is also easy to extend to 
        cover more use cases.
      </para>
      
      <bridgehead>More information</bridgehead>
      <itemizedlist>
        <listitem>
          <para>
          <xref linkend="webservices" />
          </para>
        </listitem>
        <listitem>
          <para>
          <xref linkend="extensions_developer" />
          </para>
        </listitem>
        <listitem>
          <para>
          The <ulink url="http://baseplugins.thep.lu.se">BASE plug-ins site</ulink> also
          has examples of extensions and web services implementations.
          </para>
        </listitem>
      </itemizedlist>
    </sect1>

</chapter>