KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > team > internal > core > simpleAccess > SimpleAccessOperations


1 /*******************************************************************************
2  * Copyright (c) 2000, 2003 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Common Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/cpl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/
11 package org.eclipse.team.internal.core.simpleAccess;
12
13 import org.eclipse.core.resources.IResource;
14 import org.eclipse.core.runtime.IPath;
15 import org.eclipse.core.runtime.IProgressMonitor;
16 import org.eclipse.team.core.TeamException;
17
18 /*
19  * This class represents provisional API. Its here to allow experimentation with 3rd party tools
20  * calling providers in a repository neutral manner.
21  *
22  * A provider is not required to implement this API.
23  * Implementers, and those who reference it, do so with the awareness that this class may be
24  * removed or substantially changed at future times without warning.
25  *
26  * The <code>SimpleAccessOperations</code> class exposes a basic repository model that
27  * providers may implement to allow third-party plugins to perform repository operations
28  * programmatically. For example, a code generation tool may want to get source
29  * files before generating the code, and check-in the results. If a provider plugin does
30  * not adhere to the <i>semantics</i> of the <code>SimpleAccessOperations</code> class
31  * as described, they are free to opt out of implementing it.
32  *
33  * @since 2.0
34  */
35 public interface SimpleAccessOperations {
36     /*
37      * Updates the local resource to have the same content as the corresponding remote
38      * resource. Where the local resource does not exist, this method will create it.
39      * <p>
40      * If the remote resource is a container (e.g. folder or project) this operation is equivalent
41      * to getting each non-container member of the remote resource, thereby updating the
42      * content of existing local members, creating local members to receive new remote resources,
43      * and deleting local members that no longer have a corresponding remote resource.</p>
44      * <p>
45      * The method is applied to all resources satisfying the depth parameter, described above.</p>
46      * <p>
47      * Interrupting the method (via the progress monitor) may lead to partial, but consistent, results.</p>
48      *
49      * @param resources an array of local resources to update from the corresponding remote
50      * resources.
51      * @param depth the depth to traverse the given resources, taken from <code>IResource</code>
52      * static constants.
53      * @param progress a progress monitor to indicate the duration of the operation, or
54      * <code>null</code> if progress reporting is not required.
55      * @throws TeamException if there is a problem getting one or more of the resources. The
56      * exception will contain multiple statuses, one for each resource in the <code>resources</code>
57      * array. Possible status codes include:
58      * <ul>
59      * <li>NO_REMOTE_RESOURCE</li>
60      * <li>IO_FAILED</li>
61      * <li>NOT_AUTHORIZED</li>
62      * <li>UNABLE</li>
63      * </ul>
64      */
65     public void get(IResource[] resources, int depth, IProgressMonitor progress) throws TeamException;
66
67     /*
68      * Changes the state of the local resource from checked-in to checked-out and transfers the content
69      * of the remote resource to the local resource.
70      * <p>
71      * Where no corresponding local resource exists in the workspace, one is created (including any
72      * intermediate parent containers) to receive the contents of the remote resource.</p>
73      * <p>
74      * Implementations may optimistically only flag the state change locally and rely on resolving conflicts
75      * during check-in, or they may pessimistically also checkout or lock the remote resource during a
76      * local resource checkout to avoid conflicts. The provider API does not subscribe to either model
77      * and supports each equally.</p>
78      * <p>
79      * Where checkout is applied to a resource that is already checked-out the method has no
80      * effect.</p>
81      *
82      * @param resources the array of local resources to be checked-out.
83      * @param depth the depth to traverse the given resources, taken from <code>IResource</code>
84      * constants.
85      * @param progress a progress monitor to indicate the duration of the operation, or
86      * <code>null</code> if progress reporting is not required.
87      * @throws TeamProviderException if there is a problem checking-out one or more of the resources.
88      * The exception will contain multiple statuses, one for each resource in the <code>resources</code>
89      * array. Possible status codes include:
90      * <ul>
91      * <li>NOT_CHECKED_IN</li>
92      * <li>NO_REMOTE_RESOURCE</li>
93      * <li>IO_FAILED</li>
94      * <li>NOT_AUTHORIZED</li>
95      * <li>UNABLE</li>
96      * </ul>
97      * @see checkin(IResource[], int, IProgressMonitor)
98      */
99     public void checkout(IResource[] resources, int depth, IProgressMonitor progress) throws TeamException;
100
101     /*
102      * Transfers the content of the local resource to the corresponding remote resource, and changes the
103      * state of the local resource from checked-out to checked-in.
104      * <p>
105      * If a remote resource does not exist this method creates a new remote resource with the same content
106      * as the given local resource. The local resource is said to <i>correspond</i> to the new remote resource.</p>
107      * <p>
108      * Where providers deal with stores that check-out or lock resources this method is an opportunity
109      * to transfer the content and make the corresponding remote check-in or unlock. It is envisaged that
110      * where the server maintains resource versions, checkin creates a new version of the remote resource.</p>
111      * <p>
112      * Note that some providers may <em>require</em> that a resource is checked-out before it can be
113      * checked-in. However, all providers must support the explicit checking out a resource before checking
114      * it in (e.g., even if the check out is a no-op).</p>
115      *
116      * @param resources an array of local resources to be checked-in.
117      * @param the depth to traverse the given resources, taken from <code>IResource</code>
118      * constants.
119      * @param progress a progress monitor to indicate the duration of the operation, or
120      * <code>null</code> if progress reporting is not required.
121      * @throws TeamException if there is a problem checking-in one or more of the resources.
122      * The exception will contain multiple statuses, one for each resource in the <code>resources</code>
123      * array. Possible status codes include:
124      * <ul>
125      * <li>NOT_CHECKED_OUT</li>
126      * <li>IO_FAILED</li>
127      * <li>NOT_AUTHORIZED</li>
128      * <li>UNABLE</li>
129      * </ul>
130      * @see checkout(IResource[], int, IProgressMonitor)
131      */
132     public void checkin(IResource[] resources, int depth, IProgressMonitor progress) throws TeamException;
133
134     /*
135      * Changes the state of the local resource from checked-out to checked-in without updating the contents
136      * of the remote resource.
137      * <p>
138      * Note that where the provider is a versioning provider, it is envisaged (though not required) that the
139      * uncheckout operation does not create a new version.</p>
140      * <p>
141      * Note also that <code>uncheckout()</code> does not affect the content of the local resource. The
142      * caller is required to perform a <code>get()</code> to revert the local resource if that is required
143      * (otherwise the local resource will be left with the changes that were made while the remote resource
144      * was checked-out. Furthermore, it is valid to call <code>uncheckout()</code> with an
145      * <code>IResource</code> that does not exist locally.</p>
146      *
147      * @param resources an array of the local resources that are to be unchecked-out.
148      * @param depth the depth to traverse the given resources, taken from <code>IResource</code>
149      * constants.
150      * @param progress a progress monitor to indicate the duration of the operation, or
151      * <code>null</code> if progress reporting is not required.
152      * @throws TeamProviderException if there is a problem undoing the check-out of one or more of
153      * the resources. The exception will contain multiple statuses, one for each resource in the
154      * <code>resources</code> array. Possible status codes include:
155      * <ul>
156      * <li>NOT_CHECKED_OUT</li>
157      * <li>IO_FAILED</li>
158      * <li>NOT_AUTHORIZED</li>
159      * <li>UNABLE</li>
160      * </ul>
161      * @see checkin(IResource)
162      * @see uncheckout(IResource)
163      */
164     public void uncheckout(IResource[] resources, int depth, IProgressMonitor progress) throws TeamException;
165
166     /*
167      * Deletes the remote resource corresponding to the given local resource.
168      * <p>
169      * The notion of delete is simply to make the remote resource unavailable. Where the provider
170      * supports versioning it is not specified whether the delete operation makes the version
171      * temporarily or forever unavailable, or indeed whether the entire history is made unavailable.</p>
172      * <p>
173      * Note that the <code>IResource</code>'s passed as arguments may be non-existant in the
174      * workbench, the typical case is when such a resource has been received in a core callback.</p>
175      * <p>
176      * The resource may be checked-in or checked-out prior to deletion. The local resource is not
177      * deleted by this method.</p>
178      * <p>
179      * Resource deletions are inherently deep.</p>
180      *
181      * @param resources the array of resources whose corresponding remote resources are to be deleted.
182      * @param progress a progress monitor to indicate the duration of the operation, or
183      * <code>null</code> if progress reporting is not required.
184      * @throws TeamProviderException if there is a problem deleting one or more of
185      * the resources. The exception will contain multiple statuses, one for each resource in the
186      * <code>resources</code> array. Possible status codes include:
187      * <ul>
188      * <li>NO_REMOTE_RESOURCE</li>
189      * <li>IO_FAILED</li>
190      * <li>NOT_AUTHORIZED</li>
191      * <li>UNABLE</li>
192      * </ul>
193      */
194     public void delete(IResource[] resources, IProgressMonitor progress) throws TeamException;
195
196     /*
197      * Informs the provider that a local resource's name or path has changed.
198      * <p>
199      * Some providers, such as versioning providers, may require this information to track the resource
200      * across name changes.</p>
201      * <p>
202      * Note that this method is always called <em>after</em> the local resource has been moved.</p>
203      *
204      * @param source the full name of the resource before it was moved.
205      * @param target the resource that was moved.
206      * @param progress a progress monitor to indicate the duration of the operation, or
207      * <code>null</code> if progress reporting is not required.
208      * @throws TeamProviderException if there is a problem recording the move. The exception will
209      * contain a single status. Possible status codes are:
210      * <ul>
211      * <li>NO_REMOTE_RESOURCE</li>
212      * <li>IO_FAILED</li>
213      * <li>NOT_AUTHORIZED</li>
214      * <li>UNABLE</li>
215      * </ul>
216      */
217     public void moved(IPath source, IResource target, IProgressMonitor progress) throws TeamException;
218     
219     /*
220      * Implementor's Note:
221      * The following methods are required to return promptly (i.e., they may be used to determine the state of
222      * a resource in a UI where long delays are unacceptable). Implementations may cache these values
223      * and update the cache on an explicit call to #refreshState().
224      *
225      * They are currently listed in the provider API, however, they may be moved to a new or different
226      * interface in the future to better reflect their UI-orientation.
227      */
228
229     /*
230      * Answers if the remote resource state is checked-out. If the resource has never been checked in this
231      * method will return <code>true</code>.
232      * <p>
233      * It is undefined whether this method tests for a resource being checked out to this workspace
234      * or any workspace.</p>
235      *
236      * @param resource the local resource to test.
237      * @return <code>true</code> if the resource is checked-out and <code>false</code> if it is not.
238      * @see checkout(IResource[], int, IProgressMonitor)
239      */
240     public boolean isCheckedOut(IResource resource);
241     
242     /*
243      * Answers whether the resource has a corresponding remote resource.
244      * <p>
245      * Before a resource is checked-in, the resource will occur locally but not remotely, and calls to this
246      * method will return <code>false</code>. Once a local resource is checked in (and assuming the local
247      * local resource is not moved or the remote resource deleted) there will be a corresponding remote
248      * resource and this method returns <code>true</code>.</p>
249      *
250      * @param resource the local resource to test.
251      * @return <code>true</code> if the local resource has a corresponding remote resource,
252      * and <code>false</code> otherwise.
253      * @see checkin(IResource[], int, IProgressMonitor)
254      * @see refreshState(IResource[], int, IProgressMonitor)
255      */
256     public boolean hasRemote(IResource resource);
257
258     /*
259      * Answer if the local resource currently has a different timestamp to the base timestamp
260      * for this resource.
261      *
262      * @param resource the resource to test.
263      * @return <code>true</code> if the resource has a different modification
264      * timestamp, and <code>false</code> otherwise.
265      */
266     public boolean isDirty(IResource resource);
267 }
268
Popular Tags