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