KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > team > core > mapping > ISynchronizationContext


1 /*******************************************************************************
2  * Copyright (c) 2000, 2006 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.team.core.mapping;
12
13 import org.eclipse.core.resources.IResource;
14 import org.eclipse.core.resources.mapping.ResourceMapping;
15 import org.eclipse.core.resources.mapping.ResourceTraversal;
16 import org.eclipse.core.runtime.CoreException;
17 import org.eclipse.core.runtime.IProgressMonitor;
18 import org.eclipse.core.runtime.jobs.IJobManager;
19 import org.eclipse.team.core.ICache;
20 import org.eclipse.team.core.diff.*;
21 import org.eclipse.team.core.mapping.provider.MergeContext;
22 import org.eclipse.team.core.mapping.provider.SynchronizationContext;
23
24 /**
25  * Allows a model provider to build a view of their model that includes
26  * synchronization information with a remote location (usually a repository).
27  * <p>
28  * The scope of the context is defined when the context is created. The creator
29  * of the scope may affect changes on the scope which will result in property
30  * change events from the scope and may result in change events from
31  * the diff tree. Clients should note that it is possible that a change in
32  * the scope will result in new resources with differences being covered by the scope
33  * but not result in a change event from the diff tree. This can
34  * occur because the set may already have contained a diff for the resource
35  * with the understanding that the client would have ignored it. Consequently,
36  * clients should listen to both sources in order to guarantee that they update
37  * any dependent state appropriately.
38  * <p>
39  * <a name="async">The diff tree associated with this context may be updated asynchronously in response
40  * to calls to any method of this context (e.g. refresh methods) that may result in changes
41  * in the synchronization state of resources. It may also get updated as a result
42  * of changes triggered from other sources. Hence, the callback from the diff tree
43  * to report changes may occur in the same thread as the method call or
44  * asynchronously in a separate thread, regardless of who triggered the refresh.
45  * Clients of this method (and any other asynchronous method on this context) may
46  * determine if all changes have been collected using {@link IJobManager#find(Object)}
47  * using this context as the <code>family</code> argument in order to determine
48  * if there are any jobs running that are populating the diff tree. Clients may also
49  * call {@link IJobManager#join(Object, IProgressMonitor)} if they wish to wait until
50  * all background handlers related to this context are finished.
51  * </p>
52  * <p>
53  * This interface is not intended to be implemented by clients. They should subclass
54  * {@link SynchronizationContext} or one of its subclasses instead.
55  *
56  * @see SynchronizationContext
57  * @see MergeContext
58  *
59  * @since 3.2
60  */
61 public interface ISynchronizationContext {
62
63     /**
64      * Synchronization type constant that indicates that
65      * context is a two-way synchronization.
66      */
67     public final static int TWO_WAY = 2;
68
69     /**
70      * Synchronization type constant that indicates that
71      * context is a three-way synchronization.
72      */
73     public final static int THREE_WAY = 3;
74
75     /**
76      * Return the input that defined the scope of this synchronization context.
77      * The input determines the set of resources to which the context applies.
78      * Changes in the input may result in changes to the sync-info available in
79      * the tree of this context.
80      *
81      * @return the input that defined the scope of this synchronization context.
82      */
83     ISynchronizationScope getScope();
84
85     /**
86      * Return a tree that contains {@link IDiff} entries for resources that
87      * are out-of-sync. The tree will contain entries for any out-of-sync
88      * resources that are within the scope of this context. The tree may include
89      * entries for additional resources, which should be ignored by the client.
90      * Clients can test for inclusion using the method
91      * {@link ISynchronizationScope#contains(IResource)}.
92      * <p>
93      * The returned {@link IResourceDiffTree} will be homogeneous and contain either
94      * {@link IResourceDiff} or {@link IThreeWayDiff} instances. Any
95      * {@link IThreeWayDiff} contained in the returned tree will contain
96      * {@link IResourceDiff} instances as the local and remote changes. This
97      * interface also has several helper methods for handling entries contained in
98      * the returned diff tree.
99      *
100      * @return a tree that contains an entry for any
101      * resources that are out-of-sync.
102      * @see IResourceDiffTree#getDiffs(ResourceTraversal[])
103      * @see IResourceDiffTree#getResource(IDiff)
104      */
105     public IResourceDiffTree getDiffTree();
106
107     /**
108      * Return the synchronization type. A type of <code>TWO_WAY</code>
109      * indicates that the synchronization information associated with the
110      * context will also be two-way {@link IDiff} instances (i.e. there is
111      * only a remote but no base involved in the comparison used to determine
112      * the synchronization state of resources. A type of <code>THREE_WAY</code>
113      * indicates that the synchronization information will be three-way
114      * {@link IThreeWayDiff} instances.
115      *
116      * @return the type of synchronization information available in the context
117      *
118      * @see IDiff
119      * @see IThreeWayDiff
120      */
121     public int getType();
122
123     /**
124      * Return the cache associated with this synchronization context.
125      * The cache is maintained for the lifetime of this context and is
126      * disposed when the the context is disposed. It can be used by
127      * clients to cache model state related to the context so that it can
128      * be maintained for the life of the operation to which the context
129      * applies.
130      * @return the cache associated with this synchronization context
131      */
132     public ICache getCache();
133
134     /**
135      * Dispose of the synchronization context and the cache of the context. This
136      * method should be invoked by clients when the context is no longer needed.
137      */
138     public void dispose();
139
140     /**
141      * Refresh the context in order to update the diff tree returned by
142      * {@link #getDiffTree()} to include the latest synchronization state for
143      * the resources. Any changes will be reported through the change listeners
144      * registered with the diff tree of this context.
145      * <p>
146      * Changes to the diff tree may be triggered by a call to this method or by a
147      * refresh triggered by some other source. Hence, the callback from the diff tree
148      * to report changes may occur in the same thread as the refresh or
149      * <a HREF="#async">asynchronously</a> in a separate thread, regardless of who triggered
150      * the refresh.
151      *
152      * @see #getDiffTree()
153      * @see IDiffTree#addDiffChangeListener(IDiffChangeListener)
154      *
155      * @param traversals
156      * the resource traversals which indicate which resources are to
157      * be refreshed
158      * @param flags
159      * additional refresh behavior. For instance, if
160      * <code>RemoteResourceMappingContext.FILE_CONTENTS_REQUIRED</code>
161      * is one of the flags, this indicates that the client will be
162      * accessing the contents of the files covered by the traversals.
163      * <code>NONE</code> should be used when no additional behavior
164      * is required
165      * @param monitor
166      * a progress monitor, or <code>null</code> if progress
167      * reporting is not desired
168      * @throws CoreException
169      * if the refresh fails. Reasons include:
170      * <ul>
171      * <li>The server could not be contacted for some reason (e.g.
172      * the context in which the operation is being called must be
173      * short running). The status code will be
174      * SERVER_CONTACT_PROHIBITED. </li>
175      * </ul>
176      */
177     public void refresh(ResourceTraversal[] traversals, int flags,
178             IProgressMonitor monitor) throws CoreException;
179
180     /**
181      * Refresh the portion of the context related to the given resource
182      * mappings. The provided mappings must be within the scope of this context.
183      * Refreshing mappings may result in additional resources being added to the
184      * scope of this context. If new resources are included in the scope, a
185      * property change event will be fired from the scope. If the
186      * synchronization state of any of the resources covered by the mapping
187      * change, a change event will be fired from the diff tree of this context.
188      * <p>
189      * Changes to the diff tree may be triggered by a call to this method or by
190      * a refresh triggered by some other source. Hence, the callback from the
191      * diff tree to report changes may occur in the same thread as the refresh
192      * or <a HREF="#async">asynchronously</a> in a separate thread, regardless
193      * of who triggered the refresh.
194      *
195      * @param mappings
196      * the mappings to be refreshed
197      * @param monitor
198      * a progress monitor
199      * @throws CoreException
200      * if errors occur
201      */
202     public void refresh(ResourceMapping[] mappings, IProgressMonitor monitor)
203             throws CoreException;
204
205 }
206
Popular Tags