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

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

References #2130: Upgrade 3-rd party libraries

Removed the need for a db.driver setting in base.config since the driver can be automatically loaded from the db.url setting (using DriverManagager.getDriver(url)).

  • Property svn:eol-style set to native
  • Property svn:keywords set to Date Id
File size: 16.5 KB
Line 
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">
5<!--
6  $Id: update_warnings.xml 7521 2018-11-06 08:00:49Z nicklas $
7 
8  Copyright (C) 2007 Peter Johansson, Nicklas Nordborg
9 
10  This file is part of BASE - BioArray Software Environment.
11  Available at http://base.thep.lu.se/
12 
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.
17 
18  BASE is distributed in the hope that it will be useful,
19  but WITHOUT ANY WARRANTY; without even the implied warranty of
20  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
21  GNU General Public License for more details.
22 
23  You should have received a copy of the GNU General Public License
24  along with BASE. If not, see <http://www.gnu.org/licenses/>.
25-->
26
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>
37 
38  <sect1 id="appendix.update_warnings.3.14">
39    <title>BASE 3.14</title>
40 
41    <bridgehead>The db.driver setting is no longer used</bridgehead>
42    <para>
43      The JDBC driver to use is now found automatically based on
44      the <constant>db.url</constant> setting in the <filename>base.config</filename>
45      file. The <constant>db.driver</constant> setting can be removed.
46    </para>
47   
48  </sect1>
49 
50  <sect1 id="appendix.update_warnings.3.11.1">
51    <title>BASE 3.11.1</title>
52 
53    <bridgehead>Free wells on bioplates</bridgehead>
54    <para>
55      A bug that affected the free wells information on bioplates
56      has been fixed. Existing bioplates may have incorrect number of
57      free wells and can be fixed by running a special script.
58     
59      After installing the BASE 3.11.1 update, change directory to
60      <filename class="directory">&lt;base-dir&gt;/bin/</filename> 
61      and issue
62<programlisting>
63./onetimefix.sh free_wells -u &lt;root login&gt; -p &lt;root pwd&gt;
64</programlisting>
65    </para>
66   
67  </sect1>
68 
69  <sect1 id="appendix.update_warnings.3.10">
70    <title>BASE 3.10</title>
71 
72    <bridgehead>Changed permissions for annotating items</bridgehead>
73    <para>
74      Before BASE 3.10 a user was able to create/change/delete annotations on
75      an item if the user has <code>WRITE</code> permission on the item and
76      <code>READ</code> permission on the  annotation type.
77      In BASE 3.10 several changes has been made:
78    </para>
79   
80    <itemizedlist>
81      <listitem>
82        <para>
83          <code>USE</code> permission is required on the annotation type to be able
84          to create/change/delete annotations of that type. This may cause user to no
85          longer be able to annotate certain items, unless their permissions
86          are upgraded to <code>USE</code>. Users with <code>READ</code> permission
87          can only read the annotation values.
88        </para>
89      </listitem>
90     
91      <listitem>
92        <para>
93          A new permission level, <code>ANNOTATE</code>, has been introduced.
94          In the permission hierarchy this sits between the <code>READ</code> 
95          and <code>WRITE</code> permission and can be used to give users
96          permissions to manage annotations but not other properties of an item.
97          All users with <code>WRITE</code> permission automatically get
98          <code>ANNOTATE</code> permission so this change should not affect current
99          users.
100        </para>
101      </listitem>
102    </itemizedlist>
103 
104  </sect1>
105 
106 
107  <sect1 id="appendix.update_warnings.3.9">
108    <title>BASE 3.9</title>
109 
110    <bridgehead>Incompatible API change Application API</bridgehead>
111    <para>
112      The <classname docapi="net.sf.basedb.core">Application.getSessionControl()</classname> 
113      method for getting access to an existing session has been deprecated. A new
114      version has been implemented that require that an <emphasis>external client id</emphasis>
115      is specified. Extensions and other client application may stop working unless
116      they are updated. See alos <xref linkend="appendix.incompatible.session-control"/>.
117    </para>
118 
119  </sect1>
120 
121 
122  <sect1 id="appendix.update_warnings.3.8">
123    <title>BASE 3.8</title>
124 
125    <bridgehead>updateindexes.sh is no longer needed</bridgehead>
126    <para>
127      It is no longer needed to run the <filename>updateindexes.sh</filename>
128      script as part of the upgrade or installation procedure. The funtionality
129      has been integrated into the regular <filename>updatedb.sh/initdb.sh</filename>
130      scripts.
131    </para>
132   
133    <bridgehead>Incompatible API change in ServiceSessionControl</bridgehead>
134    <para>
135      The <classname docapi="net.sf.basedb.core">ServiceSessionControl</classname> API for
136      configuration and building Hibernate <classname>SessionFactory</classname>
137      instances has been changed due the Hibernate 5 upgrade. This change affects
138      extensions that use the API for storing their own data inside the BASE database.
139      Extensions that use this API must be updated or they will not work with BASE 3.8.
140    </para>
141 
142  </sect1>
143 
144  <sect1 id="appendix.update_warnings.3.6">
145    <title>BASE 3.6</title>
146 
147    <bridgehead>Update to Java 8</bridgehead>
148    <para>
149      BASE will no longer run with Java 7. Unless you have already
150      updated to Java 8 you should do so before updating to BASE 3.6.
151      Note that BASE 3.5 works with both Java 7 and 8 so the Java
152      update can be made ahead of time.
153    </para>
154   
155    <bridgehead>Update to Tomcat 8</bridgehead>
156    <para>
157      Tomcat 7 is no longer supported. We recommend updating
158      to Tomcat 8 before updating to BASE 3.6. Note that
159      BASE 3.5 works with both Tomcat 7 and 8 so the Tomcat
160      update can be made ahead of time.
161    </para>
162 
163  </sect1>
164 
165  <sect1 id="appendix.update_warnings.3.5">
166    <title>BASE 3.5</title>
167
168    <bridgehead>Biomaterial lists have been replaced with item lists</bridgehead>
169    <para>
170      This is a major change that has caused a binary incompatibility in the BASE core
171      API. If you depend on custom extensions or plug-ins that use the biomaterial list
172      API this code must be updated before updating to BASE 3.5. Read more
173      about the incompatibilities in <xref linkend="appendix.incompatible.itemlists" />.
174    </para>
175   
176    <bridgehead>Consider updating to Java 8</bridgehead>
177    <para>
178      Oracle is no longer supporting Java 1.7. We are recommending Java 8
179      for running BASE. Java 7 is still supported, but will be removed
180      in the next version (BASE 3.6).
181    </para>
182   
183    <bridgehead>Consider updating to Tomcat 8</bridgehead>
184    <para>
185      We have now tested BASE with Tomcat 8 and it seems to work without
186      any problems. Support for Tomcat 7 will be removed in the next
187      version (BASE 3.6).
188    </para>
189   
190  </sect1>
191 
192  <sect1 id="appendix.update_warnings.3.4">
193    <title>BASE 3.4</title>
194   
195    <bridgehead>Updating from BASE 2.17 is no longer possible</bridgehead>
196    <para>
197      If you are still running an BASE 2.17 (or earlier) BASE version
198      and want to update to BASE 3.4 you must first update to BASE 3.3
199      or earlier.
200    </para>
201   
202    <bridgehead>Web services support has been removed</bridgehead>
203    <para>
204      As announced earlier web services support has been removed in BASE 3.4.
205      If anyone require web services support or similar we recommend using the BASE
206      extensions mechanism to implement exactly what is needed for that project and
207      we also beleive that a simplier API such as JSON is preferable.
208    </para>
209   
210    <bridgehead>PostgreSQL users should change db.dialect</bridgehead>
211    <para>
212      In <filename>base.config</filename> there is a <constant>db.config</constant>
213      setting. Servers running with PostgreSQL as the database should change the
214      dialect to <classname>org.hibernate.dialect.PostgreSQL9Dialect</classname>
215      since the <classname>org.hibernate.dialect.PostgreSQLDialect</classname> has
216      been deprecated.
217    </para>
218   
219  </sect1>
220
221  <sect1 id="appendix.update_warnings.3.3.3">
222    <title>BASE 3.3.3</title>
223 
224    <bridgehead>Remaining quantity</bridgehead>
225    <para>
226      A bug that affected remaining quantity calculations for
227      biomaterial item has been fixed. Existing items may have been
228      saved with incorrect remaining quantity and must be fixed.
229      After installing the BASE 3.3.3 update, the existing
230      remaining quantity values are fix by running a special script.
231      Change directory to <filename class="directory">&lt;base-dir&gt;/bin/</filename> 
232      and issue
233<programlisting>
234./onetimefix.sh remaining_quantity -u &lt;root login&gt; -p &lt;root pwd&gt;
235</programlisting>
236    </para>
237   
238  </sect1>
239 
240  <sect1 id="appendix.update_warnings.3.3">
241    <title>BASE 3.3</title>
242
243    <bridgehead>Content security policy</bridgehead>
244    <para>
245      The BASE web client now set a rather strict <emphasis>Content
246      Security Policy</emphasis> that prevent browsers from executing
247      code (including JavaScript) that is considered unsafe. Some extensions
248      may cease to work due to this. Go to
249      <menuchoice>
250        <guimenu>Administrate</guimenu>
251        <guimenuitem>Plug-ins &amp; extensions</guimenuitem>
252        <guimenuitem>Overview</guimenuitem>
253      </menuchoice> 
254      (after upgrading) to see if there are any warnings about this.
255      Read more in <xref linkend="appendix.web.xml.csp-filter" />
256      for information about how to relax the policy.
257    </para>
258
259    <bridgehead>Java SE 7 is required</bridgehead>
260    <para>
261      BASE now require <ulink url="http://www.oracle.com/technetwork/java/javase/downloads/index.html">Java SE 7</ulink>.
262      Servers with Java SE 6 or older should be updated to Java SE 7 before installing BASE 3.3.
263    </para>
264
265    <bridgehead>Tomcat 7 is required</bridgehead>
266    <para>
267      BASE now require <ulink url="http://tomcat.apache.org/download-70.cgi">Tomcat 7</ulink>.
268      Servers with Tomcat 6 or older should be updated to Tomcat 7 before installing BASE 3.3.
269    </para>
270   
271    <bridgehead>Web services support has been deprecated</bridgehead>
272    <para>
273      The current implementation is most likely not very useful and has limited
274      support for accessing information in BASE. Therefore it has been decided to
275      remove the web services support in BASE 3.4. If anyone require web services
276      support or similar we recommend using the BASE extensions mechanism to implement
277      exactly what is needed for that project and we also beleive that a simplier
278      API such as JSON is preferable.
279    </para>
280
281  </sect1>
282 
283  <sect1 id="appendix.update_warnings.3.2">
284    <title>BASE 3.2</title>
285 
286    <bridgehead>Custom logging implementations must be updated</bridgehead>
287    <para>
288      The plug-in functionality for custom logging has been converted
289      to an extension point. The default database logging will continue
290      to function, but custom logging implementations must be converted
291      to an extension. See <xref linkend="appendix.incompatible.3.2" /> and
292      <xref linkend="extensions_developer.logging" /> for more information.
293    </para>
294 
295  </sect1>
296 
297  <sect1 id="appendix.update_warnings.3.0">
298    <title>BASE 3.0</title>
299   
300    <note>
301      <title>Upgrading to BASE 3 is possible from BASE 2.17 only</title>
302      <para>
303        If your BASE is an older 2.x version you'll need to upgrade
304        to BASE 2.17 before an upgrade to BASE 3 is possible. Also note
305        that since BASE 3.3 we no longer actively test the upgrade
306        script. If upgrading doesn't work for a particular BASE 3.x version
307        (where x &gt; 2) please try to upgrade to BASE 3.2 first and then
308        from BASE 3.2 to BASE 3.x.
309      </para>
310    </note>
311
312    <warning>
313      <title>Make sure that you have a recent backup of the BASE 2.17 database</title>
314      <para>
315        Before starting the upgrade from BASE 2.17 to BASE 3 ensure that you
316        have a recent backup. If the upgrade fails you must restore the
317        2.17 database before you can try again. The upgrade only changes the
318        'static' part of the database, so you do not have to restore the
319        'dynamic' part or the uploaded files.
320      </para>
321    </warning>
322
323    <bridgehead>Old plug-ins and extensions may not work</bridgehead>
324    <para>
325      The BASE API has changed in several places and it is not certain that
326      plug-ins and extensions developed for BASE 2 works with BASE 3. The
327      upgrade will disable all plug-ins and extensions that are currently installed.
328      Before you upgrade we recommend that you go through all (external) plug-ins
329      and check if there is an updated version. The recommended approach
330      is to first upgrade BASE and then install updated versions of plug-ins
331      and extensions following the instructions in <xref 
332      linkend="plugins.installation"/>.
333    </para>
334   
335    <para>
336      If there is no updated version of a specific plug-in you may try
337      a manual re-installation of the old plug-ins. Follow the instructions
338      in <xref linkend="plugins.installation.manual" />.
339    </para>
340   
341    <para>
342      If there is no updated version and the old plug-in doesn't work with
343      BASE 3, you'll need to decide if you really need the plug-in or if
344      the upgrade should wait until a new version of the plug-in
345      has been released.
346    </para>
347   
348    <bridgehead>Batch item importer changes</bridgehead>
349    <para>
350      There are several changes to batch item importers that may affect
351      current workflows and file templates used for importing data.
352    </para>
353   
354    <itemizedlist>
355      <listitem>
356        <para>
357          Sample and extract importers: The 'pooled' column is no longer used.
358          Instead a 'parent type' column should be used with
359          the parent type as a string value (BIOSOURCE, SAMPLE or EXTRACT).
360          Existing importer configurations and file templates may have to be
361          updated. If no parent type is specified the sample importer assumes
362          a biosource and the extract importer assumes a sample.
363        </para>
364      </listitem>
365      <listitem>
366        <para>
367          Labeled extract importer: This has been deprecated and it is recommended
368          that the <emphasis>Extract importer</emphasis> is used instead.
369          We recommend that existing labeled extract importer configurations are re-created as extract
370          importer configurations. The old labeled extract importer can be
371          re-enabled, but note that the existing configurations still need
372          to be changed due to the 'pooled' column is no longer used.
373        </para>
374      </listitem>
375      <listitem>
376        <para>
377          Hybridization importer: This has been deprecated and we recommend
378          that the <emphasis>Physical bioassay importer</emphasis> is used instead.
379          Existing hybridization importer configurations should be re-created as
380          physical bioassay importer configurations.
381        </para>
382      </listitem>
383      <listitem>
384        <para>
385          Scan importer: This has been deprecated and it is recommended
386          that the <emphasis>Derived bioassay importer</emphasis> is used instead.
387          Existing scan importer configurations should be re-created as derived
388          bioassay importer configurations.
389        </para>
390      </listitem>
391    </itemizedlist>
392   
393    <note>
394      The deprecated importers can be re-enabled by an administrator from the
395      <menuchoice>
396        <guimenu>Administrate</guimenu>
397        <guisubmenu>Plug-ins &amp; extensions</guisubmenu>
398        <guimenuitem>Overview</guimenuitem>
399      </menuchoice> page, but they are
400      lacking features that are available in the new importers so this is not
401      something that we recommend.
402    </note>
403   
404    <bridgehead>MySQL and PostgreSQL versions</bridgehead>
405    <para>
406      We have only tested BASE 3 with PostgreSQL 9.1. If anyone
407      experiences any issues with earlier PostgreSQL versions, we
408      recommend an upgrade to PostgreSQL 9.1. This is a change since
409      BASE 2 which was tested with PostgreSQL 8.4. Even though BASE 3
410      may work with older PostgreSQL versions, we don't have the resources
411      needed to test and provide support for it.
412    </para>
413   
414    <para>
415      We have only tested BASE 3 with MySQL 5.1 (no change since BASE 2).
416      If anyone experiences any issues with earlier (or later) MySQL versions,
417      we recommend an upgrade/downgrade to MySQL 5.1.
418    </para>
419 
420  </sect1>
421 
422  <sect1 id="appendix.update_warnings.2.x">
423    <title>All BASE 2.x releases</title>
424   
425    <para>
426      We only support updating to BASE 3 from BASE 2.17. If you have an older BASE
427      version and wish to update to BASE 3, you first have to upgrade to BASE 2.17.
428      BASE 2.17 can be downloaded from the <ulink url="http://base.thep.lu.se/wiki/DownloadPage">BASE
429      download page</ulink>. Documentation for BASE 2.17 is available as part of the
430      download and at <ulink url="http://base.thep.lu.se/chrome/site/2.17/html/index.html"
431      >http://base.thep.lu.se/chrome/site/2.17/html/index.html</ulink>.
432    </para>
433
434  </sect1>
435 
436</appendix>
437
Note: See TracBrowser for help on using the repository browser.