KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > core > resources > ISaveParticipant


1 /*******************************************************************************
2  * Copyright (c) 2000, 2005 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/
11 package org.eclipse.core.resources;
12
13 import java.util.EventListener JavaDoc;
14 import org.eclipse.core.runtime.CoreException;
15
16 /**
17  * A participant in the saving of the workspace.
18  * <p>
19  * Plug-ins implement this interface and register to participate
20  * in workspace save operations.
21  * </p>
22  * <p>
23  * Clients may implement this interface.
24  * </p>
25  * @see IWorkspace#save(boolean, org.eclipse.core.runtime.IProgressMonitor)
26  */
27 public interface ISaveParticipant extends EventListener JavaDoc {
28     /**
29      * Tells this participant that the workspace save operation is now
30      * complete and it is free to go about its normal business.
31      * Exceptions are not expected to be thrown at this point, so they
32      * should be handled internally.
33      * <p>
34      * Note: This method is called by the platform; it is not intended
35      * to be called directly by clients.
36      * </p>
37      *
38      * @param context the save context object
39      */
40     public void doneSaving(ISaveContext context);
41
42     /**
43      * Tells this participant that the workspace is about to be
44      * saved. In preparation, the participant is expected to suspend
45      * its normal operation until further notice. <code>saving</code>
46      * will be next, followed by either <code>doneSaving</code>
47      * or <code>rollback</code> depending on whether the workspace
48      * save was successful.
49      * <p>
50      * Note: This method is called by the platform; it is not intended
51      * to be called directly by clients.
52      * </p>
53      *
54      * @param context the save context object
55      * @exception CoreException if this method fails to snapshot
56      * the state of this workspace
57      */
58     public void prepareToSave(ISaveContext context) throws CoreException;
59
60     /**
61      * Tells this participant to rollback its important state.
62      * The context's previous state number indicates what it was prior
63      * to the failed save.
64      * Exceptions are not expected to be thrown at this point, so they
65      * should be handled internally.
66      * <p>
67      * Note: This method is called by the platform; it is not intended
68      * to be called directly by clients.
69      * </p>
70      *
71      * @param context the save context object
72      * @see ISaveContext#getPreviousSaveNumber()
73      */
74     public void rollback(ISaveContext context);
75
76     /**
77      * Tells this participant to save its important state because
78      * the workspace is being saved, as described in the supplied
79      * save context.
80      * <p>
81      * Note: This method is called by the platform; it is not intended
82      * to be called directly by clients.
83      * </p>
84      * <p>
85      * The basic contract for this method is the same for full saves,
86      * snapshots and project saves: the participant must absolutely guarantee that any
87      * important user data it has gathered will not be irrecoverably lost
88      * in the event of a crash. The only difference is in the space-time
89      * tradeoffs that the participant should make.
90      * <ul>
91      * <li>Full saves: the participant is
92      * encouraged to save additional non-essential information that will aid
93      * it in retaining user state and configuration information and quickly getting
94      * back in sync with the state of the platform at a later point.
95      * </li>
96      * <li>Snapshots: the participant is discouraged from saving non-essential
97      * information that could be recomputed in the unlikely event of a crash.
98      * This lifecycle event will happen often and participant actions should take
99      * an absolute minimum of time.
100      * </li>
101      * <li>Project saves: the participant should only save project related data.
102      * It is discouraged from saving non-essential information that could be recomputed
103      * in the unlikely event of a crash.
104      * </li>
105      * </ul>
106      * For instance, the Java IDE gathers various user preferences and would want to
107      * make sure that the current settings are safe and sound after a
108      * <code>save</code> (if not saved immediately).
109      * The Java IDE would likely save computed image builder state on full saves,
110      * because this would allow the Java IDE to be restarted later and not
111      * have to recompile the world at that time. On the other hand, the Java
112      * IDE would not save the image builder state on a snapshot because
113      * that information is non-essential; in the unlikely event of a crash,
114      * the image should be rebuilt either from scratch or from the last saved
115      * state.
116      * </p>
117      * <p>
118      * The following snippet shows how a plug-in participant would write
119      * its important state to a file whose name is based on the save
120      * number for this save operation.
121      * <pre>
122      * Plugin plugin = ...; // known
123      * int saveNumber = context.getSaveNumber();
124      * String saveFileName = "save-" + Integer.toString(saveNumber);
125      * File f = plugin.getStateLocation().append(saveFileName).toFile();
126      * plugin.writeImportantState(f);
127      * context.map(new Path("save"), new Path(saveFileName));
128      * context.needSaveNumber();
129      * context.needDelta(); // optional
130      * </pre>
131      * When the plug-in is reactivated in a subsequent workspace session,
132      * it needs to re-register to participate in workspace saves. When it
133      * does so, it is handed back key information about what state it had last
134      * saved. If it's interested, it can also ask for a resource delta
135      * describing all resource changes that have happened since then, if this
136      * information is still available.
137      * The following snippet shows what a participant plug-in would
138      * need to do if and when it is reactivated:
139      * <pre>
140      * IWorkspace ws = ...; // known
141      * Plugin plugin = ...; // known
142      * ISaveParticipant saver = ...; // known
143      * ISavedState ss = ws.addSaveParticipant(plugin, saver);
144      * if (ss == null) {
145      * // activate for very first time
146      * plugin.buildState();
147      * } else {
148      * String saveFileName = ss.lookup(new Path("save"));
149      * File f = plugin.getStateLocation().append(saveFileName).toFile();
150      * plugin.readImportantState(f);
151      * IResourceChangeListener listener = new IResourceChangeListener() {
152      * public void resourceChanged(IResourceChangeEvent event) {
153      * IResourceDelta delta = event.getDelta();
154      * if (delta != null) {
155      * // fast reactivation using delta
156      * plugin.updateState(delta);
157      * } else {
158      * // slower reactivation without benefit of delta
159      * plugin.rebuildState();
160      * }
161      * };
162      * ss.processResourceChangeEvents(listener);
163      * }
164      * </pre>
165      * </p>
166      *
167      * @param context the save context object
168      * @exception CoreException if this method fails
169      * @see ISaveContext#getSaveNumber()
170      */
171     public void saving(ISaveContext context) throws CoreException;
172 }
173
Popular Tags