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

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

References #2011: Check that session id and client id match every time a new page is requested

Added notes in the documentation that this change may affect backwards compatibility.

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