com.mmoui.manager.services
Interface Updatable

All Superinterfaces:

UpdateElement

public interface Updatable
extends UpdateElement

Defines a single, downloadable updatable component (such as an addon). Each update process is run in its own thread, so it is not necessary for Updatable implementations to yield control. Minion will handle all Updatable objects as necessary.

The update process is four-stage, though some stages may be skipped depending on configuration and/or results of earlier stages. If an exception is thrown at any stage of the update process, the manager will immediately skip to the cleanup phase.

The following defines the update process as called by the manager:

• Call UpdateElement.initialize(com.mmoui.manager.services.UpdateStatusListener), pass in the UpdateStatusListener which can be used to supply status information back to the manager
• Call getLatestVersion()
• If a new version is available
  • If not configured for auto-update mode, request user confirmation (performed by update manager)
  • If user confirmed or in auto-update mode, call update()
• Call cleanup()

Only the getLatestVersion() and update() methods should rely on connections to remote servers. While this is not enforced and requirements are implementation-specific, this is the recommended best-practice to ensure stability and consistency with other Updatable implementations that may be running.

Updatable objects should perform the bulk of their work in the UpdateElement.update(boolean) method. This includes downloading the current version from the server, extracting it, verifiying it, and installing it to the appropriate location (cleaning up any old version as necessary).

Updatable objects should override the toString() method to provide naming information to the manager. The manager uses this information to automatically display status information to the user.

Version:

$Id: Updatable.java 200 2009-05-11 06:45:38Z mpdelbuono $

Author:

Matthew P. Del Buono

Nested Class Summary

Nested classes/interfaces inherited from interface com.mmoui.manager.services.UpdateElement

UpdateElement.PopupOption, UpdateElement.UpdateCancelledException

Method Summary

java.lang.String	getAuthor() Gets the author's name of this Updatable object
java.net.URL	getDonationURL() Gets a URL at which the user of the application can donate to the author of this Updatable.
java.lang.String	getLatestVersion(boolean useBeta) Gets the latest version available from the server.

Methods inherited from interface com.mmoui.manager.services.UpdateElement

cleanup, getName, getPopupOptions, initialize, interrupt, update

Method Detail

getLatestVersion

java.lang.String getLatestVersion(boolean useBeta)
                                  throws java.io.IOException,
                                         java.lang.InterruptedException

Gets the latest version available from the server.

While not enforced, this Updatable object should NOT attempt to download the package from the server. The actual download should occur during a call to update() to ensure the user has confirmed the download first. This ensures that user bandwidth is not wasted on an item that is not desired.

If the user cancels the update process during a call to getLatestVersion(), this thread will be sent an interruption event. It is the implementation's responsibility to appropriately respond to an interruption either by cleaning up before terminating or by flagging future cleanup work to be performed by a future call to cleanup(). When a cancellation occurs, it is permissible to throw an InterruptedException.

Parameters:

useBeta - true if beta versions should be considered when determining the current version, or false if only stable versions should be considered. This option is implementation-specific and does not need to be implemented if not desired.

Returns:

The version number of the most recent version if an update is available, or null if no update is available. Note that returning the same version string as the current version will trigger a call to update() by the manager, so if an update is not necessary, it is the implementation's resposibility to return null instead of a String object.

Throws:

java.io.IOException - If an I/O exception occurs while attempting to determine the latest version

java.lang.InterruptedException - If the user cancelled the process before it could be completed. Throwing this exception is not required, but is a recommended course of action after maintaining consistency. If the process was cancelled but this exception is not thrown, the update manager will still detect the cancellation and will not call update() unless the interruption was cleared. The interruption must not be cleared by the implementation to ensure consistency. In any case, cleanup() will be called.

See Also:

UpdateElement.update(boolean), UpdateElement.cleanup()

getAuthor

java.lang.String getAuthor()

Gets the author's name of this Updatable object

Returns:

The name of the author of this item, or null if no author information is available for this Updatable object

getDonationURL

java.net.URL getDonationURL()

Gets a URL at which the user of the application can donate to the author of this Updatable. This will cause a small, unobtrusive icon to be displayed, associated with this Updatable, in request for donations. When the user clicks on the icon, the URL will be opened in the default browser.

This method will always be called after getLatestVersion(boolean) returns. Until then, the donation link will be hidden. This allows modules to collect the donation link online if necessary while collecting other information.

Returns:

the URL at which donations can be given, or null if no donation link should be shown

Since:

1.1.1