VIVO Documentation
Page History
Table of Contents |
---|
...
Overview
Note |
---|
Due to the dependency updates in VIVO 1.10.x, it is important that you read the instructions here carefully, and plan your upgrade accordingly. You will need to consider: 1) The time it will take to upgrade the triple store (can not be performed against a running system) 2) SPARQL queries need to be checked for any explicit use of string datatypes 3) Any applications directly accessing the SDB triple store need to be upgraded to use Jena 3 libraries.
|
...
Warning |
---|
If you are planning an upgrade from anything prior to 1.9.x, please ensure that you read upgrade instructions relating to previous releases. If your version of VIVO is prior to 1.8.x, you will have some ontology changes to consider. |
Java 8
With the upgrade to Jena 3.x, it is required that Java 8 is used. The Maven projects have been upgraded to state a dependency on version 8, and Maven will not run without it.
...
Note |
---|
Java 9 has now been released, but has not been tested with VIVO. However, it does build and appear to run on Java 9. Note that to do so, you need to have a compatible version of Tomcat, as endorsed directory support has been removed. |
Jena 3.x
As the core framework used throughout VIVO, as well as the implementation for the default triple stores, this is the most significant part of the upgrade (although, if you have extensive Javascript customisations in your front end, that side may take more time).
Upgrading The Triple Store
Warning |
---|
This needs to be done by everybody upgrading from a previous version, using the (default) Jena triple stores. It is necessary due to the changes in handling untyped literals in RDF 1.1. If you fail to perform the upgrade, or you mix Jena libraries If you are using an alternative triple store implementation (e.g. Virtuoso, Stardog), then you do not need to reload that triple store. But please remember that VIVO uses two triple stores - content and configuration - and if you are only using an alternative content triple store, you will still need to upgrade the configuration store. |
...
- Stop Tomcat - it is vital that Tomcat / VIVO, and any other applications that may access the triple stores, are not running during this process.
- Run "mvn clean install -s <your-settings.xml>" in your VIVO 1.10.0 development area to update your web application and home directory
This will install the tools into your <vivo_home>/bin directory. Export your existing triple stores:
Warning - To export successfully, you need to ensure no other programs are accessing your triple stores.
- Your file system must have the space available and be capable of storing files large enough to contain your entire triple store serialisation.
To export your triples store, use the jena2tools utility provided with VIVO 1.10.0, in <vivo home dir>/bin, specifying the export command, as shown below.
Code Block java -jar jena2tools.jar -d <vivo home dir> -e
Arguments:
-d - the location of the Vitro/VIVO home directory
-e - run in export mode
On execution, the program will read your configuration files, find your Vitro or VIVO configuration within the vivo/vitro home directory, and get the necessary information to connect to your configuration triple store (usually <vivo home dir>/tdbModels), and your content triple store (usually in SDB). If your triple store(s) are not SDB or TDB backed, then it will simply skip them.
jena2tools will then extract the contents of the available triple stores, and dump them to <vivo home dir>/dumps in TriG format.
Warning In rare cases
jena2tools
will fail with ajava.lang.NullPointerException
. This can occur if VIVO was not properly shut down before upgrading.The preferred fix for this is to restore VIVO 1.9.x and see that it is properly started and shut down before upgrading. If this is not practical, another workaround is to delete the file named
tdbModels/journal.jrnl
in the Vitro/VIVO home directory. This may result in the loss of the most recent login information.Check that the export has completed - you should have a <vivo_home>/dumps directory, that contains the files "configuration.trig" and "content.trig".
- Empty your triple stores
Drop your database and recreate it as empty, just as you would for creating a new VIVO install. jena3tools must find an empty database (no tables) as named in your runtime.properties and will recreate your SDB triple store as tables in the named database using the triples produced by jena2tools and stored in <vivo home dir>/dumps/content.trig
Code Block mysql> DROP DATABASE vitrodb; mysql> CREATE DATABASE vitrodb CHARACTER SET utf8; mysql> GRANT ALL ON vitrodb.* TO 'vitrodbUsername'@'localhost' IDENTIFIED BY 'vitrodbPassword';
- Delete all files in <vivo home dir>/tdbModels. Jena3tools will rebuild your configuration tdbModels based on the content created by jena2tools and stored in <vivo home dir>/dumps/configuration.trig
rm -rf <vivo_home>/tdbModels
- Reload your triple stores
Having exported your triple stores, you can reload them using jena3tools, also available with VIVO 1.10.0, specifying the import command.
Code Block java -jar jena3tools.jar -d <vivo home dir> -i
Arguments:
-d - the location of the Vitro/VIVO home directory
-i - run in import mode
On execution, the program will find your Vitro or VIVO configuration within the home directory, as well as the dumps that you have created with jena2tools. It will import them into the SDB and TDB triple stores, based on the configuration of your Vitro/VIVO instance.
jena3tools will be present in <vivo home dir>/bin when you install the 1.10.0 beta. Alternatively, it can be downloaded from GitHub.
Note that this can take a while. A rough guide is to expect about 600 triples per second to reload. (Roughly 1 hour per 2 million triples). - Restart Tomcat
VIVO checks its filegraphs when starting. Restarting for the first time after an upgrade will take some time.
...
Upgrade Local Java Code
...
Using Jena
If you have local customisations or additional applications that make use of the Jena libraries, you will need to upgrade these to work with Jena 3. Mostly this is simply a case of renaming any packages in imports for Jena classes:
...
However, some classes have been moved, or removed, and some interfaces have additional methods. So in rare cases you may find that you need to make a few small changes beyond this.
A Note on Other Dependency Changes
To remove the possibility of incompatible classes being loaded, and to remove known vulnerabilities from the code base, most of the Java dependencies in VIVO have been removed, updated or replaced.
...
In total, 11 out of an original 113 dependencies are still at the same version as the previous release.
UI Changes
jQuery 1.12.4
Bootstrap based themes require a newer version of jQuery than was shipped with VIVO. In order for all of the functionality aross the UI to work, and to minimise the amount of duplication in the UI, it was necessary to upgrade all of the pages and plugins that used jQuery, so that the same upgraded version works across all of the pages and themes.
...
To aid transition, VIVO still ships with the jquery-migrate.js script, allowing most existing code to work. You should monitor the Javascript console, and apply updates if you see any logged messages in your customisations - future versions of VIVO will remove this migration script in order to upgrade to later versions.
jQuery plugins
In order to support the upgrade to jQuery 1.12.4, and remove any backward compatibility messages from the Javascript console, the following plugins have been upgraded:
...
Old | New | Notes |
---|---|---|
mb.FlipText | Jangle | Used for rotating text on the graphs (e.g. temporal graph) |
isotope | wookmark | Used to render the three columns on the index page |
D3 v4
This is another major upgrade that has architectural changes to improve modularity and make writing visualizations easier, as well as a selection of new features.
...
By making this change now, we are getting on to a maintained version of D3 (v3 has not had any releases for 18 months), and it prepares us for using D3.express in the future, for more dynamic visualization building.
ORCiD API
It has been announced that ORCiD are looking to shut down their v1.x endpoints by the end of 2017. During development to support the new v2 api, it was recognised that the way the settings are currently configured should be simplified. As a result, in order for the ORCiD integration to work in VIVO 1.10, you will need to update your runtime.properties - regardless of which version of the api that you want to use.
...
Setting | Values | Notes |
---|---|---|
orcid.clientId | <your client id> | The client ID that you obtained from ORCiD for API access |
orcid.clientPassword | <your password> | The password the you obtained from ORCiD for API access |
orcid.webappBaseUrl | <your VIVO website> | The URL for your VIVO site |
orcid.externalIdCommonName | <site description> | The text that you want to appear in ORCiD for links back to VIVO profiles |
orcid.apiVersion | 2.0 (or 1.2) | The version of the API to use. It is recommended that you use 2.0. |
orcid.api | release or sandbox | Use sandbox for development, release for production. |
List View Configurations
To produce complex views of data associated with properties (e.g. a person's publication list), VIVO allows the association of externalized SPARQL queries, and associated Freemarker template links.
...
If you have customized listViewConfig-*.xml files, you do not need to rewrite them for VIVO 1.10 - they will work unmodified. However, you will have a small performance improvement, and more readable, maintainable queries, if you choose to modify them to take advantage of the new features.
Vocabulary Services
<< Upgraded web services >>
<< Registering for a UMLS key >>
Servlet 3.0 Upgrade
The web.xml that ships with VIVO has been updated to use 3.0 semantics (the required version of Tomcat already supported 3.0).
...
Alternatively, if you want to disable a servlet, then you can set the web.xml back to 2.5 spec, and add all of the servlet configuration explicitly to the web.xml.
Java Dependencies
HttpClient
Due to OSGi bundling of some of the core dependencies, VIVO had been shipping three different versions of HttpClient, all of which were incompatible with each other, and sometimes generated errors depending on which code paths got executed first.
VIVO 1.10 brings convergence around HttpClient 4.5.3, removing the problems caused previously. If you have any customisations that depend on HttpClient (or the fluent api - fluent-hc), please ensure that you are using the versions that are already indlueded with VIVO. This may require some minor adjustments to your client code to make it compatible.
OSGi Dependencies
The OWLAPI previously included with VIVO was an OSGi bundle, and included the classes of a number of libraries (such as HttpClient above). This causes classloading conflicts. In VIVO 1.10, we are depending directly on the libraries that were being bundled, rather than the bundle in it's entirety.
In addition, Jena has OSGi dependencies for HttpClient, leading to more duplicate classes. These have been explicitly excluded - see dependencies/pom.xml for how this is done.
JSON Parsers
Four JSON parsers - GSON (com.google.gson), Glassfish (javax.json.Json, Sourceforge.net (net.sf.json) and JSON.org (org.json) have been removed, to simplify the code base, reduce vulnerabilities and improve performance.
...
If you have local customisations that use a different JSON parser, you can add the dependency to your projects, although it is recommended that migrating to Jackson is preferable for long term maintenance.
Replaced Dependencies
The CSV parser has been replaced with commons-csv.
Removed Dependencies
The following dependencies have been removed from VIVO. If you have customisations that require any of them, you will need to add them as dependencies in your own projects.
agrovocws-3.0.jar, asm-3.1.jar, aterm-java-1.8.2.jar, axis-1.3.jar, axis-jaxrpc-1.3.jar, axis-saaj-1.3.jar, bcmail-jdk14-1.38.jar, bcprov-jdk14-1.38.jar, bctsp-jdk14-1.38.jar, c3p0-0.9.2-pre4.jar, cglib-2.2.jarcommons-beanutils-1.7.0.jar, commons-discovery-0.2.jar, cos-05Nov2002.jar, csv-1.0.jar, cxf-xjc-runtime-2.6.2.jar, cxf-xjc-ts-2.6.2.jar, dom4j-1.6.1.jar, ezmorph-1.0.4.jar, gson-2.5.jar, jai_codec-1.1.3.jar, jai_core-1.1.3.jar, JavaEWAH-0.8.6.jar, javax.json-api-1.0.jar, jjtraveler-0.6.jar, jsonld-java-jena-0.2.jar, json-lib-2.2.2-jdk15.jar, lucene-analyzers-common-5.3.1.jar, lucene-core-5.3.1.jar, lucene-memory-5.3.1.jar, lucene-queries-5.3.1.jar, lucene-queryparser-5.3.1.jar, lucene-sandbox-5.3.1.jar, mail-1.4.jar, mchange-commons-java-0.2.2.jar, shared-objects-1.4.9.jar, sparqltag-1.0.jar, stax-api-1.0-2.jar, wsdl4j-1.5.1.jar
Location of runtime.properties
The preferred location of runtime.properties has changed from the <vivo_home> directory to <vivo_home>/config. VIVO will raise a warning on startup if runtime.properties is found in <vivo_home> or both <vivo_home> and <vivo_home>/config. Continue startup by refreshing or clicking continue. Move runtime.properties into the config directory to avoid the warning.