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

Last change on this file since 7221 was 7221, checked in by Nicklas Nordborg, 6 years ago

References #2033 and #2034. Added a note about the changes to the list of update warnings and incompatible changes.

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