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

Last change on this file since 3409 was 3409, checked in by Nicklas Nordborg, 14 years ago

References #552, #553, #554: Added information about backwards compatibility and Public vs. Internal
API.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 6.2 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE chapter PUBLIC
3    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
4    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
5<!--
6  $Id: api_overview.xml 3409 2007-05-30 13:35:40Z nicklas $
7
8  Copyright (C) Authors contributing to this file.
9
10  This file is part of BASE - BioArray Software Environment.
11  Available at http://base.thep.lu.se/
12
13  BASE is free software; you can redistribute it and/or
14  modify it under the terms of the GNU General Public License
15  as published by the Free Software Foundation; either version 2
16  of the License, or (at your option) any later version.
17
18  BASE is distributed in the hope that it will be useful,
19  but WITHOUT ANY WARRANTY; without even the implied warranty of
20  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
21  GNU General Public License for more details.
22
23  You should have received a copy of the GNU General Public License
24  along with this program; if not, write to the Free Software
25  Foundation, Inc., 59 Temple Place - Suite 330,
26  Boston, MA  02111-1307, USA.
27-->
28
29<chapter id="api_overview">
30  <?dbhtml dir="api"?>
31  <title>API overview (how to use and code examples)</title>
32
33  <sect1 id="api_overview.public_api">
34    <title>The Public API of BASE</title>
35   
36    <para>
37      Not all public classes and methods in the <filename>BASE2Core.jar</filename>
38      and other JAR files shipped with BASE are considered as
39      <emphasis>Public API</emphasis>. This is important knowledge
40      since we will always try to maintain backwards compatibility
41      for classes that are part of the public API. For other
42      classes, changes may be instroduced at any time without
43      notice or specific documentation. In other words:
44    </para>
45   
46    <note>
47      <title>Only use the public API when developing plug-ins</title>
48      <para>
49        This will maximize the chance that you plug-in will continue
50        to work with the next BASE release. If you use the non-public API
51        you do so at your own risk.
52      </para>
53    </note>
54   
55    <para>
56      See the <ulink url="http://base.thep.lu.se/chrome/site/doc/api/index.html"
57        >javadoc</ulink> for information about
58      what parts of the API that contributes to the public API.
59    </para>
60
61    <sect2 id="api_overview.compatibility">
62      <title>What is backwards compatibility?</title>
63     
64      <para>
65        There is a great article about this subject on <ulink 
66        url="http://wiki.eclipse.org/index.php/Evolving_Java-based_APIs"
67          >http://wiki.eclipse.org/index.php/Evolving_Java-based_APIs</ulink>.
68        This is what we will try to comply with. If you don't want to
69        read the entire article, here are some of the most important points:
70      </para>
71     
72      <variablelist>
73      <varlistentry>
74        <term>Binary compatibility</term>
75        <listitem>
76          <para>
77          <blockquote>
78            Pre-existing Client binaries must link and run with new releases of the
79            Component without recompiling.
80          </blockquote>
81         
82          For example:
83          <itemizedlist>
84          <listitem>
85            <para>
86              We can't change the number or types of parameters to a method
87              or constructor.
88            </para>
89          </listitem>
90          <listitem>
91            <para>
92              We can't add or change methods to interfaces that are intended
93              to be implemented by plug-in or client code.
94            </para>
95          </listitem>
96          </itemizedlist>
97          </para>
98        </listitem>
99      </varlistentry>
100      <varlistentry>
101        <term>Contract compatibility</term>
102        <listitem>
103          <para>
104            <blockquote>
105            API changes must not invalidate formerly legal Client code.
106            </blockquote>
107         
108            For example:
109            <itemizedlist>
110            <listitem>
111              <para>
112                We can't change the implementation of a method to do
113                things differently than before. For example, allow <constant>null</constant>
114                as a return value when it wasn't allowed before.
115              </para>
116            </listitem>
117            </itemizedlist>
118         
119            <note>
120              <para>
121              Sometimes there is a very fine line between what is considered a
122              bug and what is considered a feature. For example, if the
123              actual implementation doesn't do what the javadoc says,
124              do we change the code or do we change the documentation?
125              This has to be considered from case to case and depends on
126              the age of the code and if we expect plug-ins and clients to be
127              affected by it or not.
128              </para>
129            </note>
130          </para>
131        </listitem>
132      </varlistentry>
133      <varlistentry>
134        <term>Source code compatibility</term>
135        <listitem>
136          <para>
137          This is not an important matter and is not always possible to
138          achieve. In most cases, the problems are easy to fix.
139          Example:
140         
141          <itemizedlist>
142          <listitem>
143            <para>
144            Adding a class may break a plug-in or client that import
145            classes with <constant>.*</constant> if the same class name
146            exists in another package.
147            </para>
148          </listitem>
149          </itemizedlist>
150          </para>
151         
152        </listitem>
153      </varlistentry>
154      </variablelist>
155     
156   
157    </sect2>
158 
159  </sect1>
160
161  <sect1 id="api_overview.data_api">
162    <title>The database schema and the Data Layer API</title>
163
164    <para>
165      This documentation is only available in the old format.
166      See <ulink url="http://base.thep.lu.se/chrome/site/doc/development/overview/data/index.html"
167        >http://base.thep.lu.se/chrome/site/doc/development/overview/data/index.html</ulink>
168    </para>
169   
170  </sect1>
171 
172  <sect1 id="api_overview.core_api">
173    <title>The Core API</title>
174    <para>
175      TODO
176    </para>
177  </sect1>
178
179  <sect1 id="api_overview.query_api">
180    <title>The Query API</title>
181    <para>
182      This documentation is only available in the old format.
183      See <ulink url="http://base.thep.lu.se/chrome/site/doc/development/overview/query/index.html"
184        >http://base.thep.lu.se/chrome/site/doc/development/overview/query/index.html</ulink>
185    </para>
186   
187  </sect1>
188 
189  <sect1 id="api_overview.dynamic_and_batch_api">
190    <title>Analysis and the Dynamic and Batch API:s</title>
191    <para>
192      This documentation is only available in the old format.
193      See <ulink url="http://base.thep.lu.se/chrome/site/doc/development/overview/dynamic/index.html"
194        >http://base.thep.lu.se/chrome/site/doc/development/overview/dynamic/index.html</ulink>
195    </para>
196  </sect1>
197
198  <sect1 id="api_overview.other_api">
199    <title>Other useful classes and methods</title>
200    <para>
201      TODO
202    </para>
203  </sect1>
204 
205</chapter>
Note: See TracBrowser for help on using the repository browser.