ContextManager


1   /*******************************************************************************
2    * Copyright (c) 2000, 2007 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.Collections  ;
15  import java.util.HashSet  ;
16  import java.util.Set  ;
17  
18  import org.eclipse.core.commands.common.HandleObjectManager;
19  import org.eclipse.core.commands.util.Tracing;
20  import org.eclipse.core.internal.commands.util.Util;
21  
22  /**
23   * <p>
24   * A context manager tracks the sets of defined and enabled contexts within the
25   * application. The manager sends notification events to listeners when these
26   * sets change. It is also possible to retrieve any given context with its
27   * identifier.
28   * </p>
29   * <p>
30   * This class is not intended to be extended by clients.
31   * </p>
32   * 
33   * @since 3.1
34   */
35  public final class ContextManager extends HandleObjectManager implements
36          IContextListener {
37      
38      private static final String   DEFER_EVENTS = "org.eclipse.ui.internal.contexts.deferEvents"; //$NON-NLS-1$
39      private static final String   SEND_EVENTS = "org.eclipse.ui.internal.contexts.sendEvents"; //$NON-NLS-1$
40  
41      /**
42       * This flag can be set to <code>true</code> if the context manager should
43       * print information to <code>System.out</code> when certain boundary
44       * conditions occur.
45       */
46      public static boolean DEBUG = false;
47  
48      /**
49       * The set of active context identifiers. This value may be empty, but it is
50       * never <code>null</code>.
51       */
52      private Set   activeContextIds = new HashSet  ();
53  
54      // allow the ContextManager to send one event for a larger delta
55      private boolean caching = false;
56      
57      private int cachingRef = 0;
58  
59      private boolean activeContextsChange = false;
60      
61      private Set   oldIds = null;
62  
63      /**
64       * Activates a context in this context manager.
65       * 
66       * @param contextId
67       *            The identifier of the context to activate; must not be
68       *            <code>null</code>.
69       */
70      public final void addActiveContext(final String   contextId) {
71          if (DEFER_EVENTS.equals(contextId)) {
72              cachingRef++;
73              if (cachingRef==1) {
74                  setEventCaching(true);
75              }
76              return;
77          } else if (SEND_EVENTS.equals(contextId)) {
78              cachingRef--;
79              if (cachingRef==0) {
80                  setEventCaching(false);
81              }
82              return;
83          }
84          
85          if (activeContextIds.contains(contextId)) {
86              return;
87          }
88          activeContextsChange = true;
89  
90          if (caching) {
91              activeContextIds.add(contextId);
92          } else {
93              final Set   previouslyActiveContextIds = new HashSet  (activeContextIds);
94              activeContextIds.add(contextId);
95  
96              fireContextManagerChanged(new ContextManagerEvent(this, null,
97                      false, true, previouslyActiveContextIds));
98          }
99  
100         if (DEBUG) {
101             Tracing.printTrace("CONTEXTS", activeContextIds.toString()); //$NON-NLS-1$
102         }
103 
104     }
105 
106     /**
107      * Adds a listener to this context manager. The listener will be notified
108      * when the set of defined contexts changes. This can be used to track the
109      * global appearance and disappearance of contexts.
110      * 
111      * @param listener
112      *            The listener to attach; must not be <code>null</code>.
113      */
114     public final void addContextManagerListener(
115             final IContextManagerListener listener) {
116         addListenerObject(listener);
117     }
118 
119     public final void contextChanged(final ContextEvent contextEvent) {
120         if (contextEvent.isDefinedChanged()) {
121             final Context context = contextEvent.getContext();
122             final String   contextId = context.getId();
123             final boolean contextIdAdded = context.isDefined();
124             if (contextIdAdded) {
125                 definedHandleObjects.add(context);
126             } else {
127                 definedHandleObjects.remove(context);
128             }
129             if (isListenerAttached()) {
130                 fireContextManagerChanged(new ContextManagerEvent(this,
131                         contextId, contextIdAdded, false, null));
132             }
133         }
134     }
135 
136     /**
137      * Notifies all of the listeners to this manager that the set of defined
138      * context identifiers has changed.
139      * 
140      * @param event
141      *            The event to send to all of the listeners; must not be
142      *            <code>null</code>.
143      */
144     private final void fireContextManagerChanged(final ContextManagerEvent event) {
145         if (event == null) {
146             throw new NullPointerException  ();
147         }
148 
149         final Object  [] listeners = getListeners();
150         for (int i = 0; i < listeners.length; i++) {
151             final IContextManagerListener listener = (IContextManagerListener) listeners[i];
152             listener.contextManagerChanged(event);
153         }
154     }
155 
156     /**
157      * Returns the set of active context identifiers.
158      * 
159      * @return The set of active context identifiers; this value may be
160      *         <code>null</code> if no active contexts have been set yet. If
161      *         the set is not <code>null</code>, then it contains only
162      *         instances of <code>String</code>.
163      */
164     public final Set   getActiveContextIds() {
165         return Collections.unmodifiableSet(activeContextIds);
166     }
167 
168     /**
169      * Gets the context with the given identifier. If no such context currently
170      * exists, then the context will be created (but be undefined).
171      * 
172      * @param contextId
173      *            The identifier to find; must not be <code>null</code>.
174      * @return The context with the given identifier; this value will never be
175      *         <code>null</code>, but it might be undefined.
176      * @see Context
177      */
178     public final Context getContext(final String   contextId) {
179         checkId(contextId);
180 
181         Context context = (Context) handleObjectsById.get(contextId);
182         if (context == null) {
183             context = new Context(contextId);
184             handleObjectsById.put(contextId, context);
185             context.addContextListener(this);
186         }
187 
188         return context;
189     }
190 
191     /**
192      * Returns the set of identifiers for those contexts that are defined.
193      * 
194      * @return The set of defined context identifiers; this value may be empty,
195      *         but it is never <code>null</code>.
196      */
197     public final Set   getDefinedContextIds() {
198         return getDefinedHandleObjectIds();
199     }
200 
201     /**
202      * Returns the those contexts that are defined.
203      * 
204      * @return The defined contexts; this value may be empty, but it is never
205      *         <code>null</code>.
206      * @since 3.2
207      */
208     public final Context[] getDefinedContexts() {
209         return (Context[]) definedHandleObjects
210                 .toArray(new Context[definedHandleObjects.size()]);
211     }
212 
213     /**
214      * Deactivates a context in this context manager.
215      * 
216      * @param contextId
217      *            The identifier of the context to deactivate; must not be
218      *            <code>null</code>.
219      */
220     public final void removeActiveContext(final String   contextId) {
221         if (!activeContextIds.contains(contextId)) {
222             return;
223         }
224 
225         activeContextsChange = true;
226         if (caching) {
227             activeContextIds.remove(contextId);
228         } else {
229             final Set   previouslyActiveContextIds = new HashSet  (activeContextIds);
230             activeContextIds.remove(contextId);
231 
232             fireContextManagerChanged(new ContextManagerEvent(this, null,
233                     false, true, previouslyActiveContextIds));
234         }
235 
236         if (DEBUG) {
237             Tracing.printTrace("CONTEXTS", activeContextIds.toString()); //$NON-NLS-1$
238         }
239     }
240 
241     /**
242      * Removes a listener from this context manager.
243      * 
244      * @param listener
245      *            The listener to be removed; must not be <code>null</code>.
246      */
247     public final void removeContextManagerListener(
248             final IContextManagerListener listener) {
249         removeListenerObject(listener);
250     }
251 
252     /**
253      * Changes the set of active contexts for this context manager. The whole
254      * set is required so that internal consistency can be maintained and so
255      * that excessive recomputations do nothing occur.
256      * 
257      * @param activeContextIds
258      *            The new set of active context identifiers; may be
259      *            <code>null</code>.
260      */
261     public final void setActiveContextIds(final Set   activeContextIds) {
262         if (Util.equals(this.activeContextIds, activeContextIds)) {
263             return;
264         }
265 
266         activeContextsChange = true;
267         
268         final Set   previouslyActiveContextIds = this.activeContextIds;
269         if (activeContextIds != null) {
270             this.activeContextIds = new HashSet  ();
271             this.activeContextIds.addAll(activeContextIds);
272         } else {
273             this.activeContextIds = null;
274         }
275 
276         if (DEBUG) {
277             Tracing.printTrace("CONTEXTS", (activeContextIds == null) ? "none" //$NON-NLS-1$ //$NON-NLS-2$
278                     : activeContextIds.toString());
279         }
280 
281         if (!caching) {
282             fireContextManagerChanged(new ContextManagerEvent(this, null,
283                     false, true, previouslyActiveContextIds));
284         }
285     }
286     
287     /**
288      * Set the manager to cache context id changes.
289      * 
290      * @param cache
291      *            <code>true</code> to turn caching on, <code>false</code>
292      *            to turn caching off and send an event if necessary.
293      * @since 3.3
294      */
295     private void setEventCaching(boolean cache) {
296         if (caching == cache) {
297             return;
298         }
299         caching = cache;
300         boolean fireChange = activeContextsChange;
301         Set   holdOldIds = (oldIds==null?Collections.EMPTY_SET:oldIds);
302         
303         if (caching) {
304             oldIds = new HashSet  (activeContextIds);
305         } else {
306             oldIds = null;
307         }
308         activeContextsChange = false;
309 
310         if (!caching && fireChange) {
311             fireContextManagerChanged(new ContextManagerEvent(this, null,
312                     false, true, holdOldIds));
313         }
314     }
315 }
316
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags