-
-
Notifications
You must be signed in to change notification settings - Fork 44
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #144 from eXist-db/DP-upgrade-upgrade
further tweaks to upgrading
- Loading branch information
Showing
4 changed files
with
321 additions
and
192 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,196 @@ | ||
| <!-- $Id$ --> | ||
| <book> | ||
| <bookinfo> | ||
| <productname>eXist-db – Open Source Native XML Database</productname> | ||
| <title>Incompatibilties</title> | ||
| <date>27-11-2017</date> | ||
| <author> | ||
| <firstname>Duncan</firstname> | ||
| <surname>Paterson</surname> | ||
| </author> | ||
| </bookinfo> | ||
| <chapter> | ||
| <title>Known Issues for Binary Non-compatible Upgrades</title> | ||
| <section id="v3.0.0"> | ||
| <title>Upgrading to 3.0 stable</title> | ||
| <para>eXist-db v3.0 is not binary compatible with previous versions of eXist-db; the on-disk database file format has been updated, users should perform a full backup and restore to migrate their data.</para> | ||
| <para>eXist.db v3.0 and subsequent versions now require <emphasis>Java 8</emphasis>; Users must update to Java 8!</para> | ||
| <para>3.0 removes the the legacy Full Text Index and the text (http://exist-db.org/xquery/text) XQuery module. Users should now look toward <code>fn:analyze-string</code>, e.g. | ||
| <orderedlist> | ||
| <listitem> | ||
| <para>instead of using <code>text:groups()</code> use <code>analyze-string()//fn:group</code>,</para> | ||
| </listitem> | ||
| <listitem> | ||
| <para>instead of <code>text:filter("apparat", "([pr])")</code> use <code>analyze-string("apparat", "([pr])")//fn:match/string())</code>.</para> | ||
| </listitem> | ||
| </orderedlist> | ||
| </para> | ||
| <para>Furthermore, the SOAP APi, SOAP server, and XACML Security features were removed.</para> | ||
| <para>The versioning extension is now available as a separate <ulink url="https://github.com/eXist-db/xquery-versioning-module">EXPATH package</ulink> | ||
| </para> | ||
| <para>XQueryService has been moved from <code>DBBroker</code> to <code>BrokerPool</code>.</para> | ||
| <para>EXPath packages that incorporate Java libraries may no longer work with eXist-db v3.0 and may need to be recompiled for our API changes; packages should now explicitly specify the eXist-db versions that they are compatible with.</para> | ||
| <para>eXist-db v3.0 is the culmination of almost 1,500 changes. For more information on new features head to the <ulink url="http://exist-db.org/exist/apps/wiki/blogs/eXist//eXist-db-v3">blog</ulink>.</para> | ||
| </section> | ||
| <section id="v2.2"> | ||
| <title>Upgrading to 2.2 final</title> | ||
| <para>The 2.2 release is not binary compatible with the 1.4.x series. You need to | ||
| backup/restore. If you experience problems with user logins after the restore, please restart eXist-db.</para> | ||
| <para>2.2 introduces a <emphasis>new range index module</emphasis>. Old index definitions will still work though as we made sure to keep backwards | ||
| compatible. If you would like to upgrade to the new index, check its <ulink url="newrangeindex.xml">documentation</ulink>.</para> | ||
| <para>The XQuery engine has been updated to support the changed syntax for <emphasis>maps in XQuery 3.1</emphasis>. The query parser will still accept the | ||
| old syntax for map constructors though (<code>map { x:= "y"}</code> instead of <code>map { x: "y" }</code> in XQuery 3.1), so old | ||
| code should run without modifications. All map module functions from XQuery 3.1 are | ||
| <ulink url="{fundocs}/view.html?uri=http://www.w3.org/2005/xpath-functions/map&location=java:org.exist.xquery.functions.map.MapModule">available</ulink>.</para> | ||
| <para>The signatures for some <emphasis>higher-order utility functions</emphasis> like fn:filter, fn:fold-left and fn:fold-right have changed as well. Please review your | ||
| use of those functions. Also, fn:map is now called fn:for-each, though the old name is still accepted.</para> | ||
| <para>The bundled Lucene has been upgraded from 3.6.1 | ||
| to 4.4 with this release. Depending on what Lucene | ||
| analyzers you are using you need to change the | ||
| classnames in your | ||
| <filename>collection.xconf</filename>s. E.g. KeywordAnalyzer | ||
| and WhitespaceAnalyzer has moved into package | ||
| <filename>org.apache.lucene.analysis.core</filename>. Thus | ||
| change, any occurrence of | ||
| <filename>org.apache.lucene.analysis.WhitespaceAnalyzer</filename> | ||
| into | ||
| <filename>org.apache.lucene.analysis.core.WhitespaceAnalyzer</filename> | ||
| and all other moved classes in the collection | ||
| configurations and make sure you reindex your data | ||
| before use. You get an error notice in the | ||
| <filename>exist.log</filename> if you overlooked any | ||
| occurrences.</para> | ||
| </section> | ||
| <section id="v2.1"> | ||
| <title>Upgrading to 2.1</title> | ||
| <para>The 2.1 release is not binary compatible with the 1.4.x series. You need to | ||
| backup/restore. 2.1 is binary compatible with 2.0 though.</para> | ||
| </section> | ||
| <section id="v2.0"> | ||
| <title>Upgrading to 2.0</title> | ||
| <para>The 2.0 release is not binary compatible with the 1.4.x series. You need to | ||
| backup/restore.</para> | ||
| <section> | ||
| <title>Special Notes</title> | ||
| <variablelist> | ||
| <varlistentry> | ||
| <term>Permissions</term> | ||
| <listitem> | ||
| <para>eXist-db 2.0 closely follows the Unix security model (plus ACLs). Permissions have thus | ||
| changed between 1.4.x and 2.0. In particular, there's now an execute permission, which is | ||
| required to</para> | ||
| <orderedlist> | ||
| <listitem> | ||
| <para>execute an XQuery via any of eXist-db's interfaces</para> | ||
| </listitem> | ||
| <listitem> | ||
| <para>change into a collection to view or modify its contents</para> | ||
| </listitem> | ||
| </orderedlist> | ||
| <para>eXist-db had an update permission instead of the execute permission. Support for the update permission | ||
| has been dropped because it was not used widely.</para> | ||
| <para>When restoring data from 1.4.x, you thus need to make sure that:</para> | ||
| <orderedlist> | ||
| <listitem> | ||
| <para>collections have the appropriate execute permission</para> | ||
| </listitem> | ||
| <listitem> | ||
| <para>XQueries are executable</para> | ||
| </listitem> | ||
| </orderedlist> | ||
| <para>You can use an XQuery to automatically apply a default permission to every collection and XQuery, and | ||
| then change them manually for some collections or resources.</para> | ||
| <programlisting language="xquery">xquery version "3.0"; | ||
|
|
||
| import module namespace dbutil="http://exist-db.org/xquery/dbutil"; | ||
|
|
||
| dbutil:find-by-mimetype(xs:anyURI("/db"), "application/xquery", function($resource) { | ||
| sm:chmod($resource, "rwxr-xr-x") | ||
| }), | ||
| dbutil:scan-collections(xs:anyURI("/db"), function($collection) { | ||
| sm:chmod($collection, "rwxr-xr-x") | ||
| })</programlisting> | ||
| </listitem> | ||
| </varlistentry> | ||
| <varlistentry> | ||
| <term>Webapp Directory</term> | ||
| <listitem> | ||
| <para>Contrary to 1.4.x, eXist-db 2.0 stores most web applications into the database. The webapp | ||
| directory is thus nearly empty. It is still possible to put your web application there and it should | ||
| be accessible via the browser in the same way as before.</para> | ||
| </listitem> | ||
| </varlistentry> | ||
| </variablelist> | ||
| </section> | ||
| </section> | ||
| <section id="v1.4"> | ||
| <title>Upgrading to 1.4.0</title> | ||
| <para>The 1.4 release is not binary compatible with the 1.2.x series. You need to | ||
| backup/restore.</para> | ||
| <section> | ||
| <title>Special Notes</title> | ||
| <variablelist> | ||
| <varlistentry> | ||
| <term>Indexing</term> | ||
| <listitem> | ||
| <para>eXist-db 1.2.x used to create a default full text index on all | ||
| elements in the db. This has been <emphasis>disabled</emphasis>. The | ||
| main reasons for this are:</para> | ||
| <orderedlist> | ||
| <listitem> | ||
| <para>maintaining the default index costs performance and | ||
| memory, which could be better used for other indexes. The | ||
| index may grow very fast, which can be a destabilizing | ||
| factor.</para> | ||
| </listitem> | ||
| <listitem> | ||
| <para>the index is unspecific. The query engine cannot use it as | ||
| efficiently as a dedicated index on a set of named elements | ||
| or attributes. Carefully creating your indexes by hand will | ||
| result in much better performance.</para> | ||
| </listitem> | ||
| </orderedlist> | ||
| <para>Please consider using the new Lucene-based full text index. | ||
| However, if you need to switch back to the old behaviour to ensure | ||
| backwards compatibility, just edit the system-wide defaults in | ||
| conf.xml:</para> | ||
| <programlisting> | ||
| <markup><index> | ||
| <fulltext attributes="false" default="none"> | ||
| <exclude path="/auth"/> | ||
| </fulltext> | ||
| </index></markup> | ||
| </programlisting> | ||
| </listitem> | ||
| </varlistentry> | ||
| <varlistentry> | ||
| <term>Document Validation</term> | ||
| <listitem> | ||
| <para>Validation of XML documents during storage is now <emphasis>turned | ||
| off by default</emphasis> in <filename>conf.xml</filename>:</para> | ||
| <synopsis language="xml"><validation mode="no"></synopsis> | ||
| <para>The previous <option>auto</option> setting was apparently too | ||
| confusing for new users who did not know what to do if eXist-db refused | ||
| to store a document due to failing validation. If you are familiar | ||
| with <ulink url="validation.xml">validation</ulink>, the use of | ||
| catalog files and the like, feel free to set the default back to | ||
| <option>auto</option> or <option>yes</option>.</para> | ||
| </listitem> | ||
| </varlistentry> | ||
| <varlistentry> | ||
| <term>Cocoon</term> | ||
| <listitem> | ||
| <para>eXist-db does no longer require Cocoon for viewing documentation and | ||
| samples. Cocoon has been largely replaced by eXist-db's own <ulink url="urlrewrite.xml">URL rewriting and MVC | ||
| framework</ulink>.</para> | ||
| <para>Consequently, we now limit Cocoon to one directory of the web | ||
| application (<filename>webapp/cocoon</filename>) and moved all the | ||
| Cocoon samples in there. For the 1.5 version we completely | ||
| removed Cocoon support.</para> | ||
| </listitem> | ||
| </varlistentry> | ||
| </variablelist> | ||
| </section> | ||
| </section> | ||
| </chapter> | ||
| </book> |
Oops, something went wrong.