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

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE part PUBLIC 
    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" 
    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
<!--
  $Id$

  Copyright (C) 2011 Nicklas Nordborg

  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 3
  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 BASE. If not, see <http://www.gnu.org/licenses/>.
-->
<chapter id="migrate_2_3" chunked="0">
  <?dbhtml dir="migrate_2_3"?>
  <title>Migrating code from BASE 2 to BASE 3</title>

  <para>
    This section gives a brief overview what has changed between BASE 2 and 
    BASE 3 and how to migrate your plug-in or extension code to BASE 3.
    Do not expect that your code can be installed and function as intended
    right out of the box.
  </para>
  
  <sect1 id="migrate_2_3.compiling">
    <title>Compiling the code against BASE 3</title>
    
    <bridgehead>All deprecated methods and classes have been removed</bridgehead>
    <para>
      Before trying to compile your code against the BASE 3 API we recommend that
      you make sure that you are not using any deprecated methods or classes
      from the BASE 2.17 API. So the first step should always be to compile
      your code against the latest BASE 2.17 release. Fix any warnings
      according to the instructions in the javadoc. In most cases, there is a 
      simple replacment API that can be used instead. Since the deprecated API 
      has been removed in BASE 3 so has the instructions. You'll need to check 
      with the BASE 2.17 documentation which is located at 
      <ulink url="http://base.thep.lu.se/chrome/site/2.17">http://base.thep.lu.se/chrome/site/2.17</ulink>.
    </para>
    <para>
      Do not proceed until you are sure that your code is not using any
      deprecated API.
    </para>
    
    <bridgehead>BASE JAR files have new names</bridgehead>

    <para>
      All JAR files with the BASE API has been renamed to better
      follow the scheme used by many other projects. For example,
      <filename>BASE2Core.jar</filename> has been renamed to
      <filename>base-core-3.0.0.jar</filename>, 
      <filename>BASE2Webclient.jar</filename> has been renamed to
      <filename>base-webclient-3.0.0.jar</filename>, and so on.
    </para>
    
    <para>
      You'll need to make sure that your build system can handle this.
      Also note that the version number is included in the file name,
      so the files will change when new versions are released. 
      The BASE JAR files can be downloaded from 
      <ulink url="http://base2.thep.lu.se/base/jars/">http://base2.thep.lu.se/base/jars/</ulink>.
    </para>
      
    <bridgehead>Other changes to the API</bridgehead>

    <para>
      There are lot's of other changes to the API between BASE 2 and BASE 3.
      If your code is affected by those changes, you will have to update your
      code. Since there are many changes, both big and small, it is not 
      possible to list everything here. One good way to find out more about
      the changes is to use the BASE Trac or ask on the developers mailing 
      list. Some of the major changes are:
    </para>
        
    <itemizedlist>
      <listitem>
        <para>
          Removed the <methodname>Plugin.getAbout()</methodname> method
          from the <interfacename docapi="net.sf.basedb.core.plugin">Plugin</interfacename>
          interface. The information should instead be placed in the 
          <filename>META-INF/extensions.xml</filename> file inside the JAR
          file that the plug-in is shipped in.
        </para>
      </listitem>
    
      <listitem>
        <para>
          <classname>HardwareType</classname>, <classname>SoftwareType</classname>,
          <classname>ProtocolType</classname> and <classname>FileType</classname>
          has been replaced with <classname 
          docapi="net.sf.basedb.core">ItemSubtype</classname>.
          Additionally, several other items implement the new <interfacename 
          docapi="net.sf.basedb.core">Subtypable</interfacename> interface.
          See <ulink url="http://base.thep.lu.se/ticket/1597">ticket #1597 (Subtypes of items)</ulink>
          for more information.
        </para>
      </listitem>
      
      <listitem>
        <para>
          <classname>Label</classname> has been replaced with <classname docapi="net.sf.basedb.core">Tag</classname>.
          <classname>LabeledExtract</classname> has been merged into <classname 
          docapi="net.sf.basedb.core">Extract</classname>. <classname>Hybridization</classname> has been 
          replaced with <classname docapi="net.sf.basedb.core">PhysicalBioAssay</classname>. 
          <classname>Scan</classname> and <classname>Image</classname> has been replaced with
          <classname docapi="net.sf.basedb.core">BioAssayEvent</classname>,
          <classname docapi="net.sf.basedb.core">DerivedBioAssaySet</classname> and
          <classname docapi="net.sf.basedb.core">DerivedBioAssay</classname>.
          The changes are driven by the support for sequencing experiments. The new items are
          using the new subtype feature. For example, a hybridization in BASE 2 has been
          converted to a physical bioassay in BASE 3 with the subtype 'Hybridization'. The
          server admin can define additional subtypes. See 
          <ulink url="http://base.thep.lu.se/ticket/1153">ticket #1153 (Handling short read 
          transcript sequence data)</ulink> for more information.
          
        </para>
      </listitem>
      
      <listitem>
        <para>
          Removed validator and metadata reader properties from 
          <classname docapi="net.sf.basedb.core">DataFileType</classname>. 
          This feature is now implemented as extensions. The API is slightly 
          different and classes have been moved around a bit. See <ulink 
          url="http://base.thep.lu.se/ticket/1598">ticket #1598 (Use 
          the extensions system for data file validators and metadata readers)</ulink> for more information.
        </para>
      </listitem>
      
      <listitem>
        <para>
          TODO -- more will probably be added to this list
        </para>
      </listitem>
    </itemizedlist>
        
      
  </sect1>
  
  <sect1 id="migrate_2_3.packaging">
    <title>Packaging your code so that it installs in BASE 3</title>
    
    <para>
      The installation system for plug-ins and extensions has been reworked. We hope
      that it is easier to install things now. Basically, the plug-in installation wizard
      has been merged with the extensions installation wizard. If your package contain only
      extensions it will probably install without changes. Packages with plug-ins need some
      changes to the XML files.
    </para>
    
    <itemizedlist>
      <listitem>
        <para>
        The information that was in 
        <filename>META-INF/base-plugins.xml</filename>, should be moved to 
        <filename>META-INF/extensions.xml</filename>. The XML syntax in the new file is different
        from the old file. See <xref linkend="plugin_developer.organize.autoinstallcompatible" />
        for more information.
        </para>
      </listitem>
      
      <listitem>
        <para>
        The information that was in 
        <filename>META-INF/base-configurations.xml</filename>, should be moved to 
        <filename>META-INF/plugin-configurations.xml</filename>. The XML syntax in the
        new and old file is the same.
        </para>
      </listitem>
    </itemizedlist>
    
    <para>
      Another change is that plug-ins and extensions are 
      required to be installed in the directory specified by <code>plugins.dir</code>
      setting in the <filename>base.config</filename> file. This is usually not something that
      you need to worry about as a developer. See <ulink 
      url="http://base.thep.lu.se/ticket/1592">ticket #1592 (Unified installation 
      procedure for plug-ins, extensions and more...)</ulink> for more information.
    </para>
    
  </sect1>
  
</chapter>