blob: d3e9f3c7fbb5b1f1163be0db254fe4c2a6a3713e (
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
|
/*
* (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);
/**
* 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);
}
|
