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