World Map
Java Service Wrapper is the easiest way to make your product more reliable.
  • Free Trial
  • Buy Now

Problem

How can I distribute my Java application with the Wrapper to run on any platform?

Arrow

Solution!

The Wrapper can easily be deployed by using the "Delta Pack", a single package containing the required binaries and libraries to work out of the box on all supported platforms.

Delta Pack Overview

The Delta Pack bundles the binaries and libraries required for the Wrapper to run on all supported platforms*. It also contains the Windows bat files and Unix shell script used to launch the Wrapper. Use of these scripts make it easier to launch the Wrapper, as they will automatically select the appropriate binaries for the current platform. In other words, they let you launch the Wrapper in a transparent way, using the same commands across the different UNIX platforms (Windows using separate bat script files).

With a single configuration file, you will be able to configure the Wrapper to run your Java application either as a console application or as Windows Service/Unix Daemon on the different OSs. It is also possible to have a platform-specific configuration whenever the need arises.

Creating a single large distribution with the binaries of all platforms can make it much easier for your users to get up and running when they are not sure what they need. The resulting file is obviously large, but you are free to prune it down to only include what your users are likely to need. It is also possible to run a script after extraction to delete any files not needed for the current platform.

Even if you want to distribute your application in platform-specific bundles, the delta pack structure can be useful to include both 32 and 64-bit native files in a single distribution. This on its own is very useful so your users don't have to try and figure out what bits are needed for their specific combination of OS and Java installation.

The Delta Pack is available in all editions starting from Version 3.2.0.

NOTE

* The z/OS platform uses the EBCDIC character set, which is not ASCII compatible. If you download the z/OS distribution and view it on other systems, all of its files will appear to be corrupted. This is normal. For this reason, the z/OS platform is intentionally not included in the delta pack distributions.

Downloading the Delta Pack

On the download page, under the links for the different platforms, you will find the links to download the Delta Pack.

The Delta Pack is offered in both .tar.gz or .zip formats. The content is the same, but you may prefer one format over the other depending on your method to extract files.

Please choose your desired edition: Professional, Standard or Community.

Once your package is downloaded, please extract it.

Structure

Binaries

You can find the libraries of all supported platforms inside the lib folder.

You will also find the binaries for the different platforms and the scripts used to launch the Wrapper inside the bin folder.

For each platform, there may be both 32-bit and 64-bit versions of the libraries and binaries.

Configuration

You will find the configuration file inside the conf folder. Generally the license file is also located in this folder.

Licensing

For the Standard and Professional editions, the Wrapper requires a valid license in order to run. It is recommended (but not required) to put the license key in a separate file located in the same folder as your configuration file.

If you purchase a Development license, you will only need one license key, which is tied to your Java application and allows it to run on any platforms. This type of license, by nature, best matches with the Delta Pack.

A Server license key can only be used on a single machine, but it is possible to group license keys for multiple servers in a single file by including the host names or HostIds in the license key property names.

Example:
# license for hostid 00123456789a
wrapper.00123456789a.license.type=NODE
wrapper.00123456789a.license.id=201804010006
wrapper.00123456789a.license.licensee=Acme, Inc.
wrapper.00123456789a.license.host_id=00123456789a
wrapper.00123456789a.license.features=pro, 64bit
wrapper.00123456789a.license.upgrade_term.begin_date=2018-04-01
wrapper.00123456789a.license.upgrade_term.end_date=2019-04-01
wrapper.00123456789a.license.key.1=0222-2e8a-6f6d-4a4a
wrapper.00123456789a.license.key.2=007d-7e3c-5e2a-427e
wrapper.00123456789a.license.key.3=ce16-f5f0-59f4-d18a
wrapper.00123456789a.license.key.4=b6ca-c31a-6be8-323d

# license for hostid 00123456789b
wrapper.00123456789b.license.type=NODE
wrapper.00123456789b.license.id=201804010007
wrapper.00123456789b.license.licensee=Acme, Inc.
wrapper.00123456789b.license.host_id=00123456789b
wrapper.00123456789b.license.features=pro, 64bit
wrapper.00123456789b.license.upgrade_term.begin_date=2018-04-01
wrapper.00123456789b.license.upgrade_term.end_date=2019-04-01
wrapper.00123456789b.license.key.1=0222-2e8a-6f6d-4a4a
wrapper.00123456789b.license.key.2=007d-7e3c-5e2a-427e
wrapper.00123456789b.license.key.3=ce16-f5f0-59f4-d18a
wrapper.00123456789b.license.key.4=b6ca-c31a-6be8-323d

NOTE

It is possible to change the host name portion of the License Key properties without regenerating the key. Anytime you need to deploy the Wrapper on a new platform, you can simply add a new key to your license without editing the existing keys.

When the Delta Pack is launched on Windows or a Unix system, it will first check which architecture your license is targeting (32-bit or 64-bit). This is done because it is possible to run the Wrapper with a 32-bit license on a 64-bit OS. In this case, the Delta Pack will launch the appropriate 32-bit binary of the current platform. If your license has both 32-bit and 64-bit features enabled, or if you run the community edition, the binaries matching your OS bits will be used.

Distribution

Choosing your binaries

By default, the Delta Pack gathers the binaries and libraries for all platforms that the Wrapper supports (except z/OS).

However, you may want to remove the binaries that you don't need and repack the necessary files using your favorite compression tool. This can be useful in the following situations:

- If you choose to distribute your Java application with the Delta Pack separately for Windows and UNIX systems.

- If you know that you will not deploy the Wrapper on certain platforms or architectures, this may be good to make your package lighter and thus faster to transfer.

- If you own a 32-bit license, you may remove all 64-bit binaries since they can't be used. This was required when running on a 64-bit system until version 3.5.36. Versions 3.5.37 and above can detect the license type and launch the correct binaries, but deleting the unnecassary ones is still advised for clarity.

If you would like to learn more about the platforms supported by the Java Service Wrapper, please visit Supported Platforms Overview.

Cross-platform configuration

The Wrapper configuration properties are designed to be cross-platform, which means that you would only need a single configuration file and single set of properties in most cases. There are, however, a few good practices to handle this smoothly and for cases where you need a platform-specific configuration.

First, if you chose to deploy your Delta Pack on both Windows and Linux, make sure that all your paths included in your configuration use forward slashes '/' and not backslashes '\'. Backslashes are only supported on Windows.

If you want to localize your application, you may need to use different locale notations and encodings depending on the platform. For the wrapper.lang property, it is advised to use the UNIX notations (e.g. 'ja_JP' or 'en_US') instead of the Windows notations (e.g.'English_United States', 'Japanese_Japan'). UNIX notations also work on Windows, but Windows notations won't work on UNIX systems. For the encodings (controlled by wrapper.lang.encoding), you may use 'UTF-8' which is generally supported on all platforms, including windows. If you need to use different encodings per platform, please consider using the wrapper.lang.<platform>.encoding properties.

The following configuration properties also let you set a value per platform:

Another useful technique is to gather all common configuration in the root configuration file and write the platform-specific configuration in separate include files.

You can use the following environment variables to reference your include files from your main configuration file: WRAPPER_OS, WRAPPER_ARCH, WRAPPER_BITS.

#include ../conf/wrapper-%WRAPPER_OS%-%WRAPPER_ARCH%.conf

You can either use environment variables in the file name or in a parent folder name.

Then, you will have to create a configuration file for each platform where you need a specific configuration. Just make sure that the file names are built with the values that the environment variables will take on the platform you target. If an include configuration file is not found, it will be silently skipped.

If your application makes use of other native libraries, then you will need to set up the configuration to include the correct libraries for the current platform. This is explained on the wrapper.java.library.path.<n> page.

Support

If you have any questions, please feel free to contact us with a support request at support@tanukisoftware.com and we will be happy to help you. We are also interested in hearing your feedback and comments about this or other features.