Class Saveable
- All Implemented Interfaces:
IAdaptable
- Direct Known Subclasses:
AbstractTextEditor.TextEditorSavable
,DefaultSaveable
,SaveableComparison
Saveable
represents a unit of saveability, e.g. an editable
subset of the underlying domain model that may contain unsaved changes.
Different workbench parts (editors and views) may present the same saveables
in different ways. This interface allows the workbench to provide more
appropriate handling of operations such as saving and closing workbench
parts. For example, if two editors sharing the same saveable with unsaved
changes are closed simultaneously, the user is only prompted to save the
changes once for the shared saveable, rather than once for each editor.
Workbench parts that work in terms of saveables should implement
ISaveablesSource
.
- Since:
- 3.2
- See Also:
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionvoid
disableUI
(IWorkbenchPart[] parts, boolean closing) Disables the UI of the given parts containing this saveable if necessary.abstract void
doSave
(IProgressMonitor monitor) Saves the contents of this saveable.doSave
(IProgressMonitor monitor, IShellProvider shellProvider) Saves this saveable, or prepares this saveable for a background save operation.void
enableUI
(IWorkbenchPart[] parts) Enables the UI of the given parts containing this saveable after a background save operation has finished.abstract boolean
Clients must implement equals and hashCode as defined inObject.equals(Object)
andObject.hashCode()
.<T> T
getAdapter
(Class<T> adapter) This implementation ofIAdaptable.getAdapter(Class)
returnsnull
.abstract ImageDescriptor
Returns the image descriptor for this saveable.abstract String
getName()
Returns the name of this saveable for display purposes.abstract String
Returns the tool tip text for this saveable.abstract int
hashCode()
Clients must implement equals and hashCode as defined inObject.equals(Object)
andObject.hashCode()
.abstract boolean
isDirty()
Returns whether the contents of this saveable have changed since the last save operation.boolean
show
(IWorkbenchPage page) Attempts to show this saveable in the given page and returnstrue
on success.
-
Constructor Details
-
Saveable
public Saveable()
-
-
Method Details
-
show
Attempts to show this saveable in the given page and returnstrue
on success. The default implementation does nothing and returnsfalse
.- Parameters:
page
- the workbench page in which to show this saveable- Returns:
true
if this saveable is now visible to the user- Since:
- 3.3
-
getName
Returns the name of this saveable for display purposes.- Returns:
- the model's name; never
null
.
-
getToolTipText
Returns the tool tip text for this saveable. This text is used to differentiate between two inputs with the same name. For instance, MyClass.java in folder X and MyClass.java in folder Y. The format of the text varies between input types.- Returns:
- the tool tip text; never
null
-
getImageDescriptor
Returns the image descriptor for this saveable.- Returns:
- the image descriptor for this model; may be
null
if there is no image
-
doSave
Saves the contents of this saveable.If the save is cancelled through user action, or for any other reason, the part should invoke
setCancelled
on theIProgressMonitor
to inform the caller.This method is long-running; progress and cancellation are provided by the given progress monitor.
- Parameters:
monitor
- the progress monitor- Throws:
CoreException
- if the save fails; it is the caller's responsibility to report the failure to the user
-
isDirty
public abstract boolean isDirty()Returns whether the contents of this saveable have changed since the last save operation.Note: this method is called frequently, for example by actions to determine their enabled status.
- Returns:
true
if the contents have been modified and need saving, andfalse
if they have not changed since the last save
-
equals
Clients must implement equals and hashCode as defined inObject.equals(Object)
andObject.hashCode()
. Two saveables should be equal if their dirty state is shared, and saving one will save the other. If two saveables are equal, their names, tooltips, and images should be the same because only one of them will be shown when prompting the user to save. -
hashCode
public abstract int hashCode()Clients must implement equals and hashCode as defined inObject.equals(Object)
andObject.hashCode()
. Two saveables should be equal if their dirty state is shared, and saving one will save the other. If two saveables are equal, their hash codes MUST be the same, and their names, tooltips, and images should be the same because only one of them will be shown when prompting the user to save.IMPORTANT: Implementers should ensure that the hashCode returned is sufficiently unique so as not to collide with hashCodes returned by other implementations. It is suggested that the defining plug-in's ID be used as part of the returned hashCode, as in the following example:
int PRIME = 31; int hash = ...; // compute the "normal" hash code, e.g. based on some identifier unique within the defining plug-in return hash * PRIME + MY_PLUGIN_ID.hashCode();
-
doSave
public IJobRunnable doSave(IProgressMonitor monitor, IShellProvider shellProvider) throws CoreException Saves this saveable, or prepares this saveable for a background save operation. Returns null if this saveable has been successfully saved, or a job runnable that needs to be run to complete the save in the background. This method is called in the UI thread. If this saveable supports saving in the background, it should do only minimal work. However, since the job runnable returned by this method (if any) will not run on the UI thread, this method should copy any state that can only be accessed from the UI thread so that the job runnable will be able to access it.The supplied shell provider can be used from within this method and from within the job runnable for the purpose of parenting dialogs. Care should be taken not to open dialogs gratuitously and only if user input is required for cases where the save cannot otherwise proceed - note that in any given save operation, many saveable objects may be saved at the same time. In particular, errors should be signaled by throwing an exception, or if an error occurs while running the job runnable, an error status should be returned.
If the foreground part of the save is cancelled through user action, or for any other reason, the part should invoke
setCancelled
on theIProgressMonitor
to inform the caller. If the background part of the save is cancelled, the job should return aIStatus.CANCEL
status.This method is long-running; progress and cancellation are provided by the given progress monitor.
The default implementation of this method calls
doSave(IProgressMonitor)
and returnsnull
.- Parameters:
monitor
- a progress monitor used for reporting progress and cancellationshellProvider
- an object that can provide a shell for parenting dialogs- Returns:
null
if this saveable has been saved successfully, or a job runnable that needs to be run to complete the save in the background.- Throws:
CoreException
- if the save fails; it is the caller's responsibility to report the failure to the user- Since:
- 3.3
-
disableUI
Disables the UI of the given parts containing this saveable if necessary. This method is not intended to be called by clients. A corresponding call toSaveables that can be saved in the background should ensure that the user cannot make changes to their data from the UI, for example by disabling controls, unless they are prepared to handle this case. This method is called on the UI thread after a job runnable has been returned from
doSave(IProgressMonitor, IShellProvider)
and before spinning the event loop. Theclosing
flag indicates that this saveable is currently being saved in response to closing a workbench part, in which case further changes to this saveable through the UI must be prevented.The default implementation calls setEnabled(false) on the given parts' composites.
- Parameters:
parts
- the workbench parts containing this saveableclosing
- a boolean flag indicating whether the save was triggered by a request to close a workbench part, and all of the given parts will be closed after the save operation finishes successfully.- Since:
- 3.3
-
enableUI
Enables the UI of the given parts containing this saveable after a background save operation has finished. This method is not intended to be called by clients.The default implementation calls setEnabled(true) on the given parts' composites.
- Parameters:
parts
- the workbench parts containing this saveable- Since:
- 3.3
-
getAdapter
This implementation ofIAdaptable.getAdapter(Class)
returnsnull
. Subclasses may override. This allows two unrelated subclasses of Saveable to implementequals(Object)
andhashCode()
based on an underlying implementation class that is shared by both Saveable subclasses.- Specified by:
getAdapter
in interfaceIAdaptable
- Type Parameters:
T
- the class type- Parameters:
adapter
- the adapter class to look up- Returns:
- a object of the given class, or
null
if this object does not have an adapter for the given class - Since:
- 3.3
-