This documentation specifies the public API that install4j provides for runtime services and installer customization.

Getting started

To get started with writing custom actions and custom screens, please have a look at the Hello World Suite example project that is located in the demo subdirectory of your install4j installation. Source code for custom actions can be found in demo/actions, source code for custom screens is located in demo/screens (enterprise edition only). Both custom actions and custom screens are compiled and packaged as a JAR file in demo/custom.jar.

Classpath for framework classes

When developing our own classes, include {install4j installation directory}/resource/i4jruntime.jar in your classpath. Do not distribute this jar file with your application, install4j will handle this for you. i4jruntime.jar will be available on the classpath for custom screens and custom actions in the installer as well as for all launchers generated by install4j.

Testing and debugging

To test and debug custom screens and custom actions for your installer you can follow this procedure:

• When you build your project, enable the create additional debug launcher build option in the build section. After the build, your media file output directory will contain directories with the name debug_[name of the media file minus extension] for each media file that you have built.

• The debug directories contain

  • the Windows batch files debug_installer.bat and debug_uninstaller.bat for Windows media files
  • the shell scripts debug_installer.sh and debug_uninstaller.sh for media files of Unix based platforms

  They start the installer and the uninstaller with a plain java invocation. All exceptions are directly printed to stderr and no separate error log files are created.

• The file user.jar in the debug directory contains all your custom code. For interactive development you will not want to rebuild the project after each modification of your custom code. You can set up the installer or the uninstaller in your IDE by

  • setting the working directory to the debug directory
  • including i4jruntime.jar in the class path
  • including your custom code in the class path
  • using the main class com.install4j.runtime.installer.Installer for the installer or com.install4j.runtime.installer.Uninstaller for the uninstaller
  • passing the VM parameter -Dinstall4j.debug=true

  Note: The working directory for the executed java process must be the the debug directory, otherwise both the installer as well as the uninstaller will not work!

This procedure allows for an edit-compile-debug cycle that is much faster than building the media file and running the installer. In addition, output on stderr and stdout can be captured and you can debug your custom actions and custom screens this way.

Notes on custom install actions

Custom install actions are the most important and most common extension available in the install4j API. Custom install actions are derived from com.install4j.api.InstallAction. You have to override all appropriate methods. The performAction() method is where you do the actual work.

Internationalization

Custom actions and custom screens can be localized with the standard Java ResourceBundle mechanism (see the Java API Javadoc for java.util.ResourceBundle for further information).

The locale of the installer will always be set to the locale that is specified for the media set, not the locale of the system that the installer is running on. You can query com.install4j.api.Util.getInstallerLanguage() to find out what locale your installer is runnning with.