doc/src/docbook/developer/migrate_2_3.xml

Code
Comments
Other
Rev Date Author Line
5634 18 May 11 nicklas 1 <?xml version="1.0" encoding="UTF-8"?>
5634 18 May 11 nicklas 2 <!DOCTYPE part PUBLIC 
5634 18 May 11 nicklas 3     "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" 
5634 18 May 11 nicklas 4     "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
5634 18 May 11 nicklas 5 <!--
5634 18 May 11 nicklas 6   $Id$
5634 18 May 11 nicklas 7
5634 18 May 11 nicklas 8   Copyright (C) 2011 Nicklas Nordborg
5634 18 May 11 nicklas 9
5634 18 May 11 nicklas 10   This file is part of BASE - BioArray Software Environment.
5634 18 May 11 nicklas 11   Available at http://base.thep.lu.se/
5634 18 May 11 nicklas 12
5634 18 May 11 nicklas 13   BASE is free software; you can redistribute it and/or
5634 18 May 11 nicklas 14   modify it under the terms of the GNU General Public License
5634 18 May 11 nicklas 15   as published by the Free Software Foundation; either version 3
5634 18 May 11 nicklas 16   of the License, or (at your option) any later version.
5634 18 May 11 nicklas 17
5634 18 May 11 nicklas 18   BASE is distributed in the hope that it will be useful,
5634 18 May 11 nicklas 19   but WITHOUT ANY WARRANTY; without even the implied warranty of
5634 18 May 11 nicklas 20   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
5634 18 May 11 nicklas 21   GNU General Public License for more details.
5634 18 May 11 nicklas 22
5634 18 May 11 nicklas 23   You should have received a copy of the GNU General Public License
5634 18 May 11 nicklas 24   along with BASE. If not, see <http://www.gnu.org/licenses/>.
5634 18 May 11 nicklas 25 -->
5634 18 May 11 nicklas 26 <chapter id="migrate_2_3" chunked="0">
5782 04 Oct 11 nicklas 27   <?dbhtml filename="migrate.html" ?>
5634 18 May 11 nicklas 28   <title>Migrating code from BASE 2 to BASE 3</title>
5634 18 May 11 nicklas 29
5634 18 May 11 nicklas 30   <para>
5634 18 May 11 nicklas 31     This section gives a brief overview what has changed between BASE 2 and 
5802 12 Oct 11 nicklas 32     BASE 3 and how to migrate plug-in or extension code to BASE 3.
5634 18 May 11 nicklas 33     Do not expect that your code can be installed and function as intended
5634 18 May 11 nicklas 34     right out of the box.
5634 18 May 11 nicklas 35   </para>
5634 18 May 11 nicklas 36   
5634 18 May 11 nicklas 37   <sect1 id="migrate_2_3.compiling">
5634 18 May 11 nicklas 38     <title>Compiling the code against BASE 3</title>
5634 18 May 11 nicklas 39     
5634 18 May 11 nicklas 40     <bridgehead>All deprecated methods and classes have been removed</bridgehead>
5634 18 May 11 nicklas 41     <para>
5634 18 May 11 nicklas 42       Before trying to compile your code against the BASE 3 API we recommend that
5634 18 May 11 nicklas 43       you make sure that you are not using any deprecated methods or classes
5634 18 May 11 nicklas 44       from the BASE 2.17 API. So the first step should always be to compile
5634 18 May 11 nicklas 45       your code against the latest BASE 2.17 release. Fix any warnings
5634 18 May 11 nicklas 46       according to the instructions in the javadoc. In most cases, there is a 
5634 18 May 11 nicklas 47       simple replacment API that can be used instead. Since the deprecated API 
5634 18 May 11 nicklas 48       has been removed in BASE 3 so has the instructions. You'll need to check 
5704 22 Aug 11 nicklas 49       with the BASE 2.17 documentation which is located at:
5634 18 May 11 nicklas 50     </para>
5704 22 Aug 11 nicklas 51     
5704 22 Aug 11 nicklas 52     <itemizedlist>
5704 22 Aug 11 nicklas 53       <listitem>
7982 14 Jun 21 nicklas 54         <para><ulink url="https://base.thep.lu.se/chrome/site/2.17/html/index.html">https://base.thep.lu.se/chrome/site/2.17/html/index.html</ulink>:
5704 22 Aug 11 nicklas 55         User manual.
5704 22 Aug 11 nicklas 56         </para>
5704 22 Aug 11 nicklas 57       </listitem>
5704 22 Aug 11 nicklas 58       <listitem>
7982 14 Jun 21 nicklas 59         <para><ulink url="https://base.thep.lu.se/chrome/site/2.17/api/index.html">https://base.thep.lu.se/chrome/site/2.17/api/index.html</ulink>:
5704 22 Aug 11 nicklas 60         API documentation.
5704 22 Aug 11 nicklas 61         </para>
5704 22 Aug 11 nicklas 62       </listitem>
5704 22 Aug 11 nicklas 63     
5704 22 Aug 11 nicklas 64     </itemizedlist>
5704 22 Aug 11 nicklas 65     
5634 18 May 11 nicklas 66     <para>
5634 18 May 11 nicklas 67       Do not proceed until you are sure that your code is not using any
5634 18 May 11 nicklas 68       deprecated API.
5634 18 May 11 nicklas 69     </para>
5634 18 May 11 nicklas 70     
5634 18 May 11 nicklas 71     <bridgehead>BASE JAR files have new names</bridgehead>
5634 18 May 11 nicklas 72
5634 18 May 11 nicklas 73     <para>
5634 18 May 11 nicklas 74       All JAR files with the BASE API has been renamed to better
5802 12 Oct 11 nicklas 75       follow the scheme used by many other projects.
5634 18 May 11 nicklas 76     </para>
5634 18 May 11 nicklas 77     
5802 12 Oct 11 nicklas 78     <table frame="all" id="migrate.jarfilenames">
5802 12 Oct 11 nicklas 79       <title>JAR filename changes</title>
5802 12 Oct 11 nicklas 80       <tgroup cols="2" align="center">
5802 12 Oct 11 nicklas 81         <colspec colname="oldname" align="left"/>
5802 12 Oct 11 nicklas 82         <colspec colname="newname" align="left"/>
5802 12 Oct 11 nicklas 83         <thead>
5802 12 Oct 11 nicklas 84           <row>
5802 12 Oct 11 nicklas 85             <entry>
5802 12 Oct 11 nicklas 86               Old filename
5802 12 Oct 11 nicklas 87             </entry>
5802 12 Oct 11 nicklas 88             <entry>
5802 12 Oct 11 nicklas 89               BASE 3 filename
5802 12 Oct 11 nicklas 90             </entry>
5802 12 Oct 11 nicklas 91           </row>
5802 12 Oct 11 nicklas 92         </thead>
5802 12 Oct 11 nicklas 93         <tbody>
5802 12 Oct 11 nicklas 94           <row>
5802 12 Oct 11 nicklas 95             <entry>
5802 12 Oct 11 nicklas 96               <filename>BASE2Core.jar</filename>
5802 12 Oct 11 nicklas 97             </entry>
5802 12 Oct 11 nicklas 98             <entry>
5802 12 Oct 11 nicklas 99               <filename>base-core-3.0.0.jar</filename>
5802 12 Oct 11 nicklas 100             </entry>
5802 12 Oct 11 nicklas 101           </row>
5802 12 Oct 11 nicklas 102           <row>
5802 12 Oct 11 nicklas 103             <entry>
5802 12 Oct 11 nicklas 104               <filename>BASE2CorePlugins.jar</filename>
5802 12 Oct 11 nicklas 105             </entry>
5802 12 Oct 11 nicklas 106             <entry>
5802 12 Oct 11 nicklas 107               <filename>base-coreplugins-3.0.0.jar</filename>
5802 12 Oct 11 nicklas 108             </entry>
5802 12 Oct 11 nicklas 109           </row>
5802 12 Oct 11 nicklas 110           <row>
5802 12 Oct 11 nicklas 111             <entry>
5802 12 Oct 11 nicklas 112               <filename>BASE2Webclient.jar</filename>
5802 12 Oct 11 nicklas 113             </entry>
5802 12 Oct 11 nicklas 114             <entry>
5802 12 Oct 11 nicklas 115               <filename>base-webclient-3.0.0.jar</filename>
5802 12 Oct 11 nicklas 116             </entry>
5802 12 Oct 11 nicklas 117           </row>
5802 12 Oct 11 nicklas 118           <row>
5802 12 Oct 11 nicklas 119             <entry>
5802 12 Oct 11 nicklas 120               <filename>BASE2WSClient.jar</filename>
5802 12 Oct 11 nicklas 121             </entry>
5802 12 Oct 11 nicklas 122             <entry>
5802 12 Oct 11 nicklas 123               <filename>base-webservices-client-3.0.0.jar</filename>
5802 12 Oct 11 nicklas 124             </entry>
5802 12 Oct 11 nicklas 125           </row>
5802 12 Oct 11 nicklas 126         </tbody>
5802 12 Oct 11 nicklas 127       </tgroup>
5802 12 Oct 11 nicklas 128     </table>
5802 12 Oct 11 nicklas 129
5802 12 Oct 11 nicklas 130     <note>
5634 18 May 11 nicklas 131       Also note that the version number is included in the file name,
5634 18 May 11 nicklas 132       so the files will change when new versions are released. 
5802 12 Oct 11 nicklas 133       You'll need to make sure that your build system can handle this.
5634 18 May 11 nicklas 134       The BASE JAR files can be downloaded from 
7982 14 Jun 21 nicklas 135       <ulink url="https://base.thep.lu.se/chrome/site/files/base/jars/">https://base.thep.lu.se/chrome/site/files/base/jars/</ulink>.
5802 12 Oct 11 nicklas 136     </note>
5802 12 Oct 11 nicklas 137     
5640 24 May 11 nicklas 138   </sect1>
5640 24 May 11 nicklas 139   
5640 24 May 11 nicklas 140   <sect1 id="migrate_2_3.coreapi">
5640 24 May 11 nicklas 141   
5640 24 May 11 nicklas 142     <title>Core API changes</title>
5634 18 May 11 nicklas 143
5634 18 May 11 nicklas 144     <para>
5634 18 May 11 nicklas 145       There are lot's of other changes to the API between BASE 2 and BASE 3.
5634 18 May 11 nicklas 146       If your code is affected by those changes, you will have to update your
5634 18 May 11 nicklas 147       code. Since there are many changes, both big and small, it is not 
5634 18 May 11 nicklas 148       possible to list everything here. One good way to find out more about
5634 18 May 11 nicklas 149       the changes is to use the BASE Trac or ask on the developers mailing 
5634 18 May 11 nicklas 150       list. Some of the major changes are:
5634 18 May 11 nicklas 151     </para>
5634 18 May 11 nicklas 152         
5634 18 May 11 nicklas 153     <itemizedlist>
5634 18 May 11 nicklas 154       <listitem>
5634 18 May 11 nicklas 155         <para>
5634 18 May 11 nicklas 156           Removed the <methodname>Plugin.getAbout()</methodname> method
5634 18 May 11 nicklas 157           from the <interfacename docapi="net.sf.basedb.core.plugin">Plugin</interfacename>
5634 18 May 11 nicklas 158           interface. The information should instead be placed in the 
5634 18 May 11 nicklas 159           <filename>META-INF/extensions.xml</filename> file inside the JAR
5634 18 May 11 nicklas 160           file that the plug-in is shipped in.
5634 18 May 11 nicklas 161         </para>
5634 18 May 11 nicklas 162       </listitem>
5634 18 May 11 nicklas 163     
5634 18 May 11 nicklas 164       <listitem>
5634 18 May 11 nicklas 165         <para>
5634 18 May 11 nicklas 166           <classname>HardwareType</classname>, <classname>SoftwareType</classname>,
5634 18 May 11 nicklas 167           <classname>ProtocolType</classname> and <classname>FileType</classname>
5634 18 May 11 nicklas 168           has been replaced with <classname 
5634 18 May 11 nicklas 169           docapi="net.sf.basedb.core">ItemSubtype</classname>.
5634 18 May 11 nicklas 170           Additionally, several other items implement the new <interfacename 
5634 18 May 11 nicklas 171           docapi="net.sf.basedb.core">Subtypable</interfacename> interface.
7982 14 Jun 21 nicklas 172           See <ulink url="https://base.thep.lu.se/ticket/1597">ticket #1597 (Subtypes of items)</ulink>
5634 18 May 11 nicklas 173           for more information.
5634 18 May 11 nicklas 174         </para>
5634 18 May 11 nicklas 175       </listitem>
5634 18 May 11 nicklas 176       
5634 18 May 11 nicklas 177       <listitem>
5634 18 May 11 nicklas 178         <para>
5634 18 May 11 nicklas 179           <classname>Label</classname> has been replaced with <classname docapi="net.sf.basedb.core">Tag</classname>.
5704 22 Aug 11 nicklas 180           <classname>LabeledExtract</classname> has been merged with <classname 
5634 18 May 11 nicklas 181           docapi="net.sf.basedb.core">Extract</classname>. <classname>Hybridization</classname> has been 
5634 18 May 11 nicklas 182           replaced with <classname docapi="net.sf.basedb.core">PhysicalBioAssay</classname>. 
5634 18 May 11 nicklas 183           <classname>Scan</classname> and <classname>Image</classname> has been replaced with
5704 22 Aug 11 nicklas 184           <classname docapi="net.sf.basedb.core">DerivedBioAssay</classname>. The API for linking
5704 22 Aug 11 nicklas 185           parent/child biomaterial has been changed. The <property>pooled</property> property
5704 22 Aug 11 nicklas 186           of biomaterials has been removed.
5634 18 May 11 nicklas 187           The changes are driven by the support for sequencing experiments. The new items are
5634 18 May 11 nicklas 188           using the new subtype feature. For example, a hybridization in BASE 2 has been
5634 18 May 11 nicklas 189           converted to a physical bioassay in BASE 3 with the subtype 'Hybridization'. The
5634 18 May 11 nicklas 190           server admin can define additional subtypes. See 
7982 14 Jun 21 nicklas 191           <ulink url="https://base.thep.lu.se/ticket/1153">ticket #1153 (Handling short read 
5634 18 May 11 nicklas 192           transcript sequence data)</ulink> for more information.
5634 18 May 11 nicklas 193           
5634 18 May 11 nicklas 194         </para>
5634 18 May 11 nicklas 195       </listitem>
5634 18 May 11 nicklas 196       
5634 18 May 11 nicklas 197       <listitem>
5634 18 May 11 nicklas 198         <para>
5802 12 Oct 11 nicklas 199           <classname docapi="net.sf.basedb.core">RawBioAssay</classname> has
5802 12 Oct 11 nicklas 200           a direct link to <classname docapi="net.sf.basedb.core">Extract</classname>
5802 12 Oct 11 nicklas 201           instead of the <property>arrayIndex</property> property which has been
5802 12 Oct 11 nicklas 202           removed.
5802 12 Oct 11 nicklas 203         </para>
5802 12 Oct 11 nicklas 204       </listitem>
5802 12 Oct 11 nicklas 205       
5802 12 Oct 11 nicklas 206       <listitem>
5802 12 Oct 11 nicklas 207         <para>
5634 18 May 11 nicklas 208           Removed validator and metadata reader properties from 
5634 18 May 11 nicklas 209           <classname docapi="net.sf.basedb.core">DataFileType</classname>. 
5634 18 May 11 nicklas 210           This feature is now implemented as extensions. The API is slightly 
5640 24 May 11 nicklas 211           different and classes have been moved around a bit. See 
5640 24 May 11 nicklas 212           <xref linkend="extensions_developer.fileset_validator"/> and 
5640 24 May 11 nicklas 213           <ulink 
7982 14 Jun 21 nicklas 214           url="https://base.thep.lu.se/ticket/1598">ticket #1598 (Use 
5634 18 May 11 nicklas 215           the extensions system for data file validators and metadata readers)</ulink> for more information.
5634 18 May 11 nicklas 216         </para>
5634 18 May 11 nicklas 217       </listitem>
5634 18 May 11 nicklas 218       
5634 18 May 11 nicklas 219       <listitem>
5634 18 May 11 nicklas 220         <para>
5802 12 Oct 11 nicklas 221           A <classname docapi="net.sf.basedb.core">FileSet</classname> may
5802 12 Oct 11 nicklas 222           store more than one file for each <classname docapi="net.sf.basedb.core">DataFileType</classname>
5802 12 Oct 11 nicklas 223           which was not possible before. The API for adding files have changed.
7982 14 Jun 21 nicklas 224           See <ulink url="https://base.thep.lu.se/ticket/1604">ticket #1604
5802 12 Oct 11 nicklas 225           (Support for multiple files of the same type in a FileSet)</ulink> for 
5802 12 Oct 11 nicklas 226           more information.
5802 12 Oct 11 nicklas 227         </para>
5802 12 Oct 11 nicklas 228       </listitem>
5802 12 Oct 11 nicklas 229       
5802 12 Oct 11 nicklas 230       <listitem>
5802 12 Oct 11 nicklas 231         <para>
5758 23 Sep 11 nicklas 232           Changes to the <interfacename docapi="net.sf.basedb.util.zip">FileUnpacker</interfacename> 
5758 23 Sep 11 nicklas 233           interface. The <methodname>unpack()</methodname> method signature has changed and
5758 23 Sep 11 nicklas 234           any plug-ins that implement this interface need to be updated. The changes
5758 23 Sep 11 nicklas 235           make it possible to get information about the main zip/tar file that is being
5758 23 Sep 11 nicklas 236           unpacked. See <ulink 
7982 14 Jun 21 nicklas 237           url="https://base.thep.lu.se/ticket/978">ticket #978 (Unzipped files never inherit 
5758 23 Sep 11 nicklas 238           file type specified during upload)</ulink> for more information.
5758 23 Sep 11 nicklas 239         </para>
5758 23 Sep 11 nicklas 240       </listitem>
5827 26 Oct 11 nicklas 241       
5827 26 Oct 11 nicklas 242       <listitem>
5827 26 Oct 11 nicklas 243         <para>
5827 26 Oct 11 nicklas 244           Encrypting passwords before logging in is no longer supported. The
5827 26 Oct 11 nicklas 245           <methodname>SessionControl.login()</methodname> has been changed to
5827 26 Oct 11 nicklas 246           reflect this. While this may seem like a reduction in security it is not.
5827 26 Oct 11 nicklas 247           The previously used scheme with MD5 hashes can be cracked by brute-force on 
5827 26 Oct 11 nicklas 248           a moderate computer today. If additional security is needed we recommend that
5827 26 Oct 11 nicklas 249           BASE is installed with HTTPS access only. See <ulink 
7982 14 Jun 21 nicklas 250           url="https://base.thep.lu.se/ticket/1641">ticket #1641 (Use bcrypt for storing 
5827 26 Oct 11 nicklas 251           passwords instead of MD5)</ulink> for more information.
5827 26 Oct 11 nicklas 252         </para>
5827 26 Oct 11 nicklas 253       </listitem>
5827 26 Oct 11 nicklas 254       
5634 18 May 11 nicklas 255     </itemizedlist>
5802 12 Oct 11 nicklas 256
5634 18 May 11 nicklas 257   </sect1>
5634 18 May 11 nicklas 258   
5634 18 May 11 nicklas 259   <sect1 id="migrate_2_3.packaging">
5802 12 Oct 11 nicklas 260     <title>Packaging your plug-in so that it installs in BASE 3</title>
5634 18 May 11 nicklas 261     
5634 18 May 11 nicklas 262     <para>
5634 18 May 11 nicklas 263       The installation system for plug-ins and extensions has been reworked. We hope
5634 18 May 11 nicklas 264       that it is easier to install things now. Basically, the plug-in installation wizard
5634 18 May 11 nicklas 265       has been merged with the extensions installation wizard. If your package contain only
5634 18 May 11 nicklas 266       extensions it will probably install without changes. Packages with plug-ins need some
5634 18 May 11 nicklas 267       changes to the XML files.
5634 18 May 11 nicklas 268     </para>
5634 18 May 11 nicklas 269     
5634 18 May 11 nicklas 270     <itemizedlist>
5634 18 May 11 nicklas 271       <listitem>
5634 18 May 11 nicklas 272         <para>
5634 18 May 11 nicklas 273         The information that was in 
5634 18 May 11 nicklas 274         <filename>META-INF/base-plugins.xml</filename>, should be moved to 
5830 27 Oct 11 nicklas 275         <filename>META-INF/extensions.xml</filename>. The XML syntax in the new 
5830 27 Oct 11 nicklas 276         file is different from the old file. You'll also need to put
5830 27 Oct 11 nicklas 277         the information was returned by the <methodname>Plugin.getAbout()</methodname>
5830 27 Oct 11 nicklas 278         method in this file. See <xref 
5830 27 Oct 11 nicklas 279         linkend="plugin_developer.organize.autoinstallcompatible" /> 
5634 18 May 11 nicklas 280         for more information.
5634 18 May 11 nicklas 281         </para>
5634 18 May 11 nicklas 282       </listitem>
5634 18 May 11 nicklas 283       
5634 18 May 11 nicklas 284       <listitem>
5634 18 May 11 nicklas 285         <para>
5634 18 May 11 nicklas 286         The information that was in 
5634 18 May 11 nicklas 287         <filename>META-INF/base-configurations.xml</filename>, should be moved to 
5634 18 May 11 nicklas 288         <filename>META-INF/plugin-configurations.xml</filename>. The XML syntax in the
5634 18 May 11 nicklas 289         new and old file is the same.
5634 18 May 11 nicklas 290         </para>
5634 18 May 11 nicklas 291       </listitem>
5704 22 Aug 11 nicklas 292       
5704 22 Aug 11 nicklas 293       <listitem>
5704 22 Aug 11 nicklas 294         <para>
5704 22 Aug 11 nicklas 295           All plug-ins and extensions are required to be installed in the directory specified by 
5704 22 Aug 11 nicklas 296           <code>plugins.dir</code> setting in the <filename>base.config</filename> file. Sub-directories
5704 22 Aug 11 nicklas 297           are <emphasis>not</emphasis> searched any longer.
5704 22 Aug 11 nicklas 298           This is usually not something that you need to worry about as a developer except that
5802 12 Oct 11 nicklas 299           you should make sure the installation instruction are up to date. See 
5802 12 Oct 11 nicklas 300           <xref linkend="plugins.installation" /> and
5802 12 Oct 11 nicklas 301           <ulink 
7982 14 Jun 21 nicklas 302           url="https://base.thep.lu.se/ticket/1592">ticket #1592 (Unified installation 
5704 22 Aug 11 nicklas 303           procedure for plug-ins, extensions and more...)</ulink> for more information.
5704 22 Aug 11 nicklas 304         </para>
5704 22 Aug 11 nicklas 305       </listitem>
5704 22 Aug 11 nicklas 306       
5704 22 Aug 11 nicklas 307       <listitem>
5704 22 Aug 11 nicklas 308         <para>
5704 22 Aug 11 nicklas 309           Plug-ins/extensions that depend on 3-rd party JAR files are now recommended to include
5704 22 Aug 11 nicklas 310           those JAR file inside the <filename>META-INF/lib</filename> directory in the plug-in
5704 22 Aug 11 nicklas 311           JAR file. The <property>Class-Path</property> attribute in <filename>META-INF/MANIFEST.MF</filename>
5704 22 Aug 11 nicklas 312           must still be set. See <xref linkend="plugin_developer.organize"/> and <ulink 
7982 14 Jun 21 nicklas 313           url="https://base.thep.lu.se/ticket/1594">ticket #1594 (JarClassLoader support for JARs within JARs)</ulink>.
5704 22 Aug 11 nicklas 314         </para>
5704 22 Aug 11 nicklas 315       </listitem>
5704 22 Aug 11 nicklas 316       
5634 18 May 11 nicklas 317     </itemizedlist>
5634 18 May 11 nicklas 318     
5634 18 May 11 nicklas 319   </sect1>
5634 18 May 11 nicklas 320   
5634 18 May 11 nicklas 321 </chapter>

Generated on Sat Oct  7 02:27:18 2023 (UTC) by svndigest 0.11.2pre (dev build 1672)