public abstract class Saveable extends org.eclipse.ui.internal.InternalSaveable implements IAdaptable
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
.
ISaveablesSource
Constructor and Description |
---|
Saveable() |
Modifier and Type | Method and Description |
---|---|
void |
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.
|
IJobRunnable |
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 |
equals(Object object)
Clients must implement equals and hashCode as defined in
Object.equals(Object) and Object.hashCode() . |
Object |
getAdapter(Class adapter)
This implementation of
IAdaptable.getAdapter(Class) returns
null . |
abstract ImageDescriptor |
getImageDescriptor()
Returns the image descriptor for this saveable.
|
abstract String |
getName()
Returns the name of this saveable for display purposes.
|
abstract String |
getToolTipText()
Returns the tool tip text for this saveable.
|
abstract int |
hashCode()
Clients must implement equals and hashCode as defined in
Object.equals(Object) and Object.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 returns
true on success. |
public boolean show(IWorkbenchPage page)
true
on success. The default implementation does nothing
and returns false
.page
- the workbench page in which to show this saveabletrue
if this saveable is now visible to the userpublic abstract String getName()
null
.public abstract String getToolTipText()
null
public abstract ImageDescriptor getImageDescriptor()
null
if there is no imagepublic abstract void doSave(IProgressMonitor monitor) throws CoreException
If the save is cancelled through user action, or for any other reason,
the part should invoke setCancelled
on the
IProgressMonitor
to inform the caller.
This method is long-running; progress and cancellation are provided by the given progress monitor.
monitor
- the progress monitorCoreException
- if the save fails; it is the caller's responsibility to
report the failure to the userpublic abstract boolean isDirty()
Note: this method is called frequently, for example by actions to determine their enabled status.
true
if the contents have been modified and need
saving, and false
if they have not changed since
the last savepublic abstract boolean equals(Object object)
Object.equals(Object)
and Object.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.public abstract int hashCode()
Object.equals(Object)
and Object.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();
public IJobRunnable doSave(IProgressMonitor monitor, IShellProvider shellProvider) throws CoreException
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 the IProgressMonitor
to inform the caller. If the
background part of the save is cancelled, the job should return a
IStatus.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 returns null
.
monitor
- a progress monitor used for reporting progress and
cancellationshellProvider
- an object that can provide a shell for parenting dialogsnull
if this saveable has been saved successfully,
or a job runnable that needs to be run to complete the save in
the background.CoreException
- if the save fails; it is the caller's responsibility to
report the failure to the userpublic void disableUI(IWorkbenchPart[] parts, boolean closing)
Saveables 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. The closing
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.
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.public void enableUI(IWorkbenchPart[] parts)
The default implementation calls setEnabled(true) on the given parts' composites.
parts
- the workbench parts containing this saveablepublic Object getAdapter(Class adapter)
IAdaptable.getAdapter(Class)
returns
null
. Subclasses may override. This allows two unrelated
subclasses of Saveable to implement equals(Object)
and
hashCode()
based on an underlying implementation class that is
shared by both Saveable subclasses.getAdapter
in interface IAdaptable
adapter
- the adapter class to look upnull
if this object does not
have an adapter for the given class
Copyright (c) 2000, 2015 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs.