Compatibility :	3.3.7
Editions :
Platforms :

With the release of Wrapper version 3.3.7, the Wrapper provides the ability to change some of its resources and to customize its appearance on Windows.

When customizing the consoleless version of the Wrapper binary "wrapperW.exe", a new version of the binary (Example: MyApp.exe) will be created containing the new resources specified with the "--customize" command. The resulting binary will be locked, meaning that it is no longer possible to customize it.

When creating a new custom binary, any of the following arguments can be combined. The "--target {target.exe}" argument is always required.

Please note that the paths of all file names are relative to the location of the Wrapper binary, not necessarily relative to the location of the caller. For example, the following command will create the target file in the same directory as the "wrapperW.exe" binary and expect to find the new icon and splashscreen in that directory as well:

bin\wrapperw.exe --customize --target myapp.exe --icon myicon.ico --splash mysplash.bmp

When the Wrapper binary is customized, it is necessary to always specify a new file name for the customized version. The Wrapper will always overwrite the file if it already exists.

wrapperw.exe --customize --target myapp.exe

Putting the parameter all together would result to a command line like this:

bin\wrapperw.exe --customize --icon MyIcon.ico --splash MySplash.bmp --target MyApp.exe

This command will create a new executable MyApp.exe in the same directory the "wrapperW.exe" is located, with a customized icon and splash screen.

When customizing wrapperw.exe, a dialog box will appear to display the log output. This is useful to confirm whether the customization ended successfully or with some errors. However, in some cases such as when launching the customization from a script, showing a dialog box may block the process, as it requires human interaction to close the window. For this reason, a '--silent' parameter was added in Wrapper version 3.5.34 to never show the log dialog when customizing wrapperw.exe. Note that the property wrapper.logdialog.enable, which controls whether the log dialog should be displayed on shutdown when running the Wrapper normally, cannot be used when customizing the binaries because the configuration file is not loaded during the customization process.

wrapperw.exe --customize --silent --target myapp.exe

The Wrapper is shipped with a default icon. However, software developers may wish to replace the icon with one of the product the Wrapper is being used with. For this purpose, the Wrapper offers the feature to customize its icon.

The icon file is a standard multi layer icon file that contains all of the resolution and icon sizes that need to be supported.

wrapperw.exe --customize --target myapp.exe --icon myicon.ico

The following is a screenshot of a directory containing a customized MyApp.exe along with renamed copies of the three Java Service Wrapper Editions and their default icons.

The consoleless version of the Wrapper binary, "wrapperW.exe", by default will show a Splash Screen on startup. This splash screen can be customized with an image representing the product that the Wrapper is being used with.

The Wrapper binary wrapper.exe doesn't display a splash screen, therefore, the argument for customizing the splash screen is illegal.

Having the Wrapper display a splash screen rather than doing so from within Java has the benefit of making the applications startup seem very responsive. This is because the splash screen will be displayed before the JVM is launched and can remain visible as the Java application's classes are loaded and initialized.

The way the splash screen behaves can be controlled with the wrapper.splashscreen.mode property.

wrapperw.exe --customize --target myapp.exe --splash mysplash.bmp

Currently only bitmap (*.bmp) files are supported. There are no size or bit-depth restrictions set.

Default Java Service Wrapper Professional Edition splash screen.

Default Java Service Wrapper Standard Edition splash screen.

Example custom splash screen.

By default, if the Wrapper binary gets called without specifying any configuration file, the Wrapper will assume to use the default configuration file in the same directory where the executable is located. It is a file called {MyApp}.conf, where the name {MyApp} is based on the file name of the executable file. For instance: if the executable file is called "test.exe", the Wrapper will try to open "test.conf".

wrapperw.exe --customize --target myapp.exe --conf ../conf/myconf.conf

This option comes especially in handy when used with the "--passthrough" option described below.

By default, the Wrapper interprets parameters by itself. Any parameter that should be passed over to the JVM application had to be defined with the wrapper.app.parameter.<n> property. In Wrapper version 3.5.2, the "--" command was added to ease passing over to the JVM application. However, customizing your application with this new option will actually put the Wrapper in background and make the executable look like a native Windows Application.

Activating this functionality just requires you to add the "--passthrough" parameter in the command to customize your Wrapper executable. The new executable will start your Java application right out-of-the-box.

Because the Wrapper will pass over all parameters to the JVM, it is not possible to specify the configuration file through the command line anymore. The new executable will rather try to use the default configuration file. In order to change the default configuration file, please consider using the "--conf" option described above.

wrapperw.exe --customize --target myapp.exe --passthrough

The Wrapper binary has a version info resource defined, which sets the basic file information like version number, copyright, file description, manufacturer etc. Distributors, who are bundling their application with the Wrapper and want to put their own company information in front of the Wrapper binary, might want to replace the manufacturer name of the binary from "Tanuki Software, Ltd." to their company name.

wrapperw.exe --customize --target myapp.exe --manufacturer "My Example Company"

Starting from version 3.5.35, it is possible to embed any configuration properties into the Wrapper binaries.

Four options are available to do so:

• properties-default to change the default values of properties listed on the command line.
• property-file-default to change the default values of properties listed in a configuration file.
• properties-final to embed final properties (which can't be overwritten), listing them on the command line.
• property-file-final to embed final properties (which can't be overwritten), taking them from a configuration file.

wrapperw.exe --customize --target myapp.exe --properties-default wrapper.console.format=LPTM --properties-final wrapper.name="testwrapper" wrapper.displayname="Test Wrapper Sample Application" wrapper.description="Test Wrapper Sample Application Description"

When the configuration properties are directly listed in the command line, they should be separated by a space. Any value containing a space should be double-quoted.

wrapperw.exe --customize --target myapp.exe --property-file-default ../conf/wrapper-embedded-default.conf --property-file-final ../conf/wrapper-embedded-final.conf

It is possible to embed the license properties inside the Wrapper binaries.

wrapperw.exe --customize --target myapp.exe --property-file-final ../conf/wrapper-license.conf

To visualize which properties have been embedded into your target .exe file, you may use the 'S' or 'Z' tokens of the wrapper.properties.dump.format property, and set wrapper.properties.dump.loglevel to INFO.

Since version 3.5.36, the configuration file is no longer required once the binaries has been customized with embedded properties. Embedding all the configuration is a good way to ease launching your application!

Since version 3.5.37 it is also possible to skip the configuration file by specifying '-' in the command line used to launch the Wrapper. This allows the user to append command line properties after the '-' and override the default embedded configuration.

Introduced in version 3.5.43, the '--conf-optional' option can be used to indicate that the customized target contains enough embedded configuration to run without the need of a configuration file.

By default, the Wrapper requires a configuration file to execute. This is because it needs some minimal configuration to properly launch the Java Application. If you have set up your customization command line to embed enough configuration for the Wrapper to properly launch your Java application, you may append this option to allow the Wrapper to execute without a configuration file. This may make it easier for the end-user to launch the Wrapper executable.

If you include only a part of the configuration in the Wrapper binaries (such as the license), this option should not be used.