## install4j API documentation

This documentation specifies the public API that install4j provides for scripting installers and uninstallers, developing extensions and for accessing runtime services.

See:
Description

Packages
com.install4j.api | This package contains general utility classes for the install4j API.
com.install4j.api.actions | This package contains the interfaces and abstract base classes for actions.
com.install4j.api.beaninfo | This package contains the utility classes for writing BeanInfo classes for screens, actions and form components.
com.install4j.api.beans | This package contains the base classes for all extension points in install4j as well as special property classes.
com.install4j.api.context | This package contains classes that allow you to interact with the installer and its environment.
com.install4j.api.events | This package contains classes that allow you to listen for events generated by the installer.
com.install4j.api.formcomponents | This package contains the interface and abstract base class for form components.
com.install4j.api.launcher | This package contains classes that your own application code can use to access runtime services provided by install4j.
com.install4j.api.screens | This package contains the interfaces and abstract base classes for screens.
com.install4j.api.unix | This package contains classes with static utility methods for using Unix-specific features that are not directly supported by the Java platform.
com.install4j.api.update | This package contains classes that help you to handle auto-updates.
com.install4j.api.windows | This package contains classes with static utility methods for using Windows-specific features that are not directly supported by the Java platform.

This documentation specifies the public API that install4j provides for scripting installers and uninstallers, developing extensions and for accessing runtime services.

### Getting started

Please read "Help topics->Extending install4j->Using the install4j API" in the documentation ( directory `$INSTALL4J_HOME/doc` or `F1` in the install4j IDE) for an overview on how to use the API. Packaging your own beans as regular install4j extensions is explained under "Help topics->Extending install4j->Extensions".

To get started with writing your own screens, actions and form components, please have a look at the Custom Code example project that is located in the `samples/customCode` subdirectory of your install4j installation.

### Classpath for framework classes

When developing your own classes, you have to add `$INSTALL4J_HOME/resource/i4jruntime.jar` to your classpath. Do not distribute this jar file with your application, install4j will handle this for you. `i4jruntime.jar` will be automatically available on the classpath in the installer as well as for all launchers generated by install4j.

### Testing and debugging

To test and debug screens, actions and form components 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 your own code in the class path
  - including i4jruntime.jar in the class path
  - including user.jar in the class path. Your own code will also be contained in user.jar, but the IDE typically places project code at the beginning of the class path so it will override equivalent classes in user.jar.
  - 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 screens, actions and form components this way.

### Extension points

install4j provides three extension points: screens, actions and form components. Please see the corresponding package overview for more information:

- com.install4j.api.screens package
- com.install4j.api.actions package
- com.install4j.api.formcomponents package

### Internationalization

install4j offers custom localization files in the install4j IDE to localize your own messages. `com.install4j.api.context.Context.getMessage(String key)` gives access to all messages.

If you develop your own user-configurable screens, actions or form components, you can replace all custom localization keys and installer variables in property values with calls to the `com.install4j.api.beans.AbstractBean.replaceVariables(...)` methods. All abstract base classes for beans extend `com.install4j.api.beans.AbstractBean`.

The locale of the installer will always be set to the language selected by the user or configured for the media file, not the locale of the system that the installer is running on. You can query `com.install4j.api.context.Context.getLanguageId()` to find out what language your installer is running with.