source: trunk/doc/src/docbook/developerdoc/migrate_2_3.xml @ 5634

Last change on this file since 5634 was 5634, checked in by Nicklas Nordborg, 12 years ago

References #1603: Developers migration guide

Started on this chapter.

File size: 8.1 KB
1<?xml version="1.0" encoding="UTF-8"?>
3    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
4    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
6  $Id$
8  Copyright (C) 2011 Nicklas Nordborg
10  This file is part of BASE - BioArray Software Environment.
11  Available at
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 3
16  of the License, or (at your option) any later version.
18  BASE is distributed in the hope that it will be useful,
19  but WITHOUT ANY WARRANTY; without even the implied warranty of
21  GNU General Public License for more details.
23  You should have received a copy of the GNU General Public License
24  along with BASE. If not, see <>.
26<chapter id="migrate_2_3" chunked="0">
27  <?dbhtml dir="migrate_2_3"?>
28  <title>Migrating code from BASE 2 to BASE 3</title>
30  <para>
31    This section gives a brief overview what has changed between BASE 2 and
32    BASE 3 and how to migrate your plug-in or extension code to BASE 3.
33    Do not expect that your code can be installed and function as intended
34    right out of the box.
35  </para>
37  <sect1 id="migrate_2_3.compiling">
38    <title>Compiling the code against BASE 3</title>
40    <bridgehead>All deprecated methods and classes have been removed</bridgehead>
41    <para>
42      Before trying to compile your code against the BASE 3 API we recommend that
43      you make sure that you are not using any deprecated methods or classes
44      from the BASE 2.17 API. So the first step should always be to compile
45      your code against the latest BASE 2.17 release. Fix any warnings
46      according to the instructions in the javadoc. In most cases, there is a
47      simple replacment API that can be used instead. Since the deprecated API
48      has been removed in BASE 3 so has the instructions. You'll need to check
49      with the BASE 2.17 documentation which is located at
50      <ulink url=""></ulink>.
51    </para>
52    <para>
53      Do not proceed until you are sure that your code is not using any
54      deprecated API.
55    </para>
57    <bridgehead>BASE JAR files have new names</bridgehead>
59    <para>
60      All JAR files with the BASE API has been renamed to better
61      follow the scheme used by many other projects. For example,
62      <filename>BASE2Core.jar</filename> has been renamed to
63      <filename>base-core-3.0.0.jar</filename>,
64      <filename>BASE2Webclient.jar</filename> has been renamed to
65      <filename>base-webclient-3.0.0.jar</filename>, and so on.
66    </para>
68    <para>
69      You'll need to make sure that your build system can handle this.
70      Also note that the version number is included in the file name,
71      so the files will change when new versions are released.
72      The BASE JAR files can be downloaded from
73      <ulink url=""></ulink>.
74    </para>
76    <bridgehead>Other changes to the API</bridgehead>
78    <para>
79      There are lot's of other changes to the API between BASE 2 and BASE 3.
80      If your code is affected by those changes, you will have to update your
81      code. Since there are many changes, both big and small, it is not
82      possible to list everything here. One good way to find out more about
83      the changes is to use the BASE Trac or ask on the developers mailing
84      list. Some of the major changes are:
85    </para>
87    <itemizedlist>
88      <listitem>
89        <para>
90          Removed the <methodname>Plugin.getAbout()</methodname> method
91          from the <interfacename docapi="net.sf.basedb.core.plugin">Plugin</interfacename>
92          interface. The information should instead be placed in the
93          <filename>META-INF/extensions.xml</filename> file inside the JAR
94          file that the plug-in is shipped in.
95        </para>
96      </listitem>
98      <listitem>
99        <para>
100          <classname>HardwareType</classname>, <classname>SoftwareType</classname>,
101          <classname>ProtocolType</classname> and <classname>FileType</classname>
102          has been replaced with <classname 
103          docapi="net.sf.basedb.core">ItemSubtype</classname>.
104          Additionally, several other items implement the new <interfacename 
105          docapi="net.sf.basedb.core">Subtypable</interfacename> interface.
106          See <ulink url="">ticket #1597 (Subtypes of items)</ulink>
107          for more information.
108        </para>
109      </listitem>
111      <listitem>
112        <para>
113          <classname>Label</classname> has been replaced with <classname docapi="net.sf.basedb.core">Tag</classname>.
114          <classname>LabeledExtract</classname> has been merged into <classname 
115          docapi="net.sf.basedb.core">Extract</classname>. <classname>Hybridization</classname> has been
116          replaced with <classname docapi="net.sf.basedb.core">PhysicalBioAssay</classname>.
117          <classname>Scan</classname> and <classname>Image</classname> has been replaced with
118          <classname docapi="net.sf.basedb.core">BioAssayEvent</classname>,
119          <classname docapi="net.sf.basedb.core">DerivedBioAssaySet</classname> and
120          <classname docapi="net.sf.basedb.core">DerivedBioAssay</classname>.
121          The changes are driven by the support for sequencing experiments. The new items are
122          using the new subtype feature. For example, a hybridization in BASE 2 has been
123          converted to a physical bioassay in BASE 3 with the subtype 'Hybridization'. The
124          server admin can define additional subtypes. See
125          <ulink url="">ticket #1153 (Handling short read
126          transcript sequence data)</ulink> for more information.
128        </para>
129      </listitem>
131      <listitem>
132        <para>
133          Removed validator and metadata reader properties from
134          <classname docapi="net.sf.basedb.core">DataFileType</classname>.
135          This feature is now implemented as extensions. The API is slightly
136          different and classes have been moved around a bit. See <ulink 
137          url="">ticket #1598 (Use
138          the extensions system for data file validators and metadata readers)</ulink> for more information.
139        </para>
140      </listitem>
142      <listitem>
143        <para>
144          TODO -- more will probably be added to this list
145        </para>
146      </listitem>
147    </itemizedlist>
150  </sect1>
152  <sect1 id="migrate_2_3.packaging">
153    <title>Packaging your code so that it installs in BASE 3</title>
155    <para>
156      The installation system for plug-ins and extensions has been reworked. We hope
157      that it is easier to install things now. Basically, the plug-in installation wizard
158      has been merged with the extensions installation wizard. If your package contain only
159      extensions it will probably install without changes. Packages with plug-ins need some
160      changes to the XML files.
161    </para>
163    <itemizedlist>
164      <listitem>
165        <para>
166        The information that was in
167        <filename>META-INF/base-plugins.xml</filename>, should be moved to
168        <filename>META-INF/extensions.xml</filename>. The XML syntax in the new file is different
169        from the old file. See <xref linkend="plugin_developer.organize.autoinstallcompatible" />
170        for more information.
171        </para>
172      </listitem>
174      <listitem>
175        <para>
176        The information that was in
177        <filename>META-INF/base-configurations.xml</filename>, should be moved to
178        <filename>META-INF/plugin-configurations.xml</filename>. The XML syntax in the
179        new and old file is the same.
180        </para>
181      </listitem>
182    </itemizedlist>
184    <para>
185      Another change is that plug-ins and extensions are
186      required to be installed in the directory specified by <code>plugins.dir</code>
187      setting in the <filename>base.config</filename> file. This is usually not something that
188      you need to worry about as a developer. See <ulink 
189      url="">ticket #1592 (Unified installation
190      procedure for plug-ins, extensions and more...)</ulink> for more information.
191    </para>
193  </sect1>
Note: See TracBrowser for help on using the repository browser.