org.eclipse.jface.bindings.CachedBindingSet Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of org.eclipse.jface Show documentation
This is org.eclipse.jface jar used by Scout SDK
The newest version!
/*******************************************************************************
 * Copyright (c) 2004, 2015 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.jface.bindings;

import java.util.Collections;
import java.util.Map;

import org.eclipse.core.commands.util.Tracing;
import org.eclipse.jface.util.Util;

/**
 * 
 * A resolution of bindings for a given state. To see if we already have a
 * cached binding set, just create one of these binding sets and then look it up
 * in a map. If it is not already there, then add it and set the cached binding
 * resolution.
 * 
 *
 * @since 3.1
 */
final class CachedBindingSet {

	/**
	 * A factor for computing the hash code for all cached binding sets.
	 */
	private final static int HASH_FACTOR = 89;

	/**
	 * The seed for the hash code for all cached binding sets.
	 */
	private final static int HASH_INITIAL = CachedBindingSet.class.getName()
			.hashCode();

	/**
	 * 
	 * A representation of the tree of active contexts at the time this cached
	 * binding set was computed. It is a map of context id (String)
	 * to context id (String). Each key represents one of the
	 * active contexts or one of its ancestors, while each value represents its
	 * parent. This is a way of perserving information about what the hierarchy
	 * looked like.
	 * 
	 * 
	 * This value will be null if the contexts were disregarded
	 * in the computation. It may also be empty. All of the keys are guaranteed
	 * to be non- null, but the values can be null
	 * (i.e., no parent).
	 * 
	 */
	private final Map activeContextTree;

	/**
	 * The map representing the resolved state of the bindings. This is a map of
	 * a trigger (TriggerSequence) to binding (Binding).
	 * This value may be null if it has not yet been initialized.
	 */
	private volatile Map bindingsByTrigger;

	/**
	 * A map of triggers to collections of bindings. If this binding set
	 * contains conflicts, they are logged here.
	 *
	 * @since 3.3
	 */
	private volatile Map conflictsByTrigger;

	/**
	 * The hash code for this object. This value is computed lazily, and marked
	 * as invalid when one of the values on which it is based changes.
	 */
	private transient int hashCode;

	/**
	 * Whether hashCode still contains a valid value.
	 */
	private transient boolean hashCodeComputed = false;

	/**
	 * 
	 * The list of locales that were active at the time this binding set was
	 * computed. This list starts with the most specific representation of the
	 * locale, and moves to more general representations. For example, this
	 * array might look like ["en_US", "en", "", null].
	 * 
	 * 
	 * This value will never be null, and it will never be
	 * empty. It must contain at least one element, but its elements can be
	 * null.
	 * 
	 */
	private final String[] locales;

	/**
	 * 
	 * The list of platforms that were active at the time this binding set was
	 * computed. This list starts with the most specific representation of the
	 * platform, and moves to more general representations. For example, this
	 * array might look like ["gtk", "", null].
	 * 
	 * 
	 * This value will never be null, and it will never be
	 * empty. It must contain at least one element, but its elements can be
	 * null.
	 * 
	 */
	private final String[] platforms;

	/**
	 * A map of prefixes (TriggerSequence) to a map of
	 * available completions (possibly null, which means there
	 * is an exact match). The available completions is a map of trigger (TriggerSequence)
	 * to command identifier (String). This value is
	 * null if it has not yet been initialized.
	 */
	private volatile Map prefixTable;

	/**
	 * 
	 * The list of schemes that were active at the time this binding set was
	 * computed. This list starts with the active scheme, and then continues
	 * with all of its ancestors -- in order. For example, this might look like
	 * ["emacs", "default"].
	 * 
	 * 
	 * This value will never be null, and it will never be
	 * empty. It must contain at least one element. Its elements cannot be
	 * null.
	 * 
	 */
	private final String[] schemeIds;

	/**
	 * The map representing the resolved state of the bindings. This is a map of
	 * a command id (String) to triggers (Collection
	 * of TriggerSequence). This value may be null
	 * if it has not yet been initialized.
	 */
	private volatile Map triggersByCommandId;

	/**
	 * Constructs a new instance of CachedBindingSet.
	 *
	 * @param activeContextTree
	 *            The set of context identifiers that were active when this
	 *            binding set was calculated; may be empty. If it is
	 *            null, then the contexts were disregarded in
	 *            the computation. This is a map of context id (
	 *            String) to parent context id (
	 *            String). This is a way of caching the look of
	 *            the context tree at the time the binding set was computed.
	 * @param locales
	 *            The locales that were active when this binding set was
	 *            calculated. The first element is the currently active locale,
	 *            and it is followed by increasingly more general locales. This
	 *            must not be null and must contain at least one
	 *            element. The elements can be null, though.
	 * @param platforms
	 *            The platform that were active when this binding set was
	 *            calculated. The first element is the currently active
	 *            platform, and it is followed by increasingly more general
	 *            platforms. This must not be null and must
	 *            contain at least one element. The elements can be
	 *            null, though.
	 * @param schemeIds
	 *            The scheme that was active when this binding set was
	 *            calculated, followed by its ancestors. This may be
	 *            nullnull.
	 */
	CachedBindingSet(final Map activeContextTree, final String[] locales,
			final String[] platforms, final String[] schemeIds) {
		if (locales == null) {
			throw new NullPointerException("The locales cannot be null."); //$NON-NLS-1$
		}

		if (locales.length == 0) {
			throw new NullPointerException("The locales cannot be empty."); //$NON-NLS-1$
		}

		if (platforms == null) {
			throw new NullPointerException("The platforms cannot be null."); //$NON-NLS-1$
		}

		if (platforms.length == 0) {
			throw new NullPointerException("The platforms cannot be empty."); //$NON-NLS-1$
		}

		this.activeContextTree = activeContextTree;
		this.locales = locales;
		this.platforms = platforms;
		this.schemeIds = schemeIds;
	}

	/**
	 * Compares this binding set with another object. The objects will be equal
	 * if they are both instance of CachedBindingSet and have
	 * equivalent values for all of their properties.
	 *
	 * @param object
	 *            The object with which to compare; may be null.
	 * @return true if they are both instances of
	 *         CachedBindingSet and have the same values for all
	 *         of their properties; false otherwise.
	 */
	@Override
	public final boolean equals(final Object object) {
		if (!(object instanceof CachedBindingSet)) {
			return false;
		}

		final CachedBindingSet other = (CachedBindingSet) object;

		if (!Util.equals(activeContextTree, other.activeContextTree)) {
			return false;
		}
		if (!Util.equals(locales, other.locales)) {
			return false;
		}
		if (!Util.equals(platforms, other.platforms)) {
			return false;
		}
		return Util.equals(schemeIds, other.schemeIds);
	}

	/**
	 * Returns the map of command identifiers indexed by trigger sequence.
	 *
	 * @return A map of triggers (TriggerSequence) to bindings (Binding).
	 *         This value may be null if this was not yet
	 *         initialized.
	 */
	final Map getBindingsByTrigger() {
		return bindingsByTrigger;
	}

	/**
	 * Returns a map of conflicts for this set of contexts.
	 *
	 * @return A map of trigger to a collection of Bindings. May be
	 *         null.
	 * @since 3.3
	 */
	final Map getConflictsByTrigger() {
		return conflictsByTrigger;
	}

	/**
	 * Returns the map of prefixes to a map of trigger sequence to command
	 * identifiers.
	 *
	 * @return A map of prefixes (TriggerSequence) to a map of
	 *         available completions (possibly null, which means
	 *         there is an exact match). The available completions is a map of
	 *         trigger (TriggerSequence) to command identifier (String).
	 *         This value may be null if it has not yet been
	 *         initialized.
	 */
	final Map getPrefixTable() {
		return prefixTable;
	}

	/**
	 * Returns the map of triggers indexed by command identifiers.
	 *
	 * @return A map of command identifiers (String) to
	 *         triggers (Collection of
	 *         TriggerSequence). This value may be
	 *         null if this was not yet initialized.
	 */
	final Map getTriggersByCommandId() {
		return triggersByCommandId;
	}

	/**
	 * Computes the hash code for this cached binding set. The hash code is
	 * based only on the immutable values. This allows the set to be created and
	 * checked for in a hashed collection before doing any
	 * computation.
	 *
	 * @return The hash code for this cached binding set.
	 */
	@Override
	public final int hashCode() {
		if (!hashCodeComputed) {
			hashCode = HASH_INITIAL;
			hashCode = hashCode * HASH_FACTOR
					+ Util.hashCode(activeContextTree);
			hashCode = hashCode * HASH_FACTOR + Util.hashCode(locales);
			hashCode = hashCode * HASH_FACTOR + Util.hashCode(platforms);
			hashCode = hashCode * HASH_FACTOR + Util.hashCode(schemeIds);
			hashCodeComputed = true;
		}

		return hashCode;
	}

	/**
	 * Sets the map of command identifiers indexed by trigger.
	 *
	 * @param commandIdsByTrigger
	 *            The map to set; must not be null. This is a
	 *            map of triggers (TriggerSequence) to binding (Binding).
	 */
	final void setBindingsByTrigger(final Map commandIdsByTrigger) {
		if (commandIdsByTrigger == null) {
			throw new NullPointerException(
					"Cannot set a null binding resolution"); //$NON-NLS-1$
		}

		this.bindingsByTrigger = commandIdsByTrigger;
	}

	/**
	 * Sets the map of conflicting bindings by trigger.
	 *
	 * @param conflicts
	 *            The map to set; must not be null.
	 * @since 3.3
	 */
	final void setConflictsByTrigger(final Map conflicts) {
		if (conflicts == null) {
			throw new NullPointerException(
					"Cannot set a null binding conflicts"); //$NON-NLS-1$
		}
		conflictsByTrigger = conflicts;
	}

	/**
	 * Sets the map of prefixes to a map of trigger sequence to command
	 * identifiers.
	 *
	 * @param prefixTable
	 *            A map of prefixes (TriggerSequence) to a map
	 *            of available completions (possibly null, which
	 *            means there is an exact match). The available completions is a
	 *            map of trigger (TriggerSequence) to command
	 *            identifier (String). Must not be
	 *            null.
	 */
	final void setPrefixTable(final Map prefixTable) {
		if (prefixTable == null) {
			this.prefixTable = Collections.EMPTY_MAP;
			if (BindingManager.DEBUG) {
				Tracing.printTrace("BINDINGS", "Cannot set a null prefix table, set to EMPTY_MAP"); //$NON-NLS-1$ //$NON-NLS-2$
			}
			return;
		}

		this.prefixTable = prefixTable;
	}

	/**
	 * Sets the map of triggers indexed by command identifiers.
	 *
	 * @param triggersByCommandId
	 *            The map to set; must not be null. This is a
	 *            map of command identifiers (String) to
	 *            triggers (Collection of
	 *            TriggerSequence).
	 */
	final void setTriggersByCommandId(final Map triggersByCommandId) {
		if (triggersByCommandId == null) {
			throw new NullPointerException(
					"Cannot set a null binding resolution"); //$NON-NLS-1$
		}

		this.triggersByCommandId = triggersByCommandId;
	}

	/**
	 * @return true if all the required maps are computed and non null
	 */
	final boolean isInitialized() {
		return bindingsByTrigger != null && triggersByCommandId != null && conflictsByTrigger != null
				&& prefixTable != null;
	}
}