blob: 8c5c7ce0fd3b37c3a8e73f92869330c4b39d5576 (
plain) (
blame)
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
|
/*
* (c) Copyright IBM Corp. 2000, 2001.
* All Rights Reserved.
*/
package org.eclipse.compare.structuremergeviewer;
import org.eclipse.compare.ITypedElement;
import org.eclipse.jface.text.IDocument;
/**
* For creating a hierarchical structure of <code>IStructureComparators</code> for a
* given input object.
* In addition, it provides methods for locating a path in the hierarchical structure
* and to map a node of this structure back to the corresponding input object.
* <p>
* Structure creators are used in the following contexts:
* <ul>
* <li>
* the <code>StructureDiffViewer</code> uses an <code>IStructureCreator</code> to
* build two (or three) tree structures of its input elements (method <code>getStructure</code>).
* These trees are then compared with each other by means of the differencing engine and displayed
* with the <code>DiffTreeViewer</code>,
* </li>
* <li>
* the <code>ReplaceWithEditionDialog</code> uses an <code>IStructureCreator</code>
* to map a path back to a range of characters in the textual representation.
* </li>
* </ul>
* A <code>IStructureCreator</code> provides methods for rewriting the tree produced by the differencing
* engine to support "smart" structural differencing. E.g. certain patterns of pairs of "addition"
* and "deletion" nodes can be detected as renames and merged into a single node.
* </p>
* <p>
* Clients may implement this interface; there is no standard implementation.
* </p>
*
* @see StructureDiffViewer
* @see org.eclipse.compare.EditionSelectionDialog
* @see Differencer
*/
public interface IStructureCreator {
/**
* Returns a descriptive name which can be used in the UI of the <code>StructureDiffViewer</code>.
*
* @return a descriptive name for this <code>IStructureCreator</code>
*/
String getName();
/**
* Creates a tree structure consisting of <code>IStructureComparator</code>s
* from the given object and returns its root object.
* Implementing this method typically involves parsing the input object.
* In case of an error (e.g. a parsing error) the value <code>null</code> is returned.
*
* @param input the object from which to create the tree of <code>IStructureComparator</code>
* @return the root node of the structure or <code>null</code> in case of error
*/
IStructureComparator getStructure(Object input);
/**
* Creates the single node specified by path from the given input object.
* In case of an error (e.g. a parsing error) the value <code>null</code> is returned.
* This method is similar to <code>getStructure</code> but in
* contrast to <code>getStructure</code> only a single node without any children must be returned.
* This method is used in the <code>ReplaceWithEditionDialog</code> to locate a sub element
* (e.g. a method) within an input object (e.g. a file containing source code).
* <p>
* One (not optimized) approach to implement this method is calling <code>getStructure(input)</code>
* to build the full tree, and then finding that node within the tree that is specified
* by <code>path</code>.
* <p>
* The syntax of <code>path</code> is not specified, because it is treated by the compare subsystem
* as an opaque entity and is not further interpreted. Clients using this functionality
* will pass a value of <code>path</code> to the <code>selectEdition</code>
* method of <code>ReplaceWithEditionDialog</code> and will receive this value unchanged
* as an argument to <code>locate</code>.
*
* @param path specifies a sub object within the input object
* @param input the object from which to create the <code>IStructureComparator</code>
* @return the single node specified by <code>path</code> or <code>null</code>
*
* @see org.eclipse.compare.EditionSelectionDialog#selectEdition
*/
IStructureComparator locate(Object path, Object input);
/**
* Returns the contents of the given node as a string for the purpose
* of performing a content comparison only (that is the string will not be visible in the UI).
* If <code>ignoreWhitespace</code> is <code>true</code> all character sequences considered
* whitespace should be removed from the returned string.
*
* @param node the node for which to return a string representation
* @param ignoreWhitespace if <code>true</code> the returned string should not contain whitespace
* @return the string contents of the given node
*/
String getContents(Object node, boolean ignoreWhitespace);
/**
* Returns whether this structure creator supports tree rewriting.
* The <code>StructureDiffViewer</code> uses this method to determine
* whether to enable a "smart" button in the UI and whether to call
* the <code>rewriteTree</code> method.
*
* @return <code>true</code> if this structure creator supports tree rewriting
*/
boolean canRewriteTree();
/**
* Rewrites the tree.
* This method is only called if <code>canRewriteTree</code>
* returns <code>true</code>, and only after the difference engine has constructed the diff tree.
* Implementation of this method may perform tree rewriting such as merging
* separate but related diff elements into a single node.
*
* @param differencer the differencing engine which was used to construct the diff tree
* @param root the root of the tree returned from the differencing engine
*/
void rewriteTree(Differencer differencer, IDiffContainer root);
/**
* FIXME: need better name?
* Called whenever a copy operation has been performed on a tree node.
*
* @param node the node for which to save the new content
* @param input the object from which the structure tree was created in <code>getStructure</code>
*/
void save(IStructureComparator node, Object input);
}
|
