KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > jface > bindings > Scheme


1 /*******************************************************************************
2  * Copyright (c) 2004, 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
12 package org.eclipse.jface.bindings;
13
14 import java.util.HashSet JavaDoc;
15 import java.util.Iterator JavaDoc;
16 import java.util.Set JavaDoc;
17
18 import org.eclipse.core.commands.common.NamedHandleObject;
19 import org.eclipse.core.commands.common.NotDefinedException;
20 import org.eclipse.jface.util.Util;
21
22 /**
23  * <p>
24  * An instance of <code>IScheme</code> is a handle representing a binding
25  * scheme as defined by the extension point <code>org.eclipse.ui.bindings</code>.
26  * The identifier of the handle is the identifier of the scheme being represented.
27  * </p>
28  * <p>
29  * An instance of <code>IScheme</code> can be obtained from an instance of
30  * <code>ICommandManager</code> for any identifier, whether or not a scheme
31  * with that identifier is defined in the plugin registry.
32  * </p>
33  * <p>
34  * The handle-based nature of this API allows it to work well with runtime
35  * plugin activation and deactivation. If a scheme is defined, that means that
36  * its corresponding plug-in is active. If the plug-in is then deactivated, the
37  * scheme will still exist but it will be undefined. An attempt to use an
38  * undefined scheme will result in a <code>NotDefinedException</code>
39  * being thrown.
40  * </p>
41  * <p>
42  * This class is not intended to be extended by clients.
43  * </p>
44  *
45  * @since 3.1
46  * @see ISchemeListener
47  * @see org.eclipse.core.commands.CommandManager
48  */

49 public final class Scheme extends NamedHandleObject implements Comparable JavaDoc {
50
51     /**
52      * The collection of all objects listening to changes on this scheme. This
53      * value is <code>null</code> if there are no listeners.
54      */

55     private Set JavaDoc listeners = null;
56
57     /**
58      * The parent identifier for this scheme. This is the identifier of the
59      * scheme from which this scheme inherits some of its bindings. This value
60      * can be <code>null</code> if the scheme has no parent.
61      */

62     private String JavaDoc parentId = null;
63
64     /**
65      * Constructs a new instance of <code>Scheme</code> with an identifier.
66      *
67      * @param id
68      * The identifier to create; must not be <code>null</code>.
69      */

70     Scheme(final String JavaDoc id) {
71         super(id);
72     }
73
74     /**
75      * Registers an instance of <code>ISchemeListener</code> to listen for
76      * changes to attributes of this instance.
77      *
78      * @param schemeListener
79      * the instance of <code>ISchemeListener</code> to register.
80      * Must not be <code>null</code>. If an attempt is made to
81      * register an instance of <code>ISchemeListener</code> which
82      * is already registered with this instance, no operation is
83      * performed.
84      */

85     public final void addSchemeListener(final ISchemeListener schemeListener) {
86         if (schemeListener == null) {
87             throw new NullPointerException JavaDoc("Can't add a null scheme listener."); //$NON-NLS-1$
88
}
89
90         if (listeners == null) {
91             listeners = new HashSet JavaDoc();
92         }
93
94         listeners.add(schemeListener);
95     }
96
97     /*
98      * (non-Javadoc)
99      *
100      * @see java.lang.Comparable#compareTo(java.lang.Object)
101      */

102     public final int compareTo(final Object JavaDoc object) {
103         final Scheme scheme = (Scheme) object;
104         int compareTo = Util.compare(this.id, scheme.id);
105         if (compareTo == 0) {
106             compareTo = Util.compare(this.name, scheme.name);
107             if (compareTo == 0) {
108                 compareTo = Util.compare(this.parentId, scheme.parentId);
109                 if (compareTo == 0) {
110                     compareTo = Util.compare(this.description,
111                             scheme.description);
112                     if (compareTo == 0) {
113                         compareTo = Util.compare(this.defined, scheme.defined);
114                     }
115                 }
116             }
117         }
118
119         return compareTo;
120     }
121
122     /**
123      * <p>
124      * Defines this scheme by giving it a name, and possibly a description and a
125      * parent identifier as well. The defined property for the scheme automatically
126      * becomes <code>true</code>.
127      * </p>
128      * <p>
129      * Notification is sent to all listeners that something has changed.
130      * </p>
131      *
132      * @param name
133      * The name of this scheme; must not be <code>null</code>.
134      * @param description
135      * The description for this scheme; may be <code>null</code>.
136      * @param parentId
137      * The parent identifier for this scheme; may be
138      * <code>null</code>.
139      */

140     public final void define(final String JavaDoc name, final String JavaDoc description,
141             final String JavaDoc parentId) {
142         if (name == null) {
143             throw new NullPointerException JavaDoc(
144                     "The name of a scheme cannot be null"); //$NON-NLS-1$
145
}
146
147         final boolean definedChanged = !this.defined;
148         this.defined = true;
149
150         final boolean nameChanged = !Util.equals(this.name, name);
151         this.name = name;
152
153         final boolean descriptionChanged = !Util.equals(this.description,
154                 description);
155         this.description = description;
156
157         final boolean parentIdChanged = !Util.equals(this.parentId, parentId);
158         this.parentId = parentId;
159
160         fireSchemeChanged(new SchemeEvent(this, definedChanged, nameChanged,
161                 descriptionChanged, parentIdChanged));
162     }
163
164     /**
165      * Notifies all listeners that this scheme has changed. This sends the given
166      * event to all of the listeners, if any.
167      *
168      * @param event
169      * The event to send to the listeners; must not be
170      * <code>null</code>.
171      */

172     private final void fireSchemeChanged(final SchemeEvent event) {
173         if (event == null) {
174             throw new NullPointerException JavaDoc(
175                     "Cannot send a null event to listeners."); //$NON-NLS-1$
176
}
177
178         if (listeners == null) {
179             return;
180         }
181
182         final Iterator JavaDoc listenerItr = listeners.iterator();
183         while (listenerItr.hasNext()) {
184             final ISchemeListener listener = (ISchemeListener) listenerItr
185                     .next();
186             listener.schemeChanged(event);
187         }
188     }
189
190     /**
191      * <p>
192      * Returns the identifier of the parent of the scheme represented by this
193      * handle.
194      * </p>
195      * <p>
196      * Notification is sent to all registered listeners if this attribute
197      * changes.
198      * </p>
199      *
200      * @return the identifier of the parent of the scheme represented by this
201      * handle. May be <code>null</code>.
202      * @throws NotDefinedException
203      * if the scheme represented by this handle is not defined.
204      */

205     public final String JavaDoc getParentId() throws NotDefinedException {
206         if (!defined) {
207             throw new NotDefinedException(
208                     "Cannot get the parent identifier from an undefined scheme. " //$NON-NLS-1$
209
+ id);
210         }
211
212         return parentId;
213     }
214
215     /**
216      * Unregisters an instance of <code>ISchemeListener</code> listening for
217      * changes to attributes of this instance.
218      *
219      * @param schemeListener
220      * the instance of <code>ISchemeListener</code> to unregister.
221      * Must not be <code>null</code>. If an attempt is made to
222      * unregister an instance of <code>ISchemeListener</code> which
223      * is not already registered with this instance, no operation is
224      * performed.
225      */

226     public final void removeSchemeListener(final ISchemeListener schemeListener) {
227         if (schemeListener == null) {
228             throw new NullPointerException JavaDoc("Cannot remove a null listener."); //$NON-NLS-1$
229
}
230
231         if (listeners == null) {
232             return;
233         }
234
235         listeners.remove(schemeListener);
236
237         if (listeners.isEmpty()) {
238             listeners = null;
239         }
240     }
241
242     /**
243      * The string representation of this command -- for debugging purposes only.
244      * This string should not be shown to an end user.
245      *
246      * @return The string representation; never <code>null</code>.
247      */

248     public final String JavaDoc toString() {
249         if (string == null) {
250             final StringBuffer JavaDoc stringBuffer = new StringBuffer JavaDoc();
251             stringBuffer.append("Scheme("); //$NON-NLS-1$
252
stringBuffer.append(id);
253             stringBuffer.append(',');
254             stringBuffer.append(name);
255             stringBuffer.append(',');
256             stringBuffer.append(description);
257             stringBuffer.append(',');
258             stringBuffer.append(parentId);
259             stringBuffer.append(',');
260             stringBuffer.append(defined);
261             stringBuffer.append(')');
262             string = stringBuffer.toString();
263         }
264         return string;
265     }
266
267     /**
268      * Makes this scheme become undefined. This has the side effect of changing
269      * the name, description and parent identifier to <code>null</code>.
270      * Notification is sent to all listeners.
271      */

272     public final void undefine() {
273         string = null;
274
275         final boolean definedChanged = defined;
276         defined = false;
277
278         final boolean nameChanged = name != null;
279         name = null;
280
281         final boolean descriptionChanged = description != null;
282         description = null;
283
284         final boolean parentIdChanged = parentId != null;
285         parentId = null;
286
287         fireSchemeChanged(new SchemeEvent(this, definedChanged, nameChanged,
288                 descriptionChanged, parentIdChanged));
289     }
290 }
291
Popular Tags