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

Last change on this file since 6807 was 6807, checked in by Nicklas Nordborg, 8 years ago

References #1924, #1927 and #1325. Added information about incompatible changes and things to consider when updgrading to BASE 3.5.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Date Id
File size: 12.0 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 6807 2015-03-26 12:10:52Z 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.5">
39    <title>BASE 3.5</title>
41    <bridgehead>Biomaterial lists have been replaced with item lists</bridgehead>
42    <para>
43      This is a major change that has caused a binary compatibility in the BASE core
44      API. If you depend on custom extensions or plug-ins that use the biomaterial list
45      API this code must be updated before updating to BASE 3.5. Read more
46      about the incompatibilities in <xref linkend="appendix.incompatible.itemlists" />.
47    </para>
49    <bridgehead>Consider updating to Java 8</bridgehead>
50    <para>
51      Oracle is no longer supporting Java 1.7. We are recommending Java 8
52      for running BASE. Java 7 is still supported, but will be removed
53      in the next version (BASE 3.6).
54    </para>
56    <bridgehead>Consider updating to Tomcat 8</bridgehead>
57    <para>
58      We have now tested BASE with Tomcat 8 and it seems to work without
59      any problems. Support for Tomcat 7 will be removed in the next
60      version (BASE 3.6).
61    </para>
63  </sect1>
65  <sect1 id="appendix.update_warnings.3.4">
66    <title>BASE 3.4</title>
68    <bridgehead>Updating from BASE 2.17 is no longer possible</bridgehead>
69    <para>
70      If you are still running an BASE 2.17 (or earlier) BASE version
71      and want to update to BASE 3.4 you must first update to BASE 3.3
72      or earlier.
73    </para>
75    <bridgehead>Web services support has been removed</bridgehead>
76    <para>
77      As announced earlier web services support has been removed in BASE 3.4.
78      If anyone require web services support or similar we recommend using the BASE
79      extensions mechanism to implement exactly what is needed for that project and
80      we also beleive that a simplier API such as JSON is preferable.
81    </para>
83    <bridgehead>PostgreSQL users should change db.dialect</bridgehead>
84    <para>
85      In <filename>base.config</filename> there is a <constant>db.config</constant>
86      setting. Servers running with PostgreSQL as the database should change the
87      dialect to <classname>org.hibernate.dialect.PostgreSQL9Dialect</classname>
88      since the <classname>org.hibernate.dialect.PostgreSQLDialect</classname> has
89      been deprecated.
90    </para>
92  </sect1>
94  <sect1 id="appendix.update_warnings.3.3.3">
95    <title>BASE 3.3.3</title>
97    <bridgehead>Remaining quantity</bridgehead>
98    <para>
99      A bug that affected remaining quantity calculations for
100      biomaterial item has been fixed. Existing items may have been
101      saved with incorrect remaining quantity and must be fixed.
102      After installing the BASE 3.3.3 update, the existing
103      remaining quantity values are fix by running a special script.
104      Change directory to <filename class="directory">&lt;base-dir&gt;/bin/</filename> 
105      and issue
107./ remaining_quantity -u &lt;root login&gt; -p &lt;root pwd&gt;
109    </para>
111  </sect1>
113  <sect1 id="appendix.update_warnings.3.3">
114    <title>BASE 3.3</title>
116    <bridgehead>Content security policy</bridgehead>
117    <para>
118      The BASE web client now set a rather strict <emphasis>Content
119      Security Policy</emphasis> that prevent browsers from executing
120      code (including JavaScript) that is considered unsafe. Some extensions
121      may cease to work due to this. Go to
122      <menuchoice>
123        <guimenu>Administrate</guimenu>
124        <guimenuitem>Plug-ins &amp; extensions</guimenuitem>
125        <guimenuitem>Overview</guimenuitem>
126      </menuchoice> 
127      (after upgrading) to see if there are any warnings about this.
128      Read more in <xref linkend="appendix.web.xml.csp-filter" />
129      for information about how to relax the policy.
130    </para>
132    <bridgehead>Java SE 7 is required</bridgehead>
133    <para>
134      BASE now require <ulink url="">Java SE 7</ulink>.
135      Servers with Java SE 6 or older should be updated to Java SE 7 before installing BASE 3.3.
136    </para>
138    <bridgehead>Tomcat 7 is required</bridgehead>
139    <para>
140      BASE now require <ulink url="">Tomcat 7</ulink>.
141      Servers with Tomcat 6 or older should be updated to Tomcat 7 before installing BASE 3.3.
142    </para>
144    <bridgehead>Web services support has been deprecated</bridgehead>
145    <para>
146      The current implementation is most likely not very useful and has limited
147      support for accessing information in BASE. Therefore it has been decided to
148      remove the web services support in BASE 3.4. If anyone require web services
149      support or similar we recommend using the BASE extensions mechanism to implement
150      exactly what is needed for that project and we also beleive that a simplier
151      API such as JSON is preferable.
152    </para>
154  </sect1>
156  <sect1 id="appendix.update_warnings.3.2">
157    <title>BASE 3.2</title>
159    <bridgehead>Custom logging implementations must be updated</bridgehead>
160    <para>
161      The plug-in functionality for custom logging has been converted
162      to an extension point. The default database logging will continue
163      to function, but custom logging implementations must be converted
164      to an extension. See <xref linkend="appendix.incompatible.3.2" /> and
165      <xref linkend="extensions_developer.logging" /> for more information.
166    </para>
168  </sect1>
170  <sect1 id="appendix.update_warnings.3.0">
171    <title>BASE 3.0</title>
173    <note>
174      <title>Upgrading to BASE 3 is possible from BASE 2.17 only</title>
175      <para>
176        If your BASE is an older 2.x version you'll need to upgrade
177        to BASE 2.17 before an upgrade to BASE 3 is possible. Also note
178        that since BASE 3.3 we no longer actively test the upgrade
179        script. If upgrading doesn't work for a particular BASE 3.x version
180        (where x &gt; 2) please try to upgrade to BASE 3.2 first and then
181        from BASE 3.2 to BASE 3.x.
182      </para>
183    </note>
185    <warning>
186      <title>Make sure that you have a recent backup of the BASE 2.17 database</title>
187      <para>
188        Before starting the upgrade from BASE 2.17 to BASE 3 ensure that you
189        have a recent backup. If the upgrade fails you must restore the
190        2.17 database before you can try again. The upgrade only changes the
191        'static' part of the database, so you do not have to restore the
192        'dynamic' part or the uploaded files.
193      </para>
194    </warning>
196    <bridgehead>Old plug-ins and extensions may not work</bridgehead>
197    <para>
198      The BASE API has changed in several places and it is not certain that
199      plug-ins and extensions developed for BASE 2 works with BASE 3. The
200      upgrade will disable all plug-ins and extensions that are currently installed.
201      Before you upgrade we recommend that you go through all (external) plug-ins
202      and check if there is an updated version. The recommended approach
203      is to first upgrade BASE and then install updated versions of plug-ins
204      and extensions following the instructions in <xref 
205      linkend="plugins.installation"/>.
206    </para>
208    <para>
209      If there is no updated version of a specific plug-in you may try
210      a manual re-installation of the old plug-ins. Follow the instructions
211      in <xref linkend="plugins.installation.manual" />.
212    </para>
214    <para>
215      If there is no updated version and the old plug-in doesn't work with
216      BASE 3, you'll need to decide if you really need the plug-in or if
217      the upgrade should wait until a new version of the plug-in
218      has been released.
219    </para>
221    <bridgehead>Batch item importer changes</bridgehead>
222    <para>
223      There are several changes to batch item importers that may affect
224      current workflows and file templates used for importing data.
225    </para>
227    <itemizedlist>
228      <listitem>
229        <para>
230          Sample and extract importers: The 'pooled' column is no longer used.
231          Instead a 'parent type' column should be used with
232          the parent type as a string value (BIOSOURCE, SAMPLE or EXTRACT).
233          Existing importer configurations and file templates may have to be
234          updated. If no parent type is specified the sample importer assumes
235          a biosource and the extract importer assumes a sample.
236        </para>
237      </listitem>
238      <listitem>
239        <para>
240          Labeled extract importer: This has been deprecated and it is recommended
241          that the <emphasis>Extract importer</emphasis> is used instead.
242          We recommend that existing labeled extract importer configurations are re-created as extract
243          importer configurations. The old labeled extract importer can be
244          re-enabled, but note that the existing configurations still need
245          to be changed due to the 'pooled' column is no longer used.
246        </para>
247      </listitem>
248      <listitem>
249        <para>
250          Hybridization importer: This has been deprecated and we recommend
251          that the <emphasis>Physical bioassay importer</emphasis> is used instead.
252          Existing hybridization importer configurations should be re-created as
253          physical bioassay importer configurations.
254        </para>
255      </listitem>
256      <listitem>
257        <para>
258          Scan importer: This has been deprecated and it is recommended
259          that the <emphasis>Derived bioassay importer</emphasis> is used instead.
260          Existing scan importer configurations should be re-created as derived
261          bioassay importer configurations.
262        </para>
263      </listitem>
264    </itemizedlist>
266    <note>
267      The deprecated importers can be re-enabled by an administrator from the
268      <menuchoice>
269        <guimenu>Administrate</guimenu>
270        <guisubmenu>Plug-ins &amp; extensions</guisubmenu>
271        <guimenuitem>Overview</guimenuitem>
272      </menuchoice> page, but they are
273      lacking features that are available in the new importers so this is not
274      something that we recommend.
275    </note>
277    <bridgehead>MySQL and PostgreSQL versions</bridgehead>
278    <para>
279      We have only tested BASE 3 with PostgreSQL 9.1. If anyone
280      experiences any issues with earlier PostgreSQL versions, we
281      recommend an upgrade to PostgreSQL 9.1. This is a change since
282      BASE 2 which was tested with PostgreSQL 8.4. Even though BASE 3
283      may work with older PostgreSQL versions, we don't have the resources
284      needed to test and provide support for it.
285    </para>
287    <para>
288      We have only tested BASE 3 with MySQL 5.1 (no change since BASE 2).
289      If anyone experiences any issues with earlier (or later) MySQL versions,
290      we recommend an upgrade/downgrade to MySQL 5.1.
291    </para>
293  </sect1>
295  <sect1 id="appendix.update_warnings.2.x">
296    <title>All BASE 2.x releases</title>
298    <para>
299      We only support updating to BASE 3 from BASE 2.17. If you have an older BASE
300      version and wish to update to BASE 3, you first have to upgrade to BASE 2.17.
301      BASE 2.17 can be downloaded from the <ulink url="">BASE
302      download page</ulink>. Documentation for BASE 2.17 is available as part of the
303      download and at <ulink url=""
304      ></ulink>.
305    </para>
307  </sect1>
Note: See TracBrowser for help on using the repository browser.