org.eclipse.compare.structuremergeviewer.IStructureCreator Maven / Gradle / Ivy
/*******************************************************************************
* Copyright (c) 2000, 2011 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.compare.structuremergeviewer;
/**
* Interface used to create a hierarchical structure of
* IStructureComparators 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.
*
* Structure creators are used in the following contexts:
*
* -
* the
StructureDiffViewer uses an IStructureCreator to
* build two (or three) tree structures of its input elements (method getStructure).
* These trees are then compared with each other by means of the differencing engine and displayed
* with the DiffTreeViewer,
*
* -
* the
ReplaceWithEditionDialog uses an IStructureCreator
* to map a path back to a range of characters in the textual representation.
*
*
* A IStructureCreator 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.
*
*
* Clients may implement this interface; there is no standard implementation.
*
*
* @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 StructureDiffViewer.
*
* @return a descriptive name for this IStructureCreator
*/
String getName();
/**
* Creates a tree structure consisting of IStructureComparators
* 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 null is returned.
*
* @param input the object from which to create the tree of IStructureComparator
* @return the root node of the structure or null 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 null is returned.
* This method is similar to getStructure but in
* contrast to getStructure only a single node without any children must be returned.
* This method is used in the ReplaceWithEditionDialog to locate a sub element
* (e.g. a method) within an input object (e.g. a file containing source code).
*
* One (not optimized) approach to implement this method is calling getStructure(input)
* to build the full tree, and then finding that node within the tree that is specified
* by path.
*
* The syntax of path 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 path to the selectEdition
* method of ReplaceWithEditionDialog and will receive this value unchanged
* as an argument to locate.
*
* @param path specifies a sub object within the input object
* @param input the object from which to create the IStructureComparator
* @return the single node specified by path or null
*
*/
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 ignoreWhitespace is true 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 true the returned string should not contain whitespace
* @return the string contents of the given node
*/
String getContents(Object node, boolean ignoreWhitespace);
/**
* 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 getStructure
*/
void save(IStructureComparator node, Object input);
}