public interface Context
InstallerContext
or an UninstallerContext
, depending on
whether they are part of the installer or uninstaller.InstallerContext
,
UninstallerContext
Modifier and Type | Method and 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 |
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(java.lang.Class<? extends Action> 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.
|
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 |
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) . |
java.lang.String getLanguageId()
java.lang.String getMessage(java.lang.String key) throws java.util.MissingResourceException
getMessage(String, Object[])
with the arguments
parameter
set to null
.key
- the localization keyjava.util.MissingResourceException
- if the key cannot be foundgetMessage(String, Object[])
java.lang.String getMessage(java.lang.String key, java.lang.Object... arguments) throws java.util.MissingResourceException
resource/messages/messages_*.utf8
files
or a key in a custom localization file.
The search order is
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.key
- the localization keyarguments
- the arguments as processed by the java.text.MessageFormat
class. Can be null
.java.util.MissingResourceException
- if the key cannot be foundjava.io.File getInstallationDirectory()
/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.java.io.File getDefaultInstallationDirectory()
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)
.java.io.File getContentDirectory()
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()
.java.io.File getResourceDirectory()
boolean isUnattended()
true
or false
.boolean isConsole()
true
or false
.boolean isGui()
true
or false
.boolean isArchive()
true
or false
.java.lang.String getApplicationId()
java.lang.String getAddOnApplicationId()
void addInstallerEventListener(InstallerEventListener listener) throws NotSupportedInElevationException
listener
- the listener that should be added.NotSupportedInElevationException
- if this method is called by an elevated actionvoid removeInstallerEventListener(InstallerEventListener listener) throws NotSupportedInElevationException
addInstallerEventListener
.listener
- the listener that should be removed.NotSupportedInElevationException
- if this method is called by an elevated actionaddInstallerEventListener(InstallerEventListener)
void gotoScreen(Screen screen) throws NotSupportedInElevationException
Corresponds to gotoScreen(screen, false, false)
.
screen
- the screen to be activated.NotSupportedInElevationException
- if this method is called by an elevated actiongotoScreen(Screen, boolean, boolean)
void gotoScreen(Screen screen, boolean checkCondition, boolean executeActions) throws NotSupportedInElevationException
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.
screen
- the screen to be activated.checkCondition
- if the "Condition expression" of the target screen should be checked or notexecuteActions
- 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.NotSupportedInElevationException
- if this method is called by an elevated actiongetScreens()
,
getScreens(Class)
,
getFirstScreen(Class)
Screen getScreenById(java.lang.String id) throws NotSupportedInElevationException
id
- the ID of the screennull
if no screen with the specified ID existsNotSupportedInElevationException
- if this method is called by an elevated actionScreen[] getScreens()
Screen[] getScreens(java.lang.Class screenClass) throws NotSupportedInElevationException
screenClass
- the class of the screen.NotSupportedInElevationException
- if this method is called by an elevated actionScreen getFirstScreen(java.lang.Class screenClass) throws NotSupportedInElevationException
getScreens(Class)
should be used.screenClass
- the class of the screen.null
if no screen of this class could be found.NotSupportedInElevationException
- if this method is called by an elevated actiongetScreens(Class)
Action getActionById(java.lang.String id) throws NotSupportedInElevationException
id
- the ID of the actionnull
if no action with the specified ID existsNotSupportedInElevationException
- if this method is called by an elevated actionAction[] getActions(Screen screen) throws NotSupportedInElevationException
screen
- the screen whose associated actions should be returnedNotSupportedInElevationException
- if this method is called by an elevated actionAction[] getActions(java.lang.Class<? extends Action> actionClass, Screen screen) throws NotSupportedInElevationException
actionClass
- the class of the action.screen
- the screen whose associated actions should be returnedNotSupportedInElevationException
- if this method is called by an elevated actionAction getFirstAction(java.lang.Class<? extends Action> actionClass, Screen screen) throws NotSupportedInElevationException
getActions(Class, Screen)
should be used.actionClass
- the class of the action.screen
- the screen whose associated action should be returned or null
if all screens should be searchednull
if no action of this class could be found for the specified screen.NotSupportedInElevationException
- if this method is called by an elevated actiongetActions(Class, Screen)
java.lang.String getId(Action action)
This is the reverse method of getActionById(String)
.
action
- the action whose ID should be returnedjava.lang.String getId(Screen screen)
This is the reverse method of getScreenById(String)
.
screen
- the screen whose ID should be returnedWizardContext getWizardContext()
NotSupportedInElevationException
- if this method is called by an elevated actionjava.util.Collection<FileSetSetup> getFileSets()
FileSetSetup
instances.FileSetSetup
FileSetSetup getFileSetById(java.lang.String id)
id
- the IDFileSetSetup
or null
if the ID doesn't exist.FileSetSetup
FileSetSetup getFileSetByName(java.lang.String name)
name
- the nameFileSetSetup
or null
if no file see with this name exists.FileSetSetup
java.util.Collection<InstallationComponentSetup> getInstallationComponents()
InstallationComponentSetup
instances.InstallationComponentSetup
InstallationComponentSetup getInstallationComponentById(java.lang.String id)
id
- the IDInstallationComponentSetup
or null
if the ID doesn't exist.InstallationComponentSetup
java.util.Collection<LauncherSetup> getLaunchers()
LauncherSetup
instances.LauncherSetup
LauncherSetup getLauncherById(java.lang.String id)
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.id
- the IDLauncherSetup
or null
if the ID doesn't exist.Install4JPropertyDescriptor.CONTEXT_LAUNCHER_ID
boolean isCancelling()
true
or false
.void handleCriticalException(java.lang.Throwable e)
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.
e
- the exceptionjava.io.File getDestinationFile(java.io.File archiveFile)
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.archiveFile
- the relative file in the distribution treejava.io.File getDestinationFile(java.lang.String archivePath)
getDestinationFile
, only with a path argument.archivePath
- the relative path in the distribution treegetDestinationFile(File)
FileInfo getDestinationFileInfo(java.lang.String archivePath)
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.archivePath
- the relative path in the distribution treeFileInfo
information objectgetDestinationFile(File)
,
getDestinationFile(String)
java.lang.Object getVariable(java.lang.String variableName)
variableName
- the name of the installer variable. Do not use the IDE syntax ${installer:...} for this parameter.null
if the variable with the specified name was not defined.setVariable(String, Object)
boolean getBooleanVariable(java.lang.String variableName)
java.lang.Boolean
.variableName
- the name of the installer variable. Do not use the IDE syntax ${installer:...} for this parameter.true
if the variable value equals java.lang.Boolean.TRUE
or false
otherwise
(also if the variable has not been defined)getVariable(String)
void setVariable(java.lang.String variableName, java.lang.Object value)
variableName
- the name of the installer variable. Do not use the IDE syntax ${installer:...} for this parameter.value
- the new variable valuegetVariable(String)
java.util.Set<java.lang.String> getVariableNames()
java.lang.String
.getVariable(String)
,
setVariable(String, Object)
java.lang.String getCompilerVariable(java.lang.String variableName)
variableName
- the name of the compiler variable. Do not use the IDE syntax ${compiler:...} for this parameter.null
if the variable with the specified name was not defined.java.lang.Object runScript(ScriptProperty scriptProperty, Bean bean, java.lang.Object... parameters) throws java.lang.Exception
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.scriptProperty
- the value of the script propertybean
- the bean that defines the script propertyparameters
- the additional parametersnull
if the return type of the script is void
java.lang.Exception
- Scripts are user-defined and can throw all sorts of exceptions.ScriptPropertyDescriptor
ProgressInterface getProgressInterface()
During rollback, a special rollback dialog will be shown and make its progress interface available through this method.
Screen.getProgressInterface(ProgressInterface)
void goForward(int numberOfScreens, boolean checkCondition, boolean executeActions) throws NotSupportedInElevationException
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.
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 notexecuteActions
- 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.NotSupportedInElevationException
- if this method is called by an elevated actionvoid goBack(int numberOfScreens) throws NotSupportedInElevationException
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.
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.NotSupportedInElevationException
- if this method is called by an elevated actiongoBackInHistory(int)
void goBackInHistory(int numberOfScreens) throws NotSupportedInElevationException
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.
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.NotSupportedInElevationException
- if this method is called by an elevated actiongoBack(int)
void goBackInHistory(Screen targetScreen) throws NotSupportedInElevationException
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.
targetScreen
- the screen to be activated.NotSupportedInElevationException
- if this method is called by an elevated actiongetScreens()
,
getScreens(Class)
,
getFirstScreen(Class)
java.io.File getExternalFile(ExternalFile externalFile, boolean installedLocation)
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.externalFile
- the value of the ExternalFile
propertyinstalledLocation
- 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.java.io.File getExternalFile(LocalizedExternalFile localizedExternalFile, boolean installedLocation)
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)
.localizedExternalFile
- the value of the LocalizedExternalFile
propertyinstalledLocation
- 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.boolean isErrorOccurred()
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.
setErrorOccurred(boolean)
void setErrorOccurred(boolean errorOccurred)
isErrorOccurred
.errorOccurred
- the new error flagisErrorOccurred()
void registerResponseFileVariable(java.lang.String variableName)
java.util.Date
values
can be encoded in the response file.variableName
- the variable namevoid unregisterResponseFileVariable(java.lang.String variableName)
registerResponseFileVariable(String)
. This also
works for system installer variables that are written to the response filevariableName
- the variable namevoid registerResponseFileComment(java.lang.String variableName, java.lang.String comment)
variableName
- the variable namecomment
- the comment. Setting a comment to null
, removes the comment.registerResponseFileVariable(String)
void registerHiddenVariable(java.lang.String variableName)
variableName
- the variable namevoid triggerReboot(boolean askUser)
askUser
- if true, the user will be asked if he wants to perform a reboot.boolean isRebootRequired()
void finish(int exitCode)
exitCode
- the exit code.boolean hasBeenElevated()
NotSupportedInElevationException
.true
if elevatedjava.io.Serializable runElevated(RemoteCallable remoteCallable, boolean alwaysExecute)
Note: Do not interact with the GUI or call methods like Util.showMessage(String)
in the code.
remoteCallable
- the remoteCallable to executealwaysExecute
- also execute the remoteCallable if it cannot be executed with full admin rights.RemoteCallable.execute()
java.io.Serializable runUnelevated(RemoteCallable remoteCallable)
Note: Do not interact with the GUI or call methods like Util.showMessage(String)
in the code.
remoteCallable
- the remoteCallable to executeRemoteCallable.execute()
void initializeLazilyCreatedScreens()
true
from
Screen.isCreateLazily()
.void addToClassPath(java.io.File file)
Screen.createComponent()
is called.file
- the JAR file or the classpath directory rootScreen.isCreateLazily()
java.lang.String[] getExtraCommandLineArguments()
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).
java.lang.String getMediaFileId()
java.lang.String getVersion()
java.lang.String getApplicationName()
sys.fullName
installer variable on which all installer and i18n variables
have been replaced.