com.mmoui.manager.services
Interface UpdateElement

All Known Subinterfaces:

Updatable, Uploadable

public interface UpdateElement

Defines a single updatable component for use by an UpdateService. This interface should not be used directly; module authors should instead either implement Updatable or Uploadable (or a combination of the two) for presentation by the UpdateService.

Since:

2.2.0

Version:

$Id: UpdateElement.java 198 2009-05-10 23:30:33Z mpdelbuono $

Author:

Matthew P. Del Buono

See Also:

Updatable, Uploadable

Nested Class Summary

static interface	UpdateElement.PopupOption Defines a single option to be displayed in a JPopupMenu
static class	UpdateElement.UpdateCancelledException Defines an exception that can occur when an update is cancelled.

Method Summary

void	cleanup() Cleans up this UpdateElement object.
java.lang.String	getName() Gets the name of this UpdateElement object for display on the UI
UpdateElement.PopupOption[]	getPopupOptions() Gets the list of options presented to the user when the item is right clicked from within the table, as a JPopupMenu.
void	initialize(UpdateStatusListener listener) Performs local initialization of this UpdateElement object in preparation for update work.
void	interrupt() Interrupts the update process.
void	update(boolean useBeta) Performs the update work required by this UpdateElement.

Method Detail

initialize

void initialize(UpdateStatusListener listener)

Performs local initialization of this UpdateElement object in preparation for update work. The implementation should store the given UpdateStatusListener as it can be used at any point during the update process, but will not be passed to any other methods.

While not enforced, this method should not require any connection to remote servers and should only handle local initialization. Any remote information required to complete initialization should be requested during future calls which request the information explcitly.

Parameters:

listener - The UpdateStatusListener object which can be used to supply status information to the update manager.

update

void update(boolean useBeta)
            throws java.io.IOException,
                   java.lang.InterruptedException

Performs the update work required by this UpdateElement. This is where the majority of the updating work will be performed. This method will be called by the update dispatcher if it has determined that the component should proceed with its update. This method for making this decision is dependent upon the particular type of UpdateElement object implemented.

If an exception is thrown, the manager does not have enough knowledge about the state of this package to perform appropriate cleanup and rollback from any changes that may have occurred prior to the exception. As a result, it is the UpdateElement object's responsibility to clean up prior to throwing an exception (or to schedule cleanup during a future call to cleanup() if necessary).

If the user requests cancellation of this update process, then the thread running this update process may be sent an interrupt event. To respond gracefully, it is the UpdateElement's responsibility to appropriately respond to an interruption. It is permissible to throw an InterruptedException in such a case, however it is the implementation's responsibility to maintain consistency by either cleaning up before throwing the InterruptedException or by flagging required cleanup for a future call to cleanup().

Parameters:

useBeta - true if the absolute latest, but potentially unstable, version should be used, or false if only the most recent stable version should be used. Use of this parameter is implementation-specific and not required.

Throws:

java.io.IOException - if the update could not be completed due to an exception that occurred.

java.lang.InterruptedException - If the user cancelled the update process before it could be completed. Throwing this exception is not required, but is a recommended course of action after maintaining consistency. If this exception is not thrown after a cancellation, the update manager will assume the update completed successfully.

cleanup

void cleanup()

Cleans up this UpdateElement object. The implementation should terminate any persistent connections to remote servers and/or file streams which it may still have open and perform any finalization or rollback work necessary to put the system in a consistent state.

Note that if the user cancels the update process or if an exception occurs during the update process, this method will be called. As a result, the update process must be prepared to accept a cleanup request at any point in time (though it is guaranteed that it will not occur while in the middle of the call to initialize(com.mmoui.manager.services.UpdateStatusListener), as each update process runs in a single thread). As a result, cleanup routines must be capable of detecting the state of the process to determine what levels of cleanup are necessary.

It is a best-practice to avoid setting update status during calls to cleanup() as it may overwrite useful error information. The update manager sets the update status before calls to cleanup() and will not reset them.

interrupt

void interrupt()

Interrupts the update process. This is called asynchronously when the user cancels the process associated with this object.

The update may or may not be in process when interrupt() is called, however the implementation must guarantee that if any attempt to perform an update action occurs after a call to interrupt(), an InterruptedException will be thrown to force the process into interruption. cleanup() will always be called at some point after an interruption, and must not be circumvented (though the implementation may wish to remember that an interruption occurred to change the cleanup work that is to be performed)

This method must always succeed, and not return until the process has been interrupted (or, if this UpdateElement object is not currently in control of the update process, it will return when the interruption has been marked)

getPopupOptions

UpdateElement.PopupOption[] getPopupOptions()

Gets the list of options presented to the user when the item is right clicked from within the table, as a JPopupMenu. These options are presented in the order specified, and are in addition to the default options provided by the Minion.

Returns:

an ordered list of UpdateElement.PopupOption objects which specify the name of the option and the callback to call.

Since:

1.0.1

getName

java.lang.String getName()

Gets the name of this UpdateElement object for display on the UI

Returns:

The name of this item as it should be displayed on the UI