There are two different use cases where the install4j API is required: Within expression/script properties in the configuration GUI and for the development of custom elements in install4j. The development of custom elements in install4j is rarely necessary for typical installers, most simple custom actions can be performed with a "Run script" action and most custom forms can be realized with a "Customizable form" screen.
If you would like use your IDE while writing more complex custom code, you can put a single call to custom code into expression/script properties. The location of your custom code classes must be configured on the "Installer->Custom Code & Resources" step, so install4j will package it with the installer and put in into the class path. In this way you can completely avoid the use of the interfaces required to extend install4j.
Using expression/script properties in install4j is required for wiring together screens and actions as well as for the conditional execution of screens and actions. The most important element in this respect is the context which is an instance of
com.api.install4j.context.InstallerContext
in an installercom.api.install4j.context.UninstallerContext
in an uninstallerThe context allows you to query the environment and the configuration of the installer as well as to perform some common tasks.
See the documentation of the com.install4j.api.context package for the complete documentation of all methods in the context. Some common applications include:
Setting the installation directory
By usingcontext.setInstallationDirectory(File installationDirectory)
in the installer context,
you can change the default installation directory for the installer. Typically, this call is placed into a
"Run script" action on the "Startup" screen.
Getting and setting installer variables
ThegetVariable(String variableName)
and setVariable(String variableName, Object value)
methods allow you to query and modify installer variables. Note that besides the "Run script" action, there is also a
"Set a variable action" where you don't have to call setVariable
yourself.
Conditionally executing screens or actions
Often, condition expressions for screens and actions check the values of variables. In addition, the context provides a number of boolean getters that you can use for conditionally executing screens and actions depending on the installer mode and environment. These methods includeisConsole()
, isUnattended()
and others.
Navigating between screens
Depending on the user selection on a screen, you might want to skip a number of screens. ThegoForward(...)
, goBack(...)
and goBackInHistory(...)
methods provide the easiest way to achieve this.
Many other context methods are only useful if you develop custom elements for install4j.
Also have a look at the com.install4j.api.Util
class which offers a number of utility methods
that are useful in expression/script properties.
To develop custom elements in your IDE, you have to add the install4j API to the compilation class path. The entire install4j API is contained in the single artifact with maven coordinates
group: com.install4j artifact: install4j-runtime version: <install4j version>
where the install4j version corresponding to this manual is 8.0.
Jar, source and javadoc artifacts are published to the repository at
https://maven.ej-technologies.com/repository
You can either add the API to your development class path with a build tool like Gradle or Maven, or use the JAR file
resource/i4jruntime.jar
in the install4j installation.
To browse the Javadoc, go to
javadoc/index.html
For a general overview on how to start developing with the install4j API, how to set up your IDE and how to debug your custom elements, see the API overview in the javadoc.
install4j provides four extension points: actions, screens, form components and styles
All actions, screens and form components in install4j use this API themselves. To make your custom elements selectable in the install4j IDE, you first have to configure the custom code locations on the "Installer->Custom Code & resources" step. When you add an action, screen or form component, the first popup gives you the choice on whether to add a standard element or search for suitable elements in your custom code.
If you want to ship your custom code to third parties, consider packaging an install4j extension, which displays your custom elements alongside the standard elements that are provided by install4j and allows you to add dependency JAR files that are included in the installers if any of the contained elements are used in a project.
install4j serializes all instances of screens, actions and form components with the default serialization mechanism for JavaBeans.
To learn more about JavaBeans serialization, visit
Compiler variables are replaced in the serialized representation of a bean. In this way, compiler variable
replacement is automatically available for all properties of type java.lang.String
.
The values of installer variables and localization keys are determined at runtime, so you
have to call the utility methods in com.install4j.api.beans.AbstractBean
before you use the values in the installer or uninstaller.
For more information on variables, see the separate help topic.
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 call com.install4j.api.context.Context.getLanguageId()
to find out what language your installer is running with.
To test and debug screens, actions and form components for your installer, 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
debug_installer.bat
and debug_uninstaller.bat
for Windows media filesdebug_installer.sh
and debug_uninstaller.sh
for media files of Unix based platformsThese scripts 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
com.install4j.runtime.installer.Installer
for the installer or
com.install4j.runtime.installer.Uninstaller
for the uninstaller-Dinstall4j.debug=true
Note that the working directory for the executed java process must be 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.