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  ;
15  import java.util.Iterator  ;
16  import java.util.Set  ;
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   {
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   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   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   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  ("Can't add a null scheme listener."); //$NON-NLS-1$
88          }
89  
90          if (listeners == null) {
91              listeners = new HashSet  ();
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   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   name, final String   description,
141             final String   parentId) {
142         if (name == null) {
143             throw new NullPointerException  (
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  (
175                     "Cannot send a null event to listeners."); //$NON-NLS-1$
176         }
177 
178         if (listeners == null) {
179             return;
180         }
181 
182         final Iterator   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   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  ("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   toString() {
249         if (string == null) {
250             final StringBuffer   stringBuffer = new StringBuffer  ();
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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags