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

import org.eclipse.core.commands.IParameter;
import org.eclipse.core.commands.IParameterValues;
import org.eclipse.core.commands.ITypedParameter;
import org.eclipse.core.commands.ParameterType;
import org.eclipse.core.commands.ParameterValuesException;
import org.eclipse.core.commands.common.HandleObject;
import org.eclipse.core.runtime.CoreException;
import org.eclipse.core.runtime.IConfigurationElement;
import org.eclipse.ui.internal.util.Util;

/**
 * <p>
 * A parameter for a command. A parameter identifies a type of information that
 * the command might accept. For example, a "Show View" command might accept the
 * id of a view for display. This parameter also identifies possible values, for
 * display in the user interface.
 * </p>
 * <p>
 * Parameters are mutable, and can change as the command changes. Notifications
 * will not be sent if the parameter itself changes. Listeners can be attached
 * to the command.
 * </p>
 * 
 * @since 3.1
 */
public final class Parameter implements IParameter, ITypedParameter {

	/**
	 * The name of the configuration element attribute contain the values. This
	 * is used to retrieve the executable extension
	 * <code>IParameterValues</code>.
	 */
	private static final String ATTRIBUTE_VALUES = "values"; //$NON-NLS-1$

	/**
	 * The constant integer hash code value meaning the hash code has not yet
	 * been computed.
	 */
	private static final int HASH_CODE_NOT_COMPUTED = -1;

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

	/**
	 * The seed for the hash code for all schemes.
	 */
	private static final int HASH_INITIAL = HandleObject.class.getName()
			.hashCode();

	/**
	 * 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 = HASH_CODE_NOT_COMPUTED;

	/**
	 * The identifier for this object. This identifier should be unique across
	 * all objects of the same type and should never change. This value will
	 * never be <code>null</code>.
	 */
	protected final String id;

	/**
	 * The non-externalized name of this parameter. The name is used as the in a
	 * name-value parameter map. This value will never be <code>null</code>.
	 */
	private final String name;

	/**
	 * Whether the parameter is optional (as opposed to required).
	 */
	private final boolean optional;

	/**
	 * The type for this parameter. This value may be <code>null</code> if the
	 * parameter is not typed.
	 */
	private final ParameterType parameterType;

	/**
	 * The string representation of this object. This string is for debugging
	 * purposes only, and is not meant to be displayed to the user. This value
	 * is computed lazily, and is cleared if one of its dependent values
	 * changes.
	 */
	protected transient String string = null;

	/**
	 * The actual <code>IParameterValues</code> implementation. This is lazily
	 * loaded from the <code>valuesConfigurationElement</code>, to avoid
	 * unnecessary class-loading.
	 */
	private transient IParameterValues values = null;

	/**
	 * The configuration element providing the executable extension that will
	 * implement <code>IParameterValues</code>. This value will not be
	 * <code>null</code>.
	 */
	private final IConfigurationElement valuesConfigurationElement;

	/**
	 * Constructs a new instance of <code>Parameter</code> with all of its
	 * values pre-defined.
	 * 
	 * @param id
	 *            The identifier for this parameter; must not be
	 *            <code>null</code>.
	 * @param name
	 *            The name for this parameter; must not be <code>null</code>.
	 * @param values
	 *            The values for this parameter; must not be <code>null</code>.
	 * @param parameterType
	 *            the type for this parameter; may be <code>null</code> if the
	 *            parmeter doesn't declare type.
	 * @param optional
	 *            Whether this parameter is optional (as opposed to required).
	 * @param commandService
	 *            The command service from which parameter types can be
	 *            retrieved; must not be <code>null</code>.
	 */
	public Parameter(final String id, final String name,
			final IConfigurationElement values,
			final ParameterType parameterType, final boolean optional) {
		if (id == null) {
			throw new NullPointerException(
					"Cannot create a parameter with a null id"); //$NON-NLS-1$
		}

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

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

		this.id = id;
		this.name = name;
		this.valuesConfigurationElement = values;
		this.parameterType = parameterType;
		this.optional = optional;
	}

	/**
	 * Tests whether this object is equal to another object. A parameter is only
	 * equal to another parameter with the same properties.
	 * 
	 * @param object
	 *            The object with which to compare; may be <code>null</code>.
	 * @return <code>true</code> if the objects are equal; <code>false</code>
	 *         otherwise.
	 */
	public final boolean equals(final Object object) {
		if (this == object) {
			return true;
		}

		if (!(object instanceof Parameter)) {
			return false;
		}

		final Parameter parameter = (Parameter) object;
		if (!Util.equals(id, parameter.id)) {
			return false;
		}
		if (!Util.equals(name, parameter.name)) {
			return false;
		}
		if (!Util.equals(values, parameter.values)) {
			return false;
		}

		return Util.equals(optional, parameter.optional);
	}

	public final String getId() {
		return id;
	}

	public final String getName() {
		return name;
	}

	public final ParameterType getParameterType() {
		return parameterType;
	}

	public final IParameterValues getValues() throws ParameterValuesException {
		if (values == null) {
			try {
				values = (IParameterValues) valuesConfigurationElement
						.createExecutableExtension(ATTRIBUTE_VALUES);
			} catch (final CoreException e) {
				throw new ParameterValuesException(
						"Problem creating parameter values", e); //$NON-NLS-1$
			} catch (final ClassCastException e) {
				throw new ParameterValuesException(
						"Parameter values were not an instance of IParameterValues", e); //$NON-NLS-1$
			}
		}

		return values;
	}

	public final int hashCode() {
		if (hashCode == HASH_CODE_NOT_COMPUTED) {
			hashCode = HASH_INITIAL * HASH_FACTOR + Util.hashCode(id);
			if (hashCode == HASH_CODE_NOT_COMPUTED) {
				hashCode++;
			}
		}
		return hashCode;
	}

	public final boolean isOptional() {
		return optional;
	}

	public final String toString() {
		if (string == null) {
			final StringBuffer buffer = new StringBuffer();

			buffer.append("Parameter("); //$NON-NLS-1$
			buffer.append(id);
			buffer.append(',');
			buffer.append(name);
			buffer.append(',');
			buffer.append(values);
			buffer.append(',');
			buffer.append(optional);
			buffer.append(')');

			string = buffer.toString();
		}

		return string;
	}
}