RemoteResourceMappingContext


1   /*******************************************************************************
2    * Copyright (c) 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.internal.resources.mapping;
12  
13  import org.eclipse.core.resources.*;
14  import org.eclipse.core.runtime.CoreException;
15  import org.eclipse.core.runtime.IProgressMonitor;
16  
17  /**
18   * A remote mapping context provides a model element with a view of the remote state
19   * of local resources as they relate to a repository operation that is in
20   * progress. A repository provider can pass an instance of this interface to a
21   * model element when obtaining a set of traversals for a model element. This
22   * allows the model element to query the remote state of a resource in order to
23   * determine if there are resources that exist remotely but do not exist locally
24   * that should be included in the traversal. The traversals should also be as 
25   * as possible to allow for optimization of remote operations.
26   * <p>
27   * This class may be subclassed by clients.
28   * </p>
29   * 
30   * @see ResourceMapping
31   * @see ResourceMappingContext
32   * @since 3.1
33   */
34  public abstract class RemoteResourceMappingContext extends ResourceMappingContext {
35  
36      /**
37       * Refresh flag constant (bit mask value 0) indicating that no
38       * additional refresh behavior is required.
39       */
40      public static final int NONE = 0;
41      
42      /**
43       * Refresh flag constant (bit mask value 1) indicating that
44       * the mapping will be making use of the contents of the files
45       * covered by the traversals being refreshed.
46       */
47      public static final int FILE_CONTENTS_REQUIRED = 1;
48  
49      /**
50       * Return whether the contents of the corresponding remote differs from the
51       * content of the local file in the context of the current operation. By this
52       * we mean that this method will return <code>true</code> if the remote contents differ
53       * from the local contents and these remote contents would be fetched as part of the
54       * operation associated with the context. 
55       * For instance, when updating the workspace to the latest remote state,
56       * this method would only return <code>true</code> if the remote contentd have changed
57       * since the last time the contents where updated. However, if replace the local contents,
58       * the methdo would return <code>true</code> if either the remote contents or the lcoal contents 
59       * have changed.
60       * <p>
61       * This can be used by clients to determine if
62       * they need to fetch the remote contents in order to determine if the
63       * resources that constitute the model element are different in another
64       * location. If the lcoa file exists and the remote file does not, then
65       * the contents will be said to differ (i.e. <code>true</code> is returned).
66       * </p>
67       * 
68       * @param file the local file
69       * @param monitor a progress monitor, or <code>null</code> if progress
70       *    reporting is not desired
71       * @return whether the contents of the corresponding remote differs from the
72       *         content of the local file
73       * @exception CoreException if the contents could not be compared. Reasons include:
74       * <ul>
75       * <li>The corresponding remote resource is not a container
76       *    (status code will be IResourceStatus.RESOURCE_WRONG_TYPE).</li>
77       * </ul>
78       */
79      public abstract boolean contentDiffers(IFile file, IProgressMonitor monitor) throws CoreException;
80  
81      /**
82       * Returns an instance of IStorage in order to allow the
83       * caller to access the contents of the remote that corresponds to the given
84       * local resource. If the remote file does not exist, <code>null</code> is
85       * returned. The provided local file handle need not exist locally. A
86       * exception is thrown if the corresponding remote resource is not a file.
87       * <p>
88       * This method may be long running as a server may need to be contacted to
89       * obtain the contents of the file.
90       * </p>
91       * 
92       * @param file the local file
93       * @param monitor a progress monitor, or <code>null</code> if progress
94       *    reporting is not desired
95       * @return a storage that provides access to the contents of the local
96       *         resource's corresponding remote resource. If the remote file
97       *         does not exist, <code>null</code> is returned
98       * @exception CoreException if the contents could not be fetched. Reasons include:
99       * <ul>
100      * <li>The corresponding remote resource is not a container
101      *    (status code will be IResourceStatus.RESOURCE_WRONG_TYPE).</li>
102      * </ul>
103      */
104     public abstract IStorage fetchContents(IFile file, IProgressMonitor monitor) throws CoreException;
105 
106     /**
107      * Returns the list of member resources whose corresponding remote resources
108      * are members of the corresponding remote resource of the given local
109      * container. The container need not exist locally and the result may
110      * include entries that do not exist locally and may not include all local
111      * children. An empty list is returned if the remote resource which
112      * corresponds to the container is empty. A <code>null</code> is
113      * returned if the remote does not exist. An exception is thrown if the
114      * corresponding remote is not capable of having members.
115      * <p>
116      * This method may be long running as a server may need to be contacted to
117      * obtain the members of the containers corresponding remote resource.
118      * </p>
119      * 
120      * @param container the local container
121      * @param monitor a progress monitor, or <code>null</code> if progress
122      *    reporting is not desired
123      * @return a list of member resources whose corresponding remote resources
124      *    are members of the remote counterpart of the given container or
125      *    <code>null</code> if the remote does not exist.
126      * @exception CoreException if the members could not be fetched. Reasons include:
127      * <ul>
128      * <li>The corresponding remote resource is not a container
129      *    (status code will be IResourceStatus.RESOURCE_WRONG_TYPE).</li>
130      * </ul>
131      */
132     public abstract IResource[] fetchMembers(IContainer container, IProgressMonitor monitor) throws CoreException;
133 
134     /**
135      * Refresh the known remote state for any resources covered by the given traversals.
136      * Clients who require the latest remote state should invoke this method before
137      * invoking any others of the class. Mappings can use this method as a hint to the
138      * context provider of which resources will be required for the mapping to generate
139      * the proper set of traversals. 
140      * <p>
141      * Note that this is really only a hint to the context provider.
142      * It is up to implementors to decide, based on the provided traversals, how to efficiently
143      * perform the refresh. In the ideal case, calls to {@link #contentDiffers} and {@link #fetchMembers}
144      * would not need to contact the server after a call to a refresh with appropriate traversals. Also, ideally, 
145      * if {@link #FILE_CONTENTS_REQUIRED} is on of the flags, then the contents for these files will be chached as efficiently
146      * as possible so that calls to {@link #fetchContents} will also not need to contact the server. This may
147      * not be possible for all context providers, so clients cannot assume that the above mentioed methods will not
148      * be long running. It is still advisably for clients to call {@link #refresh} with as much details
149      * as possible since, in the case where a provider is optimized performance will be much better.
150      * </p>
151      * 
152      * @param traversals the resource traversals which indicate which resources are to be refreshed
153      * @param flags additional refresh behavior. For instance, if <code>FILE_CONTENTS_REQUIRED</code> 
154      *      is one of the flags, this indicates that the client will be accessing the contents of
155      *      the files covered by the traversals. <code>NONE</code> shoudl be used when no additional
156      *      behavior is required
157      * @param monitor a progress monitor, or <code>null</code> if progress
158      *    reporting is not desired
159      * @exception CoreException if the members could not be fetched.
160      */
161     public abstract void refresh(ResourceTraversal[] traversals, int flags, IProgressMonitor monitor) throws CoreException;
162 
163 }
164
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags