Context


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.core.commands.contexts;
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.core.internal.commands.util.Util;
21  
22  /**
23   * <p>
24   * A context is an answer to the question "when". Other services can listen for
25   * the activation and deactivation of contexts, and change their own state in
26   * response to these changes. For example, Eclipse's key binding service listens
27   * to context activation and deactivation to determine which key bindings should
28   * be active.
29   * </p>
30   * <p>
31   * An instance of this interface can be obtained from an instance of
32   * <code>ContextManager</code> for any identifier, whether or not an context
33   * with that identifier is defined in the extension registry.
34   * </p>
35   * <p>
36   * The handle-based nature of this API allows it to work well with runtime
37   * plugin activation and deactivation. If a context is defined, that means that
38   * its corresponding plug-in is active. If the plug-in is then deactivated, the
39   * context will still exist but it will be undefined. An attempts to use an
40   * undefined context will result in a <code>NotDefinedException</code> being
41   * thrown.
42   * </p>
43   * <p>
44   * This class is not intended to be extended by clients.
45   * </p>
46   * 
47   * @since 3.1
48   * @see ContextManager
49   */
50  public final class Context extends NamedHandleObject implements Comparable   {
51  
52      /**
53       * The collection of all objects listening to changes on this context. This
54       * value is <code>null</code> if there are no listeners.
55       */
56      private Set   listeners = null;
57  
58      /**
59       * The parent identifier for this context. The meaning of a parent is
60       * dependent on the system using contexts. This value can be
61       * <code>null</code> if the context has no parent.
62       */
63      private String   parentId = null;
64  
65      /**
66       * Constructs a new instance of <code>Context</code>.
67       * 
68       * @param id
69       *            The id for this context; must not be <code>null</code>.
70       */
71      Context(final String   id) {
72          super(id);
73      }
74  
75      /**
76       * Registers an instance of <code>IContextListener</code> to listen for
77       * changes to properties of this instance.
78       * 
79       * @param listener
80       *            the instance to register. Must not be <code>null</code>. If
81       *            an attempt is made to register an instance which is already
82       *            registered with this instance, no operation is performed.
83       */
84      public final void addContextListener(final IContextListener listener) {
85          if (listener == null) {
86              throw new NullPointerException  ();
87          }
88  
89          if (listeners == null) {
90              listeners = new HashSet  ();
91          }
92  
93          listeners.add(listener);
94      } 
95      
96      /* (non-Javadoc)
97       * @see java.lang.Comparable#compareTo(java.lang.Object)
98       */
99      public final int compareTo(final Object   object) {
100         final Context scheme = (Context) object;
101         int compareTo = Util.compare(this.id, scheme.id);
102         if (compareTo == 0) {
103             compareTo = Util.compare(this.name, scheme.name);
104             if (compareTo == 0) {
105                 compareTo = Util.compare(this.parentId, scheme.parentId);
106                 if (compareTo == 0) {
107                     compareTo = Util.compare(this.description,
108                             scheme.description);
109                     if (compareTo == 0) {
110                         compareTo = Util.compare(this.defined, scheme.defined);
111                     }
112                 }
113             }
114         }
115 
116         return compareTo;
117     }
118 
119     /**
120      * <p>
121      * Defines this context by giving it a name, and possibly a description and
122      * a parent identifier as well. The defined property automatically becomes
123      * <code>true</code>.
124      * </p>
125      * <p>
126      * Notification is sent to all listeners that something has changed.
127      * </p>
128      * 
129      * @param name
130      *            The name of this context; must not be <code>null</code>.
131      * @param description
132      *            The description for this context; may be <code>null</code>.
133      * @param parentId
134      *            The parent identifier for this context; may be
135      *            <code>null</code>.
136      */
137     public final void define(final String   name, final String   description,
138             final String   parentId) {
139         if (name == null) {
140             throw new NullPointerException  (
141                     "The name of a scheme cannot be null"); //$NON-NLS-1$
142         }
143 
144         final boolean definedChanged = !this.defined;
145         this.defined = true;
146 
147         final boolean nameChanged = !Util.equals(this.name, name);
148         this.name = name;
149 
150         final boolean descriptionChanged = !Util.equals(this.description,
151                 description);
152         this.description = description;
153 
154         final boolean parentIdChanged = !Util.equals(this.parentId, parentId);
155         this.parentId = parentId;
156 
157         fireContextChanged(new ContextEvent(this, definedChanged, nameChanged,
158                 descriptionChanged, parentIdChanged));
159     }
160 
161     /**
162      * Notifies all listeners that this context has changed. This sends the
163      * given event to all of the listeners, if any.
164      * 
165      * @param event
166      *            The event to send to the listeners; must not be
167      *            <code>null</code>.
168      */
169     private final void fireContextChanged(final ContextEvent event) {
170         if (event == null) {
171             throw new NullPointerException  (
172                     "Cannot send a null event to listeners."); //$NON-NLS-1$
173         }
174 
175         if (listeners == null) {
176             return;
177         }
178 
179         final Iterator   listenerItr = listeners.iterator();
180         while (listenerItr.hasNext()) {
181             final IContextListener listener = (IContextListener) listenerItr
182                     .next();
183             listener.contextChanged(event);
184         }
185     }
186 
187     /**
188      * Returns the identifier of the parent of this instance.
189      * <p>
190      * Notification is sent to all registered listeners if this property
191      * changes.
192      * </p>
193      * 
194      * @return the identifier of the parent of this instance. May be
195      *         <code>null</code>.
196      * @throws NotDefinedException
197      *             if this instance is not defined.
198      */
199     public final String   getParentId() throws NotDefinedException {
200         if (!defined) {
201             throw new NotDefinedException(
202                     "Cannot get the parent identifier from an undefined context. " //$NON-NLS-1$
203                     +id);
204         }
205 
206         return parentId;
207     }
208 
209     /**
210      * Unregisters an instance of <code>IContextListener</code> listening for
211      * changes to properties of this instance.
212      * 
213      * @param contextListener
214      *            the instance to unregister. Must not be <code>null</code>.
215      *            If an attempt is made to unregister an instance which is not
216      *            already registered with this instance, no operation is
217      *            performed.
218      */
219     public final void removeContextListener(
220             final IContextListener contextListener) {
221         if (contextListener == null) {
222             throw new NullPointerException  ("Cannot remove a null listener."); //$NON-NLS-1$
223         }
224 
225         if (listeners == null) {
226             return;
227         }
228 
229         listeners.remove(contextListener);
230 
231         if (listeners.isEmpty()) {
232             listeners = null;
233         }
234     }
235 
236     /**
237      * The string representation of this context -- for debugging purposes only.
238      * This string should not be shown to an end user.
239      * 
240      * @return The string representation; never <code>null</code>.
241      */
242     public final String   toString() {
243         if (string == null) {
244             final StringBuffer   stringBuffer = new StringBuffer  ();
245             stringBuffer.append("Context("); //$NON-NLS-1$
246             stringBuffer.append(id);
247             stringBuffer.append(',');
248             stringBuffer.append(name);
249             stringBuffer.append(',');
250             stringBuffer.append(description);
251             stringBuffer.append(',');
252             stringBuffer.append(parentId);
253             stringBuffer.append(',');
254             stringBuffer.append(defined);
255             stringBuffer.append(')');
256             string = stringBuffer.toString();
257         }
258         return string;
259     }
260 
261     /**
262      * Makes this context become undefined. This has the side effect of changing
263      * the name, description and parent identifier to <code>null</code>.
264      * Notification is sent to all listeners.
265      */
266     public final void undefine() {
267         string = null;
268 
269         final boolean definedChanged = defined;
270         defined = false;
271 
272         final boolean nameChanged = name != null;
273         name = null;
274 
275         final boolean descriptionChanged = description != null;
276         description = null;
277 
278         final boolean parentIdChanged = parentId != null;
279         parentId = null;
280 
281         fireContextChanged(new ContextEvent(this, definedChanged, nameChanged,
282                 descriptionChanged, parentIdChanged));
283     }
284 }
285
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags