## install4j API documentation

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

See:
Description

Packages
com.install4j.api | This package contains classes that can be used to develop custom actions and custom screens for install4j installers.
com.install4j.api.launcher | This package contains classes that can be user in your launcher to use services provided by install4j.
com.install4j.api.windows | This package contains classes with static utility methods for accessing Windows system services.

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.