Introduction

All standard actions, screens and form components in install4j use the installer API themselves. With this API you can create new elements that are displayed in the standard registries by packaging a JAR file with a few special manifest entries and putting that JAR file into the extensions directory of your install4j installation.

Configurability

An extension to install4j will likely need to be configurable by the user. install4j uses the JavaBean specification to control the user presentation of properties in the install4j IDE. Screens, actions, and form components correspond to beans in this context.

Optionally, you can add BeanInfo classes. In essence, a BeanInfo class next to the bean itself describes which properties are editable and optionally gives details on how they should be presented. Please see the documentation of the com.install4j.api.beaninfo package for the complete documentation on how to develop BeanInfo classes. Also, the $INSTALL4J_HOME/samples/customCode/src directory contains a sample action with the associated BeanInfo class.

JAR manifest

In order to tell install4j which classes are screens, actions or form components, you have to use the following manifest keys:

• Install-Action
  for actions implementing com.install4j.api.actions.InstallAction
• Uninstall-Action
  for actions implementing com.install4j.api.actions.UninstallAction
• Installer-Screen
  for screens implementing com.install4j.api.screens.InstallerScreen
• Uninstaller-Screen
  for screens implementing com.install4j.api.screens.UninstallerScreen
• Form-Component
  for form components implementing com.install4j.api.formcomponents.FormComponent
• Style-Component
  for form components implementing com.install4j.api.formcomponents.FormComponent that should also be available in styles. Such form components should not take any user input because they will have a different life-cycle in styles than in screens.

Please note that usually you do not implement these interfaces yourself, but rather extend one of the abstract base classes.

A typical manifest with one action and one screen looks like this:

Depends-On: driver.jar common.jar

Name: com/mycorp/actions/MyAction.class
Install-Action: true

Name: com/mycorp/screens/MyScreen.class
Installer-Screen: true
Uninstaller-Screen: true

Note: If you only have named sections and no global section in your manifest file, the first line must be an empty line since it separates the global keys from the named sections.

The Depends-On manifest key can specify a number of relative JAR files separated by spaces that must be included when the extension is deployed. That key can also occur separately for each named section.

As you see in the example for the screen, each class can have multiple keys if the appropriate interfaces are implemented.

Localization

Extensions can provide localized messages. During development, you can keep these messages in the custom localization file of the project that you use for testing purposes. When packaging the extensions, these custom localization files have to be given special names and be put into a particular location in the extension JAR file.

The names of the extension localization files have to be the same as those of the system localization files in the $INSTALL4J_HOME/resource/messages directory, i.e. messages_en.utf8 and similarly for other languages. The java.util.Properties file encoding is also supported if the file name has a .properties extension, like messages_en.properties.

When creating the extension JAR file, all extension localization files have to be put into the directory messages. No special directives in the manifest are required. Dependencies included with the Depends-On manifest key are not scanned for extension localization files.

Extension deployment

On startup, install4j will scan the manifests of all JAR files that it finds in the $INSTALL4J_HOME/extensions directory. Any screens, actions or form components that are found in the manifests are added to the standard registries. If a bean cannot be instantiated, the exception is printed to stderr which is captured in $INSTALL4J_HOME/bin/error.log and no further error is displayed.

If any of those screens, actions or form components are selected by the user, the required JAR files are deployed with the generated installers. This means that installing extensions does not create an overhead for installers that do not use them.