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

Last change on this file since 7598 was 7598, checked in by Nicklas Nordborg, 5 years ago

References #2135: Remove support for secondary storage

Updated documentation.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Date Id
File size: 18.5 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 7598 2019-02-22 08:51:39Z 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>Secondary storage support has been removed</bridgehead>
42    <para>
43      The <guilabel>Secondary storage</guilabel> feature has been removed.
44      Files that are located in the secondary storage will be marked as offline
45      by the upgrade script. The recommendation is to replace this feature with
46      an external files solution instead.
47    </para>
50  </sect1>
52  <sect1 id="appendix.update_warnings.3.14">
53    <title>BASE 3.14</title>
55    <bridgehead>The db.driver setting is no longer used</bridgehead>
56    <para>
57      The JDBC driver to use is now found automatically based on
58      the <constant>db.url</constant> setting in the <filename>base.config</filename>
59      file. The <constant>db.driver</constant> setting can be removed.
60    </para>
62    <bridgehead>The (very) old Authenticator API has been removed</bridgehead>
63    <para>
64      The <code>net.sf.basedb.core.authentication.Authenticator</code>
65      interface and other related code that was deprecated in BASE 3.3
66      has been removed. Systems that still use old authentication code
67      need to replace this with a newer version before updating.
68    </para>
70    <bridgehead>Changes to the authentication system</bridgehead>
71    <para>
72      The authentication system has been updated to make it easier to
73      install more than one external authentication manager. The changes
74      are backwards compatible and existing authentication managers should
75      still work as before as long as they are the only ones installed.
76      However, the existing authentication managers will probably not work
77      well if more than one is installed since they lack some features that
78      are neccessary in order to cooperate with other managers. Before installing
79      more than one authentication manager it is recommended that they are
80      updated to newer versions.
81    </para>
83    <para>
84      Newer authentication managers typically no longer provide support for
85      password authentication. If the intention is that some users still should be
86      able to login with username+password, it is recommended that the
87      <guilabel>Password login form</guilabel> is enabled. Go to
88      <menuchoice>
89        <guimenu>Administrate</guimenu>
90        <guisubmenu>Plug-ins &amp; extensions</guisubmenu>
91        <guimenuitem>Overview</guimenuitem>
92      </menuchoice> and locate the <guilabel>Login form customization</guilabel>
93      extension point to find it.
94    </para>
96  </sect1>
98  <sect1 id="appendix.update_warnings.3.11.1">
99    <title>BASE 3.11.1</title>
101    <bridgehead>Free wells on bioplates</bridgehead>
102    <para>
103      A bug that affected the free wells information on bioplates
104      has been fixed. Existing bioplates may have incorrect number of
105      free wells and can be fixed by running a special script.
107      After installing the BASE 3.11.1 update, change directory to
108      <filename class="directory">&lt;base-dir&gt;/bin/</filename> 
109      and issue
111./ free_wells -u &lt;root login&gt; -p &lt;root pwd&gt;
113    </para>
115  </sect1>
117  <sect1 id="appendix.update_warnings.3.10">
118    <title>BASE 3.10</title>
120    <bridgehead>Changed permissions for annotating items</bridgehead>
121    <para>
122      Before BASE 3.10 a user was able to create/change/delete annotations on
123      an item if the user has <code>WRITE</code> permission on the item and
124      <code>READ</code> permission on the  annotation type.
125      In BASE 3.10 several changes has been made:
126    </para>
128    <itemizedlist>
129      <listitem>
130        <para>
131          <code>USE</code> permission is required on the annotation type to be able
132          to create/change/delete annotations of that type. This may cause user to no
133          longer be able to annotate certain items, unless their permissions
134          are upgraded to <code>USE</code>. Users with <code>READ</code> permission
135          can only read the annotation values.
136        </para>
137      </listitem>
139      <listitem>
140        <para>
141          A new permission level, <code>ANNOTATE</code>, has been introduced.
142          In the permission hierarchy this sits between the <code>READ</code> 
143          and <code>WRITE</code> permission and can be used to give users
144          permissions to manage annotations but not other properties of an item.
145          All users with <code>WRITE</code> permission automatically get
146          <code>ANNOTATE</code> permission so this change should not affect current
147          users.
148        </para>
149      </listitem>
150    </itemizedlist>
152  </sect1>
155  <sect1 id="appendix.update_warnings.3.9">
156    <title>BASE 3.9</title>
158    <bridgehead>Incompatible API change Application API</bridgehead>
159    <para>
160      The <classname docapi="net.sf.basedb.core">Application.getSessionControl()</classname> 
161      method for getting access to an existing session has been deprecated. A new
162      version has been implemented that require that an <emphasis>external client id</emphasis>
163      is specified. Extensions and other client application may stop working unless
164      they are updated. See alos <xref linkend="appendix.incompatible.session-control"/>.
165    </para>
167  </sect1>
170  <sect1 id="appendix.update_warnings.3.8">
171    <title>BASE 3.8</title>
173    <bridgehead> is no longer needed</bridgehead>
174    <para>
175      It is no longer needed to run the <filename></filename>
176      script as part of the upgrade or installation procedure. The funtionality
177      has been integrated into the regular <filename></filename>
178      scripts.
179    </para>
181    <bridgehead>Incompatible API change in ServiceSessionControl</bridgehead>
182    <para>
183      The <classname docapi="net.sf.basedb.core">ServiceSessionControl</classname> API for
184      configuration and building Hibernate <classname>SessionFactory</classname>
185      instances has been changed due the Hibernate 5 upgrade. This change affects
186      extensions that use the API for storing their own data inside the BASE database.
187      Extensions that use this API must be updated or they will not work with BASE 3.8.
188    </para>
190  </sect1>
192  <sect1 id="appendix.update_warnings.3.6">
193    <title>BASE 3.6</title>
195    <bridgehead>Update to Java 8</bridgehead>
196    <para>
197      BASE will no longer run with Java 7. Unless you have already
198      updated to Java 8 you should do so before updating to BASE 3.6.
199      Note that BASE 3.5 works with both Java 7 and 8 so the Java
200      update can be made ahead of time.
201    </para>
203    <bridgehead>Update to Tomcat 8</bridgehead>
204    <para>
205      Tomcat 7 is no longer supported. We recommend updating
206      to Tomcat 8 before updating to BASE 3.6. Note that
207      BASE 3.5 works with both Tomcat 7 and 8 so the Tomcat
208      update can be made ahead of time.
209    </para>
211  </sect1>
213  <sect1 id="appendix.update_warnings.3.5">
214    <title>BASE 3.5</title>
216    <bridgehead>Biomaterial lists have been replaced with item lists</bridgehead>
217    <para>
218      This is a major change that has caused a binary incompatibility in the BASE core
219      API. If you depend on custom extensions or plug-ins that use the biomaterial list
220      API this code must be updated before updating to BASE 3.5. Read more
221      about the incompatibilities in <xref linkend="appendix.incompatible.itemlists" />.
222    </para>
224    <bridgehead>Consider updating to Java 8</bridgehead>
225    <para>
226      Oracle is no longer supporting Java 1.7. We are recommending Java 8
227      for running BASE. Java 7 is still supported, but will be removed
228      in the next version (BASE 3.6).
229    </para>
231    <bridgehead>Consider updating to Tomcat 8</bridgehead>
232    <para>
233      We have now tested BASE with Tomcat 8 and it seems to work without
234      any problems. Support for Tomcat 7 will be removed in the next
235      version (BASE 3.6).
236    </para>
238  </sect1>
240  <sect1 id="appendix.update_warnings.3.4">
241    <title>BASE 3.4</title>
243    <bridgehead>Updating from BASE 2.17 is no longer possible</bridgehead>
244    <para>
245      If you are still running an BASE 2.17 (or earlier) BASE version
246      and want to update to BASE 3.4 you must first update to BASE 3.3
247      or earlier.
248    </para>
250    <bridgehead>Web services support has been removed</bridgehead>
251    <para>
252      As announced earlier web services support has been removed in BASE 3.4.
253      If anyone require web services support or similar we recommend using the BASE
254      extensions mechanism to implement exactly what is needed for that project and
255      we also beleive that a simplier API such as JSON is preferable.
256    </para>
258    <bridgehead>PostgreSQL users should change db.dialect</bridgehead>
259    <para>
260      In <filename>base.config</filename> there is a <constant>db.config</constant>
261      setting. Servers running with PostgreSQL as the database should change the
262      dialect to <classname>org.hibernate.dialect.PostgreSQL9Dialect</classname>
263      since the <classname>org.hibernate.dialect.PostgreSQLDialect</classname> has
264      been deprecated.
265    </para>
267  </sect1>
269  <sect1 id="appendix.update_warnings.3.3.3">
270    <title>BASE 3.3.3</title>
272    <bridgehead>Remaining quantity</bridgehead>
273    <para>
274      A bug that affected remaining quantity calculations for
275      biomaterial item has been fixed. Existing items may have been
276      saved with incorrect remaining quantity and must be fixed.
277      After installing the BASE 3.3.3 update, the existing
278      remaining quantity values are fix by running a special script.
279      Change directory to <filename class="directory">&lt;base-dir&gt;/bin/</filename> 
280      and issue
282./ remaining_quantity -u &lt;root login&gt; -p &lt;root pwd&gt;
284    </para>
286  </sect1>
288  <sect1 id="appendix.update_warnings.3.3">
289    <title>BASE 3.3</title>
291    <bridgehead>Content security policy</bridgehead>
292    <para>
293      The BASE web client now set a rather strict <emphasis>Content
294      Security Policy</emphasis> that prevent browsers from executing
295      code (including JavaScript) that is considered unsafe. Some extensions
296      may cease to work due to this. Go to
297      <menuchoice>
298        <guimenu>Administrate</guimenu>
299        <guimenuitem>Plug-ins &amp; extensions</guimenuitem>
300        <guimenuitem>Overview</guimenuitem>
301      </menuchoice> 
302      (after upgrading) to see if there are any warnings about this.
303      Read more in <xref linkend="appendix.web.xml.csp-filter" />
304      for information about how to relax the policy.
305    </para>
307    <bridgehead>Java SE 7 is required</bridgehead>
308    <para>
309      BASE now require <ulink url="">Java SE 7</ulink>.
310      Servers with Java SE 6 or older should be updated to Java SE 7 before installing BASE 3.3.
311    </para>
313    <bridgehead>Tomcat 7 is required</bridgehead>
314    <para>
315      BASE now require <ulink url="">Tomcat 7</ulink>.
316      Servers with Tomcat 6 or older should be updated to Tomcat 7 before installing BASE 3.3.
317    </para>
319    <bridgehead>Web services support has been deprecated</bridgehead>
320    <para>
321      The current implementation is most likely not very useful and has limited
322      support for accessing information in BASE. Therefore it has been decided to
323      remove the web services support in BASE 3.4. If anyone require web services
324      support or similar we recommend using the BASE extensions mechanism to implement
325      exactly what is needed for that project and we also beleive that a simplier
326      API such as JSON is preferable.
327    </para>
329  </sect1>
331  <sect1 id="appendix.update_warnings.3.2">
332    <title>BASE 3.2</title>
334    <bridgehead>Custom logging implementations must be updated</bridgehead>
335    <para>
336      The plug-in functionality for custom logging has been converted
337      to an extension point. The default database logging will continue
338      to function, but custom logging implementations must be converted
339      to an extension. See <xref linkend="appendix.incompatible.3.2" /> and
340      <xref linkend="extensions_developer.logging" /> for more information.
341    </para>
343  </sect1>
345  <sect1 id="appendix.update_warnings.3.0">
346    <title>BASE 3.0</title>
348    <note>
349      <title>Upgrading to BASE 3 is possible from BASE 2.17 only</title>
350      <para>
351        If your BASE is an older 2.x version you'll need to upgrade
352        to BASE 2.17 before an upgrade to BASE 3 is possible. Also note
353        that since BASE 3.3 we no longer actively test the upgrade
354        script. If upgrading doesn't work for a particular BASE 3.x version
355        (where x &gt; 2) please try to upgrade to BASE 3.2 first and then
356        from BASE 3.2 to BASE 3.x.
357      </para>
358    </note>
360    <warning>
361      <title>Make sure that you have a recent backup of the BASE 2.17 database</title>
362      <para>
363        Before starting the upgrade from BASE 2.17 to BASE 3 ensure that you
364        have a recent backup. If the upgrade fails you must restore the
365        2.17 database before you can try again. The upgrade only changes the
366        'static' part of the database, so you do not have to restore the
367        'dynamic' part or the uploaded files.
368      </para>
369    </warning>
371    <bridgehead>Old plug-ins and extensions may not work</bridgehead>
372    <para>
373      The BASE API has changed in several places and it is not certain that
374      plug-ins and extensions developed for BASE 2 works with BASE 3. The
375      upgrade will disable all plug-ins and extensions that are currently installed.
376      Before you upgrade we recommend that you go through all (external) plug-ins
377      and check if there is an updated version. The recommended approach
378      is to first upgrade BASE and then install updated versions of plug-ins
379      and extensions following the instructions in <xref 
380      linkend="plugins.installation"/>.
381    </para>
383    <para>
384      If there is no updated version of a specific plug-in you may try
385      a manual re-installation of the old plug-ins. Follow the instructions
386      in <xref linkend="plugins.installation.manual" />.
387    </para>
389    <para>
390      If there is no updated version and the old plug-in doesn't work with
391      BASE 3, you'll need to decide if you really need the plug-in or if
392      the upgrade should wait until a new version of the plug-in
393      has been released.
394    </para>
396    <bridgehead>Batch item importer changes</bridgehead>
397    <para>
398      There are several changes to batch item importers that may affect
399      current workflows and file templates used for importing data.
400    </para>
402    <itemizedlist>
403      <listitem>
404        <para>
405          Sample and extract importers: The 'pooled' column is no longer used.
406          Instead a 'parent type' column should be used with
407          the parent type as a string value (BIOSOURCE, SAMPLE or EXTRACT).
408          Existing importer configurations and file templates may have to be
409          updated. If no parent type is specified the sample importer assumes
410          a biosource and the extract importer assumes a sample.
411        </para>
412      </listitem>
413      <listitem>
414        <para>
415          Labeled extract importer: This has been deprecated and it is recommended
416          that the <emphasis>Extract importer</emphasis> is used instead.
417          We recommend that existing labeled extract importer configurations are re-created as extract
418          importer configurations. The old labeled extract importer can be
419          re-enabled, but note that the existing configurations still need
420          to be changed due to the 'pooled' column is no longer used.
421        </para>
422      </listitem>
423      <listitem>
424        <para>
425          Hybridization importer: This has been deprecated and we recommend
426          that the <emphasis>Physical bioassay importer</emphasis> is used instead.
427          Existing hybridization importer configurations should be re-created as
428          physical bioassay importer configurations.
429        </para>
430      </listitem>
431      <listitem>
432        <para>
433          Scan importer: This has been deprecated and it is recommended
434          that the <emphasis>Derived bioassay importer</emphasis> is used instead.
435          Existing scan importer configurations should be re-created as derived
436          bioassay importer configurations.
437        </para>
438      </listitem>
439    </itemizedlist>
441    <note>
442      The deprecated importers can be re-enabled by an administrator from the
443      <menuchoice>
444        <guimenu>Administrate</guimenu>
445        <guisubmenu>Plug-ins &amp; extensions</guisubmenu>
446        <guimenuitem>Overview</guimenuitem>
447      </menuchoice> page, but they are
448      lacking features that are available in the new importers so this is not
449      something that we recommend.
450    </note>
452    <bridgehead>MySQL and PostgreSQL versions</bridgehead>
453    <para>
454      We have only tested BASE 3 with PostgreSQL 9.1. If anyone
455      experiences any issues with earlier PostgreSQL versions, we
456      recommend an upgrade to PostgreSQL 9.1. This is a change since
457      BASE 2 which was tested with PostgreSQL 8.4. Even though BASE 3
458      may work with older PostgreSQL versions, we don't have the resources
459      needed to test and provide support for it.
460    </para>
462    <para>
463      We have only tested BASE 3 with MySQL 5.1 (no change since BASE 2).
464      If anyone experiences any issues with earlier (or later) MySQL versions,
465      we recommend an upgrade/downgrade to MySQL 5.1.
466    </para>
468  </sect1>
470  <sect1 id="appendix.update_warnings.2.x">
471    <title>All BASE 2.x releases</title>
473    <para>
474      We only support updating to BASE 3 from BASE 2.17. If you have an older BASE
475      version and wish to update to BASE 3, you first have to upgrade to BASE 2.17.
476      BASE 2.17 can be downloaded from the <ulink url="">BASE
477      download page</ulink>. Documentation for BASE 2.17 is available as part of the
478      download and at <ulink url=""
479      ></ulink>.
480    </para>
482  </sect1>
Note: See TracBrowser for help on using the repository browser.