Introduction

There are two different circumstances where you might want to use the install4j API: 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 not like to miss 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, 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.

When you want to use install4j classes within your IDE, you can add $INSTALL4J_HOME/resource/i4jruntime.jar to your classpath (in your IDE). Do not distribute this jar file with your application, install4j will handle this for you.

Expression/script properties

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 installer
• com.api.install4j.context.UninstallerContext
  in an uninstaller

The context allows you to query the environment and the configuration of the installer as well as to perform some common tasks.

Please 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 using context.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
  The getVariable(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 include isConsole(), isUnattended() and others.
• Navigating between screens
  Depending on the user selection on a screen, you might want to skip a number of screens. The goForward(...), 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.

Developing custom elements for install4j

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, please see the API overview in the javadoc.

install4j provides three extension points:

• Actions
  Please see the documentation of the com.install4j.api.actions package for the complete documentation on how to develop actions.
• Screens
  Please see the documentation of the com.install4j.api.screens package for the complete documentation on how to develop screens.
• Form components
  Please see the documentation of the com.install4j.api.formcomponents package for the complete documentation on how to develop form components.

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. 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 use your custom code in multiple projects, consider packaging an install4j extension, which displays your custom elements alongside the standard elements that are provided by install4j and allows you to ship them easily to third parties.

Serialization

install4j serializes all instances of screens, actions and form components with the default serialization mechanism for JavaBeans that is present in Java since version 1.4 (the minimum Java version for installers).

To learn more about JavaBeans serialization, please visit

• https://docs.oracle.com/javase/8/docs/api/java/beans/XMLEncoder.html for API documentation on the long-term persistence mechanism for JavaBeans.
• http://www.oracle.com/technetwork/java/persistence4-140124.html/ for information on how to write your own persistence delegates. In your bean infos for screens, actions and form components you can specify a list of additional persistence delegates for non-default types.

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, please see the separate help topic.