KickJava   Java API By Example, From Geeks To Geeks.

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


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 org.eclipse.core.runtime.IPath;
14
15 /**
16  * A context for workspace <code>save</code> operations.
17  * <p>
18  * Note that <code>IWorkspace.save</code> uses a
19  * different save context for each registered participant,
20  * allowing each to declare whether they have actively
21  * participated and decide whether to receive a resource
22  * delta on reactivation.
23  * </p>
24  * <p>
25  * This interface is not intended to be implemented by clients.
26  * </p>
27  *
28  * @see IWorkspace#save(boolean, org.eclipse.core.runtime.IProgressMonitor)
29  */
30 public interface ISaveContext {
31
32     /*====================================================================
33      * Constants related to save kind
34      *====================================================================*/
35
36     /**
37      * Type constant which identifies a full save.
38      *
39      * @see ISaveContext#getKind()
40      */
41     public static final int FULL_SAVE = 1;
42
43     /**
44      * Type constant which identifies a snapshot.
45      *
46      * @see ISaveContext#getKind()
47      */
48     public static final int SNAPSHOT = 2;
49
50     /**
51      * Type constant which identifies a project save.
52      *
53      * @see ISaveContext#getKind()
54      */
55     public static final int PROJECT_SAVE = 3;
56
57     /**
58      * Returns current files mapped with the <code>ISaveContext.map</code>
59      * facility or an empty array if there are no mapped files.
60      *
61      * @return the files currently mapped by the participant
62      *
63      * @see #map(IPath, IPath)
64      */
65     public IPath[] getFiles();
66
67     /**
68      * Returns the type of this save. The types can be:
69      * <ul>
70      * <li> <code>ISaveContext.FULL_SAVE</code></li>
71      * <li> <code>ISaveContext.SNAPSHOT</code></li>
72      * <li> <code>ISaveContext.PROJECT_SAVE</code></li>
73      * </ul>
74      *
75      * @return the type of the current save
76      */
77     public int getKind();
78
79     /**
80      * Returns the number for the previous save in
81      * which the plug-in actively participated, or <code>0</code>
82      * if the plug-in has never actively participated in a save before.
83      * <p>
84      * In the event of an unsuccessful save, this is the value to
85      * <code>rollback</code> to.
86      * </p>
87      *
88      * @return the previous save number if positive, or <code>0</code>
89      * if never saved before
90      * @see ISaveParticipant#rollback(ISaveContext)
91      */
92     public int getPreviousSaveNumber();
93
94     /**
95      * If the current save is a project save, this method returns the project
96      * being saved.
97      *
98      * @return the project being saved or <code>null</code> if this is not
99      * project save
100      *
101      * @see #getKind()
102      */
103     public IProject getProject();
104
105     /**
106      * Returns the number for this save. This number is
107      * guaranteed to be <code>1</code> more than the
108      * previous save number.
109      * <p>
110      * This is the value to use when, for example, creating files
111      * in which a participant will save its data.
112      * </p>
113      *
114      * @return the save number
115      * @see ISaveParticipant#saving(ISaveContext)
116      */
117     public int getSaveNumber();
118
119     /**
120      * Returns the current location for the given file or
121      * <code>null</code> if none.
122      *
123      * @return the location of a given file or <code>null</code>
124      * @see #map(IPath, IPath)
125      * @see ISavedState#lookup(IPath)
126      */
127     public IPath lookup(IPath file);
128
129     /**
130      * Maps the given plug-in file to its real location. This method is intended to be used
131      * with <code>ISaveContext.getSaveNumber()</code> to map plug-in configuration
132      * file names to real locations.
133      * <p>
134      * For example, assume a plug-in has a configuration file named "config.properties".
135      * The map facility can be used to map that logical name onto a real
136      * name which is specific to a particular save (e.g., 10.config.properties,
137      * where 10 is the current save number). The paths specified here should
138      * always be relative to the plug-in state location for the plug-in saving the state.
139      * </p>
140      * <p>
141      * Each save participant must manage the deletion of its old state files. Old state files
142      * can be discovered using <code>getPreviousSaveNumber</code> or by using
143      * <code>getFiles</code> to discover the current files and comparing that to the
144      * list of files on disk.
145      * </p>
146      * @param file the logical name of the participant's data file
147      * @param location the real (i.e., filesystem) name by which the file should be known
148      * for this save, or <code>null</code> to remove the entry
149      * @see #lookup(IPath)
150      * @see #getSaveNumber()
151      * @see #needSaveNumber()
152      * @see ISavedState#lookup(IPath)
153      */
154     public void map(IPath file, IPath location);
155
156     /**
157      * Indicates that the saved workspace tree should be remembered so that a delta
158      * will be available in a subsequent session when the plug-in re-registers
159      * to participate in saves. If this method is not called, no resource delta will
160      * be made available. This facility is not available for marker deltas.
161      * Plug-ins must assume that all markers may have changed when they are activated.
162      * <p>
163      * Note that this is orthogonal to <code>needSaveNumber</code>. That is,
164      * one can ask for a delta regardless of whether or not one is an active participant.
165      * </p>
166      * <p>
167      * Note that deltas are not guaranteed to be saved even if saving is requested.
168      * Deltas cannot be supplied where the previous state is too old or has become invalid.
169      * </p>
170      * <p>
171      * This method is only valid for full saves. It is ignored during snapshots
172      * or project saves.
173      * </p>
174      *
175      * @see IWorkspace#addSaveParticipant(org.eclipse.core.runtime.Plugin, ISaveParticipant)
176      * @see ISavedState#processResourceChangeEvents(IResourceChangeListener)
177      */
178     public void needDelta();
179
180     /**
181      * Indicates that this participant has actively participated in this save.
182      * If the save is successful, the current save number will be remembered;
183      * this save number will be the previous save number for subsequent saves
184      * until the participant again actively participates.
185      * <p>
186      * If this method is not called, the plug-in is not deemed to be an active
187      * participant in this save.
188      * </p>
189      * <p>
190      * Note that this is orthogonal to <code>needDelta</code>. That is,
191      * one can be an active participant whether or not one asks for a delta.
192      * </p>
193      *
194      * @see IWorkspace#addSaveParticipant(org.eclipse.core.runtime.Plugin, ISaveParticipant)
195      * @see ISavedState#getSaveNumber()
196      */
197     public void needSaveNumber();
198 }
199
Popular Tags