Eclipse Platform
Release 3.2

org.eclipse.ui
Class Saveable

java.lang.Object
  extended byorg.eclipse.ui.Saveable
Direct Known Subclasses:
SaveableComparison

public abstract class Saveable
extends Object

A 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:
ISaveablesSource

Constructor Summary
Saveable()
           
 
Method Summary
abstract  void doSave(IProgressMonitor monitor)
          Saves the contents of this saveable.
abstract  boolean equals(Object object)
          Clients must implement equals and hashCode as defined in Object.equals(Object) and Object.hashCode().
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.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Saveable

public Saveable()
Method Detail

getName

public abstract String getName()
Returns the name of this saveable for display purposes.

Returns:
the model's name; never null.

getToolTipText

public abstract String 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

public abstract ImageDescriptor getImageDescriptor()
Returns the image descriptor for this saveable.

Returns:
the image descriptor for this model; may be null if there is no image

doSave

public abstract void doSave(IProgressMonitor monitor)
                     throws CoreException
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 the IProgressMonitor 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, and false if they have not changed since the last save

equals

public abstract boolean equals(Object object)
Clients must implement equals and hashCode as defined in 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.

Parameters:
object -
Returns:
true if this Saveable is equal to the given object

hashCode

public abstract int hashCode()
Clients must implement equals and hashCode as defined in 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();
 

Returns:
a hash code

Eclipse Platform
Release 3.2

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2000, 2006. All rights reserved.