| /******************************************************************************* |
| * 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; |
| } |
| } |