Migration guide from LTS-2019 to LTS-2021

This guide provides a high level overview for migrating the latest nevisLogRend LTS 2019 release to the new LTS 2021 release. For additional details refer to the technical documentation.

Deployment Type - Standalone

Only standalone deployment is supported. If your instances still use adnjboss, adnwildfly or any other non-standalone deployment type, the instances need to be recreated and the configuration migrated. The [technical documentation] contains information of how new instances can be created.

Removed deprecated TLS Protocols

For security reasons, the standalone server now supports fewer TLS protocols and ciphers by default. See the chapter "Server Configuration Properties" in the nevisLogRend Reference Guide for the updated list of supported ciphers and protocols. This change may break existing deployments. If you use protocols and ciphers that are supported by default and your clients do not support them, it is recommended that you update your HTTP clients. If this is not possible:

• Open the logrend.propertiesconfiguration file.
• Specify the protocols and ciphers supported by your clients in the attributes server.tls.supported-protocols and server.tls.cipher-suites.

Removed Rendering Support

Support for "Structured Box Rendering" and "Custom JSP Rendering" is removed completely. If your production environment is affected, you need to migrate to Velocity templates.

Updated jQuery Version

Existing velocity templates and JavaScript libraries require updating. Newly created nevisLogRend instances will be based on jQuery 3.6.0. As this only applies to newly created instances, existing instances must be patched manually. This is because a version upgrade of nevisLogRend does not automatically change the (customizable) relevant jQuery files in the instance directory. You can find the jQuery files here: /var/opt/nevislogrend/<instance>/data/applications/<application>/webdata/js/

• Also update the source files in the instance directory so that they refer to the new jQuery script.
• It is possible that an application uses a very old version of jQuery, for example because the nevisLogRend instance was not revised for a while. In this case, the source files in the application directory using jQuery may not be compatible with the new jQuery version. To resolve this, patch the relevant source files according to the instructions described here: `http://jquery.com/upgrade-guide/.

Updated Velocity Version

The Velocity template engine was updated from version 1.7 to version 2.3. This upgrade can lead to incompatibilities with old Velocity templates, depending on the variables and syntax you use in your templates.

In the new version, some of the Velocity configurations have been renamed. To find the affected configurations, check the nevisLogRend log files after the upgrade for WARN log entries in the category org.apache.velocity.deprecation. For an example, see the following code snippet. To rename an affected configuration, follow the instructions in the log line. Keep in mind that in the nevisLogRend application configurations, Velocity properties have a velocity. prefix to distinguish them from the regular nevisLogRend application configurations.

Example log line

2021-07-08 15:37:30,943 main org.apache.velocity.deprecation WARN configuration key 'velocimacro.permissions.allow.inline.local.scope' has been deprecated in favor of 'velocimacro.inline.local_scope'

Changes in third-party Velocity-tools features

The chapter "Rendering Engines" in the nevisLogRend reference guide includes an overview of the available third-party Velocity tools. If you use any of these tools, you most likely have to adapt your Velocity templates to change to the new syntax. The following list summarizes the changes: browser: Changed The previous class BrowserSnifferToolis replaced with the class BrowserTool. The old class is deprecated and removed. The previous class IteratorTool is replaced with the class LoopTool. The class ListTool is deprecated and removed. The list tool contained list functions that were not available directly on the list. You can now use list functions directly available on list objects. Instead of the AlternatorTool, use CSS3 nth-child(even/odd) selectors or #if($foreach.index % 2). The previous class LinkTool (tools.LinkTool) is replaced with the class LinkTool (without "tools."). The previous class ParameterParser is replaced with the class ParameterTool. The previous class SortTool is replaced with the class CollectionTool.

If you experience unexpected behaviour other than before the upgrade, and the previously mentioned changes do not apply, try enablig the backwards compatibility flags in the application configuration (/var/opt/nevislogrend/<instance>/data/applications/<application>/resources/conf/default.properties), as described in the Velocity migration guides:

# No automatic conversion of methods arguments
velocity.introspector.conversion_handler.class=none

# Use backward compatible space gobbling
velocity.parser.space_gobbling=bc

# Have #if($foo) only returns false if $foo is false or null
velocity.directive.if.empty_check=false

# Allow '-' in identifiers (since 2.1)
velocity.parser.allow_hyphen_in_identifiers=true

# Enable backward compatibility mode for Velocimacros
velocity.velocimacro.enable_bc_mode=true

# When using an invalid reference handler, also include quiet references (since 2.2)
velocity.event_handler.invalid_references.quiet=true

# When using an invalid reference handler, also include null references (since 2.2)
velocity.event_handler.invalid_references.null=true

# When using an invalid reference handler, also include tested references (since 2.2)
velocity.event_handler.invalid_references.tested=true

General Velocity migration guides from Apache are available here:

http://velocity.apache.org/engine/2.3/upgrading.html/