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

Last change on this file since 7631 was 7631, checked in by Nicklas Nordborg, 3 years ago

References #2138: Officially support Java 11 (or later)

Updated documentation to recommend Java 11.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Date Id
File size: 20.7 KB
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE appendix PUBLIC
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: update_warnings.xml 7631 2019-03-11 08:31:16Z nicklas $
8  Copyright (C) 2007 Peter Johansson, 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 <>.
27<appendix id="appendix.update_warnings">
28  <?dbhtml filename="updatewarnings.html" ?>
29  <title>Things to consider when updating an existing BASE installation</title>
30  <para>
31    This document is a list of things that may have to be considered
32    when updating a BASE installation to a newer version. The <xref 
33    linkend="installation.upgrade" /> section only include the most
34    recent information that is needed for updating the previous BASE version
35    to the current version.
36  </para>
38  <sect1 id="appendix.update_warnings.3.15">
39    <title>BASE 3.15</title>
41    <bridgehead>Consider upgrading to Java 11 (OpenJDK)</bridgehead>
42    <para>
43      The next BASE release, BASE 3.16, will only support Java 11 or later. BASE 3.15 is
44      the last BASE version that supports Java 8. Our recommendation is to upgrade to
45      Java 11 as soon as possible. Note that Oracle no longer provide a free JDK or JRE.
46      Instead, OpenJDK has to be used, which can be downloaded from
47      <ulink url="" />
48    </para>
50    <para>
51      If you experience any problems with BASE 3.15 and Java 8
52      you could try removing the listed files from the <filename>www/WEB-INF/lib</filename>
53      directory and then restart Tomcat.
54    </para>
56    <itemizedlist>
57      <listitem><filename>java.activation-api-1.2.0.jar</filename></listitem>
58      <listitem><filename>jaxb-api-2.3.1.jar</filename></listitem>
59      <listitem><filename>jaxb-core-</filename></listitem>
60      <listitem><filename>jaxb-impl-2.3.1.jar</filename></listitem>
61    </itemizedlist>
63    <bridgehead>Consider upgrading to Tomcat 9 and PostgreSQL 11</bridgehead>
64    <para>
65      We have started to test BASE with Tomcat 9 and PostgreSQL 11 and we have
66      not found any problems  so far. For new installations we recommend that Tomcat 9
67      and PostgreSQL 11 is used. Official support for Tomcat 8 and PostgreSQL 9 will be
68      dropped in a future BASE version. For existing installations our recommendation
69      is to start planning for an upgrade to Tomcat 9 and PostgreSQL 11.
70    </para>
72    <bridgehead>Secondary storage support has been removed</bridgehead>
73    <para>
74      The <guilabel>Secondary storage</guilabel> feature has been removed.
75      Files that are located in the secondary storage will be marked as offline
76      by the upgrade script. The recommendation is to replace this feature with
77      an external files solution instead.
78    </para>
80    <bridgehead>Customizations made in Tomcat's global web.xml file</bridgehead>
81    <para>
82      In the configuration directory for Tomcat there is a <filename>web.xml</filename>
83      file that define global options for all web applications. The settings in this file
84      can be overridden per web application in the <filename>WEB-INF/classes/web.xml</filename>.
85      BASE 3.15 re-defines the <code>jsp</code> <sgmltag class="starttag">servlet</sgmltag>
86      definition to make sure that JSP files are compiled with proper settings. Changes that
87      have been made to the global <filename>web.xml</filename> file for the <code>jsp</code>
88      <sgmltag class="starttag">servlet</sgmltag> must be moved or copied to the
89      <filename>web.xml</filename> file for the BASE web application.
90    </para>
92  </sect1>
94  <sect1 id="appendix.update_warnings.3.14">
95    <title>BASE 3.14</title>
97    <bridgehead>The db.driver setting is no longer used</bridgehead>
98    <para>
99      The JDBC driver to use is now found automatically based on
100      the <constant>db.url</constant> setting in the <filename>base.config</filename>
101      file. The <constant>db.driver</constant> setting can be removed.
102    </para>
104    <bridgehead>The (very) old Authenticator API has been removed</bridgehead>
105    <para>
106      The <code>net.sf.basedb.core.authentication.Authenticator</code>
107      interface and other related code that was deprecated in BASE 3.3
108      has been removed. Systems that still use old authentication code
109      need to replace this with a newer version before updating.
110    </para>
112    <bridgehead>Changes to the authentication system</bridgehead>
113    <para>
114      The authentication system has been updated to make it easier to
115      install more than one external authentication manager. The changes
116      are backwards compatible and existing authentication managers should
117      still work as before as long as they are the only ones installed.
118      However, the existing authentication managers will probably not work
119      well if more than one is installed since they lack some features that
120      are neccessary in order to cooperate with other managers. Before installing
121      more than one authentication manager it is recommended that they are
122      updated to newer versions.
123    </para>
125    <para>
126      Newer authentication managers typically no longer provide support for
127      password authentication. If the intention is that some users still should be
128      able to login with username+password, it is recommended that the
129      <guilabel>Password login form</guilabel> is enabled. Go to
130      <menuchoice>
131        <guimenu>Administrate</guimenu>
132        <guisubmenu>Plug-ins &amp; extensions</guisubmenu>
133        <guimenuitem>Overview</guimenuitem>
134      </menuchoice> and locate the <guilabel>Login form customization</guilabel>
135      extension point to find it.
136    </para>
138  </sect1>
140  <sect1 id="appendix.update_warnings.3.11.1">
141    <title>BASE 3.11.1</title>
143    <bridgehead>Free wells on bioplates</bridgehead>
144    <para>
145      A bug that affected the free wells information on bioplates
146      has been fixed. Existing bioplates may have incorrect number of
147      free wells and can be fixed by running a special script.
149      After installing the BASE 3.11.1 update, change directory to
150      <filename class="directory">&lt;base-dir&gt;/bin/</filename> 
151      and issue
153./ free_wells -u &lt;root login&gt; -p &lt;root pwd&gt;
155    </para>
157  </sect1>
159  <sect1 id="appendix.update_warnings.3.10">
160    <title>BASE 3.10</title>
162    <bridgehead>Changed permissions for annotating items</bridgehead>
163    <para>
164      Before BASE 3.10 a user was able to create/change/delete annotations on
165      an item if the user has <code>WRITE</code> permission on the item and
166      <code>READ</code> permission on the  annotation type.
167      In BASE 3.10 several changes has been made:
168    </para>
170    <itemizedlist>
171      <listitem>
172        <para>
173          <code>USE</code> permission is required on the annotation type to be able
174          to create/change/delete annotations of that type. This may cause user to no
175          longer be able to annotate certain items, unless their permissions
176          are upgraded to <code>USE</code>. Users with <code>READ</code> permission
177          can only read the annotation values.
178        </para>
179      </listitem>
181      <listitem>
182        <para>
183          A new permission level, <code>ANNOTATE</code>, has been introduced.
184          In the permission hierarchy this sits between the <code>READ</code> 
185          and <code>WRITE</code> permission and can be used to give users
186          permissions to manage annotations but not other properties of an item.
187          All users with <code>WRITE</code> permission automatically get
188          <code>ANNOTATE</code> permission so this change should not affect current
189          users.
190        </para>
191      </listitem>
192    </itemizedlist>
194  </sect1>
197  <sect1 id="appendix.update_warnings.3.9">
198    <title>BASE 3.9</title>
200    <bridgehead>Incompatible API change Application API</bridgehead>
201    <para>
202      The <classname docapi="net.sf.basedb.core">Application.getSessionControl()</classname> 
203      method for getting access to an existing session has been deprecated. A new
204      version has been implemented that require that an <emphasis>external client id</emphasis>
205      is specified. Extensions and other client application may stop working unless
206      they are updated. See alos <xref linkend="appendix.incompatible.session-control"/>.
207    </para>
209  </sect1>
212  <sect1 id="appendix.update_warnings.3.8">
213    <title>BASE 3.8</title>
215    <bridgehead> is no longer needed</bridgehead>
216    <para>
217      It is no longer needed to run the <filename></filename>
218      script as part of the upgrade or installation procedure. The funtionality
219      has been integrated into the regular <filename></filename>
220      scripts.
221    </para>
223    <bridgehead>Incompatible API change in ServiceSessionControl</bridgehead>
224    <para>
225      The <classname docapi="net.sf.basedb.core">ServiceSessionControl</classname> API for
226      configuration and building Hibernate <classname>SessionFactory</classname>
227      instances has been changed due the Hibernate 5 upgrade. This change affects
228      extensions that use the API for storing their own data inside the BASE database.
229      Extensions that use this API must be updated or they will not work with BASE 3.8.
230    </para>
232  </sect1>
234  <sect1 id="appendix.update_warnings.3.6">
235    <title>BASE 3.6</title>
237    <bridgehead>Update to Java 8</bridgehead>
238    <para>
239      BASE will no longer run with Java 7. Unless you have already
240      updated to Java 8 you should do so before updating to BASE 3.6.
241      Note that BASE 3.5 works with both Java 7 and 8 so the Java
242      update can be made ahead of time.
243    </para>
245    <bridgehead>Update to Tomcat 8</bridgehead>
246    <para>
247      Tomcat 7 is no longer supported. We recommend updating
248      to Tomcat 8 before updating to BASE 3.6. Note that
249      BASE 3.5 works with both Tomcat 7 and 8 so the Tomcat
250      update can be made ahead of time.
251    </para>
253  </sect1>
255  <sect1 id="appendix.update_warnings.3.5">
256    <title>BASE 3.5</title>
258    <bridgehead>Biomaterial lists have been replaced with item lists</bridgehead>
259    <para>
260      This is a major change that has caused a binary incompatibility in the BASE core
261      API. If you depend on custom extensions or plug-ins that use the biomaterial list
262      API this code must be updated before updating to BASE 3.5. Read more
263      about the incompatibilities in <xref linkend="appendix.incompatible.itemlists" />.
264    </para>
266    <bridgehead>Consider updating to Java 8</bridgehead>
267    <para>
268      Oracle is no longer supporting Java 1.7. We are recommending Java 8
269      for running BASE. Java 7 is still supported, but will be removed
270      in the next version (BASE 3.6).
271    </para>
273    <bridgehead>Consider updating to Tomcat 8</bridgehead>
274    <para>
275      We have now tested BASE with Tomcat 8 and it seems to work without
276      any problems. Support for Tomcat 7 will be removed in the next
277      version (BASE 3.6).
278    </para>
280  </sect1>
282  <sect1 id="appendix.update_warnings.3.4">
283    <title>BASE 3.4</title>
285    <bridgehead>Updating from BASE 2.17 is no longer possible</bridgehead>
286    <para>
287      If you are still running an BASE 2.17 (or earlier) BASE version
288      and want to update to BASE 3.4 you must first update to BASE 3.3
289      or earlier.
290    </para>
292    <bridgehead>Web services support has been removed</bridgehead>
293    <para>
294      As announced earlier web services support has been removed in BASE 3.4.
295      If anyone require web services support or similar we recommend using the BASE
296      extensions mechanism to implement exactly what is needed for that project and
297      we also beleive that a simplier API such as JSON is preferable.
298    </para>
300    <bridgehead>PostgreSQL users should change db.dialect</bridgehead>
301    <para>
302      In <filename>base.config</filename> there is a <constant>db.config</constant>
303      setting. Servers running with PostgreSQL as the database should change the
304      dialect to <classname>org.hibernate.dialect.PostgreSQL9Dialect</classname>
305      since the <classname>org.hibernate.dialect.PostgreSQLDialect</classname> has
306      been deprecated.
307    </para>
309  </sect1>
311  <sect1 id="appendix.update_warnings.3.3.3">
312    <title>BASE 3.3.3</title>
314    <bridgehead>Remaining quantity</bridgehead>
315    <para>
316      A bug that affected remaining quantity calculations for
317      biomaterial item has been fixed. Existing items may have been
318      saved with incorrect remaining quantity and must be fixed.
319      After installing the BASE 3.3.3 update, the existing
320      remaining quantity values are fix by running a special script.
321      Change directory to <filename class="directory">&lt;base-dir&gt;/bin/</filename> 
322      and issue
324./ remaining_quantity -u &lt;root login&gt; -p &lt;root pwd&gt;
326    </para>
328  </sect1>
330  <sect1 id="appendix.update_warnings.3.3">
331    <title>BASE 3.3</title>
333    <bridgehead>Content security policy</bridgehead>
334    <para>
335      The BASE web client now set a rather strict <emphasis>Content
336      Security Policy</emphasis> that prevent browsers from executing
337      code (including JavaScript) that is considered unsafe. Some extensions
338      may cease to work due to this. Go to
339      <menuchoice>
340        <guimenu>Administrate</guimenu>
341        <guimenuitem>Plug-ins &amp; extensions</guimenuitem>
342        <guimenuitem>Overview</guimenuitem>
343      </menuchoice> 
344      (after upgrading) to see if there are any warnings about this.
345      Read more in <xref linkend="appendix.web.xml.csp-filter" />
346      for information about how to relax the policy.
347    </para>
349    <bridgehead>Java SE 7 is required</bridgehead>
350    <para>
351      BASE now require <ulink url="">Java SE 7</ulink>.
352      Servers with Java SE 6 or older should be updated to Java SE 7 before installing BASE 3.3.
353    </para>
355    <bridgehead>Tomcat 7 is required</bridgehead>
356    <para>
357      BASE now require <ulink url="">Tomcat 7</ulink>.
358      Servers with Tomcat 6 or older should be updated to Tomcat 7 before installing BASE 3.3.
359    </para>
361    <bridgehead>Web services support has been deprecated</bridgehead>
362    <para>
363      The current implementation is most likely not very useful and has limited
364      support for accessing information in BASE. Therefore it has been decided to
365      remove the web services support in BASE 3.4. If anyone require web services
366      support or similar we recommend using the BASE extensions mechanism to implement
367      exactly what is needed for that project and we also beleive that a simplier
368      API such as JSON is preferable.
369    </para>
371  </sect1>
373  <sect1 id="appendix.update_warnings.3.2">
374    <title>BASE 3.2</title>
376    <bridgehead>Custom logging implementations must be updated</bridgehead>
377    <para>
378      The plug-in functionality for custom logging has been converted
379      to an extension point. The default database logging will continue
380      to function, but custom logging implementations must be converted
381      to an extension. See <xref linkend="appendix.incompatible.3.2" /> and
382      <xref linkend="extensions_developer.logging" /> for more information.
383    </para>
385  </sect1>
387  <sect1 id="appendix.update_warnings.3.0">
388    <title>BASE 3.0</title>
390    <note>
391      <title>Upgrading to BASE 3 is possible from BASE 2.17 only</title>
392      <para>
393        If your BASE is an older 2.x version you'll need to upgrade
394        to BASE 2.17 before an upgrade to BASE 3 is possible. Also note
395        that since BASE 3.3 we no longer actively test the upgrade
396        script. If upgrading doesn't work for a particular BASE 3.x version
397        (where x &gt; 2) please try to upgrade to BASE 3.2 first and then
398        from BASE 3.2 to BASE 3.x.
399      </para>
400    </note>
402    <warning>
403      <title>Make sure that you have a recent backup of the BASE 2.17 database</title>
404      <para>
405        Before starting the upgrade from BASE 2.17 to BASE 3 ensure that you
406        have a recent backup. If the upgrade fails you must restore the
407        2.17 database before you can try again. The upgrade only changes the
408        'static' part of the database, so you do not have to restore the
409        'dynamic' part or the uploaded files.
410      </para>
411    </warning>
413    <bridgehead>Old plug-ins and extensions may not work</bridgehead>
414    <para>
415      The BASE API has changed in several places and it is not certain that
416      plug-ins and extensions developed for BASE 2 works with BASE 3. The
417      upgrade will disable all plug-ins and extensions that are currently installed.
418      Before you upgrade we recommend that you go through all (external) plug-ins
419      and check if there is an updated version. The recommended approach
420      is to first upgrade BASE and then install updated versions of plug-ins
421      and extensions following the instructions in <xref 
422      linkend="plugins.installation"/>.
423    </para>
425    <para>
426      If there is no updated version of a specific plug-in you may try
427      a manual re-installation of the old plug-ins. Follow the instructions
428      in <xref linkend="plugins.installation.manual" />.
429    </para>
431    <para>
432      If there is no updated version and the old plug-in doesn't work with
433      BASE 3, you'll need to decide if you really need the plug-in or if
434      the upgrade should wait until a new version of the plug-in
435      has been released.
436    </para>
438    <bridgehead>Batch item importer changes</bridgehead>
439    <para>
440      There are several changes to batch item importers that may affect
441      current workflows and file templates used for importing data.
442    </para>
444    <itemizedlist>
445      <listitem>
446        <para>
447          Sample and extract importers: The 'pooled' column is no longer used.
448          Instead a 'parent type' column should be used with
449          the parent type as a string value (BIOSOURCE, SAMPLE or EXTRACT).
450          Existing importer configurations and file templates may have to be
451          updated. If no parent type is specified the sample importer assumes
452          a biosource and the extract importer assumes a sample.
453        </para>
454      </listitem>
455      <listitem>
456        <para>
457          Labeled extract importer: This has been deprecated and it is recommended
458          that the <emphasis>Extract importer</emphasis> is used instead.
459          We recommend that existing labeled extract importer configurations are re-created as extract
460          importer configurations. The old labeled extract importer can be
461          re-enabled, but note that the existing configurations still need
462          to be changed due to the 'pooled' column is no longer used.
463        </para>
464      </listitem>
465      <listitem>
466        <para>
467          Hybridization importer: This has been deprecated and we recommend
468          that the <emphasis>Physical bioassay importer</emphasis> is used instead.
469          Existing hybridization importer configurations should be re-created as
470          physical bioassay importer configurations.
471        </para>
472      </listitem>
473      <listitem>
474        <para>
475          Scan importer: This has been deprecated and it is recommended
476          that the <emphasis>Derived bioassay importer</emphasis> is used instead.
477          Existing scan importer configurations should be re-created as derived
478          bioassay importer configurations.
479        </para>
480      </listitem>
481    </itemizedlist>
483    <note>
484      The deprecated importers can be re-enabled by an administrator from the
485      <menuchoice>
486        <guimenu>Administrate</guimenu>
487        <guisubmenu>Plug-ins &amp; extensions</guisubmenu>
488        <guimenuitem>Overview</guimenuitem>
489      </menuchoice> page, but they are
490      lacking features that are available in the new importers so this is not
491      something that we recommend.
492    </note>
494    <bridgehead>MySQL and PostgreSQL versions</bridgehead>
495    <para>
496      We have only tested BASE 3 with PostgreSQL 9.1. If anyone
497      experiences any issues with earlier PostgreSQL versions, we
498      recommend an upgrade to PostgreSQL 9.1. This is a change since
499      BASE 2 which was tested with PostgreSQL 8.4. Even though BASE 3
500      may work with older PostgreSQL versions, we don't have the resources
501      needed to test and provide support for it.
502    </para>
504    <para>
505      We have only tested BASE 3 with MySQL 5.1 (no change since BASE 2).
506      If anyone experiences any issues with earlier (or later) MySQL versions,
507      we recommend an upgrade/downgrade to MySQL 5.1.
508    </para>
510  </sect1>
512  <sect1 id="appendix.update_warnings.2.x">
513    <title>All BASE 2.x releases</title>
515    <para>
516      We only support updating to BASE 3 from BASE 2.17. If you have an older BASE
517      version and wish to update to BASE 3, you first have to upgrade to BASE 2.17.
518      BASE 2.17 can be downloaded from the <ulink url="">BASE
519      download page</ulink>. Documentation for BASE 2.17 is available as part of the
520      download and at <ulink url=""
521      ></ulink>.
522    </para>
524  </sect1>
Note: See TracBrowser for help on using the repository browser.