/*******************************************************************************
 * Copyright (c) 2003, 2005 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.ui.commands;

import org.eclipse.core.expressions.Expression;
import org.eclipse.ui.ISources;
import org.eclipse.ui.internal.util.Util;

/**
 * <p>
 * An instance of this interface represents a priority for use with instances of
 * <code>HandlerSubmission</code>.
 * </p>
 * <p>
 * The order of precedence (from highest to lowest) is as follows. Submissions
 * with higher priority will be preferred over those with lower priority.
 * </p>
 * <ol>
 * <li>MEDIUM</li>
 * <li>LOW</li>
 * <li>LEGACY</li>
 * </ol>
 * </p>
 * <p>
 * This class is not intended to be extended by clients.
 * </p>
 * 
 * @since 3.0
 * @see HandlerSubmission
 * @see org.eclipse.ui.ISources
 * @see org.eclipse.ui.handlers.IHandlerService#activateHandler(String,
 *      IHandler, Expression)
 * @deprecated This concept is now captured in the <code>ISources</code>
 *             integer constants.
 * 
 */
public final class Priority implements Comparable {

	/**
	 * An instance representing 'legacy' priority.
	 */
	public final static Priority LEGACY = new Priority(ISources.LEGACY_LEGACY);

	/**
	 * An instance representing 'low' priority.
	 */
	public final static Priority LOW = new Priority(ISources.LEGACY_LOW);

	/**
	 * An instance representing 'medium' priority.
	 */
	public final static Priority MEDIUM = new Priority(ISources.LEGACY_MEDIUM);

	/**
	 * The string representation of this priority. This is computed once
	 * (lazily). Before it is computed, this value is <code>null</code>.
	 */
	private transient String string = null;

	/**
	 * The priority value for this instance. A lesser integer is considered to
	 * have a higher priority.
	 */
	private int value;

	/**
	 * Constructs a new instance of <code>Priority</code> using a value. This
	 * constructor should only be used internally. Priority instances should be
	 * retrieved from the static members defined above.
	 * 
	 * @param value
	 *            The priority value; a lesser integer is consider to have a
	 *            higher priority value.
	 */
	private Priority(int value) {
		this.value = value;
	}

	/**
	 * @see Comparable#compareTo(java.lang.Object)
	 */
	public int compareTo(Object object) {
		Priority castedObject = (Priority) object;
		int compareTo = Util.compare(value, castedObject.value);
		return compareTo;
	}

	/**
	 * The value for this priority. The lesser the value, the higher priority
	 * this represents.
	 * 
	 * @return The integer priority value.
	 */
	int getValue() {
		return value;
	}

	/**
	 * @see Object#toString()
	 */
	public String toString() {
		if (string == null) {
			final StringBuffer stringBuffer = new StringBuffer();
			stringBuffer.append("[value="); //$NON-NLS-1$
			stringBuffer.append(value);
			stringBuffer.append(']');
			string = stringBuffer.toString();
		}

		return string;
	}
}