UpdateChecker (install4j API)
Description: declaration: package: com.install4j.api.update, class: UpdateChecker

# Class UpdateChecker

java.lang.Object
com.install4j.api.update.UpdateChecker

public class UpdateChecker extends Object
Utility class to download an update descriptor programmatically from a given URL. In an installer application, it is recommended to use the "Check for update" action instead. This class is mainly intended for checking for updates in your application.

In order to use this class in your application, please include `resource/i4jruntime.jar` from your install4j installation into your class path. You do not need to distribute this file along with your application, install4j will do this automatically for you.

See Also:
  - `UpdateDescriptor`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `UpdateChecker()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static void`
  `executeScheduledUpdate(List<String> updaterArguments, boolean restartLauncher, Runnable shutdownRunnable)`
  If an update is scheduled for installation, execute the update installer and shutdown the current launcher.
  `static void`
  `executeScheduledUpdate(List<String> updaterArguments, boolean restartLauncher, List<String> launcherArguments, Runnable shutdownRunnable)`
  If an update is scheduled for installation, execute the update installer and shutdown the current launcher.
  `static UpdateDescriptor`
  `getUpdateDescriptor(UpdateCheckRequest updateCheckRequest)`
  Download an `updates.xml` file programatically from a given URL and returns an `UpdateDescriptor` instance.
  `static UpdateDescriptor`
  `getUpdateDescriptor(String urlSpec, ApplicationDisplayMode displayMode)`
  Convenience method for `getUpdateDescriptor(UpdateCheckRequest)`.
  `static UpdateDescriptor`
  `getUpdateDescriptor(String urlSpec, ApplicationDisplayMode displayMode, ErrorHandlingCallback errorHandlingCallback)`
  Convenience method for `getUpdateDescriptor(UpdateCheckRequest)`.
  `static boolean`
  `isUpdateScheduled()`
  Checks if the "Schedule update installation" action has registered a downloaded update for installation.
  `static boolean`
  `isVersionGreaterThan(String expectedHigherVersion, String expectedLowerVersion)`
  Compares two version strings and checks if the first version is greater than the second version.
  `static boolean`
  `isVersionLessThanOrEqual(String expectedLowerVersion, String expectedHigherVersion)`
  Compares two version strings and checks if the first version is lower or equal than the second version.

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### UpdateChecker

    public UpdateChecker()

- ## Method Details

  - ### getUpdateDescriptor

    public static UpdateDescriptor getUpdateDescriptor(String urlSpec, ApplicationDisplayMode displayMode) throws UserCanceledException, IOException
    Convenience method for `getUpdateDescriptor(UpdateCheckRequest)`.
    Parameters:
      `urlSpec` - see `UpdateCheckRequest.urlSpec(String)`
      `displayMode` - see `UpdateCheckRequest.applicationDisplayMode(ApplicationDisplayMode)`
    Throws:
      `UserCanceledException` - if the user cancels the proxy dialog
      `IOException` - if the download fails

  - ### getUpdateDescriptor

    public static UpdateDescriptor getUpdateDescriptor(String urlSpec, ApplicationDisplayMode displayMode, ErrorHandlingCallback errorHandlingCallback) throws UserCanceledException, IOException
    Convenience method for `getUpdateDescriptor(UpdateCheckRequest)`.
    Parameters:
      `urlSpec` - see `UpdateCheckRequest.urlSpec(String)`
      `displayMode` - see `UpdateCheckRequest.applicationDisplayMode(ApplicationDisplayMode)`
      `errorHandlingCallback` - see `UpdateCheckRequest.errorHandlingCallback(ErrorHandlingCallback)`
    Throws:
      `UserCanceledException` - if the user cancels the proxy dialog
      `IOException` - if the download fails

  - ### getUpdateDescriptor

    public static UpdateDescriptor getUpdateDescriptor(UpdateCheckRequest updateCheckRequest) throws UserCanceledException, IOException
    Download an `updates.xml` file programatically from a given URL and returns an `UpdateDescriptor` instance. The `UpdateCheckRequest` specifies the URL and other connection options.
    Parameters:
      `updateCheckRequest` - the update check request
    Returns:
      the update descriptor
    Throws:
      `UserCanceledException` - if the user cancels the proxy dialog
      `IOException` - if the download fails

  - ### isUpdateScheduled

    public static boolean isUpdateScheduled()
    Checks if the "Schedule update installation" action has registered a downloaded update for installation. This method returns `false` if the update won't be currently executed because of a failed previous installation or because the installer is currently running. If an update fails or is canceled, it will be rescheduled after 24 hours. The number of times the rescheduling happens can be configured with the "Schedule update installation" action.
    Returns:
      `true` if scheduled and ready to be executed

  - ### executeScheduledUpdate

    public static void executeScheduledUpdate(List<String> updaterArguments, boolean restartLauncher, Runnable shutdownRunnable)
    If an update is scheduled for installation, execute the update installer and shutdown the current launcher.

    Equivalent to calling `executeScheduledUpdate(List, boolean, List, Runnable)` with `null` for the `launcherArguments` parameter

    Parameters:
      `updaterArguments` - updaterArguments to be passed to the updater.
      `restartLauncher` - if `true` a GUI or a console launcher will be restarted after the installation. If called from a service launcher, the installer must take care of starting the service again. It can use `context.getBooleanVariable("sys.automaticUpdate")` if restart should be done conditionally.
      `shutdownRunnable` - if you want to invoke a custom routine for shutting down the current JVM, you can pass in a `Runnable`. Otherwise, `System.exit(0)` will be called. If you pass in a Runnable, you must call `System.exit` at the end of your shutdown procedure.

  - ### executeScheduledUpdate

    public static void executeScheduledUpdate(List<String> updaterArguments, boolean restartLauncher, List<String> launcherArguments, Runnable shutdownRunnable)
    If an update is scheduled for installation, execute the update installer and shutdown the current launcher.
    Parameters:
      `updaterArguments` - updaterArguments to be passed to the updater.
      `restartLauncher` - if `true` a GUI or a console launcher will be restarted after the installation. If called from a service launcher, the installer must take care of starting the service again. It can use `context.getBooleanVariable("sys.automaticUpdate")` if restart should be done conditionally.
      `launcherArguments` - if `restartLauncher` is `true` and this method is called within a GUI or a console launcher, the given arguments will be passed to the restarted launcher
      `shutdownRunnable` - if you want to invoke a custom routine for shutting down the current JVM, you can pass in a `Runnable`. Otherwise, `System.exit(0)` will be called. If you pass in a Runnable, you must call `System.exit` at the end of your shutdown procedure.

  - ### isVersionLessThanOrEqual

    public static boolean isVersionLessThanOrEqual(String expectedLowerVersion, String expectedHigherVersion)
    Compares two version strings and checks if the first version is lower or equal than the second version. This implementation is used by `UpdateDescriptor.getPossibleUpdateEntry()` and `UpdateDescriptorEntry.checkVersionCompatible(String)` to check the compliance with the range of the minimum and maximum updatable version.
    Parameters:
      `expectedLowerVersion` - the version that is expected to be lower or equal
      `expectedHigherVersion` - the version that is expected to be higher or equal
    Returns:
      `true` if `expectedHigherVersion` is higher or equal than `expectedLowerVersion`

  - ### isVersionGreaterThan

    public static boolean isVersionGreaterThan(String expectedHigherVersion, String expectedLowerVersion)
    Compares two version strings and checks if the first version is greater than the second version. This implementation is used by `UpdateDescriptor.getPossibleUpdateEntry()` and `UpdateDescriptorEntry.checkVersionCompatible(String)` to check if a new version is greater than the installed version.
    Parameters:
      `expectedHigherVersion` - the version that is expected to be higher
      `expectedLowerVersion` - the version that is expected to be lower
    Returns:
      `true` if `expectedHigherVersion` is higher than `installedVersion`