IStructureCreator


1   /*******************************************************************************
2    * Copyright (c) 2000, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.compare.structuremergeviewer;
12  
13  /**
14   * Interface used to create a hierarchical structure of
15   * <code>IStructureComparator</code>s for a given input object.
16   * In addition, it provides methods for locating a path in the hierarchical structure
17   * and to map a node of this structure back to the corresponding input object.
18   * <p>
19   * Structure creators are used in the following contexts:
20   * <ul>
21   * <li>
22   * the <code>StructureDiffViewer</code> uses an <code>IStructureCreator</code> to
23   * build two (or three) tree structures of its input elements (method <code>getStructure</code>).
24   * These trees are then compared with each other by means of the differencing engine and displayed
25   * with the <code>DiffTreeViewer</code>,
26   * </li>
27   * <li>
28   * the <code>ReplaceWithEditionDialog</code> uses an <code>IStructureCreator</code>
29   * to map a path back to a range of characters in the textual representation.
30   * </li>
31   * </ul>
32   * A <code>IStructureCreator</code> provides methods for rewriting the tree produced by the differencing
33   * engine to support "smart" structural differencing. E.g. certain patterns of pairs of "addition"
34   * and "deletion" nodes can be detected as renames and merged into a single node.
35   * </p>
36   * <p>
37   * Clients may implement this interface; there is no standard implementation.
38   * </p>
39   *
40   * @see StructureDiffViewer
41   * @see org.eclipse.compare.EditionSelectionDialog
42   * @see Differencer
43   */
44  public interface IStructureCreator {
45  
46      /**
47       * Returns a descriptive name which can be used in the UI of the <code>StructureDiffViewer</code>.
48       *
49       * @return a descriptive name for this <code>IStructureCreator</code>
50       */
51      String   getName();
52  
53      /**
54       * Creates a tree structure consisting of <code>IStructureComparator</code>s
55       * from the given object and returns its root object.
56       * Implementing this method typically involves parsing the input object.
57       * In case of an error (e.g. a parsing error) the value <code>null</code> is returned.
58       *
59       * @param input the object from which to create the tree of <code>IStructureComparator</code>
60       * @return the root node of the structure or <code>null</code> in case of error
61       */
62      IStructureComparator getStructure(Object   input);
63  
64      /**
65       * Creates the single node specified by path from the given input object.
66       * In case of an error (e.g. a parsing error) the value <code>null</code> is returned.
67       * This method is similar to <code>getStructure</code> but in
68       * contrast to <code>getStructure</code> only a single node without any children must be returned.
69       * This method is used in the <code>ReplaceWithEditionDialog</code> to locate a sub element
70       * (e.g. a method) within an input object (e.g. a file containing source code).
71       * <p>
72       * One (not optimized) approach to implement this method is calling <code>getStructure(input)</code>
73       * to build the full tree, and then finding that node within the tree that is specified
74       * by <code>path</code>.
75       * <p>
76       * The syntax of <code>path</code> is not specified, because it is treated by the compare subsystem
77       * as an opaque entity and is not further interpreted. Clients using this functionality
78       * will pass a value of <code>path</code> to the <code>selectEdition</code>
79       * method of <code>ReplaceWithEditionDialog</code> and will receive this value unchanged
80       * as an argument to <code>locate</code>.
81       *
82       * @param path specifies a sub object within the input object
83       * @param input the object from which to create the <code>IStructureComparator</code>
84       * @return the single node specified by <code>path</code> or <code>null</code>
85       *
86       * @see org.eclipse.compare.EditionSelectionDialog#selectEdition
87       */
88      IStructureComparator locate(Object   path, Object   input);
89  
90      /**
91       * Returns the contents of the given node as a string for the purpose
92       * of performing a content comparison only (that is the string will not be visible in the UI).
93       * If <code>ignoreWhitespace</code> is <code>true</code> all character sequences considered
94       * whitespace should be removed from the returned string.
95       *
96       * @param node the node for which to return a string representation
97       * @param ignoreWhitespace if <code>true</code> the returned string should not contain whitespace
98       * @return the string contents of the given node
99       */
100     String   getContents(Object   node, boolean ignoreWhitespace);
101 
102     /**
103      * Called whenever a copy operation has been performed on a tree node.
104      *
105      * @param node the node for which to save the new content
106      * @param input the object from which the structure tree was created in <code>getStructure</code>
107      */
108     void save(IStructureComparator node, Object   input);
109 }
110 
111
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags