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

Last change on this file since 5640 was 5640, checked in by Nicklas Nordborg, 11 years ago

References #1590: Documentation cleanup

Checked and changed the following chapters in Part IV: Developer documentation:

  • Plug-in developer sections 7-9. (section 6 is not yet done since there are tickets that will affect lots of information in this section)
  • Extensions developer + added a new section with more information about extension points shipped with BASE.
File size: 8.2 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE part 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$
7
8  Copyright (C) 2011 Nicklas Nordborg
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 3
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 BASE. If not, see <http://www.gnu.org/licenses/>.
25-->
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>
29
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>
36 
37  <sect1 id="migrate_2_3.compiling">
38    <title>Compiling the code against BASE 3</title>
39   
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="http://base.thep.lu.se/chrome/site/2.17">http://base.thep.lu.se/chrome/site/2.17</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>
56   
57    <bridgehead>BASE JAR files have new names</bridgehead>
58
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>
67   
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="http://base2.thep.lu.se/base/jars/">http://base2.thep.lu.se/base/jars/</ulink>.
74    </para>
75  </sect1>
76 
77  <sect1 id="migrate_2_3.coreapi">
78 
79    <title>Core API changes</title>
80
81    <para>
82      There are lot's of other changes to the API between BASE 2 and BASE 3.
83      If your code is affected by those changes, you will have to update your
84      code. Since there are many changes, both big and small, it is not
85      possible to list everything here. One good way to find out more about
86      the changes is to use the BASE Trac or ask on the developers mailing
87      list. Some of the major changes are:
88    </para>
89       
90    <itemizedlist>
91      <listitem>
92        <para>
93          Removed the <methodname>Plugin.getAbout()</methodname> method
94          from the <interfacename docapi="net.sf.basedb.core.plugin">Plugin</interfacename>
95          interface. The information should instead be placed in the
96          <filename>META-INF/extensions.xml</filename> file inside the JAR
97          file that the plug-in is shipped in.
98        </para>
99      </listitem>
100   
101      <listitem>
102        <para>
103          <classname>HardwareType</classname>, <classname>SoftwareType</classname>,
104          <classname>ProtocolType</classname> and <classname>FileType</classname>
105          has been replaced with <classname 
106          docapi="net.sf.basedb.core">ItemSubtype</classname>.
107          Additionally, several other items implement the new <interfacename 
108          docapi="net.sf.basedb.core">Subtypable</interfacename> interface.
109          See <ulink url="http://base.thep.lu.se/ticket/1597">ticket #1597 (Subtypes of items)</ulink>
110          for more information.
111        </para>
112      </listitem>
113     
114      <listitem>
115        <para>
116          <classname>Label</classname> has been replaced with <classname docapi="net.sf.basedb.core">Tag</classname>.
117          <classname>LabeledExtract</classname> has been merged into <classname 
118          docapi="net.sf.basedb.core">Extract</classname>. <classname>Hybridization</classname> has been
119          replaced with <classname docapi="net.sf.basedb.core">PhysicalBioAssay</classname>.
120          <classname>Scan</classname> and <classname>Image</classname> has been replaced with
121          <classname docapi="net.sf.basedb.core">BioAssayEvent</classname>,
122          <classname docapi="net.sf.basedb.core">DerivedBioAssaySet</classname> and
123          <classname docapi="net.sf.basedb.core">DerivedBioAssay</classname>.
124          The changes are driven by the support for sequencing experiments. The new items are
125          using the new subtype feature. For example, a hybridization in BASE 2 has been
126          converted to a physical bioassay in BASE 3 with the subtype 'Hybridization'. The
127          server admin can define additional subtypes. See
128          <ulink url="http://base.thep.lu.se/ticket/1153">ticket #1153 (Handling short read
129          transcript sequence data)</ulink> for more information.
130         
131        </para>
132      </listitem>
133     
134      <listitem>
135        <para>
136          Removed validator and metadata reader properties from
137          <classname docapi="net.sf.basedb.core">DataFileType</classname>.
138          This feature is now implemented as extensions. The API is slightly
139          different and classes have been moved around a bit. See
140          <xref linkend="extensions_developer.fileset_validator"/> and
141          <ulink 
142          url="http://base.thep.lu.se/ticket/1598">ticket #1598 (Use
143          the extensions system for data file validators and metadata readers)</ulink> for more information.
144        </para>
145      </listitem>
146     
147      <listitem>
148        <para>
149          TODO -- more will probably be added to this list
150        </para>
151      </listitem>
152    </itemizedlist>
153       
154     
155  </sect1>
156 
157  <sect1 id="migrate_2_3.packaging">
158    <title>Packaging your code so that it installs in BASE 3</title>
159   
160    <para>
161      The installation system for plug-ins and extensions has been reworked. We hope
162      that it is easier to install things now. Basically, the plug-in installation wizard
163      has been merged with the extensions installation wizard. If your package contain only
164      extensions it will probably install without changes. Packages with plug-ins need some
165      changes to the XML files.
166    </para>
167   
168    <itemizedlist>
169      <listitem>
170        <para>
171        The information that was in
172        <filename>META-INF/base-plugins.xml</filename>, should be moved to
173        <filename>META-INF/extensions.xml</filename>. The XML syntax in the new file is different
174        from the old file. See <xref linkend="plugin_developer.organize.autoinstallcompatible" />
175        for more information.
176        </para>
177      </listitem>
178     
179      <listitem>
180        <para>
181        The information that was in
182        <filename>META-INF/base-configurations.xml</filename>, should be moved to
183        <filename>META-INF/plugin-configurations.xml</filename>. The XML syntax in the
184        new and old file is the same.
185        </para>
186      </listitem>
187    </itemizedlist>
188   
189    <para>
190      Another change is that plug-ins and extensions are
191      required to be installed in the directory specified by <code>plugins.dir</code>
192      setting in the <filename>base.config</filename> file. This is usually not something that
193      you need to worry about as a developer. See <ulink 
194      url="http://base.thep.lu.se/ticket/1592">ticket #1592 (Unified installation
195      procedure for plug-ins, extensions and more...)</ulink> for more information.
196    </para>
197   
198  </sect1>
199 
200</chapter>
Note: See TracBrowser for help on using the repository browser.