HowTo: How to upgrade the Java Service Wrapper

When releasing new versions of the Java Service Wrapper, Tanuki Software always takes great care to make sure that existing configuration files and API calls are all compatible with newer versions of the Wrapper.

In the rare cases where functionality needs to be modified in an incompatible way, a note is always made in the Release Notes and on the individual documentation about the feature.

The upgrade steps are simple:

• Locate the version of Java Service Wrapper that you wish to use and download the distribution for the desired platform.

• Stop the running Java Service Wrapper to be upgraded.

• On Windows: Copy the bin\wrapper.exe, lib\wrapper.dll, and lib\wrapper.jar files over the old files of the same names.

  On UNIX: Copy the bin/wrapper, lib/libwrapper.so, and lib/wrapper.jar files over the old files of the same names.

• If you are upgrading from a Wrapper version prior to 3.5.0, please open your conf\wrapper.conf file and add a file encoding to the first line of the configuration file:

  #encoding=UTF-8

  An example of Configuration file can be found here.

  If your configuration makes use of include files (cascading style), then each configuration file should start with an encoding line.

  The old configuration file should otherwise work as is, but it is recommended that you review the src\conf\wrapper.conf.in template file from the new Wrapper version for additions that may be of interest.

• In most cases, the batch files and shell scripts will work with newer versions of the Wrapper, but especially on UNIX platforms, it is recommended that these files are also updated.

  On Windows: The new batch files can be found in the src\bin\ directory. Usually these files can be copied and simply renamed to match the naming of your application.

  On UNIX: The new shell script can be found at src/bin/App.sh.in (on older Wrapper versions, this file was named 'sh.script.in'). If there are any customizations in the current shell script, please make sure to add them in the new shell script. Remember that everything below the settings section should not be modified.

  Since version 3.5.37, the UNIX Shell script tries to load an optional source file which can contain all your customized configuration. This allows the shell script to be kept in its original state and thus simplifies future upgrades. This custom source file is executed after setting the variables on the top of the script, so any variable set in it will override the default configuration of the Shell script. In order for this to work, the source file should have the same basename as the script and be suffixed with a '.shconf' extension.

• (Standard / Professional Edition)

  For Standard or Professional Editions of the Wrapper, please make sure that the Upgrade Term in your License File wrapper-license.conf allows you to upgrade to the new version. Each version has a release date and the Wrapper's license will allow any version of the Wrapper which has been released prior to your Upgrade Term upgrade_term.end_date to be run.

  Server License: If the Upgrade Term does not allow you to use a new version, you can Renew the Upgrade Term. When the Upgrade Term has been renewed then you may need to update your wrapper-license.conf file to be able to run a new version.

  Development License: If you have renewed your Annual Maintenance and Services (TSIMS) then you may need to update your wrapper-license.conf file to be able to run a new version.

  It is possible to verify that a license will authorize a version of the Wrapper by comparing the Upgrade Term with the release dates on the Wrapper version page.

• You may wish to review the release notes to see what improvements have been made between Wrapper versions.

• Once the License Key has been saved/replaced in the wrapper-license.conf, we recommend immediately restarting the Wrapper to ensure that there are no problems. The Wrapper does not require this, but if the newly saved file has any problems, the Wrapper would fail to start the next time the system is rebooted.