KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > core > commands > ParameterType


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 package org.eclipse.core.commands;
12
13 import org.eclipse.core.commands.common.HandleObject;
14 import org.eclipse.core.commands.common.NotDefinedException;
15 import org.eclipse.core.internal.commands.util.Util;
16
17 /**
18  * <p>
19  * Provides information about the type of a command parameter. Clients can use a
20  * parameter type to check if an object matches the type of the parameter with
21  * {@link #isCompatible(Object)} and can get an
22  * {@link AbstractParameterValueConverter} to convert between objects matching
23  * the parameter type and strings that encode the object's identity.
24  * </p>
25  * <p>
26  * A command parameter is not required to declare a type. To determine if a
27  * given parameter has a type, check if an {@link IParameter} implements
28  * {@link ITypedParameter} and if so, use
29  * {@link ITypedParameter#getParameterType()} like this:
30  * </p>
31  *
32  * <pre>
33  * IParameter parameter = // ... get IParameter from Command
34  * if (parameter instanceof ITypedParameter) {
35  * ParameterType type = ((ITypedParameter)parameter).getParameterType();
36  * if (type != null) {
37  * // this parameter has a ParameterType
38  * }
39  * }
40  * </pre>
41  *
42  * @see IParameter
43  * @see ITypedParameter#getParameterType()
44  * @since 3.2
45  */

46 public final class ParameterType extends HandleObject implements Comparable JavaDoc {
47
48     /**
49      * TODO: this was copied from
50      * org.eclipse.core.internal.expressions.Expressions is there a better place
51      * to reference this?
52      *
53      * @param element
54      * The element to test; may be <code>null</code>.
55      * @param type
56      * The type against which we are testing;may be <code>null</code>.
57      * @return <code>true</code> if the <code>element</code> is an instance
58      * of <code>type</code>; <code>false</code> otherwise.
59      */

60     private static final boolean isInstanceOf(final Object JavaDoc element,
61             final String JavaDoc type) {
62         // null isn't an instanceof of anything.
63
if (element == null) {
64             return false;
65         }
66         return isSubtype(element.getClass(), type);
67     }
68
69     /**
70      * TODO: this was copied from
71      * org.eclipse.core.internal.expressions.Expressions is there a better place
72      * to reference this?
73      *
74      * @param clazz
75      * The class to match; may be <code>null</code>.
76      * @param type
77      * The type against which we are testing;may be <code>null</code>.
78      * @return <code>true</code> if the <code>element</code> is an instance
79      * of <code>type</code>; <code>false</code> otherwise.
80      */

81     private static final boolean isSubtype(final Class JavaDoc clazz, final String JavaDoc type) {
82         if (clazz.getName().equals(type)) {
83             return true;
84         }
85         final Class JavaDoc superClass = clazz.getSuperclass();
86         if (superClass != null && isSubtype(superClass, type)) {
87             return true;
88         }
89         final Class JavaDoc[] interfaces = clazz.getInterfaces();
90         for (int i = 0; i < interfaces.length; i++) {
91             if (isSubtype(interfaces[i], type)) {
92                 return true;
93             }
94         }
95         return false;
96     }
97
98     /**
99      * An {@link AbstractParameterValueConverter} for converting parameter
100      * values between objects and strings. This may be <code>null</code>.
101      */

102     private transient AbstractParameterValueConverter parameterTypeConverter;
103
104     /**
105      * A string specifying the object type of this parameter type. This will be
106      * <code>null</code> when the parameter type is undefined but never null
107      * when it is defined.
108      */

109     private transient String JavaDoc type = null;
110
111     /**
112      * Constructs a new instance based on the given identifier. When a parameter
113      * type is first constructed, it is undefined. Parameter types should only
114      * be constructed by the {@link CommandManager} to ensure that the
115      * identifier remains unique.
116      *
117      * @param id
118      * The identifier for this type. This value must not be
119      * <code>null</code>, and must be unique amongst all parameter
120      * types.
121      */

122     ParameterType(final String JavaDoc id) {
123         super(id);
124     }
125
126     /**
127      * Adds a listener to this parameter type that will be notified when its
128      * state changes.
129      *
130      * @param listener
131      * The listener to be added; must not be <code>null</code>.
132      */

133     public final void addListener(final IParameterTypeListener listener) {
134         addListenerObject(listener);
135     }
136
137     /**
138      * Compares this parameter type with another object by comparing each of the
139      * non-transient attributes.
140      *
141      * @param object
142      * The object with which to compare; must be an instance of
143      * {@link ParameterType}.
144      * @return A negative integer, zero or a positive integer, if the object is
145      * greater than, equal to or less than this parameter type.
146      */

147     public final int compareTo(final Object JavaDoc object) {
148         final ParameterType castedObject = (ParameterType) object;
149         int compareTo = Util.compare(defined, castedObject.defined);
150         if (compareTo == 0) {
151             compareTo = Util.compare(id, castedObject.id);
152         }
153         return compareTo;
154     }
155
156     /**
157      * <p>
158      * Defines this parameter type, setting the defined property to
159      * <code>true</code>.
160      * </p>
161      * <p>
162      * Notification is sent to all listeners that something has changed.
163      * </p>
164      *
165      * @param type
166      * a string identifying the Java object type for this parameter
167      * type; <code>null</code> is interpreted as
168      * <code>"java.lang.Object"</code>
169      * @param parameterTypeConverter
170      * an {@link AbstractParameterValueConverter} to perform
171      * string/object conversions for parameter values; may be
172      * <code>null</code>
173      */

174     public final void define(final String JavaDoc type,
175             final AbstractParameterValueConverter parameterTypeConverter) {
176
177         final boolean definedChanged = !this.defined;
178         this.defined = true;
179
180         this.type = (type == null) ? Object JavaDoc.class.getName() : type;
181         this.parameterTypeConverter = parameterTypeConverter;
182
183         fireParameterTypeChanged(new ParameterTypeEvent(this, definedChanged));
184     }
185
186     /**
187      * Notifies all listeners that this parameter type has changed. This sends
188      * the given event to all of the listeners, if any.
189      *
190      * @param event
191      * The event to send to the listeners; must not be
192      * <code>null</code>.
193      */

194     private final void fireParameterTypeChanged(final ParameterTypeEvent event) {
195         if (event == null) {
196             throw new NullPointerException JavaDoc(
197                     "Cannot send a null event to listeners."); //$NON-NLS-1$
198
}
199
200         if (!isListenerAttached()) {
201             return;
202         }
203
204         final Object JavaDoc[] listeners = getListeners();
205         for (int i = 0; i < listeners.length; i++) {
206             final IParameterTypeListener listener = (IParameterTypeListener) listeners[i];
207             listener.parameterTypeChanged(event);
208         }
209     }
210
211     /**
212      * Returns the value converter associated with this parameter, if any.
213      *
214      * @return The parameter value converter, or <code>null</code> if there is
215      * no value converter for this parameter.
216      * @throws NotDefinedException
217      * if the parameter type is not currently defined
218      */

219     public final AbstractParameterValueConverter getValueConverter()
220             throws NotDefinedException {
221         if (!isDefined()) {
222             throw new NotDefinedException(
223                     "Cannot use getValueConverter() with an undefined ParameterType"); //$NON-NLS-1$
224
}
225
226         return parameterTypeConverter;
227     }
228
229     /**
230      * Returns whether the provided value is compatible with this parameter
231      * type. An object is compatible with a parameter type if the object is an
232      * instance of the class defined as the parameter's type class.
233      *
234      * @param value
235      * an object to check for compatibility with this parameter type;
236      * may be <code>null</code>.
237      * @return <code>true</code> if the value is compatible with this type,
238      * <code>false</code> otherwise
239      * @throws NotDefinedException
240      * if the parameter type is not currently defined
241      */

242     public boolean isCompatible(Object JavaDoc value) throws NotDefinedException {
243         if (!isDefined()) {
244             throw new NotDefinedException(
245                     "Cannot use isCompatible() with an undefined ParameterType"); //$NON-NLS-1$
246
}
247         return isInstanceOf(value, type);
248     }
249
250     /**
251      * Unregisters listener for changes to properties of this parameter type.
252      *
253      * @param listener
254      * the instance to unregister. Must not be <code>null</code>.
255      * If an attempt is made to unregister an instance which is not
256      * already registered with this instance, no operation is
257      * performed.
258      */

259     public final void removeListener(final IParameterTypeListener listener) {
260         removeListenerObject(listener);
261     }
262
263     /**
264      * The string representation of this parameter type. For debugging purposes
265      * only. This string should not be shown to an end user.
266      *
267      * @return The string representation; never <code>null</code>.
268      */

269     public final String JavaDoc toString() {
270         if (string == null) {
271             final StringBuffer JavaDoc stringBuffer = new StringBuffer JavaDoc();
272             stringBuffer.append("ParameterType("); //$NON-NLS-1$
273
stringBuffer.append(id);
274             stringBuffer.append(',');
275             stringBuffer.append(defined);
276             stringBuffer.append(')');
277             string = stringBuffer.toString();
278         }
279         return string;
280     }
281
282     /**
283      * Makes this parameter type become undefined. Notification is sent to all
284      * listeners.
285      */

286     public final void undefine() {
287         string = null;
288
289         final boolean definedChanged = defined;
290         defined = false;
291
292         type = null;
293         parameterTypeConverter = null;
294
295         fireParameterTypeChanged(new ParameterTypeEvent(this, definedChanged));
296     }
297
298 }
299
Popular Tags