Parameter


1   /*******************************************************************************
2    * Copyright (c) 2005, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  
12  package org.eclipse.ui.internal.commands;
13  
14  import org.eclipse.core.commands.IParameter;
15  import org.eclipse.core.commands.IParameterValues;
16  import org.eclipse.core.commands.ITypedParameter;
17  import org.eclipse.core.commands.ParameterType;
18  import org.eclipse.core.commands.ParameterValuesException;
19  import org.eclipse.core.commands.common.HandleObject;
20  import org.eclipse.core.runtime.CoreException;
21  import org.eclipse.core.runtime.IConfigurationElement;
22  import org.eclipse.ui.internal.util.Util;
23  
24  /**
25   * <p>
26   * A parameter for a command. A parameter identifies a type of information that
27   * the command might accept. For example, a "Show View" command might accept the
28   * id of a view for display. This parameter also identifies possible values, for
29   * display in the user interface.
30   * </p>
31   * <p>
32   * Parameters are mutable, and can change as the command changes. Notifications
33   * will not be sent if the parameter itself changes. Listeners can be attached
34   * to the command.
35   * </p>
36   * 
37   * @since 3.1
38   */
39  public final class Parameter implements IParameter, ITypedParameter {
40  
41      /**
42       * The name of the configuration element attribute contain the values. This
43       * is used to retrieve the executable extension
44       * <code>IParameterValues</code>.
45       */
46      private static final String   ATTRIBUTE_VALUES = "values"; //$NON-NLS-1$
47  
48      /**
49       * The constant integer hash code value meaning the hash code has not yet
50       * been computed.
51       */
52      private static final int HASH_CODE_NOT_COMPUTED = -1;
53  
54      /**
55       * A factor for computing the hash code for all schemes.
56       */
57      private static final int HASH_FACTOR = 89;
58  
59      /**
60       * The seed for the hash code for all schemes.
61       */
62      private static final int HASH_INITIAL = HandleObject.class.getName()
63              .hashCode();
64  
65      /**
66       * The hash code for this object. This value is computed lazily, and marked
67       * as invalid when one of the values on which it is based changes.
68       */
69      private transient int hashCode = HASH_CODE_NOT_COMPUTED;
70  
71      /**
72       * The identifier for this object. This identifier should be unique across
73       * all objects of the same type and should never change. This value will
74       * never be <code>null</code>.
75       */
76      protected final String   id;
77  
78      /**
79       * The non-externalized name of this parameter. The name is used as the in a
80       * name-value parameter map. This value will never be <code>null</code>.
81       */
82      private final String   name;
83  
84      /**
85       * Whether the parameter is optional (as opposed to required).
86       */
87      private final boolean optional;
88  
89      /**
90       * The type for this parameter. This value may be <code>null</code> if the
91       * parameter is not typed.
92       */
93      private final ParameterType parameterType;
94  
95      /**
96       * The string representation of this object. This string is for debugging
97       * purposes only, and is not meant to be displayed to the user. This value
98       * is computed lazily, and is cleared if one of its dependent values
99       * changes.
100      */
101     protected transient String   string = null;
102 
103     /**
104      * The actual <code>IParameterValues</code> implementation. This is lazily
105      * loaded from the <code>valuesConfigurationElement</code>, to avoid
106      * unnecessary class-loading.
107      */
108     private transient IParameterValues values = null;
109 
110     /**
111      * The configuration element providing the executable extension that will
112      * implement <code>IParameterValues</code>. This value will not be
113      * <code>null</code>.
114      */
115     private final IConfigurationElement valuesConfigurationElement;
116 
117     /**
118      * Constructs a new instance of <code>Parameter</code> with all of its
119      * values pre-defined.
120      * 
121      * @param id
122      *            The identifier for this parameter; must not be
123      *            <code>null</code>.
124      * @param name
125      *            The name for this parameter; must not be <code>null</code>.
126      * @param values
127      *            The values for this parameter; must not be <code>null</code>.
128      * @param parameterType
129      *            the type for this parameter; may be <code>null</code> if the
130      *            parmeter doesn't declare type.
131      * @param optional
132      *            Whether this parameter is optional (as opposed to required).
133      * @param commandService
134      *            The command service from which parameter types can be
135      *            retrieved; must not be <code>null</code>.
136      */
137     public Parameter(final String   id, final String   name,
138             final IConfigurationElement values,
139             final ParameterType parameterType, final boolean optional) {
140         if (id == null) {
141             throw new NullPointerException  (
142                     "Cannot create a parameter with a null id"); //$NON-NLS-1$
143         }
144 
145         if (name == null) {
146             throw new NullPointerException  (
147                     "The name of a parameter cannot be null."); //$NON-NLS-1$
148         }
149 
150         if (values == null) {
151             throw new NullPointerException  (
152                     "The values for a parameter cannot be null."); //$NON-NLS-1$
153         }
154 
155         this.id = id;
156         this.name = name;
157         this.valuesConfigurationElement = values;
158         this.parameterType = parameterType;
159         this.optional = optional;
160     }
161 
162     /**
163      * Tests whether this object is equal to another object. A parameter is only
164      * equal to another parameter with the same properties.
165      * 
166      * @param object
167      *            The object with which to compare; may be <code>null</code>.
168      * @return <code>true</code> if the objects are equal; <code>false</code>
169      *         otherwise.
170      */
171     public final boolean equals(final Object   object) {
172         if (this == object) {
173             return true;
174         }
175 
176         if (!(object instanceof Parameter)) {
177             return false;
178         }
179 
180         final Parameter parameter = (Parameter) object;
181         if (!Util.equals(id, parameter.id)) {
182             return false;
183         }
184         if (!Util.equals(name, parameter.name)) {
185             return false;
186         }
187         if (!Util.equals(values, parameter.values)) {
188             return false;
189         }
190 
191         return Util.equals(optional, parameter.optional);
192     }
193 
194     public final String   getId() {
195         return id;
196     }
197 
198     public final String   getName() {
199         return name;
200     }
201 
202     public final ParameterType getParameterType() {
203         return parameterType;
204     }
205 
206     public final IParameterValues getValues() throws ParameterValuesException {
207         if (values == null) {
208             try {
209                 values = (IParameterValues) valuesConfigurationElement
210                         .createExecutableExtension(ATTRIBUTE_VALUES);
211             } catch (final CoreException e) {
212                 throw new ParameterValuesException(
213                         "Problem creating parameter values", e); //$NON-NLS-1$
214             } catch (final ClassCastException   e) {
215                 throw new ParameterValuesException(
216                         "Parameter values were not an instance of IParameterValues", e); //$NON-NLS-1$
217             }
218         }
219 
220         return values;
221     }
222 
223     public final int hashCode() {
224         if (hashCode == HASH_CODE_NOT_COMPUTED) {
225             hashCode = HASH_INITIAL * HASH_FACTOR + Util.hashCode(id);
226             if (hashCode == HASH_CODE_NOT_COMPUTED) {
227                 hashCode++;
228             }
229         }
230         return hashCode;
231     }
232 
233     public final boolean isOptional() {
234         return optional;
235     }
236 
237     public final String   toString() {
238         if (string == null) {
239             final StringBuffer   buffer = new StringBuffer  ();
240 
241             buffer.append("Parameter("); //$NON-NLS-1$
242             buffer.append(id);
243             buffer.append(',');
244             buffer.append(name);
245             buffer.append(',');
246             buffer.append(values);
247             buffer.append(',');
248             buffer.append(optional);
249             buffer.append(')');
250 
251             string = buffer.toString();
252         }
253 
254         return string;
255     }
256 }
257
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags