## install4j API documentation

## com.install4j.api.context
Interface Context

All Known Subinterfaces:
  InstallerContext, UninstallerContext

    public interface Context

Base class for installation and uninstallation context. The actual context passed to screens, actions and form components is either an `InstallerContext` or an `UninstallerContext`, depending on whether they are part of the installer or uninstaller.

Author:
  ej-technologies GmbH
See Also:
  `InstallerContext`, `UninstallerContext`

Method Summary
`void` | `addInstallerEventListener(InstallerEventListener listener)` Add a listener to receive installer events.
`Action` | `getActionById(java.lang.String id)` Get a particular action with the specified ID.
`Action[]` | `getActions(java.lang.Class actionClass, Screen screen)` Get all registered actions for a specified screen and a given action class.
`Action[]` | `getActions(Screen screen)` Get all registered actions for a specified screen.
`java.lang.String` | `getAddOnApplicationId()` Returns the add on application id if this project generates add-on installers.
`java.lang.String` | `getApplicationId()` Returns the application id of this project.
`boolean` | `getBooleanVariable(java.lang.String variableName)` Convenience method to get an installer variable with a type of `java.lang.Boolean`.
`java.lang.String` | `getCompilerVariable(java.lang.String variableName)` Gets the value of a compiler variable as it was defined for this media file at compile time.
`java.io.File` | `getDestinationFile(java.io.File archiveFile)` Get the location where the installer will install a file in the distribution tree.
`java.io.File` | `getDestinationFile(java.lang.String archivePath)` Same as `getDestinationFile`, only with a path argument.
`FileInfo` | `getDestinationFileInfo(java.lang.String archivePath)` Analyze a path in the distribution tree.
`java.io.File` | `getExternalFile(ExternalFile externalFile, boolean installedLocation)` Get the location of an external file that was packaged with the installer.
`FileSetSetup` | `getFileSetById(java.lang.String id)` Returns the file set for a specified ID.
`java.util.Collection` | `getFileSets()` Returns all additional files sets contained in this installer.
`Action` | `getFirstAction(java.lang.Class actionClass, Screen screen)` Get the registered action for a specified screen and a given action class.
`Screen` | `getFirstScreen(java.lang.Class screenClass)` Get the registered screen for a given screen class.
`InstallationComponentSetup` | `getInstallationComponentById(java.lang.String id)` Returns the installation component for a specified ID.
`java.util.Collection` | `getInstallationComponents()` Returns all installation components for this installer.
`java.io.File` | `getInstallationDirectory()` Retrieves the installation directory selected by the user, or the default installation directory if the user has not yet made a selection.
`java.lang.String` | `getLanguageId()` Return the ISO code for the language that the installer is running with.
`LauncherSetup` | `getLauncherById(java.lang.String id)` Returns the launcher for a specified ID.
`java.util.Collection` | `getLaunchers()` Returns all launchers for this installer.
`java.lang.String` | `getMessage(java.lang.String key)` Get a message for a localization key.
`ProgressInterface` | `getProgressInterface()` Get the current progress interface.
`Screen` | `getScreenById(java.lang.String id)` Get a particular screen with the specified ID.
`Screen[]` | `getScreens()` Get all registered screens.
`Screen[]` | `getScreens(java.lang.Class screenClass)` Get all registered screens for a given screen class.
`java.lang.Object` | `getVariable(java.lang.String variableName)` Get an installer variable.
`java.util.Set` | `getVariableNames()` Get the names of all defined installer variables.
`WizardContext` | `getWizardContext()` Get the wizard context if the installer or uninstaller is running in GUI mode.
`void` | `goBack(int numberOfScreens)` Go backwards in the screen sequence.
`void` | `goBackInHistory(int numberOfScreens)` Go backwards in the screen history.
`void` | `goBackInHistory(Screen targetScreen)` Go backwards in the screen history to the target screen.
`void` | `goForward(int numberOfScreens, boolean checkCondition, boolean executeActions)` Go forward in the screen sequence.
`void` | `gotoScreen(Screen screen)` Programmatically switch to another screen in the installer.
`void` | `handleCriticalException(java.lang.Throwable e)` If you encounter an exception in your code that cannot be handled, you can use this method to invoke the default exception handling of the install4j runtime.
`boolean` | `isCancelling()` Returns whether the user has cancelled the installation or not.
`boolean` | `isConsole()` Returns whether the installer or uninstaller is running in console mode.
`boolean` | `isErrorOccured()` Determine if an error has occured for any of the previous actions.
`boolean` | `isUnattended()` Returns whether the installer or uninstaller is running in unattended mode.
`void` | `registerHiddenVariable(java.lang.String variableName)` Register a variable whose values should not be written to the installation log file.
`void` | `registerResponseFileVariable(java.lang.String variableName)` Register a variable that should be written to the response file when the installation is finished.
`void` | `removeInstallerEventListener(InstallerEventListener listener)` Remove a listener added with `addInstallerEventListener`.
`java.lang.Object` | `runScript(ScriptProperty scriptProperty, Bean bean, java.lang.Object[] parameters)` Run a script.
`void` | `setErrorOccured(boolean errorOccured)` Clear or set the error flag that is described for `isErrorOccured`.
`void` | `setVariable(java.lang.String variableName, java.lang.Object value)` Set an installer variable.
`void` | `triggerReboot(boolean askUser)` Triggers a reboot at the end of installation or uninstallation on Windows.

Method Detail

### getLanguageId

    java.lang.String getLanguageId()

  Return the ISO code for the language that the installer is running with. If only the principal language has been configured for the installer, this will always be the code for the principal language. If additional languages have been configured, the user can select a language or the language has been automatically determined by the installer, depending on the settings on the "Languages" tab in the install4j GUI. If the installer chooses a language automatically and none of the additional languages matches the system locale, the principal language will be used.

  Returns:
    the ISO code for the language. This code is displayed in brackets after the language name in the install4j GUI.

### getMessage

    java.lang.String getMessage(java.lang.String key)
                                throws java.util.MissingResourceException

  Get a message for a localization key. The key can be either a system key as present in the `resource/messages/messages_*.utf8` files or a key in a custom localization file.

  The search order is

  - custom localization file for actual language
  - custom localization file for principal language
  - system localization file provided by install4j

  Parameters:
    `key` - the localization key
  Returns:
    the message
  Throws:
    `java.util.MissingResourceException` - if the key cannot be found

### getInstallationDirectory

    java.io.File getInstallationDirectory()

  Retrieves the installation directory selected by the user, or the default installation directory if the user has not yet made a selection.

  Returns:
    the installation directory

### isUnattended

    boolean isUnattended()

  Returns whether the installer or uninstaller is running in unattended mode.

  Returns:
    `true` or `false`.

### isConsole

    boolean isConsole()

  Returns whether the installer or uninstaller is running in console mode.

  Returns:
    `true` or `false`.

### getApplicationId

    java.lang.String getApplicationId()

  Returns the application id of this project.

  Returns:
    the application id

### getAddOnApplicationId

    java.lang.String getAddOnApplicationId()

  Returns the add on application id if this project generates add-on installers.

  Returns:
    the add on application id or the empty string if the project generates regular installers.

### addInstallerEventListener

    void addInstallerEventListener(InstallerEventListener listener)

  Add a listener to receive installer events.

  Parameters:
    `listener` - the listener that should be added.

### removeInstallerEventListener

    void removeInstallerEventListener(InstallerEventListener listener)

  Remove a listener added with `addInstallerEventListener`.

  Parameters:
    `listener` - the listener that should be removed.
  See Also:
    `addInstallerEventListener(com.install4j.api.events.InstallerEventListener)`

### gotoScreen

    void gotoScreen(Screen screen)

  Programmatically switch to another screen in the installer. If the given screen has not been registered, the operation will fail. Registered screens can be obtained from the `getScreenById(...)`, `getScreens(...)` and `getFirstScreen(...)` methods.

  Note: This method only has a direct effect when called from a screen. When called from an action, all remaining actions for the screen will be executed and the most recent request for a screen change will then be performed.

  Parameters:
    `screen` - the screen to be activated.
  See Also:
    `getScreens()`, `getScreens(Class)`, `getFirstScreen(Class)`

### getScreenById

    Screen getScreenById(java.lang.String id)

  Get a particular screen with the specified ID. You can display screen IDs in the install4j IDE.

  Parameters:
    `id` - the ID of the screen
  Returns:
    the screens, or `null` if no screen with the spcified ID exists

### getScreens

    Screen[] getScreens()

  Get all registered screens.

  Returns:
    the screens

### getScreens

    Screen[] getScreens(java.lang.Class screenClass)

  Get all registered screens for a given screen class.

  Parameters:
    `screenClass` - the class of the screen.
  Returns:
    the screens or `null` if no screen of this class could be found.

### getFirstScreen

    Screen getFirstScreen(java.lang.Class screenClass)

  Get the registered screen for a given screen class. If multiple screens of the same class are registered, the first occurrence is returned. In that case, `getScreens(Class screenClass)` should be used.

  Parameters:
    `screenClass` - the class of the screen.
  Returns:
    the screen or `null` if no screen of this class could be found.
  See Also:
    `getScreens(Class)`

### getActionById

    Action getActionById(java.lang.String id)

  Get a particular action with the specified ID. You can display action IDs in the install4j IDE.

  Parameters:
    `id` - the ID of the action
  Returns:
    the action, or `null` if no action with the spcified ID exists

### getActions

    Action[] getActions(Screen screen)

  Get all registered actions for a specified screen.

  Parameters:
    `screen` - the screen whose associated actions should be returned
  Returns:
    the actions or `null` if the specified screen has no associated actions.

### getActions

    Action[] getActions(java.lang.Class actionClass,
                        Screen screen)

  Get all registered actions for a specified screen and a given action class.

  Parameters:
    `actionClass` - the class of the action.
    `screen` - the screen whose associated actions should be returned
  Returns:
    the actions or `null` if no actions of this class could be found for the specified screen.

### getFirstAction

    Action getFirstAction(java.lang.Class actionClass,
                          Screen screen)

  Get the registered action for a specified screen and a given action class. If multiple actions of the same class are registered, the first occurrence is returned. In that case, `getActions(Class actionClass, Screen screen)` should be used.

  Parameters:
    `actionClass` - the class of the action.
    `screen` - the screen whose associated action should be returned or `null if all screens should be searched`
  Returns:
    the action or `null` if no action of this class could be found for the specified screen.
  See Also:
    `getActions(Class, com.install4j.api.screens.Screen)`

### getWizardContext

    WizardContext getWizardContext()

  Get the wizard context if the installer or uninstaller is running in GUI mode. The wizard context allows you to modify the installer GUI.

  Returns:
    the wizard context or `null` if the installer or uninstaller is running in unattended or console mode.

### getFileSets

    java.util.Collection getFileSets()

  Returns all additional files sets contained in this installer. If no file sets have been defined in the install4j GUI, the returned collection will be empty. The default file set is not contained in this list and will always be installed by the "Install files" action. The items in the collection will be in the same order as defined in the GUI.

  Returns:
    a collection containing `FileSet` instances.
  See Also:
    `FileSetSetup`

### getFileSetById

    FileSetSetup getFileSetById(java.lang.String id)

  Returns the file set for a specified ID. You can display file set IDs in the install4j IDE.

  Parameters:
    `id` - the ID
  Returns:
    the `FileSet` or `null` if the ID doesn't exist.
  See Also:
    `FileSetSetup`

### getInstallationComponents

    java.util.Collection getInstallationComponents()

  Returns all installation components for this installer. If no installation components have been defined in the install4j GUI, the returned collection will be empty. The items in the collection will be in the same order as defined in the GUI.

  Returns:
    a collection containing `InstallationComponentSetup` instances.
  See Also:
    `InstallationComponentSetup`

### getInstallationComponentById

    InstallationComponentSetup getInstallationComponentById(java.lang.String id)

  Returns the installation component for a specified ID. You can display component IDs in the install4j IDE.

  Parameters:
    `id` - the ID
  Returns:
    the `InstallationComponentSetup` or `null` if the ID doesn't exist.
  See Also:
    `InstallationComponentSetup`

### getLaunchers

    java.util.Collection getLaunchers()

  Returns all launchers for this installer. If no launchers have been defined in the install4j GUI, the returned collection will be empty. The items in the collection will be in the same order as defined in the GUI.

  Returns:
    a collection containing `LauncherSetup` instances.
  See Also:
    `LauncherSetup`

### getLauncherById

    LauncherSetup getLauncherById(java.lang.String id)

  Returns the launcher for a specified ID. The ID of a launcher can be displayed the install4j GUI by invoking Launcher->Show Launcher IDs from the main menu when the Launchers section is active. The method is important for beans that have a property of type `java.lang.String` whose property descriptor has a context of type `CONTEXT_LAUNCHER_ID`. The property will contain a launcher id that can be resolved at runtime with this method.

  Parameters:
    `id` - the ID
  Returns:
    the `LauncherSetup` or `null` if the ID doesn't exist.
  See Also:
    `Install4JPropertyDescriptor.CONTEXT_LAUNCHER_ID`

### isCancelling

    boolean isCancelling()

  Returns whether the user has cancelled the installation or not. Long-running actions should check this method frequently to comply with a cancel request from the user.

  Returns:
    `true` or `false`.

### handleCriticalException

    void handleCriticalException(java.lang.Throwable e)

  If you encounter an exception in your code that cannot be handled, you can use this method to invoke the default exception handling of the install4j runtime. An error report will be prepared, the user will be notified and the installer or uninstaller will quit. No rollback will be performed.

  This method is for exceptional circumstances only. Do not call this method if an action fails in an expected way: if you return `false` from an action, its configurable failure strategy can be used to inform the user of the failure and rollback previous actions.

  Parameters:
    `e` - the exception

### getDestinationFile

    java.io.File getDestinationFile(java.io.File archiveFile)

  Get the location where the installer will install a file in the distribution tree. This method is important for actions with properties of type `java.io.File`. The property values will be relative file names and contain encoded information about installation roots. With this method, the installation location can be resolved. Note that the result of this method can change over time as installer variables or the installation directory are changed.

  Parameters:
    `archiveFile` - the relative file in the distribution tree
  Returns:
    the location of the installed file

### getDestinationFile

    java.io.File getDestinationFile(java.lang.String archivePath)

  Same as `getDestinationFile`, only with a path argument.

  Parameters:
    `archivePath` - the relative path in the distribution tree
  Returns:
    the location of the installed file
  See Also:
    `getDestinationFile(java.io.File)`

### getDestinationFileInfo

    FileInfo getDestinationFileInfo(java.lang.String archivePath)

  Analyze a path in the distribution tree. Beans with `java.io.File` properties can use this method to split paths into root information and relative information and to resolve the installation location of a file in the distribution tree. The `getDestinationFile(..)` methods directly give you the installed file location.

  Parameters:
    `archivePath` - the relative path in the distribution tree
  Returns:
    the `FileInfo` information object
  See Also:
    `getDestinationFile(java.io.File)`, `getDestinationFile(String)`

### getVariable

    java.lang.Object getVariable(java.lang.String variableName)

  Get an installer variable. In the install4j GUI, installer variables are written as ${installer:variableName}. Please read the help topic on variables in the documentation for more information.

  Parameters:
    `variableName` - the name of the installer variable. Do not use the IDE syntax ${installer:...} for this parameter.
  Returns:
    the variable value or `null` if the variable with the specified name was not defined.
  See Also:
    `setVariable(String, Object)`

### getBooleanVariable

    boolean getBooleanVariable(java.lang.String variableName)

  Convenience method to get an installer variable with a type of `java.lang.Boolean`.

  Parameters:
    `variableName` - the name of the installer variable. Do not use the IDE syntax ${installer:...} for this parameter.
  Returns:
    `true` if the varaible value equals `java.lang.Boolean.TUE` or `false` otherwise (also if the variable has not been defined)
  See Also:
    `getVariable(String)`

### setVariable

    void setVariable(java.lang.String variableName,
                     java.lang.Object value)

  Set an installer variable. Please read the help topic on variables in the documentation for more information.

  Parameters:
    `variableName` - the name of the installer variable. Do not use the IDE syntax ${installer:...} for this parameter.
    `value` - the new variable value
  See Also:
    `getVariable(String)`

### getVariableNames

    java.util.Set getVariableNames()

  Get the names of all defined installer variables. Please read the help topic on variables in the documentation.

  Returns:
    a set of variables names of type `java.lang.String`.
  See Also:
    `getVariable(String)`, `setVariable(String, Object)`

### getCompilerVariable

    java.lang.String getCompilerVariable(java.lang.String variableName)

  Gets the value of a compiler variable as it was defined for this media file at compile time. Compiler variables are defined on the "Compiler variables" tab and can be overridden for each media file. System compiler variables are also available from this method. In the install4j IDE, compiler variables are written as ${compiler:variableName}. Please read the help topic on variables in the documentation for more information.

  Parameters:
    `variableName` - the name of the compiler variable. Do not use the IDE syntax ${compiler:...} for this parameter.
  Returns:
    the variable value or `null` if the variable with the specified name was not defined.

### runScript

    java.lang.Object runScript(ScriptProperty scriptProperty,
                               Bean bean,
                               java.lang.Object[] parameters)
                               throws java.lang.Exception

  Run a script. Beans that have properties of type `com.install4j.api.beans.ScriptProperty` can run these user-defined scripts at runtime with this method. Script properties require a property descriptor in the associated BeanInfo class that contains information about the return type as well as any additional parameters.

  Parameters:
    `scriptProperty` - the value of the script property
    `bean` - the bean that defines the script property
    `parameters` - the additional parameters or `null` if there are no additional parameters
  Returns:
    the result of the script or `null` if the retun type of the script is `void`
  Throws:
    `java.lang.Exception` - Scripts are user-defined and can throw all sorts of exceptions.
  See Also:
    `ScriptPropertyDescriptor`

### getProgressInterface

    ProgressInterface getProgressInterface()

  Get the current progress interface. If called by a screen or form component, this will be a default progress interface where status messages and progress methods do nothing. A screen can replace that default progress interface with a different implementation so that the status messages and progress methods invoked by the associated actions are displayed on the screen. This is done by the "Installation" screen and the customizable "Display progress" screen.

  During rollback, a special rollback dialog will be shown and make its progress interface available through this method.

  Returns:
    the current progress interface
  See Also:
    `Screen.getProgressInterface(ProgressInterface)`

### goForward

    void goForward(int numberOfScreens,
                   boolean checkCondition,
                   boolean executeActions)

  Go forward in the screen sequence.

  Note: This method only has a direct effect when called from a screen. When called from an action, all remaining actions for the screen will be executed and the most recent request for a screen change will then be performed.

  Parameters:
    `numberOfScreens` - the number of screens to move forward. If the resulting index is beyond the last screen, the installer or uninstaller will quit.
    `checkCondition` - if the "Condition expression" of the target screen should be checked or not
    `executeActions` - if the associated actions of the current screen should be performed or not. This parameter has no effect if this method is called from an action.

### goBack

    void goBack(int numberOfScreens)

  Go backwards in the screen sequence. This is the sequence that is displayed on the "Screens" tab in the install4j GUI. You can go backwards in the screen history with the `goBackInHistory` method.

  Note: This method only has a direct effect when called from a screen. When called from an action, all remaining actions for the screen will be executed and the most recent request for a screen change will then be performed.

  Parameters:
    `numberOfScreens` - the number of screens to move backwards. If the resulting index is negative, a `RuntimeException` will be thrown.
  See Also:
    `goBackInHistory(int)`

### goBackInHistory

    void goBackInHistory(int numberOfScreens)

  Go backwards in the screen history. This is not necessarily the same as the screen sequence, since the screenflow can be changed programmatically.

  Note: This method only has a direct effect when called from a screen. When called from an action, all remaining actions for the screen will be executed and the most recent request for a screen change will then be performed.

  Parameters:
    `numberOfScreens` - the number of screens to move backwards in the screen history. If the resulting index is negative, a `RuntimeException` will be thrown.
  See Also:
    `goBack(int)`

### goBackInHistory

    void goBackInHistory(Screen targetScreen)

  Go backwards in the screen history to the target screen. If the given screen has not been registered or was not display previously, the operation will fail. Registered screens can be obtained from the `getScreenById(...)`, `getScreens(...)` and `getFirstScreen(...)` methods.

  Note: This method only has a direct effect when called from a screen. When called from an action, all remaining actions for the screen will be executed and the most recent request for a screen change will then be performed.

  Parameters:
    `targetScreen` - the screen to be activated.
  See Also:
    `getScreens()`, `getScreens(Class)`, `getFirstScreen(Class)`

### getExternalFile

    java.io.File getExternalFile(ExternalFile externalFile,
                                 boolean installedLocation)

  Get the location of an external file that was packaged with the installer. Beans that define properties of type `ExternalFile` can access those files at runtime. When the installer is started, an external file is located in a temporary directory. After the "Install files" action has run, the external file is also copied to the `.install4j` directory in the installation directory.

  Parameters:
    `externalFile` - the value of the `ExternalFile` property
    `installedLocation` - if `true`, this method returns the location in the `.install4j` directory, otherwise the location in the temporary directory is returned. If called in an uninstaller, this argument has no effect and the location in the `.install4j` directory will always be returned.
  Returns:
    the resolved external file

### isErrorOccured

    boolean isErrorOccured()

  Determine if an error has occured for any of the previous actions. After an action fails, this method returns `true`. If the failure strategy of the failed action is configured in such a way that the execution of the installer continues, you might want to react to the error in a subsequent action.

  Note: This error flag is never cleared. You have to clear it manually with the `setErrorOccured` method. If you want to make sure that the error originates in a certain range of actions, you have to add a "Run script" action just before that range and call `context.setErrorOccured(false)` in order to clear any earlier error.

  Returns:
    if an error has occurred or not
  See Also:
    `setErrorOccured(boolean)`

### setErrorOccured

    void setErrorOccured(boolean errorOccured)

  Clear or set the error flag that is described for `isErrorOccured`.

  Parameters:
    `errorOccured` - the new error flag
  See Also:
    `isErrorOccured()`

### registerResponseFileVariable

    void registerResponseFileVariable(java.lang.String variableName)

  Register a variable that should be written to the response file when the installation is finished.

  Parameters:
    `variableName` - the variable name

### registerHiddenVariable

    void registerHiddenVariable(java.lang.String variableName)

  Register a variable whose values should not be written to the installation log file. You can use this method for variables which contain passwords or other information that should not be saved to disk.

  Parameters:
    `variableName` - the variable name

### triggerReboot

    void triggerReboot(boolean askUser)

  Triggers a reboot at the end of installation or uninstallation on Windows.

  Parameters:
    `askUser` - if true, the user will be asked if he wants to perform a reboot.