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.
|
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.
|
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.
|
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 |
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
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()
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(java.io.File)
.java.io.File getContentDirectory()
getInstallationDirectory()
.
For single bundle installers on Mac OS X, 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()
boolean isConsole()
boolean isArchive()
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
listener
- the listener that should be removed.NotSupportedInElevationException
- if this method is called by an elevated actionaddInstallerEventListener(com.install4j.api.events.InstallerEventListener)
void gotoScreen(Screen screen) 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.
screen
- the screen to be activated.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 screenNotSupportedInElevationException
- 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
screenClass
- the class of the screen.NotSupportedInElevationException
- if this method is called by an elevated actiongetScreens(Class)
Action getActionById(java.lang.String id) throws NotSupportedInElevationException
id
- the ID of the actionNotSupportedInElevationException
- 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
actionClass
- the class of the action.screen
- the screen whose associated action should be returned or null if all screens should be searchedNotSupportedInElevationException
- if this method is called by an elevated actiongetActions(Class, com.install4j.api.screens.Screen)
WizardContext getWizardContext()
NotSupportedInElevationException
- if this method is called by an elevated actionjava.util.Collection<FileSetSetup> getFileSets()
FileSetSetup
FileSetSetup getFileSetById(java.lang.String id)
id
- the IDFileSetSetup
FileSetSetup getFileSetByName(java.lang.String name)
name
- the nameFileSetSetup
java.util.Collection<InstallationComponentSetup> getInstallationComponents()
InstallationComponentSetup
InstallationComponentSetup getInstallationComponentById(java.lang.String id)
id
- the IDInstallationComponentSetup
java.util.Collection<LauncherSetup> getLaunchers()
LauncherSetup
LauncherSetup getLauncherById(java.lang.String id)
id
- the IDInstall4JPropertyDescriptor.CONTEXT_LAUNCHER_ID
boolean isCancelling()
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)
archiveFile
- the relative file in the distribution treejava.io.File getDestinationFile(java.lang.String archivePath)
archivePath
- the relative path in the distribution treegetDestinationFile(java.io.File)
FileInfo getDestinationFileInfo(java.lang.String archivePath)
archivePath
- the relative path in the distribution treegetDestinationFile(java.io.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.setVariable(String, Object)
boolean getBooleanVariable(java.lang.String variableName)
variableName
- the name of the installer variable. Do not use the IDE syntax ${installer:...} for this parameter.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()
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.java.lang.Object runScript(ScriptProperty scriptProperty, Bean bean, java.lang.Object[] parameters) throws java.lang.Exception
scriptProperty
- the value of the script propertybean
- the bean that defines the script propertyparameters
- the additional parameters or null if there are no additional parametersjava.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
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
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
- 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(com.install4j.api.beans.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()
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)
errorOccurred
- the new error flagisErrorOccurred()
void registerResponseFileVariable(java.lang.String variableName)
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
.java.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()
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()