KickJava   Java API By Example, From Geeks To Geeks.

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


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.runtime.*;
14 import org.eclipse.core.runtime.jobs.ISchedulingRule;
15
16 /**
17  * The purpose of this interface is to provide support for model level
18  * auto-merging. It is helpful in the cases where a file may contain multiple
19  * model elements or a model element consists of multiple files. It can also be
20  * used for cases where there is a one-to-one mapping between model elements and
21  * files, although <code>IStreamMerger</code> can also be used in that case.
22  *
23  * Clients should group resource mappings by model provider and then attempt to
24  * obtain a merger from the model provider using the adaptable mechanism as
25  * follows:
26  *
27  * <pre>
28  * Object o = mapping.getModelProvider().getAdapter(IResourceMappingMerger.class);
29  * if (o instanceof IResourceMappingMerger.class) {
30  * IResourceMappingMerger merger = (IResourceMappingMerger)o;
31  * ...
32  * }
33  * </pre>
34  *
35  * <p>
36  * Clients are not expected to implement this interface but should subclass
37  * {@link ResourceMappingMerger} instead.
38  *
39  * @see ResourceMappingMerger
40  * @see IStorageMerger
41  * @see org.eclipse.core.resources.mapping.ResourceMapping
42  * @see org.eclipse.core.resources.mapping.ModelProvider
43  * @see org.eclipse.team.core.mapping.IMergeContext
44  *
45  * @since 3.2
46  */
47 public interface IResourceMappingMerger {
48
49     /**
50      * Attempt to automatically merge the mappings of the merge context(<code>MergeContext#getMappings()</code>).
51      * The merge context provides access to the out-of-sync resources (<code>MergeContext#getSyncInfoTree()</code>)
52      * associated with the mappings to be merged. The set of provided mappings
53      * may come from multiple model providers. A particular implementation of
54      * this interface should only merge the mappings associated with their model
55      * provider. Also, the set of resources may contain additional resources
56      * that are not part of the mappings being merged. Implementors of this
57      * interface should use the mappings to determine which resources to merge
58      * and what additional semantics can be used to attempt the merge.
59      * <p>
60      * The type of merge to be performed depends on what is returned by the
61      * <code>MergeContext#getType()</code> method. If the type is
62      * <code>MergeContext.TWO_WAY</code> the merge will replace the local
63      * contents with the remote contents, ignoring any local changes. For
64      * <code>THREE_WAY</code>, the base is used to attempt to merge remote
65      * changes with local changes.
66      * <p>
67      * If merging was not possible for one or more of the mappings to which this
68      * merge applies, these mappings should be returned in an
69      * <code>MergeStatus</code> whose code is
70      * <code>MergeStatus.CONFLICTS</code> and which provides access to the
71      * mappings which could not be merged. Note that it is up to the model to
72      * decide whether it wants to break one of the provided resource mappings
73      * into several sub-mappings and attempt auto-merging at that level.
74      *
75      * @param mergeContext a context that provides access to the resources
76      * involved in the merge. The context must not be
77      * <code>null</code>.
78      * @param monitor a progress monitor
79      * @return a status indicating the results of the operation. A code of
80      * <code>MergeStatus.CONFLICTS</code> indicates that some or all
81      * of the resource mappings could not be merged. The mappings that
82      * were not merged are available using
83      * <code>MergeStatus#getConflictingMappings()</code>
84      * @throws CoreException if errors occurred
85      */
86     public IStatus merge(IMergeContext mergeContext,
87             IProgressMonitor monitor) throws CoreException;
88     
89     /**
90      * Return the scheduling rule that is required to merge
91      * all the changes that apply to this merger in the given
92      * context. When calling {@link #merge(IMergeContext, IProgressMonitor)},
93      * lients must ensure that they either have obtained
94      * a rule that covers the rule returned by this method or
95      * they must not hold any rule.
96      * @param context the context that contains the changes to be merged
97      * @return the scheduling rule required by this merger to merge all
98      * the changes in the gibven context belonging to the merger's
99      * model provider.
100      */
101     public ISchedulingRule getMergeRule(IMergeContext context);
102     
103     /**
104      * Validate an auto-merge for the given context. This
105      * method must be invoked for all mergers involved
106      * in the merge before the auto-merge is attempted.
107      * The purpose of the validation is to indicate whether there
108      * are conditions in the merge context that make an auto-merge
109      * undesirable. The purpose is not to indicate that conflicts
110      * exist (this is done by the <code>merge</code> method) but instead
111      * to indicate that the nature of one of more incoming changes
112      * is such that performing an auto-merge may be undesirable.
113      * <p>
114      * Clients should validate before performing the merge and, if
115      * any of the returned status are not OK, should prompt the
116      * user to make them aware of the potential side effects.
117      * The user may still decide to attempt an auto-merge, in which case
118      * the client may still invoke the <code>merge</code> method.
119      *
120      * @param mergeContext a context that provides access to the resources
121      * involved in the merge. The context must not be
122      * <code>null</code>.
123      * @param monitor a progress monitor
124      * @return a status indicating any potential side effects of
125      * performing an auto-merge.
126      */
127     public IStatus validateMerge(IMergeContext mergeContext,
128             IProgressMonitor monitor);
129
130 }
131
Popular Tags