source: trunk/doc/src/docbook/appendix/update_warnings.xml @ 7916

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE appendix PUBLIC 
    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" 
    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
<!--
  $Id: update_warnings.xml 7916 2021-02-24 07:50:51Z nicklas $
  
  Copyright (C) 2007 Peter Johansson, 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/>.
-->

<appendix id="appendix.update_warnings">
  <?dbhtml filename="updatewarnings.html" ?>
  <title>Things to consider when updating an existing BASE installation</title>
  <para>
    This document is a list of things that may have to be considered 
    when updating a BASE installation to a newer version. The <xref 
    linkend="installation.upgrade" /> section only include the most 
    recent information that is needed for updating the previous BASE version
    to the current version.
  </para>

  <sect1 id="appendix.update_warnings.3.18">
    <title>BASE 3.18</title>

    <bridgehead>Support for MySQL is ending in BASE 3.19</bridgehead>
    <para>
      This is the last release of BASE that is tested with MySQL 8.0.
      Starting with BASE 3.19 we will only test with and support PostgreSQL.
      BASE may still work with MySQL after that, but we recommend that 
      existing installations are migrated to PostgreSQL as soon as possible.
    </para>
  
  </sect1>


  <sect1 id="appendix.update_warnings.3.17">
    <title>BASE 3.17</title>
  
    <bridgehead>MySQL versions before 8.0 are no longer supported</bridgehead>
    <para>
      Starting with this release, we no longer test BASE with MySQL versions
      before 8.0. We are recommending existing installations are upgraded to
      use MySQL 8 or migrated to PostgreSQL.
    </para>
    
  </sect1>

  
  <sect1 id="appendix.update_warnings.3.16">
    <title>BASE 3.16</title>
  
    <bridgehead>Java 11 or later is now required (OpenJDK)</bridgehead>
    <para>
      Starting with this release, Java 11 is required for running BASE. 
      BASE 3.15 was the last BASE version with support for Java 8. 
      Note that Oracle no longer provide a free JDK or JRE.
      Instead, OpenJDK has to be used, which can be downloaded from 
      <ulink url="https://openjdk.java.net/" />
    </para>
    
    <bridgehead>Tomcat 8 and PostgreSQL 9 are no longer supported</bridgehead>
    <para>
      Starting with this release, we no longer test BASE with Tomcat 8
      or PostgreSQL 9. Thus, we are recommening that existing installations
      are upgraded to at least Tomcat 9 and PostgreSQL 11.
    </para>
    
  </sect1>
  
  <sect1 id="appendix.update_warnings.3.15">
    <title>BASE 3.15</title>
  
    <bridgehead>Consider upgrading to Java 11 (OpenJDK)</bridgehead>
    <para>
      The next BASE release, BASE 3.16, will only support Java 11 or later. BASE 3.15 is 
      the last BASE version that supports Java 8. Our recommendation is to upgrade to
      Java 11 as soon as possible. Note that Oracle no longer provide a free JDK or JRE.
      Instead, OpenJDK has to be used, which can be downloaded from 
      <ulink url="https://openjdk.java.net/" />
    </para>
    
    <para>
      If you experience any problems with BASE 3.15 and Java 8
      you could try removing the listed files from the <filename>www/WEB-INF/lib</filename>
      directory and then restart Tomcat.
    </para>
    
    <itemizedlist>
      <listitem><filename>java.activation-api-1.2.0.jar</filename></listitem>
      <listitem><filename>jaxb-api-2.3.1.jar</filename></listitem>
      <listitem><filename>jaxb-core-2.3.0.1.jar</filename></listitem>
      <listitem><filename>jaxb-impl-2.3.1.jar</filename></listitem>
    </itemizedlist>
  
    <bridgehead>Consider upgrading to Tomcat 9 and PostgreSQL 11</bridgehead>
    <para>
      We have started to test BASE with Tomcat 9 and PostgreSQL 11 and we have 
      not found any problems  so far. For new installations we recommend that Tomcat 9 
      and PostgreSQL 11 is used. Official support for Tomcat 8 and PostgreSQL 9 will be 
      dropped in a future BASE version. For existing installations our recommendation
      is to start planning for an upgrade to Tomcat 9 and PostgreSQL 11.
    </para>
  
    <bridgehead>Secondary storage support has been removed</bridgehead>
    <para>
      The <guilabel>Secondary storage</guilabel> feature has been removed. 
      Files that are located in the secondary storage will be marked as offline
      by the upgrade script. The recommendation is to replace this feature with 
      an external files solution instead.
    </para>
    
    <bridgehead>Spot images support has been removed</bridgehead>
    <para>
      It is no longer possible to create new spot images or view existing
      spot images via the BASE web client. Existing source image files and
      zip archives with generated spot images have not been removed.
    </para>
  
    <bridgehead>Customizations made in Tomcat's global web.xml file</bridgehead>
    <para>
      In the configuration directory for Tomcat there is a <filename>web.xml</filename>
      file that define global options for all web applications. The settings in this file
      can be overridden per web application in the <filename>WEB-INF/classes/web.xml</filename>.
      BASE 3.15 re-defines the <code>jsp</code> <sgmltag class="starttag">servlet</sgmltag>
      definition to make sure that JSP files are compiled with proper settings. Changes that
      have been made to the global <filename>web.xml</filename> file for the <code>jsp</code>
      <sgmltag class="starttag">servlet</sgmltag> must be moved or copied to the 
      <filename>web.xml</filename> file for the BASE web application.
    </para>
  
  </sect1>
  
  <sect1 id="appendix.update_warnings.3.14">
    <title>BASE 3.14</title>
  
    <bridgehead>The db.driver setting is no longer used</bridgehead>
    <para>
      The JDBC driver to use is now found automatically based on
      the <constant>db.url</constant> setting in the <filename>base.config</filename>
      file. The <constant>db.driver</constant> setting can be removed.
    </para>
    
    <bridgehead>The (very) old Authenticator API has been removed</bridgehead>
    <para>
      The <code>net.sf.basedb.core.authentication.Authenticator</code>
      interface and other related code that was deprecated in BASE 3.3
      has been removed. Systems that still use old authentication code 
      need to replace this with a newer version before updating.
    </para>

    <bridgehead>Changes to the authentication system</bridgehead>
    <para>
      The authentication system has been updated to make it easier to
      install more than one external authentication manager. The changes
      are backwards compatible and existing authentication managers should
      still work as before as long as they are the only ones installed.
      However, the existing authentication managers will probably not work
      well if more than one is installed since they lack some features that
      are neccessary in order to cooperate with other managers. Before installing
      more than one authentication manager it is recommended that they are
      updated to newer versions.
    </para>
    
    <para>
      Newer authentication managers typically no longer provide support for
      password authentication. If the intention is that some users still should be 
      able to login with username+password, it is recommended that the 
      <guilabel>Password login form</guilabel> is enabled. Go to
      <menuchoice>
        <guimenu>Administrate</guimenu>
        <guisubmenu>Plug-ins &amp; extensions</guisubmenu>
        <guimenuitem>Overview</guimenuitem>
      </menuchoice> and locate the <guilabel>Login form customization</guilabel>
      extension point to find it.
    </para>
    
  </sect1>
  
  <sect1 id="appendix.update_warnings.3.11.1">
    <title>BASE 3.11.1</title>
  
    <bridgehead>Free wells on bioplates</bridgehead>
    <para>
      A bug that affected the free wells information on bioplates 
      has been fixed. Existing bioplates may have incorrect number of
      free wells and can be fixed by running a special script.
      
      After installing the BASE 3.11.1 update, change directory to 
      <filename class="directory">&lt;base-dir&gt;/bin/</filename> 
      and issue
<programlisting>
./onetimefix.sh free_wells -u &lt;root login&gt; -p &lt;root pwd&gt;
</programlisting>
    </para>
    
  </sect1>
  
  <sect1 id="appendix.update_warnings.3.10">
    <title>BASE 3.10</title>
  
    <bridgehead>Changed permissions for annotating items</bridgehead>
    <para>
      Before BASE 3.10 a user was able to create/change/delete annotations on
      an item if the user has <code>WRITE</code> permission on the item and 
      <code>READ</code> permission on the  annotation type. 
      In BASE 3.10 several changes has been made:
    </para>
    
    <itemizedlist>
      <listitem>
        <para>
          <code>USE</code> permission is required on the annotation type to be able 
          to create/change/delete annotations of that type. This may cause user to no
          longer be able to annotate certain items, unless their permissions
          are upgraded to <code>USE</code>. Users with <code>READ</code> permission 
          can only read the annotation values.
        </para>
      </listitem>
      
      <listitem>
        <para>
          A new permission level, <code>ANNOTATE</code>, has been introduced. 
          In the permission hierarchy this sits between the <code>READ</code> 
          and <code>WRITE</code> permission and can be used to give users 
          permissions to manage annotations but not other properties of an item. 
          All users with <code>WRITE</code> permission automatically get 
          <code>ANNOTATE</code> permission so this change should not affect current
          users.
        </para>
      </listitem>
    </itemizedlist>
  
  </sect1>
  
  
  <sect1 id="appendix.update_warnings.3.9">
    <title>BASE 3.9</title>
  
    <bridgehead>Incompatible API change Application API</bridgehead>
    <para>
      The <classname docapi="net.sf.basedb.core">Application.getSessionControl()</classname> 
      method for getting access to an existing session has been deprecated. A new
      version has been implemented that require that an <emphasis>external client id</emphasis>
      is specified. Extensions and other client application may stop working unless
      they are updated. See alos <xref linkend="appendix.incompatible.session-control"/>.
    </para>
  
  </sect1>
  
  
  <sect1 id="appendix.update_warnings.3.8">
    <title>BASE 3.8</title>
  
    <bridgehead>updateindexes.sh is no longer needed</bridgehead>
    <para>
      It is no longer needed to run the <filename>updateindexes.sh</filename>
      script as part of the upgrade or installation procedure. The funtionality
      has been integrated into the regular <filename>updatedb.sh/initdb.sh</filename>
      scripts.
    </para>
    
    <bridgehead>Incompatible API change in ServiceSessionControl</bridgehead>
    <para>
      The <classname docapi="net.sf.basedb.core">ServiceSessionControl</classname> API for 
      configuration and building Hibernate <classname>SessionFactory</classname>
      instances has been changed due the Hibernate 5 upgrade. This change affects
      extensions that use the API for storing their own data inside the BASE database.
      Extensions that use this API must be updated or they will not work with BASE 3.8.
    </para>
  
  </sect1>
  
  <sect1 id="appendix.update_warnings.3.6">
    <title>BASE 3.6</title>
  
    <bridgehead>Update to Java 8</bridgehead>
    <para>
      BASE will no longer run with Java 7. Unless you have already
      updated to Java 8 you should do so before updating to BASE 3.6.
      Note that BASE 3.5 works with both Java 7 and 8 so the Java 
      update can be made ahead of time.
    </para>
    
    <bridgehead>Update to Tomcat 8</bridgehead>
    <para>
      Tomcat 7 is no longer supported. We recommend updating
      to Tomcat 8 before updating to BASE 3.6. Note that 
      BASE 3.5 works with both Tomcat 7 and 8 so the Tomcat 
      update can be made ahead of time.
    </para>
  
  </sect1>
  
  <sect1 id="appendix.update_warnings.3.5">
    <title>BASE 3.5</title>

    <bridgehead>Biomaterial lists have been replaced with item lists</bridgehead>
    <para>
      This is a major change that has caused a binary incompatibility in the BASE core
      API. If you depend on custom extensions or plug-ins that use the biomaterial list
      API this code must be updated before updating to BASE 3.5. Read more
      about the incompatibilities in <xref linkend="appendix.incompatible.itemlists" />.
    </para>
    
    <bridgehead>Consider updating to Java 8</bridgehead>
    <para>
      Oracle is no longer supporting Java 1.7. We are recommending Java 8
      for running BASE. Java 7 is still supported, but will be removed
      in the next version (BASE 3.6).
    </para>
    
    <bridgehead>Consider updating to Tomcat 8</bridgehead>
    <para>
      We have now tested BASE with Tomcat 8 and it seems to work without
      any problems. Support for Tomcat 7 will be removed in the next 
      version (BASE 3.6).
    </para>
    
  </sect1>
  
  <sect1 id="appendix.update_warnings.3.4">
    <title>BASE 3.4</title>
    
    <bridgehead>Updating from BASE 2.17 is no longer possible</bridgehead>
    <para>
      If you are still running an BASE 2.17 (or earlier) BASE version
      and want to update to BASE 3.4 you must first update to BASE 3.3
      or earlier.
    </para>
    
    <bridgehead>Web services support has been removed</bridgehead>
    <para>
      As announced earlier web services support has been removed in BASE 3.4.
      If anyone require web services support or similar we recommend using the BASE 
      extensions mechanism to implement exactly what is needed for that project and 
      we also beleive that a simplier API such as JSON is preferable.
    </para>
    
    <bridgehead>PostgreSQL users should change db.dialect</bridgehead>
    <para>
      In <filename>base.config</filename> there is a <constant>db.config</constant>
      setting. Servers running with PostgreSQL as the database should change the
      dialect to <classname>org.hibernate.dialect.PostgreSQL9Dialect</classname>
      since the <classname>org.hibernate.dialect.PostgreSQLDialect</classname> has
      been deprecated.
    </para>
    
  </sect1>

  <sect1 id="appendix.update_warnings.3.3.3">
    <title>BASE 3.3.3</title>
  
    <bridgehead>Remaining quantity</bridgehead>
    <para>
      A bug that affected remaining quantity calculations for 
      biomaterial item has been fixed. Existing items may have been
      saved with incorrect remaining quantity and must be fixed.
      After installing the BASE 3.3.3 update, the existing
      remaining quantity values are fix by running a special script.
      Change directory to <filename class="directory">&lt;base-dir&gt;/bin/</filename> 
      and issue
<programlisting>
./onetimefix.sh remaining_quantity -u &lt;root login&gt; -p &lt;root pwd&gt;
</programlisting>
    </para>
    
  </sect1>
  
  <sect1 id="appendix.update_warnings.3.3">
    <title>BASE 3.3</title>

    <bridgehead>Content security policy</bridgehead>
    <para>
      The BASE web client now set a rather strict <emphasis>Content 
      Security Policy</emphasis> that prevent browsers from executing
      code (including JavaScript) that is considered unsafe. Some extensions
      may cease to work due to this. Go to
      <menuchoice>
        <guimenu>Administrate</guimenu>
        <guimenuitem>Plug-ins &amp; extensions</guimenuitem>
        <guimenuitem>Overview</guimenuitem>
      </menuchoice> 
      (after upgrading) to see if there are any warnings about this.
      Read more in <xref linkend="appendix.web.xml.csp-filter" />
      for information about how to relax the policy.
    </para>

    <bridgehead>Java SE 7 is required</bridgehead>
    <para>
      BASE now require <ulink url="http://www.oracle.com/technetwork/java/javase/downloads/index.html">Java SE 7</ulink>. 
      Servers with Java SE 6 or older should be updated to Java SE 7 before installing BASE 3.3.
    </para>

    <bridgehead>Tomcat 7 is required</bridgehead>
    <para>
      BASE now require <ulink url="http://tomcat.apache.org/download-70.cgi">Tomcat 7</ulink>.
      Servers with Tomcat 6 or older should be updated to Tomcat 7 before installing BASE 3.3.
    </para>
    
    <bridgehead>Web services support has been deprecated</bridgehead>
    <para>
      The current implementation is most likely not very useful and has limited
      support for accessing information in BASE. Therefore it has been decided to
      remove the web services support in BASE 3.4. If anyone require web services
      support or similar we recommend using the BASE extensions mechanism to implement
      exactly what is needed for that project and we also beleive that a simplier
      API such as JSON is preferable.
    </para>

  </sect1>
  
  <sect1 id="appendix.update_warnings.3.2">
    <title>BASE 3.2</title>
  
    <bridgehead>Custom logging implementations must be updated</bridgehead>
    <para>
      The plug-in functionality for custom logging has been converted
      to an extension point. The default database logging will continue
      to function, but custom logging implementations must be converted
      to an extension. See <xref linkend="appendix.incompatible.3.2" /> and 
      <xref linkend="extensions_developer.logging" /> for more information.
    </para>
  
  </sect1>
  
  <sect1 id="appendix.update_warnings.3.0">
    <title>BASE 3.0</title>
    
    <note>
      <title>Upgrading to BASE 3 is possible from BASE 2.17 only</title>
      <para>
        If your BASE is an older 2.x version you'll need to upgrade
        to BASE 2.17 before an upgrade to BASE 3 is possible. Also note
        that since BASE 3.3 we no longer actively test the upgrade
        script. If upgrading doesn't work for a particular BASE 3.x version 
        (where x &gt; 2) please try to upgrade to BASE 3.2 first and then 
        from BASE 3.2 to BASE 3.x.
      </para>
    </note>

    <warning>
      <title>Make sure that you have a recent backup of the BASE 2.17 database</title>
      <para>
        Before starting the upgrade from BASE 2.17 to BASE 3 ensure that you
        have a recent backup. If the upgrade fails you must restore the 
        2.17 database before you can try again. The upgrade only changes the
        'static' part of the database, so you do not have to restore the
        'dynamic' part or the uploaded files.
      </para>
    </warning>

    <bridgehead>Old plug-ins and extensions may not work</bridgehead>
    <para>
      The BASE API has changed in several places and it is not certain that
      plug-ins and extensions developed for BASE 2 works with BASE 3. The
      upgrade will disable all plug-ins and extensions that are currently installed.
      Before you upgrade we recommend that you go through all (external) plug-ins
      and check if there is an updated version. The recommended approach
      is to first upgrade BASE and then install updated versions of plug-ins
      and extensions following the instructions in <xref 
      linkend="plugins.installation"/>.
    </para>
    
    <para>
      If there is no updated version of a specific plug-in you may try 
      a manual re-installation of the old plug-ins. Follow the instructions
      in <xref linkend="plugins.installation.manual" />.
    </para>
    
    <para>
      If there is no updated version and the old plug-in doesn't work with
      BASE 3, you'll need to decide if you really need the plug-in or if
      the upgrade should wait until a new version of the plug-in 
      has been released.
    </para>
    
    <bridgehead>Batch item importer changes</bridgehead>
    <para>
      There are several changes to batch item importers that may affect
      current workflows and file templates used for importing data.
    </para>
    
    <itemizedlist>
      <listitem>
        <para>
          Sample and extract importers: The 'pooled' column is no longer used.
          Instead a 'parent type' column should be used with
          the parent type as a string value (BIOSOURCE, SAMPLE or EXTRACT). 
          Existing importer configurations and file templates may have to be 
          updated. If no parent type is specified the sample importer assumes
          a biosource and the extract importer assumes a sample.
        </para>
      </listitem>
      <listitem>
        <para>
          Labeled extract importer: This has been deprecated and it is recommended
          that the <emphasis>Extract importer</emphasis> is used instead. 
          We recommend that existing labeled extract importer configurations are re-created as extract 
          importer configurations. The old labeled extract importer can be 
          re-enabled, but note that the existing configurations still need
          to be changed due to the 'pooled' column is no longer used.
        </para>
      </listitem>
      <listitem>
        <para>
          Hybridization importer: This has been deprecated and we recommend
          that the <emphasis>Physical bioassay importer</emphasis> is used instead. 
          Existing hybridization importer configurations should be re-created as 
          physical bioassay importer configurations. 
        </para>
      </listitem>
      <listitem>
        <para>
          Scan importer: This has been deprecated and it is recommended
          that the <emphasis>Derived bioassay importer</emphasis> is used instead. 
          Existing scan importer configurations should be re-created as derived 
          bioassay importer configurations.
        </para>
      </listitem>
    </itemizedlist>
    
    <note>
      The deprecated importers can be re-enabled by an administrator from the 
      <menuchoice>
        <guimenu>Administrate</guimenu>
        <guisubmenu>Plug-ins &amp; extensions</guisubmenu>
        <guimenuitem>Overview</guimenuitem>
      </menuchoice> page, but they are
      lacking features that are available in the new importers so this is not
      something that we recommend.
    </note>
    
    <bridgehead>MySQL and PostgreSQL versions</bridgehead>
    <para>
      We have only tested BASE 3 with PostgreSQL 9.1. If anyone
      experiences any issues with earlier PostgreSQL versions, we 
      recommend an upgrade to PostgreSQL 9.1. This is a change since
      BASE 2 which was tested with PostgreSQL 8.4. Even though BASE 3 
      may work with older PostgreSQL versions, we don't have the resources 
      needed to test and provide support for it.
    </para>
    
    <para>
      We have only tested BASE 3 with MySQL 5.1 (no change since BASE 2). 
      If anyone experiences any issues with earlier (or later) MySQL versions, 
      we recommend an upgrade/downgrade to MySQL 5.1.
    </para>
  
  </sect1>
  
  <sect1 id="appendix.update_warnings.2.x">
    <title>All BASE 2.x releases</title>
    
    <para>
      We only support updating to BASE 3 from BASE 2.17. If you have an older BASE
      version and wish to update to BASE 3, you first have to upgrade to BASE 2.17.
      BASE 2.17 can be downloaded from the <ulink url="http://base.thep.lu.se/wiki/DownloadPage">BASE 
      download page</ulink>. Documentation for BASE 2.17 is available as part of the
      download and at <ulink url="http://base.thep.lu.se/chrome/site/2.17/html/index.html"
      >http://base.thep.lu.se/chrome/site/2.17/html/index.html</ulink>.
    </para>

  </sect1>
  
</appendix>