Module org.update4j
Package org.update4j.service

Interface UpdateHandler

All Superinterfaces:
Injectable, Service
All Known Implementing Classes:
DefaultUpdateHandler
public interface UpdateHandler extends Service
An implementation of this interface can be used to get callbacks on all stages of the update process.

The order of the method invocation are precisely as follows:

For more info how to use services, check out the GitHub Wiki.

Author:
Mordechai Meisels

  • Method Details

    • init

      default void init​(UpdateContext context) throws Throwable
      Called after injection (see Configuration.update(Injectable)) but before anything update related has started.

      To do any initialization before injection, do it in the constructor, but be aware that unless you specify the handler in the updateHandler section of the configuration, the constructor might be called even if this provider will not be used in the end. This happens as the service loading mechanism first loads all providers and then compares versions to use the one with the highest version.

      You can use the UpdateContext to get information or the current state of the update process, any time. Its values are updated along the process to reflect any change.

      Parameters:
      context - Check the state of the update with this object.
      Throws:
      Throwable - Freely throw any exception, it will gracefully terminate the update process and revert any file changes.

    • startCheckUpdates

      default void startCheckUpdates() throws Throwable
      Called after init(UpdateContext), just before starting to check for updates.
      Throws:
      Throwable - Freely throw any exception, it will gracefully terminate the update process and revert any file changes.

    • shouldCheckForUpdate

      default boolean shouldCheckForUpdate​(FileMetadata file)
      Do your own logic here to decide whether a particular file should be updated. The default implementation returns true for every file.

      This method is called before checking if the file is outdated.

      Parameters:
      file - The file to probe if it should be checked for updates.
      Throws:
      Throwable - Freely throw any exception, it will gracefully terminate the update process and revert any file changes.

    • startCheckUpdateFile

      default void startCheckUpdateFile​(FileMetadata file) throws Throwable
      Called before this individual file is checked if it is outdated.
      Parameters:
      file - The file that will soon be checked if outdated.
      Throws:
      Throwable - Freely throw any exception, it will gracefully terminate the update process and revert any file changes.

    • doneCheckUpdateFile

      default void doneCheckUpdateFile​(FileMetadata file, boolean requires) throws Throwable
      Checking if this file requires an update is complete, and UpdateContext.getRequiresUpdate() was updated to include this file.
      Parameters:
      file - The file that was just checked.
      requires - Whether this file in fact requires an update.
      Throws:
      Throwable - Freely throw any exception, it will gracefully terminate the update process and revert any file changes.

    • updateCheckUpdatesProgress

      default void updateCheckUpdatesProgress​(float frac) throws Throwable
      Updates the 'check update' task progress. Called once for every file in the config. It will be called the first time with the value 0f.

      The value is based on bytes of all files in the config, not file count.

      Parameters:
      frac - A value from 0f to 1f representing the percent of the job done.
      Throws:
      Throwable - Freely throw any exception, it will gracefully terminate the update process and revert any file changes.

    • doneCheckUpdates

      default void doneCheckUpdates() throws Throwable
      All files were passed for an update check (or not, if shouldCheckForUpdate(FileMetadata) returned false) and the UpdateContext.getRequiresUpdate() is up-to-date.
      Throws:
      Throwable - Freely throw any exception, it will gracefully terminate the update process and revert any file changes.

    • startDownloads

      default void startDownloads() throws Throwable
      If there are any files that need an update, this method will get called once.
      Throws:
      Throwable - Freely throw any exception, it will gracefully terminate the update process and revert any file changes.

    • openDownloadStream

      default InputStream openDownloadStream​(FileMetadata file) throws Throwable
      Do any logic to obtain an InputStream for this file. You can do all kinds of interesting stuff here, as accessing authenticated API, use different protocols (as old-fashioned sockets if you really prefer) etc.

      Do not read anything from the stream, just return a newly opened stream and let the framework do the rest.

      By default it will try to access the file from FileMetadata.getUri() assuming it is openly available without any authentication.

      Parameters:
      file - The file to get an input stream for.
      Returns:
      The newly opened input stream, unread.
      Throws:
      Throwable - Freely throw any exception, it will gracefully terminate the update process and revert any file changes.

    • startDownloadFile

      default void startDownloadFile​(FileMetadata file) throws Throwable
      Called once for every file that requires an update, just before the connection is established.
      Parameters:
      file - The file that will now be downloaded.
      Throws:
      Throwable - Freely throw any exception, it will gracefully terminate the update process and revert any file changes.

    • updateDownloadFileProgress

      default void updateDownloadFileProgress​(FileMetadata file, float frac) throws Throwable
      Called repeatedly, updating the frac value to reflect the state of the download of this individual file. It will be called the first time with the value 0f.

      You can observe the remote server latency, by comparing the time between startDownloadFile(FileMetadata) and this method with the value of 0f.

      Parameters:
      file - The file currently being downloaded.
      frac - A value from 0f to 1f representing the percent of the job done.
      Throws:
      Throwable - Freely throw any exception, it will gracefully terminate the update process and revert any file changes.

    • updateDownloadProgress

      default void updateDownloadProgress​(float frac) throws Throwable
      Called repeatedly, updating the frac value to reflect the overall state of the download of all files. It will be called the first time with the value 0f.
      Parameters:
      frac - A value from 0f to 1f representing the percent of the job done.
      Throws:
      Throwable - Freely throw any exception, it will gracefully terminate the update process and revert any file changes.

    • validatingFile

      default void validatingFile​(FileMetadata file, Path path) throws Throwable
      The file was successfully downloaded and is now about to be passed through a series of validations.

      You can do your own validations here using the tempFile to read the actual file. Throw an exception to fail the download in case of validation fail.

      Parameters:
      file - The file about to be passing through validations.
      path - The actual file, only moved to its final location once all downloads succeed. In archive-based updates, the path is inside the archive.
      Throws:
      Throwable - Freely throw any exception, it will gracefully terminate the update process and revert any file changes.

    • doneDownloadFile

      default void doneDownloadFile​(FileMetadata file, Path path) throws Throwable
      The file was successfully downloaded to path and UpdateContext.getUpdated() was already updated to reflect this.

      The file will only be placed in its final location once all files successfully download. In archive-based updates the path is inside the archive.

      Parameters:
      file - The file that just completed download
      path - The temporary location of the file, only moved to its final location once all downloads succeed. In archive-based updates, the path is inside the archive.
      Throws:
      Throwable - Freely throw any exception, it will gracefully terminate the update process and revert any file changes.

    • doneDownloads

      default void doneDownloads() throws Throwable
      If the update was a regular — non-temp — update: All downloads completed and all temporary files were moved to its final location. If an exception is thrown in this method, the new files remain untouched and failed(Throwable) will be called.

      If the update was a temp update: All downloads completed and reside in their temporary location. If an exception is thrown in this method, it will delete the update, revert any changes and failed(Throwable) will be called.

      If the update was an archive-based update: The archive is completed and ready to be installed.

      This method will only be called if there were actually files that required updates.

      Throws:
      Throwable - Any exception will be passed to failed(Throwable) and the update() method will return false.

    • failed

      default void failed​(Throwable t)
      Called when the update process failed.

      If an exception arises in this method, the exception will bubble up to the Configuration.update() method.

      Parameters:
      t - The exception thrown that failed the update process.

    • succeeded

      default void succeeded()
      Called when the update process is complete, even if no files actually required an update.

      If an exception arises in this method, the exception will bubble up to the Configuration.update() method.

    • stop

      default void stop()
      Called just before the Configuration.update() method returns, regardless of the error state (unless an exception was thrown in failed(Throwable) or succeeded()).

      If an exception arises in this method, the exception will bubble up to the Configuration.update() method.

    • getResult

      default Object getResult()
      Called by UpdateResult.result(). If result() is never called, this will never get called either.

      You're free to use any return type, it will automatically be cast to the receiver type of the caller of UpdateResult.result(): 

       // When defining:
 public MyType getResult() {
     return new MyType();
 }
 
 
 // You can do this without a cast:
 MyType myResult = update(...).result();
 
 // But this fails with ClassCastException:
 String str = update(...).result();
      Returns: