de.caff.util

## Interface SemanticVersionChecker.ProgramAccess

- Enclosing class:
    SemanticVersionChecker

      public static interface SemanticVersionChecker.ProgramAccess

  Program information necessary for automatic update.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.String[]` | `endWithoutExit()` End the application, but don't exit.
    `SemVer` | `getCurrentVersion()` Get a string describing the current version.
    `java.lang.String` | `getInfoFileUrl()` Get the URL of the file containing version and possibly other information.
    `default java.io.File` | `getOutputJar()` Get the file to which the downloaded jar is written.
    `java.lang.String` | `getPackageUrl(SemVer versionNumber, SemVer oldVersion)` Get the URL of an update zip.
    `java.lang.String` | `getProgramJarName()` Get the base name of the installed jar file.
    `java.lang.String` | `getUpdateUrl(SemVer versionNumber, SemVer oldVersion)` Get the URL of the program jar.
    `boolean` | `isNewerVersion(SemVer version)` Tell whether a given version is newer.
    `default boolean` | `isNewerVersion(java.lang.String version)` Tell whether a given version is newer.
    `boolean` | `isUserOkayDownload(SemVer currentVersion, SemVer newVersion)` Get an okay from the user to download and install a new version.
    `boolean` | `isUserOkayRestart(SemVer currentVersion, SemVer newVersion)` Get an okay from the user to restart the program.
    `default boolean` | `registerRenameShutdownHook(java.io.File tmpFile)` Register a shutdown hook for renaming the temp file where the updated jar is stored to?
    `void` | `showErrorDownloadFailureIO(SemVer currentVersion, SemVer newVersion, java.lang.String url, java.io.IOException exception)` Show an error method that downloading failed because the file could not be downloaded due to i/o problems.
    `void` | `showErrorDownloadFailureNotFound(SemVer currentVersion, SemVer newVersion, java.lang.String url, java.lang.Exception exception)` Show an error method that downloading failed because the file was not accessible.
    `void` | `showInfoNeedRestart(SemVer currentVersion, SemVer newVersion)` Show an info that a restart of the application is necessary in order to run the new version.
    `void` | `showInfoNoUpdatePossible(java.net.URL url, SemVer currentVersion, SemVer newVersion)` Show the HTML content of an URL describing why an update is not possible.
    `default void` | `versionIsCurrent()` Informative callback called when it is determined that there is no newer version available.

- - ### Method Detail

    - #### getCurrentVersion

          @NotNull
          SemVer getCurrentVersion()

      Get a string describing the current version.
      Returns:
        current version as string

    - #### isNewerVersion

          boolean isNewerVersion(@NotNull
                                 SemVer version)

      Tell whether a given version is newer.
      Parameters:
        `version` - possibly newer semantic version
      Returns:
        `true` version is newer than the current version
        `false` version is not new than the current version

    - #### isNewerVersion

          default boolean isNewerVersion(@NotNull
                                         java.lang.String version)

      Tell whether a given version is newer.
      Parameters:
        `version` - possibly newer version, assumed to represent a semantic version
      Returns:
        `true` version is newer than the current version
        `false` version is not new than the current version

    - #### getInfoFileUrl

          @NotNull
          java.lang.String getInfoFileUrl()

      Get the URL of the file containing version and possibly other information.

      The file format is simple. A line starting with a hash character (`#`) is starting a comment. Empty lines are ignored. All other lines have the format
      `TAG: CONTENT`
      where TAG is one of the following

      - `VERSION`: `CONTENT` is the current version number
      - `MINJVM`: `CONTENT` is the minimal version of the JVM necessary to run the program (eg `1.5`)
      - `NOUPDATE[vnr]`: with `vnr` being a version number (meaning exactly this version) or a version number prefixed with a < sign (meaning all versions before the given version), and `CONTENT` being the URL of a HTML file describing the reason why an automatic update for the described versions is not possible.
      Returns:
        URL to info file

    - #### getPackageUrl

          @Nullable
          java.lang.String getPackageUrl(@NotNull
                                                   SemVer versionNumber,
                                                   @NotNull
                                                   SemVer oldVersion)

      Get the URL of an update zip. This is useful when there is more than one file to update, in which case this zip is downloaded and unpacked.
      Parameters:
        `versionNumber` - version number requested.
        `oldVersion` - old version currently running
      Returns:
        update URL or `null` if there is no update possible

    - #### getUpdateUrl

          @Nullable
          java.lang.String getUpdateUrl(@NotNull
                                                  SemVer versionNumber,
                                                  @NotNull
                                                  SemVer oldVersion)

      Get the URL of the program jar. The program jar is the jar necessary for a complete new installation.
      Parameters:
        `versionNumber` - version number requested
        `oldVersion` - number of installed version
      Returns:
        URL of program jar, or `null` if there is no update location, in which case `getPackageUrl(SemVer, SemVer)` should not return `null`

    - #### getProgramJarName

          @NotNull
          java.lang.String getProgramJarName()

      Get the base name of the installed jar file.
      Returns:
        name of installed jar file

    - #### getOutputJar

          @Nullable
          default java.io.File getOutputJar()

      Get the file to which the downloaded jar is written. The default behavior (return `null`) is to overwrite the currently running jar.
      Returns:
        explicit jar output or `null` for the default behavior

    - #### showInfoNoUpdatePossible

          void showInfoNoUpdatePossible(@NotNull
                                        java.net.URL url,
                                        @NotNull
                                        SemVer currentVersion,
                                        @NotNull
                                        SemVer newVersion)

      Show the HTML content of an URL describing why an update is not possible.
      Parameters:
        `url` - URL to show
        `currentVersion` - current version
        `newVersion` - new version

    - #### versionIsCurrent

          default void versionIsCurrent()

      Informative callback called when it is determined that there is no newer version available.

    - #### isUserOkayDownload

          boolean isUserOkayDownload(@NotNull
                                     SemVer currentVersion,
                                     @NotNull
                                     SemVer newVersion)

      Get an okay from the user to download and install a new version.

      Typical question text:
      "A new version of XY is available: "+version+
      "Do you want to download and install it?"

      Parameters:
        `currentVersion` - current version
        `newVersion` - new version
      Returns:
        `true`: install new version
        `false`: don't install new version

    - #### isUserOkayRestart

          boolean isUserOkayRestart(@NotNull
                                    SemVer currentVersion,
                                    @NotNull
                                    SemVer newVersion)

      Get an okay from the user to restart the program.

      Typical question text:
      "The new version "+version+" is now installed."+
      "Would you like to restart?"

      Parameters:
        `currentVersion` - current version
        `newVersion` - new version
      Returns:
        `true`: restart into new version
        `false`: keep running

    - #### showInfoNeedRestart

          void showInfoNeedRestart(@NotNull
                                   SemVer currentVersion,
                                   @NotNull
                                   SemVer newVersion)

      Show an info that a restart of the application is necessary in order to run the new version.

      This is called when it is not possible to do an automatic restart. Typical text:
      " "The new version "+version+" is now installed."+
      "You'll need to restart the program to finish the installation."

      Parameters:
        `currentVersion` - current version
        `newVersion` - new version

    - #### showErrorDownloadFailureNotFound

          void showErrorDownloadFailureNotFound(@NotNull
                                                SemVer currentVersion,
                                                @NotNull
                                                SemVer newVersion,
                                                @NotNull
                                                java.lang.String url,
                                                @NotNull
                                                java.lang.Exception exception)

      Show an error method that downloading failed because the file was not accessible.
      Parameters:
        `currentVersion` - current version
        `newVersion` - new version which was tried to be downloaded
        `url` - URL with which it was tried to download
        `exception` - the exception on which the error is based

    - #### showErrorDownloadFailureIO

          void showErrorDownloadFailureIO(@NotNull
                                          SemVer currentVersion,
                                          @NotNull
                                          SemVer newVersion,
                                          @NotNull
                                          java.lang.String url,
                                          @NotNull
                                          java.io.IOException exception)

      Show an error method that downloading failed because the file could not be downloaded due to i/o problems.
      Parameters:
        `currentVersion` - current version
        `newVersion` - new version which was tried to be downloaded
        `url` - URL with which it was tried to download
        `exception` - the exception on which the error is based

    - #### endWithoutExit

          @Nullable
          java.lang.String[] endWithoutExit()

      End the application, but don't exit.

      This should write all necessary data to disk, and store the preferences, stop all threads no longer necessary and close all windows.

      Returns:
        array of commandline arguments to be provided for the newly started application in order to restore the current state

    - #### registerRenameShutdownHook

          default boolean registerRenameShutdownHook(@NotNull
                                                     java.io.File tmpFile)

      Register a shutdown hook for renaming the temp file where the updated jar is stored to?
      Parameters:
        `tmpFile` - temporary file
      Returns:
        `true`: for automatically taking care
        `false`: the program access itself cares for renaming