de.caff.util

Interface SemanticVersionChecker.ProgramAccess

Enclosing class:

SemanticVersionChecker

public static interface SemanticVersionChecker.ProgramAccess

Program information necessary for automatic update.

Method Summary

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