KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > compare > structuremergeviewer > ICompareInput


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 import org.eclipse.compare.ITypedElement;
14 import org.eclipse.swt.graphics.Image;
15
16 /**
17  * Interface for objects used as input to a two-way or three-way compare viewer.
18  * It defines API for accessing the three sides for the compare,
19  * and a name and image which is used when displaying the three way input
20  * in the UI, for example, in a title bar.
21  * <p>
22  * Note: at most two sides of an <code>ICompareInput</code> can be <code>null</code>,
23  * (as it is normal for additions or deletions) but not all three.
24  * <p>
25  * <code>ICompareInput</code> provides methods for registering
26  * <code>ICompareInputChangeListener</code>s
27  * that get informed if one (or more)
28  * of the three sides of an <code>ICompareInput</code> object changes its value.
29  * <p>
30  * For example when accepting an incoming addition
31  * the (non-<code>null</code>) left side of an <code>ICompareInput</code>
32  * is copied to the right side by means of method <code>copy</code>.
33  * This should trigger a call to <code>compareInputChanged</code> of registered
34  * <code>ICompareInputChangeListener</code>s.
35  * <p>
36  * Clients can implement this interface, or use the convenience implementation
37  * <code>DiffNode</code>.
38  * </p>
39  *
40  * @see StructureDiffViewer
41  * @see org.eclipse.compare.contentmergeviewer.ContentMergeViewer
42  * @see DiffNode
43  */
44 public interface ICompareInput {
45
46     /**
47      * Returns name of input.
48      * This name is displayed when this input is shown in a viewer.
49      * In many cases this name is the name of one of the non-<code>null</code> sides or a combination
50      * thereof.
51      *
52      * @return name of input
53      */
54     String JavaDoc getName();
55     
56     /**
57      * Returns an image representing this input.
58      * This image is typically displayed when this input is shown in a viewer.
59      * In many cases this image is the image of one of the non-<code>null</code> sides.
60      *
61      * @return image representing this input, or <code>null</code> if no icon should be shown
62      */
63     Image getImage();
64
65     /**
66      * Returns the kind of difference between the
67      * three sides ancestor, left and right.
68      * This field is only meaningful if the <code>ICompareInput</code>
69      * is the result of another compare. In this case it is used
70      * together with <code>getImage</code> to compose a icon
71      * which reflects the kind of difference between the two or three elements.
72      *
73      * @return kind of difference (see <code>Differencer</code>)
74      */
75     int getKind();
76     
77     /**
78      * Returns the ancestor side of this input.
79      * Returns <code>null</code> if this input has no ancestor
80      * or in the two-way compare case.
81      *
82      * @return the ancestor of this input, or <code>null</code>
83      */
84     ITypedElement getAncestor();
85     
86     /**
87      * Returns the left side of this input.
88      * Returns <code>null</code> if there is no left side (deletion or addition).
89      *
90      * @return the left side of this input, or <code>null</code>
91      */
92     ITypedElement getLeft();
93     
94     /**
95      * Returns the right side of this input.
96      * Returns <code>null</code> if there is no right side (deletion or addition).
97      *
98      * @return the right side of this input, or <code>null</code>
99      */
100     ITypedElement getRight();
101     
102     /**
103      * Registers the given listener for notification.
104      * If the identical listener is already registered the method has no effect.
105      *
106      * @param listener the listener to register for changes of this input
107      */
108     void addCompareInputChangeListener(ICompareInputChangeListener listener);
109     
110     /**
111      * Unregisters the given listener.
112      * If the identical listener is not registered the method has no effect.
113      *
114      * @param listener the listener to unregister
115      */
116     void removeCompareInputChangeListener(ICompareInputChangeListener listener);
117     
118     /**
119      * Copy one side (source) to the other side (destination) depending on the
120      * value of <code>leftToRight</code>. This method is called from
121      * a merge viewer if a corresponding action ("take left" or "take right")
122      * has been pressed.
123      * <p>
124      * The implementation should handle the following cases:
125      * <UL>
126      * <LI>
127      * if the source side is <code>null</code> the destination must be deleted,
128      * <LI>
129      * if the destination is <code>null</code> the destination must be created
130      * and filled with the contents from the source,
131      * <LI>
132      * if both sides are non-<code>null</code> the contents of source must be copied to destination.
133      * </UL>
134      * In addition the implementation should send out notification to the registered
135      * <code>ICompareInputChangeListener</code>.
136      *
137      * @param leftToRight if <code>true</code> the left side is copied to the right side.
138      * If <code>false</code> the right side is copied to the left side
139      */
140     void copy(boolean leftToRight);
141 }
142
143
Popular Tags