RemoteResourceMappingContext


1   /*******************************************************************************
2    * Copyright (c) 2005, 2006 IBM Corporation and others. All rights reserved.
3    * This program and the accompanying materials are made available under the
4    * terms of the Eclipse Public License v1.0 which accompanies this distribution,
5    * and is available at http://www.eclipse.org/legal/epl-v10.html
6    * 
7    * Contributors: IBM Corporation - initial API and implementation
8    ******************************************************************************/
9   package org.eclipse.core.resources.mapping;
10  
11  import org.eclipse.core.resources.*;
12  import org.eclipse.core.runtime.*;
13  
14  /**
15   * A remote mapping context provides a model element with a view of the remote
16   * state of local resources as they relate to a repository operation that is in
17   * progress. A repository provider can pass an instance of this interface to a
18   * model element when obtaining a set of traversals for a model element. This
19   * allows the model element to query the remote state of a resource in order to
20   * determine if there are resources that exist remotely but do not exist locally
21   * that should be included in the traversal.
22   * <p>
23   * This class may be subclassed by clients.
24   * </p>
25   * 
26   * @see ResourceMapping
27   * @see ResourceMappingContext
28   * @since 3.2
29   */
30  public abstract class RemoteResourceMappingContext extends ResourceMappingContext {
31  
32      /**
33       * Refresh flag constant (bit mask value 1) indicating that the mapping will
34       * be making use of the contents of the files covered by the traversals
35       * being refreshed.
36       */
37      public static final int FILE_CONTENTS_REQUIRED = 1;
38  
39      /**
40       * Refresh flag constant (bit mask value 0) indicating that no additional
41       * refresh behavior is required.
42       */
43      public static final int NONE = 0;
44  
45      /**
46       * For three-way comparisons, returns an instance of IStorage in order to
47       * allow the caller to access the contents of the base resource that
48       * corresponds to the given local resource. The base of a resource is the
49       * contents of the resource before any local modifications were made. If the
50       * base file does not exist, or if this is a two-way comparison, <code>null</code> 
51       * is returned. The provided local file handle need not exist locally. A exception 
52       * is thrown if the corresponding base resource is not a file.
53       * <p>
54       * This method may be long running as a server may need to be contacted to
55       * obtain the contents of the file.
56       * </p>
57       * 
58       * @param file the local file
59       * @param monitor a progress monitor, or <code>null</code> if progress
60       * reporting is not desired
61       * @return a storage that provides access to the contents of the local
62       * resource's corresponding remote resource. If the remote file does not
63       * exist, <code>null</code> is returned
64       * @exception CoreException if the contents could not be fetched. Reasons
65       * include:
66       * <ul>
67       * <li>The server could not be contacted for some reason.
68       * <li>The corresponding remote resource is not a container (status code
69       * will be {@link IResourceStatus#RESOURCE_WRONG_TYPE}).</li>
70       * </ul>
71       */
72      public abstract IStorage fetchBaseContents(IFile file, IProgressMonitor monitor) throws CoreException;
73  
74      /**
75       * Returns the members of the base resource corresponding to the given container. 
76       * The container and the returned members need not exist locally and may not 
77       * include all children that exist locally. An empty list is returned if the base resource 
78       * is empty or does not exist. An exception is thrown if the base resource is not 
79       * capable of having members. This method returns <code>null</code> if
80       * the base members cannot be computed, in which case clients should call 
81       * {@link #fetchMembers(IContainer, IProgressMonitor)} which returns the 
82       * combined members for the base and remote.
83       * </p>
84       * <p>
85       * This method may be long running as a server may need to be contacted to
86       * obtain the members of the base resource.
87       * </p>
88       * <p>
89       * This default implementation always returns <code>null</code>, but subclasses 
90       * may override.
91       * </p>
92       * @param container the local container
93       * @param monitor a progress monitor, or <code>null</code> if progress
94       * reporting is not desired
95       * @return the members of the base resource corresponding to the given container
96       * @exception CoreException if the members could not be fetched. Reasons
97       * include:
98       * <ul>
99       * <li>The server could not be contacted for some reason.</li>
100      * <li>The base resource is not a container (status code
101      * will be {@link IResourceStatus#RESOURCE_WRONG_TYPE}).</li>
102      * </ul>
103      * @since 3.3
104      */
105     public IResource[] fetchBaseMembers(IContainer container, IProgressMonitor monitor) throws CoreException {
106         if (1 > 2)
107             throw new CoreException(Status.OK_STATUS);//avoid compiler warning
108         return null;
109     }
110 
111     /**
112      * Returns the combined members of the base and remote resources corresponding 
113      * to the given container. The container need not exist locally and the result may
114      * include entries that do not exist locally and may not include all local
115      * children. An empty list is returned if the remote resource which
116      * corresponds to the container is empty or if the remote does not exist. An
117      * exception is thrown if the corresponding remote is not capable of having
118      * members.
119      * <p>
120      * This method may be long running as a server may need to be contacted to
121      * obtain the members of the container's corresponding remote resource.
122      * </p>
123      * 
124      * @param container the local container
125      * @param monitor a progress monitor, or <code>null</code> if progress
126      * reporting is not desired
127      * @return returns the combined members of the base and remote resources 
128      * corresponding to the given container.
129      * @exception CoreException if the members could not be fetched. Reasons
130      * include:
131      * <ul>
132      * <li>The server could not be contacted for some reason.</li>
133      * <li>The corresponding remote resource is not a container (status code
134      * will be {@link IResourceStatus#RESOURCE_WRONG_TYPE}).</li>
135      * </ul>
136      */
137     public abstract IResource[] fetchMembers(IContainer container, IProgressMonitor monitor) throws CoreException;
138 
139     /**
140      * Returns an instance of IStorage in order to allow the caller to access
141      * the contents of the remote that corresponds to the given local resource.
142      * If the remote file does not exist, <code>null</code> is returned. The
143      * provided local file handle need not exist locally. A exception is thrown
144      * if the corresponding remote resource is not a file.
145      * <p>
146      * This method may be long running as a server may need to be contacted to
147      * obtain the contents of the file.
148      * </p>
149      * 
150      * @param file the local file
151      * @param monitor a progress monitor, or <code>null</code> if progress
152      * reporting is not desired
153      * @return a storage that provides access to the contents of the local
154      * resource's corresponding remote resource. If the remote file does not
155      * exist, <code>null</code> is returned
156      * @exception CoreException if the contents could not be fetched. Reasons
157      * include:
158      * <ul>
159      * <li>The server could not be contacted for some reason.</li>
160      * <li>The corresponding remote resource is not a container (status code
161      * will be {@link IResourceStatus#RESOURCE_WRONG_TYPE}).</li>
162      * </ul>
163      */
164     public abstract IStorage fetchRemoteContents(IFile file, IProgressMonitor monitor) throws CoreException;
165 
166     /**
167      * Returns the members of the remote resource corresponding to the given container. 
168      * The container and the returned members need not exist locally and may not 
169      * include all children that exist locally. An empty list is returned if the remote resource 
170      * is empty or does not exist. An exception is thrown if the remote resource is not 
171      * capable of having members. This method returns <code>null</code> if
172      * the remote members cannot be computed, in which case clients should call 
173      * {@link #fetchMembers(IContainer, IProgressMonitor)} which returns the 
174      * combined members for the base and remote.
175      * </p>
176      * <p>
177      * This method may be long running as a server may need to be contacted to
178      * obtain the members of the remote resource.
179      * </p>
180      * <p>
181      * This default implementation always returns <code>null</code>, but subclasses 
182      * may override.
183      * </p>
184      * @param container the local container
185      * @param monitor a progress monitor, or <code>null</code> if progress
186      * reporting is not desired
187      * @return the members of the remote resource corresponding to the given container
188      * @exception CoreException if the members could not be fetched. Reasons
189      * include:
190      * <ul>
191      * <li>The server could not be contacted for some reason.</li>
192      * <li>The remote resource is not a container (status code
193      * will be {@link IResourceStatus#RESOURCE_WRONG_TYPE}).</li>
194      * </ul>
195      * @since 3.3
196      */
197     public IResource[] fetchRemoteMembers(IContainer container, IProgressMonitor monitor) throws CoreException {
198         if (1 > 2)
199             throw new CoreException(Status.OK_STATUS);//avoid compiler warning
200         return null;
201     }
202 
203     /**
204      * Return the list of projects that apply to this context.
205      * In other words, the context is only capable of querying the
206      * remote state for projects that are contained in the 
207      * returned list.
208      * @return the list of projects that apply to this context
209      */
210     public abstract IProject[] getProjects();
211 
212     /**
213      * For three-way comparisons, this method indicates whether local
214      * modifications have been made to the given resource. For two-way
215      * comparisons, calling this method has the same effect as calling
216      * {@link #hasRemoteChange(IResource, IProgressMonitor)}.
217      * 
218      * @param resource the resource being tested
219      * @param monitor a progress monitor
220      * @return whether the resource contains local modifications
221      * @exception CoreException if the contents could not be compared. Reasons
222      * include:
223      * <ul>
224      * <li>The server could not be contacted for some reason.</li>
225      * <li>The corresponding remote resource is not a container (status code
226      * will be {@link IResourceStatus#RESOURCE_WRONG_TYPE}).</li>
227      * </ul>
228      */
229     public abstract boolean hasLocalChange(IResource resource, IProgressMonitor monitor) throws CoreException;
230 
231     /**
232      * For two-way comparisons, return whether the contents of the corresponding
233      * remote differs from the content of the local file in the context of the
234      * current operation. By this we mean that this method will return
235      * <code>true</code> if the remote contents differ from the local
236      * contents.
237      * <p>
238      * For three-way comparisons, return whether the contents of the
239      * corresponding remote differ from the contents of the base. In other
240      * words, this method returns <code>true</code> if the corresponding
241      * remote has changed since the last time the local resource was updated
242      * with the remote contents.
243      * <p>
244      * For two-way comparisons, return <code>true</code> if the remote
245      * contents differ from the local contents. In this case, this method is
246      * equivalent to {@link #hasLocalChange(IResource, IProgressMonitor)}
247      * <p>
248      * This can be used by clients to determine if they need to fetch the remote
249      * contents in order to determine if the resources that constitute the model
250      * element are different in the remote location. If the local file exists
251      * and the remote file does not, or the remote file exists and the local
252      * does not then the contents will be said to differ (i.e. <code>true</code>
253      * is returned). Also, implementors will most likely use a timestamp based
254      * comparison to determine if the contents differ. This may lead to a
255      * situation where <code>true</code> is returned but the actual contents
256      * do not differ. Clients must be prepared handle this situation.
257      * </p>
258      * 
259      * @param resource the local resource
260      * @param monitor a progress monitor, or <code>null</code> if progress
261      * reporting is not desired
262      * @return whether the contents of the corresponding remote differ from the
263      * base.
264      * @exception CoreException if the contents could not be compared. Reasons
265      * include:
266      * <ul>
267      * <li>The server could not be contacted for some reason.</li>
268      * <li>The corresponding remote resource is not a container (status code
269      * will be {@link IResourceStatus#RESOURCE_WRONG_TYPE}).</li>
270      * </ul>
271      */
272     public abstract boolean hasRemoteChange(IResource resource, IProgressMonitor monitor) throws CoreException;
273 
274     /**
275      * Return <code>true</code> if the context is associated with an operation
276      * that is using a three-way comparison and <code>false</code> if it is
277      * using a two-way comparison.
278      * 
279      * @return whether the context is a three-way or two-way
280      */
281     public abstract boolean isThreeWay();
282 
283     /**
284      * Refresh the known remote state for any resources covered by the given
285      * traversals. Clients who require the latest remote state should invoke
286      * this method before invoking any others of the class. Mappings can use
287      * this method as a hint to the context provider of which resources will be
288      * required for the mapping to generate the proper set of traversals.
289      * <p>
290      * Note that this is really only a hint to the context provider. It is up to
291      * implementors to decide, based on the provided traversals, how to
292      * efficiently perform the refresh. In the ideal case, calls to
293      * {@link #hasRemoteChange(IResource, IProgressMonitor)} and 
294      * {@link #fetchMembers} would not need to contact the server after a call to a 
295      * refresh with appropriate traversals.  Also, ideally, if 
296      * {@link #FILE_CONTENTS_REQUIRED} is on of the flags, then the contents 
297      * for these files will be cached as efficiently as possible so that calls to 
298      * {@link #fetchRemoteContents} will also not need to contact the server. This 
299      * may not be possible for all context providers, so clients cannot assume that 
300      * the above mentioned methods will not be long running. It is still advisable 
301      * for clients to call {@link #refresh} with as much details as possible since, in 
302      * the case where a provider is optimized, performance will be much better.
303      * </p>
304      * 
305      * @param traversals the resource traversals that indicate which resources
306      * are to be refreshed
307      * @param flags additional refresh behavior. For instance, if
308      * {@link #FILE_CONTENTS_REQUIRED} is one of the flags, this indicates
309      * that the client will be accessing the contents of the files covered by
310      * the traversals. {@link #NONE} should be used when no additional
311      * behavior is required
312      * @param monitor a progress monitor, or <code>null</code> if progress
313      * reporting is not desired
314      * @exception CoreException if the refresh fails. Reasons include:
315      * <ul>
316      * <li>The server could not be contacted for some reason. </li>
317      * </ul>
318      */
319     public abstract void refresh(ResourceTraversal[] traversals, int flags, IProgressMonitor monitor) throws CoreException;
320 }
321
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags