Interface Context

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void addInstallerEventListener​(InstallerEventListener listener)
      Add a listener to receive installer events.
      void addToClassPath​(java.io.File file)
      Add a JAR file or a classpath directory root to the classpath of the installer application.
      void cancel()
      Cancel the installer application without asking any questions.
      void finish​(int exitCode)
      Quits the process in an ordered manner.
      Action getActionById​(java.lang.String id)
      Get a particular action with the specified ID.
      Action[] getActions​(Screen screen)
      Get all registered actions for a specified screen.
      Action[] getActions​(java.lang.Class<? extends Action> actionClass, Screen screen)
      Get all registered actions for a specified screen and a given action class.
      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.
      java.lang.String getApplicationName()
      Returns the name of the application.
      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 getContentDirectory()
      Retrieves the directory that is mapped to the "Installation directory" in the distribution tree.
      java.io.File getDefaultInstallationDirectory()
      Retrieves the default installation directory configured in the install4j IDE.
      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.
      java.io.File getExternalFile​(LocalizedExternalFile localizedExternalFile, boolean installedLocation)
      Get the location of a localized external file that was packaged with the installer.
      java.lang.String[] getExtraCommandLineArguments()
      Returns an array with the command line arguments that were not recognized by install4j.
      FileSetSetup getFileSetById​(java.lang.String id)
      Returns the file set for a specified ID.
      FileSetSetup getFileSetByName​(java.lang.String name)
      Returns one file set with the specified name.
      java.util.Collection<FileSetSetup> getFileSets()
      Returns all additional files sets contained in this installer.
      Action getFirstAction​(java.lang.Class<? extends Action> 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.
      java.lang.String getId​(Action action)
      Get the ID that the framework associates with an action.
      java.lang.String getId​(Screen screen)
      Get the ID that the framework associates with a screen.
      InstallationComponentSetup getInstallationComponentById​(java.lang.String id)
      Returns the installation component for a specified ID.
      java.util.Collection<InstallationComponentSetup> 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<LauncherSetup> getLaunchers()
      Returns all launchers for this installer.
      java.lang.String getMediaFileId()
      Returns the ID of the media file that was used to create this installer.
      java.lang.String getMessage​(java.lang.String key)
      Get a message for a localization key.
      java.lang.String getMessage​(java.lang.String key, java.lang.Object... arguments)
      Get a message for a localization key.
      ProgressInterface getProgressInterface()
      Get the current progress interface.
      java.io.File getResourceDirectory()
      Retrieves the directory where the resource files are present that have been configured on the Installer->Custom Code &Resources tab.
      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<java.lang.String> getVariableNames()
      Get the names of all defined installer variables.
      java.lang.String getVersion()
      Returns the version of the installer.
      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 without checking the condition of the target screen or executing any actions.
      void gotoScreen​(Screen screen, boolean checkCondition, boolean executeActions)
      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 hasBeenElevated()
      Returns if the code is running in the elevated helper process started by the "Request privileges" action.
      void initializeLazilyCreatedScreens()
      Initialize all lazily created screens.
      boolean isArchive()
      Returns whether the media set was an archive as opposed to an installer.
      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 isErrorOccurred()
      Determine if an error has occurred for any of the previous actions.
      boolean isGui()
      Returns whether the installer or uninstaller is running in GUI mode.
      boolean isRebootRequired()
      Returns whether a reboot is required on Windows.
      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 registerResponseFileComment​(java.lang.String variableName, java.lang.String comment)
      Register a comment for a variable that is written to the response 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.io.Serializable runElevated​(RemoteCallable remoteCallable, boolean alwaysExecute)
      Execute an remoteCallable with full admin rights if possible.
      java.lang.Object runScript​(ScriptProperty scriptProperty, Bean bean, java.lang.Object... parameters)
      Run a script.
      java.io.Serializable runUnelevated​(RemoteCallable remoteCallable)
      Execute an remoteCallable with the rights of the original user that started the installer.
      void runWithSuspendedActions​(java.lang.Runnable runnable)
      Execute some code while any running actions are suspended.
      void setErrorOccurred​(boolean errorOccurred)
      Clear or set the error flag that is described for isErrorOccurred.
      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.
      void unregisterResponseFileVariable​(java.lang.String variableName)
      Reverses the action of registerResponseFileVariable(String).
    • 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. This method is equivalent to getMessage(String, Object[]) with the arguments parameter set to null.
        Parameters:
        key - the localization key
        Returns:
        the message
        Throws:
        java.util.MissingResourceException - if the key cannot be found
        See Also:
        getMessage(String, Object[])
      • getMessage

        java.lang.String getMessage​(java.lang.String key,
                                    java.lang.Object... arguments)
                             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

        The message is passed to

        
         java.text.MessageFormat.format(message, arguments)
         
        which replaces variables of the form {0} that are embedded in the message key.
        Parameters:
        key - the localization key
        arguments - the arguments as processed by the java.text.MessageFormat class. Can be null.
        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. Note that on macOS this is usually /Applications. If you delete this directory, it will have catastrophic consequences on macOS. To get the directory where files are installed in a cross-platform way, please use getContentDirectory() instead.
        Returns:
        the installation directory
      • getDefaultInstallationDirectory

        java.io.File getDefaultInstallationDirectory()
        Retrieves the default installation directory configured in the install4j IDE. If "Detect previous installation directory" is selected on the "Installer->Update options" tab, the value returned by getInstallationDirectory() may not be the same as the one configured in the install4j IDE. If you need to fall back to the default directory for some reason, you can use the return value of this method and call InstallerContext.setInstallationDirectory(File).
        Returns:
        the default installation directory as configured in the install4j IDE
      • getContentDirectory

        java.io.File getContentDirectory()
        Retrieves the directory that is mapped to the "Installation directory" in the distribution tree. On Windows, Linux and Unix, this is the same as getInstallationDirectory(). For single bundle installers on macOS, this is [Bundle name].app/Contents/Resources/app/. To reference an installed file in a cross-platform way, use this method and not getInstallationDirectory().
        Returns:
        the installation directory
      • getResourceDirectory

        java.io.File getResourceDirectory()
        Retrieves the directory where the resource files are present that have been configured on the Installer->Custom Code &Resources tab.
        Returns:
        the resources 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.
      • isGui

        boolean isGui()
        Returns whether the installer or uninstaller is running in GUI mode.
        Returns:
        true or false.
      • isArchive

        boolean isArchive()
        Returns whether the media set was an archive as opposed to an installer.
        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.
      • gotoScreen

        void gotoScreen​(Screen screen,
                        boolean checkCondition,
                        boolean executeActions)
                 throws NotSupportedInElevationException
        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.
        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.
        Throws:
        NotSupportedInElevationException - if this method is called by an elevated action
        See Also:
        getScreens(), getScreens(Class), getFirstScreen(Class)
      • getScreenById

        Screen getScreenById​(java.lang.String id)
                      throws NotSupportedInElevationException
        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 specified ID exists
        Throws:
        NotSupportedInElevationException - if this method is called by an elevated action
      • getScreens

        Screen[] getScreens()
        Get all registered screens.
        Returns:
        the screens
      • getScreens

        Screen[] getScreens​(java.lang.Class screenClass)
                     throws NotSupportedInElevationException
        Get all registered screens for a given screen class.
        Parameters:
        screenClass - the class of the screen.
        Returns:
        the screens or an empty array if no screen of this class could be found.
        Throws:
        NotSupportedInElevationException - if this method is called by an elevated action
      • getFirstScreen

        Screen getFirstScreen​(java.lang.Class screenClass)
                       throws NotSupportedInElevationException
        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) should be used.
        Parameters:
        screenClass - the class of the screen.
        Returns:
        the screen or null if no screen of this class could be found.
        Throws:
        NotSupportedInElevationException - if this method is called by an elevated action
        See Also:
        getScreens(Class)
      • getActionById

        Action getActionById​(java.lang.String id)
                      throws NotSupportedInElevationException
        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 specified ID exists
        Throws:
        NotSupportedInElevationException - if this method is called by an elevated action
      • getActions

        Action[] getActions​(Screen screen)
                     throws NotSupportedInElevationException
        Get all registered actions for a specified screen.
        Parameters:
        screen - the screen whose associated actions should be returned
        Returns:
        the actions or an empty array if the specified screen has no associated actions.
        Throws:
        NotSupportedInElevationException - if this method is called by an elevated action
      • getActions

        Action[] getActions​(java.lang.Class<? extends Action> actionClass,
                            Screen screen)
                     throws NotSupportedInElevationException
        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 an empty array if no actions of this class could be found for the specified screen.
        Throws:
        NotSupportedInElevationException - if this method is called by an elevated action
      • getFirstAction

        Action getFirstAction​(java.lang.Class<? extends Action> actionClass,
                              Screen screen)
                       throws NotSupportedInElevationException
        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, 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.
        Throws:
        NotSupportedInElevationException - if this method is called by an elevated action
        See Also:
        getActions(Class, Screen)
      • getId

        java.lang.String getId​(Action action)
        Get the ID that the framework associates with an action.

        This is the reverse method of getActionById(String).

        Parameters:
        action - the action whose ID should be returned
        Returns:
        the ID
      • getId

        java.lang.String getId​(Screen screen)
        Get the ID that the framework associates with a screen.

        This is the reverse method of getScreenById(String).

        Parameters:
        screen - the screen whose ID should be returned
        Returns:
        the ID
      • 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. The methods in the wizard context are not functional, if the installer or uninstaller is running in unattended or console mode, in those cases they will do nothing.
        Returns:
        the wizard context.
        Throws:
        NotSupportedInElevationException - if this method is called by an elevated action
      • getFileSets

        java.util.Collection<FileSetSetup> 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 FileSetSetup 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 FileSetSetup or null if the ID doesn't exist.
        See Also:
        FileSetSetup
      • getFileSetByName

        FileSetSetup getFileSetByName​(java.lang.String name)
        Returns one file set with the specified name.
        Parameters:
        name - the name
        Returns:
        the FileSetSetup or null if no file see with this name exists.
        See Also:
        FileSetSetup
      • getInstallationComponents

        java.util.Collection<InstallationComponentSetup> 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<LauncherSetup> 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.
      • cancel

        void cancel()
        Cancel the installer application without asking any questions. Rollback of already executed actions will be performed.

        If a question has to be asked first, use runWithSuspendedActions(Runnable) and call this method from the Runnable.

      • runWithSuspendedActions

        void runWithSuspendedActions​(java.lang.Runnable runnable)
        Execute some code while any running actions are suspended. Actions are only suspended when they check whether the installer is being cancelled, so the currently executing action may not be suspended immediately. It makes sense to call this method as a reaction to an external event, such as a click on a button. For example, you can then ask the user whether the installer application should be canceled and if yes, call cancel() in the Runnable.
        Parameters:
        runnable - the code that will be executed while the actions are suspended
      • 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(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(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 variable value equals java.lang.Boolean.TRUE 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<java.lang.String> 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
        Returns:
        the result of the script or null if the return 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)
                throws NotSupportedInElevationException
        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.
        Throws:
        NotSupportedInElevationException - if this method is called by an elevated action
      • goBack

        void goBack​(int numberOfScreens)
             throws NotSupportedInElevationException
        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. You can pass 0 to return to the current screen from an action.
        Throws:
        NotSupportedInElevationException - if this method is called by an elevated action
        See Also:
        goBackInHistory(int)
      • goBackInHistory

        void goBackInHistory​(int numberOfScreens)
                      throws NotSupportedInElevationException
        Go backwards in the screen history. This is not necessarily the same as the screen sequence, since the screen flow 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. You can pass 0 to return to the current screen from an action.
        Throws:
        NotSupportedInElevationException - if this method is called by an elevated action
        See Also:
        goBack(int)
      • goBackInHistory

        void goBackInHistory​(Screen targetScreen)
                      throws NotSupportedInElevationException
        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.
        Throws:
        NotSupportedInElevationException - if this method is called by an elevated action
        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
      • getExternalFile

        java.io.File getExternalFile​(LocalizedExternalFile localizedExternalFile,
                                     boolean installedLocation)
        Get the location of a localized external file that was packaged with the installer. This will return file for the selected language as given by getLanguageId(). If no suitable localization exists, the file for the principal language is returned. The remaining behavior of this method is identical to getExternalFile(ExternalFile, boolean).
        Parameters:
        localizedExternalFile - the value of the LocalizedExternalFile 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
      • isErrorOccurred

        boolean isErrorOccurred()
        Determine if an error has occurred 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 setErrorOccurred 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.setErrorOccurred(false) in order to clear any earlier error.

        Returns:
        if an error has occurred or not
        See Also:
        setErrorOccurred(boolean)
      • setErrorOccurred

        void setErrorOccurred​(boolean errorOccurred)
        Clear or set the error flag that is described for isErrorOccurred.
        Parameters:
        errorOccurred - the new error flag
        See Also:
        isErrorOccurred()
      • registerResponseFileVariable

        void registerResponseFileVariable​(java.lang.String variableName)
        Register a variable that should be written to the response file when the installation is finished. Variables to which form components are bound are automatically registered as response file variables. Only strings, primitive wrappers, as well as string arrays, int arrays and java.util.Date values can be encoded in the response file.
        Parameters:
        variableName - the variable name
      • unregisterResponseFileVariable

        void unregisterResponseFileVariable​(java.lang.String variableName)
        Reverses the action of registerResponseFileVariable(String). This also works for system installer variables that are written to the response file
        Parameters:
        variableName - the variable name
      • registerResponseFileComment

        void registerResponseFileComment​(java.lang.String variableName,
                                         java.lang.String comment)
        Register a comment for a variable that is written to the response file. The comment can be a multi-line string. If non-empty lines do not start with a # character, the # character is prepended. Compiler variables, installer variables and i18n variables are replaced in the comment string.
        Parameters:
        variableName - the variable name
        comment - the comment. Setting a comment to null, removes the comment.
        See Also:
        registerResponseFileVariable(String)
      • 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.
      • isRebootRequired

        boolean isRebootRequired()
        Returns whether a reboot is required on Windows.
        Returns:
        if a reboot is required or not
      • finish

        void finish​(int exitCode)
        Quits the process in an ordered manner. All changes will be retained.
        Parameters:
        exitCode - the exit code.
      • hasBeenElevated

        boolean hasBeenElevated()
        Returns if the code is running in the elevated helper process started by the "Request privileges" action. In this case the code has full privileges, but it can interact with the GUI is a limited way and some methods in this context will throw a NotSupportedInElevationException.
        Returns:
        true if elevated
      • runElevated

        java.io.Serializable runElevated​(RemoteCallable remoteCallable,
                                         boolean alwaysExecute)
        Execute an remoteCallable with full admin rights if possible. If the current process has full admin rights the remoteCallable is executed in-process. Otherwise, if a 'require admin user' action and macOS or Windows Vista and higher has spawned a helper process with full rights it is executed by this process.

        Note: Do not interact with the GUI or call methods like Util.showMessage(String) in the code.

        Parameters:
        remoteCallable - the remoteCallable to execute
        alwaysExecute - also execute the remoteCallable if it cannot be executed with full admin rights.
        Returns:
        the object returned by RemoteCallable.execute()
      • runUnelevated

        java.io.Serializable runUnelevated​(RemoteCallable remoteCallable)
        Execute an remoteCallable with the rights of the original user that started the installer. If no elevation has been done by the 'require admin user' action the remoteCallable is executed in-process. Otherwise, it is executed by the original process.

        Note: Do not interact with the GUI or call methods like Util.showMessage(String) in the code.

        Parameters:
        remoteCallable - the remoteCallable to execute
        Returns:
        the object returned by RemoteCallable.execute()
      • initializeLazilyCreatedScreens

        void initializeLazilyCreatedScreens()
        Initialize all lazily created screens. Screens provided by install4j are not created lazily, so this method only has an effect, if you have custom screens that return true from Screen.isCreateLazily().
      • addToClassPath

        void addToClassPath​(java.io.File file)
        Add a JAR file or a classpath directory root to the classpath of the installer application. This method if useful if you have lazily created custom screens in your project and you have to add installed JAR files to the classpath before the Screen.createComponent() is called.
        Parameters:
        file - the JAR file or the classpath directory root
        See Also:
        Screen.isCreateLazily()
      • getExtraCommandLineArguments

        java.lang.String[] getExtraCommandLineArguments()
        Returns an array with the command line arguments that were not recognized by install4j. The arguments are in the same order as specified on the command line. The options recognized by install4j are removed.

        This is useful if you want to provide switches for console or unattended installers without resorting to system properties (-Dname=value) or installer variables (-Vname=value).

        Returns:
        the command line arguments
      • getMediaFileId

        java.lang.String getMediaFileId()
        Returns the ID of the media file that was used to create this installer.
        Returns:
        the media file ID
      • getVersion

        java.lang.String getVersion()
        Returns the version of the installer. For installer applications this is the currently installed version.
        Returns:
        the version
      • getApplicationName

        java.lang.String getApplicationName()
        Returns the name of the application. This is the same as the sys.fullName installer variable on which all installer and i18n variables have been replaced.
        Returns:
        the application name