source: trunk/doc/src/docbook/developerdoc/api_overview.xml @ 3487

<?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: api_overview.xml 3487 2007-06-13 17:56:05Z peter $

  Copyright (C) Authors contributing to this file.

  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 2
  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 this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place - Suite 330,
  Boston, MA  02111-1307, USA.
-->

<chapter id="api_overview">
  <?dbhtml dir="api"?>
  <title>API overview (how to use and code examples)</title>

  <sect1 id="api_overview.public_api">
    <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
      <emphasis>Public API</emphasis>. This is important knowledge
      since we will always try to maintain backwards compatibility
      for classes that are part of the public API. For other
      classes, changes may be instroduced at any time without
      notice or specific documentation. In other words:
    </para>
    
    <note>
      <title>Only use the public API when developing plug-ins</title>
      <para>
        This will maximize the chance that you plug-in will continue
        to work with the next BASE release. If you use the non-public API
        you do so at your own risk.
      </para>
    </note>
    
    <para>
      See the <ulink url="http://base.thep.lu.se/chrome/site/doc/api/index.html"
        >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 
      <code>@deprecated</code> should be considered as part of the internal API 
      and may be removed in a subsequent relase without warning.
    </para>
    
    <para>
      See <xref linkend="appendix.incompatible" /> to read more about
      changes that have been introduced by each release.
    </para>

    <sect2 id="api_overview.compatibility">
      <title>What is backwards compatibility?</title>
      
      <para>
        There is a great article about this subject on <ulink 
        url="http://wiki.eclipse.org/index.php/Evolving_Java-based_APIs"
          >http://wiki.eclipse.org/index.php/Evolving_Java-based_APIs</ulink>.
        This is what we will try to comply with. If you do not want to
        read the entire article, here are some of the most important points:
      </para>
      
      
      <sect3 id="api_overview.compatibility.binary">
        <title>Binary compatibility</title>
        <para>
        <blockquote>
          Pre-existing Client binaries must link and run with new releases of the 
          Component without recompiling.
        </blockquote>
        
        For example:
        <itemizedlist>
        <listitem>
          <para>
            We cannot change the number or types of parameters to a method
            or constructor.
          </para>
        </listitem>
        <listitem>
          <para>
            We cannot add or change methods to interfaces that are intended
            to be implemented by plug-in or client code.
          </para>
        </listitem>
        </itemizedlist>
        </para>       
      </sect3>
      
      <sect3 id="api_overview.compatibility.contract">
        <title>Contract compatibility</title>
        <para>
          <blockquote>
          API changes must not invalidate formerly legal Client code.
          </blockquote>
        
          For example:
          <itemizedlist>
          <listitem>
            <para>
              We cannot change the implementation of a method to do
              things differently than before. For example, allow <constant>null</constant>
              as a return value when it was not allowed before.
            </para>
          </listitem>
          </itemizedlist>
        
          <note>
            <para>
            Sometimes there is a very fine line between what is considered a
            bug and what is considered a feature. For example, if the
            actual implementation does not do what the javadoc says,
            do we change the code or do we change the documentation?
            This has to be considered from case to case and depends on 
            the age of the code and if we expect plug-ins and clients to be
            affected by it or not.
            </para>
          </note>
        </para>
      </sect3>
      
      <sect3 id="api_overview.compatibility.source">
        <title>Source code compatibility</title>
        <para>
        This is not an important matter and is not always possible to
        achieve. In most cases, the problems are easy to fix.
        Example:
        
        <itemizedlist>
        <listitem>
          <para>
          Adding a class may break a plug-in or client that import
          classes with <constant>.*</constant> if the same class name
          exists in another package.
          </para>
        </listitem>
        </itemizedlist>
        </para>
      </sect3>
    </sect2>
  </sect1>

  <sect1 id="api_overview.data_api">
    <title>The database schema and the Data Layer API</title>

    <para>
      This documentation is only available in the old format.
      See <ulink url="http://base.thep.lu.se/chrome/site/doc/development/overview/data/index.html"
        >http://base.thep.lu.se/chrome/site/doc/development/overview/data/index.html</ulink>
    </para>
    
  </sect1>
  
  <sect1 id="api_overview.core_api">
    <title>The Core API</title>
    <para>
      TODO
    </para>
  </sect1>

  <sect1 id="api_overview.query_api">
    <title>The Query API</title>
    <para>
      This documentation is only available in the old format.
      See <ulink url="http://base.thep.lu.se/chrome/site/doc/development/overview/query/index.html"
        >http://base.thep.lu.se/chrome/site/doc/development/overview/query/index.html</ulink>
    </para>
    
  </sect1>
  
  <sect1 id="api_overview.dynamic_and_batch_api">
    <title>Analysis and the Dynamic and Batch API:s</title>
    <para>
      This documentation is only available in the old format.
      See <ulink url="http://base.thep.lu.se/chrome/site/doc/development/overview/dynamic/index.html"
        >http://base.thep.lu.se/chrome/site/doc/development/overview/dynamic/index.html</ulink>
    </para>
  </sect1>

  <sect1 id="api_overview.other_api">
    <title>Other useful classes and methods</title>
    <para>
      TODO
    </para>
  </sect1>
  
</chapter>