Follow Techotopia on Twitter

On-line Guides
All Guides
eBook Store
iOS / Android
Linux for Beginners
Office Productivity
Linux Installation
Linux Security
Linux Utilities
Linux Virtualization
Linux Kernel
System/Network Admin
Programming
Scripting Languages
Development Tools
Web Development
GUI Toolkits/Desktop
Databases
Mail Systems
openSolaris
Eclipse Documentation
Techotopia.com
Virtuatopia.com

How To Guides
Virtualization
General System Admin
Linux Security
Linux Filesystems
Web Servers
Graphics & Desktop
PC Hardware
Windows
Problem Solutions
Privacy Policy

  




 

 


Eclipse Platform
Release 3.5

org.eclipse.core.resources
Interface ISaveParticipant

All Superinterfaces:
EventListener

public interface ISaveParticipant
extends EventListener

A participant in the saving of the workspace.

Plug-ins implement this interface and register to participate in workspace save operations.

Clients may implement this interface.

See Also:
IWorkspace.save(boolean, org.eclipse.core.runtime.IProgressMonitor)

Method Summary
 void doneSaving ( ISaveContext context)
          Tells this participant that the workspace save operation is now complete and it is free to go about its normal business.
 void prepareToSave ( ISaveContext context)
          Tells this participant that the workspace is about to be saved.
 void rollback ( ISaveContext context)
          Tells this participant to rollback its important state.
 void saving ( ISaveContext context)
          Tells this participant to save its important state because the workspace is being saved, as described in the supplied save context.
 

Method Detail

doneSaving

void doneSaving(
ISaveContext context)
Tells this participant that the workspace save operation is now complete and it is free to go about its normal business. Exceptions are not expected to be thrown at this point, so they should be handled internally.

Note: This method is called by the platform; it is not intended to be called directly by clients.

Parameters:
context - the save context object

prepareToSave

void prepareToSave(
ISaveContext context)
                   throws 
CoreException
Tells this participant that the workspace is about to be saved. In preparation, the participant is expected to suspend its normal operation until further notice. saving will be next, followed by either doneSaving or rollback depending on whether the workspace save was successful.

Note: This method is called by the platform; it is not intended to be called directly by clients.

Parameters:
context - the save context object
Throws:
CoreException - if this method fails to snapshot the state of this workspace

rollback

void rollback(
ISaveContext context)
Tells this participant to rollback its important state. The context's previous state number indicates what it was prior to the failed save. Exceptions are not expected to be thrown at this point, so they should be handled internally.

Note: This method is called by the platform; it is not intended to be called directly by clients.

Parameters:
context - the save context object
See Also:
ISaveContext.getPreviousSaveNumber()

saving

void saving(
ISaveContext context)
            throws 
CoreException
Tells this participant to save its important state because the workspace is being saved, as described in the supplied save context.

Note: This method is called by the platform; it is not intended to be called directly by clients.

The basic contract for this method is the same for full saves, snapshots and project saves: the participant must absolutely guarantee that any important user data it has gathered will not be irrecoverably lost in the event of a crash. The only difference is in the space-time tradeoffs that the participant should make.

  • Full saves: the participant is encouraged to save additional non-essential information that will aid it in retaining user state and configuration information and quickly getting back in sync with the state of the platform at a later point.
  • Snapshots: the participant is discouraged from saving non-essential information that could be recomputed in the unlikely event of a crash. This lifecycle event will happen often and participant actions should take an absolute minimum of time.
  • Project saves: the participant should only save project related data. It is discouraged from saving non-essential information that could be recomputed in the unlikely event of a crash.
For instance, the Java IDE gathers various user preferences and would want to make sure that the current settings are safe and sound after a save (if not saved immediately). The Java IDE would likely save computed image builder state on full saves, because this would allow the Java IDE to be restarted later and not have to recompile the world at that time. On the other hand, the Java IDE would not save the image builder state on a snapshot because that information is non-essential; in the unlikely event of a crash, the image should be rebuilt either from scratch or from the last saved state.

The following snippet shows how a plug-in participant would write its important state to a file whose name is based on the save number for this save operation.

     Plugin plugin = ...; // known
     int saveNumber = context.getSaveNumber();
     String saveFileName = "save-" + Integer.toString(saveNumber);
     File f = plugin.getStateLocation().append(saveFileName).toFile();
     plugin.writeImportantState(f);
     context.map(new Path("save"), new Path(saveFileName));
     context.needSaveNumber();
     context.needDelta(); // optional
 
When the plug-in is reactivated in a subsequent workspace session, it needs to re-register to participate in workspace saves. When it does so, it is handed back key information about what state it had last saved. If it's interested, it can also ask for a resource delta describing all resource changes that have happened since then, if this information is still available. The following snippet shows what a participant plug-in would need to do if and when it is reactivated:
     IWorkspace ws = ...; // known
     Plugin plugin = ...; // known
     ISaveParticipant saver = ...; // known
     ISavedState ss = ws.addSaveParticipant(plugin, saver);
     if (ss == null) {
         // activate for very first time
         plugin.buildState();
     } else {
         String saveFileName = ss.lookup(new Path("save"));
         File f = plugin.getStateLocation().append(saveFileName).toFile();
         plugin.readImportantState(f);
         IResourceChangeListener listener = new IResourceChangeListener() {
             public void resourceChanged(IResourceChangeEvent event) {
                 IResourceDelta delta = event.getDelta();
                 if (delta != null) {
                     // fast reactivation using delta
                     plugin.updateState(delta);
                 } else {
                     // slower reactivation without benefit of delta
                     plugin.rebuildState();
                 }
         };
         ss.processResourceChangeEvents(listener);
     }
 

Parameters:
context - the save context object
Throws:
CoreException - if this method fails
See Also:
ISaveContext.getSaveNumber()

Eclipse Platform
Release 3.5

Guidelines for using Eclipse APIs.

Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.


 
 
  Published under the terms of the Eclipse Public License Version 1.0 ("EPL") Design by Interspire