001: /*******************************************************************************
002: * Copyright (c) 2004, 2007 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.jface.bindings;
011:
012: import java.util.Map;
013:
014: import org.eclipse.jface.util.Util;
015:
016: /**
017: * <p>
018: * A resolution of bindings for a given state. To see if we already have a
019: * cached binding set, just create one of these binding sets and then look it up
020: * in a map. If it is not already there, then add it and set the cached binding
021: * resolution.
022: * </p>
023: *
024: * @since 3.1
025: */
026: final class CachedBindingSet {
027:
028: /**
029: * A factor for computing the hash code for all cached binding sets.
030: */
031: private final static int HASH_FACTOR = 89;
032:
033: /**
034: * The seed for the hash code for all cached binding sets.
035: */
036: private final static int HASH_INITIAL = CachedBindingSet.class
037: .getName().hashCode();
038:
039: /**
040: * <p>
041: * A representation of the tree of active contexts at the time this cached
042: * binding set was computed. It is a map of context id (<code>String</code>)
043: * to context id (<code>String</code>). Each key represents one of the
044: * active contexts or one of its ancestors, while each value represents its
045: * parent. This is a way of perserving information about what the hierarchy
046: * looked like.
047: * </p>
048: * <p>
049: * This value will be <code>null</code> if the contexts were disregarded
050: * in the computation. It may also be empty. All of the keys are guaranteed
051: * to be non- <code>null</code>, but the values can be <code>null</code>
052: * (i.e., no parent).
053: * </p>
054: */
055: private final Map activeContextTree;
056:
057: /**
058: * The map representing the resolved state of the bindings. This is a map of
059: * a trigger (<code>TriggerSequence</code>) to binding (<code>Binding</code>).
060: * This value may be <code>null</code> if it has not yet been initialized.
061: */
062: private Map bindingsByTrigger = null;
063:
064: /**
065: * A map of triggers to collections of bindings. If this binding set
066: * contains conflicts, they are logged here.
067: *
068: * @since 3.3
069: */
070: private Map conflictsByTrigger = null;
071:
072: /**
073: * The hash code for this object. This value is computed lazily, and marked
074: * as invalid when one of the values on which it is based changes.
075: */
076: private transient int hashCode;
077:
078: /**
079: * Whether <code>hashCode</code> still contains a valid value.
080: */
081: private transient boolean hashCodeComputed = false;
082:
083: /**
084: * <p>
085: * The list of locales that were active at the time this binding set was
086: * computed. This list starts with the most specific representation of the
087: * locale, and moves to more general representations. For example, this
088: * array might look like ["en_US", "en", "", null].
089: * </p>
090: * <p>
091: * This value will never be <code>null</code>, and it will never be
092: * empty. It must contain at least one element, but its elements can be
093: * <code>null</code>.
094: * </p>
095: */
096: private final String[] locales;
097:
098: /**
099: * <p>
100: * The list of platforms that were active at the time this binding set was
101: * computed. This list starts with the most specific representation of the
102: * platform, and moves to more general representations. For example, this
103: * array might look like ["gtk", "", null].
104: * </p>
105: * <p>
106: * This value will never be <code>null</code>, and it will never be
107: * empty. It must contain at least one element, but its elements can be
108: * <code>null</code>.
109: * </p>
110: */
111: private final String[] platforms;
112:
113: /**
114: * A map of prefixes (<code>TriggerSequence</code>) to a map of
115: * available completions (possibly <code>null</code>, which means there
116: * is an exact match). The available completions is a map of trigger (<code>TriggerSequence</code>)
117: * to command identifier (<code>String</code>). This value is
118: * <code>null</code> if it has not yet been initialized.
119: */
120: private Map prefixTable = null;
121:
122: /**
123: * <p>
124: * The list of schemes that were active at the time this binding set was
125: * computed. This list starts with the active scheme, and then continues
126: * with all of its ancestors -- in order. For example, this might look like
127: * ["emacs", "default"].
128: * </p>
129: * <p>
130: * This value will never be <code>null</code>, and it will never be
131: * empty. It must contain at least one element. Its elements cannot be
132: * <code>null</code>.
133: * </p>
134: */
135: private final String[] schemeIds;
136:
137: /**
138: * The map representing the resolved state of the bindings. This is a map of
139: * a command id (<code>String</code>) to triggers (<code>Collection</code>
140: * of <code>TriggerSequence</code>). This value may be <code>null</code>
141: * if it has not yet been initialized.
142: */
143: private Map triggersByCommandId = null;
144:
145: /**
146: * Constructs a new instance of <code>CachedBindingSet</code>.
147: *
148: * @param activeContextTree
149: * The set of context identifiers that were active when this
150: * binding set was calculated; may be empty. If it is
151: * <code>null</code>, then the contexts were disregarded in
152: * the computation. This is a map of context id (
153: * <code>String</code>) to parent context id (
154: * <code>String</code>). This is a way of caching the look of
155: * the context tree at the time the binding set was computed.
156: * @param locales
157: * The locales that were active when this binding set was
158: * calculated. The first element is the currently active locale,
159: * and it is followed by increasingly more general locales. This
160: * must not be <code>null</code> and must contain at least one
161: * element. The elements can be <code>null</code>, though.
162: * @param platforms
163: * The platform that were active when this binding set was
164: * calculated. The first element is the currently active
165: * platform, and it is followed by increasingly more general
166: * platforms. This must not be <code>null</code> and must
167: * contain at least one element. The elements can be
168: * <code>null</code>, though.
169: * @param schemeIds
170: * The scheme that was active when this binding set was
171: * calculated, followed by its ancestors. This may be
172: * <code>null</code or empty. The
173: * elements cannot be <code>null</code>.
174: */
175: CachedBindingSet(final Map activeContextTree,
176: final String[] locales, final String[] platforms,
177: final String[] schemeIds) {
178: if (locales == null) {
179: throw new NullPointerException(
180: "The locales cannot be null."); //$NON-NLS-1$
181: }
182:
183: if (locales.length == 0) {
184: throw new NullPointerException(
185: "The locales cannot be empty."); //$NON-NLS-1$
186: }
187:
188: if (platforms == null) {
189: throw new NullPointerException(
190: "The platforms cannot be null."); //$NON-NLS-1$
191: }
192:
193: if (platforms.length == 0) {
194: throw new NullPointerException(
195: "The platforms cannot be empty."); //$NON-NLS-1$
196: }
197:
198: this .activeContextTree = activeContextTree;
199: this .locales = locales;
200: this .platforms = platforms;
201: this .schemeIds = schemeIds;
202: }
203:
204: /**
205: * Compares this binding set with another object. The objects will be equal
206: * if they are both instance of <code>CachedBindingSet</code> and have
207: * equivalent values for all of their properties.
208: *
209: * @param object
210: * The object with which to compare; may be <code>null</code>.
211: * @return <code>true</code> if they are both instances of
212: * <code>CachedBindingSet</code> and have the same values for all
213: * of their properties; <code>false</code> otherwise.
214: */
215: public final boolean equals(final Object object) {
216: if (!(object instanceof CachedBindingSet)) {
217: return false;
218: }
219:
220: final CachedBindingSet other = (CachedBindingSet) object;
221:
222: if (!Util.equals(activeContextTree, other.activeContextTree)) {
223: return false;
224: }
225: if (!Util.equals(locales, other.locales)) {
226: return false;
227: }
228: if (!Util.equals(platforms, other.platforms)) {
229: return false;
230: }
231: return Util.equals(schemeIds, other.schemeIds);
232: }
233:
234: /**
235: * Returns the map of command identifiers indexed by trigger sequence.
236: *
237: * @return A map of triggers (<code>TriggerSequence</code>) to bindings (<code>Binding</code>).
238: * This value may be <code>null</code> if this was not yet
239: * initialized.
240: */
241: final Map getBindingsByTrigger() {
242: return bindingsByTrigger;
243: }
244:
245: /**
246: * Returns a map of conflicts for this set of contexts.
247: *
248: * @return A map of trigger to a collection of Bindings. May be
249: * <code>null</code>.
250: * @since 3.3
251: */
252: final Map getConflictsByTrigger() {
253: return conflictsByTrigger;
254: }
255:
256: /**
257: * Returns the map of prefixes to a map of trigger sequence to command
258: * identifiers.
259: *
260: * @return A map of prefixes (<code>TriggerSequence</code>) to a map of
261: * available completions (possibly <code>null</code>, which means
262: * there is an exact match). The available completions is a map of
263: * trigger (<code>TriggerSequence</code>) to command identifier (<code>String</code>).
264: * This value may be <code>null</code> if it has not yet been
265: * initialized.
266: */
267: final Map getPrefixTable() {
268: return prefixTable;
269: }
270:
271: /**
272: * Returns the map of triggers indexed by command identifiers.
273: *
274: * @return A map of command identifiers (<code>String</code>) to
275: * triggers (<code>Collection</code> of
276: * <code>TriggerSequence</code>). This value may be
277: * <code>null</code> if this was not yet initialized.
278: */
279: final Map getTriggersByCommandId() {
280: return triggersByCommandId;
281: }
282:
283: /**
284: * Computes the hash code for this cached binding set. The hash code is
285: * based only on the immutable values. This allows the set to be created and
286: * checked for in a hashed collection <em>before</em> doing any
287: * computation.
288: *
289: * @return The hash code for this cached binding set.
290: */
291: public final int hashCode() {
292: if (!hashCodeComputed) {
293: hashCode = HASH_INITIAL;
294: hashCode = hashCode * HASH_FACTOR
295: + Util.hashCode(activeContextTree);
296: hashCode = hashCode * HASH_FACTOR + Util.hashCode(locales);
297: hashCode = hashCode * HASH_FACTOR
298: + Util.hashCode(platforms);
299: hashCode = hashCode * HASH_FACTOR
300: + Util.hashCode(schemeIds);
301: hashCodeComputed = true;
302: }
303:
304: return hashCode;
305: }
306:
307: /**
308: * Sets the map of command identifiers indexed by trigger.
309: *
310: * @param commandIdsByTrigger
311: * The map to set; must not be <code>null</code>. This is a
312: * map of triggers (<code>TriggerSequence</code>) to binding (<code>Binding</code>).
313: */
314: final void setBindingsByTrigger(final Map commandIdsByTrigger) {
315: if (commandIdsByTrigger == null) {
316: throw new NullPointerException(
317: "Cannot set a null binding resolution"); //$NON-NLS-1$
318: }
319:
320: this .bindingsByTrigger = commandIdsByTrigger;
321: }
322:
323: /**
324: * Sets the map of conflicting bindings by trigger.
325: *
326: * @param conflicts
327: * The map to set; must not be <code>null</code>.
328: * @since 3.3
329: */
330: final void setConflictsByTrigger(final Map conflicts) {
331: if (conflicts == null) {
332: throw new NullPointerException(
333: "Cannot set a null binding conflicts"); //$NON-NLS-1$
334: }
335: conflictsByTrigger = conflicts;
336: }
337:
338: /**
339: * Sets the map of prefixes to a map of trigger sequence to command
340: * identifiers.
341: *
342: * @param prefixTable
343: * A map of prefixes (<code>TriggerSequence</code>) to a map
344: * of available completions (possibly <code>null</code>, which
345: * means there is an exact match). The available completions is a
346: * map of trigger (<code>TriggerSequence</code>) to command
347: * identifier (<code>String</code>). Must not be
348: * <code>null</code>.
349: */
350: final void setPrefixTable(final Map prefixTable) {
351: if (prefixTable == null) {
352: throw new NullPointerException(
353: "Cannot set a null prefix table"); //$NON-NLS-1$
354: }
355:
356: this .prefixTable = prefixTable;
357: }
358:
359: /**
360: * Sets the map of triggers indexed by command identifiers.
361: *
362: * @param triggersByCommandId
363: * The map to set; must not be <code>null</code>. This is a
364: * map of command identifiers (<code>String</code>) to
365: * triggers (<code>Collection</code> of
366: * <code>TriggerSequence</code>).
367: */
368: final void setTriggersByCommandId(final Map triggersByCommandId) {
369: if (triggersByCommandId == null) {
370: throw new NullPointerException(
371: "Cannot set a null binding resolution"); //$NON-NLS-1$
372: }
373:
374: this.triggersByCommandId = triggersByCommandId;
375: }
376: }
|