org.eclipse.compare.structuremergeviewer.IStructureCreator Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of org.eclipse.compare Show documentation
This is org.eclipse.compare jar used by Scout SDK
The newest version!
/*******************************************************************************
 * 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);
}