ExecutionEvent


1   /*******************************************************************************
2    * Copyright (c) 2005, 2007 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 java.util.Collections  ;
14  import java.util.Map  ;
15  
16  import org.eclipse.core.commands.common.NotDefinedException;
17  
18  /**
19   * <p>
20   * The data object to pass to the command (and its handler) as it executes. This
21   * carries information about the current state of the application, and the
22   * application context in which the command was executed.
23   * </p>
24   * <p>
25   * An execution event carries three blocks of data: the parameters, the trigger,
26   * and the application context. How these blocks are used is application
27   * dependent. In the Eclipse workbench, the trigger is an SWT event, and the
28   * application context contains information about the selection and active part.
29   * </p>
30   * 
31   * @since 3.1
32   */
33  public final class ExecutionEvent {
34  
35      /**
36       * The state of the application at the time the execution was triggered. In
37       * the Eclipse workbench, this might contain information about the active
38       * part of the active selection (for example). This value may be
39       * <code>null</code>.
40       */
41      private final Object   applicationContext;
42  
43      /**
44       * The command being executed. This value may be <code>null</code>.
45       */
46      private final Command command;
47  
48      /**
49       * The parameters to qualify the execution. For handlers that normally
50       * prompt for additional information, these can be used to avoid prompting.
51       * This value may be empty, but it is never <code>null</code>.
52       */
53      private final Map   parameters;
54  
55      /**
56       * The object that triggered the execution. In an event-driven architecture,
57       * this is typically just another event. In the Eclipse workbench, this is
58       * typically an SWT event. This value may be <code>null</code>.
59       */
60      private final Object   trigger;
61  
62      /**
63       * Constructs a new instance of <code>ExecutionEvent</code> with no
64       * parameters, no trigger and no application context. This is just a
65       * convenience method.
66       * 
67       * @since 3.2
68       */
69      public ExecutionEvent() {
70          this(null, Collections.EMPTY_MAP, null, null);
71      }
72  
73      /**
74       * Constructs a new instance of <code>ExecutionEvent</code>.
75       * 
76       * @param parameters
77       *            The parameters to qualify the execution; must not be
78       *            <code>null</code>. This must be a map of parameter ids (<code>String</code>)
79       *            to parameter values (<code>String</code>).
80       * @param trigger
81       *            The object that triggered the execution; may be
82       *            <code>null</code>.
83       * @param applicationContext
84       *            The state of the application at the time the execution was
85       *            triggered; may be <code>null</code>.
86       * @deprecated use
87       *             {@link ExecutionEvent#ExecutionEvent(Command, Map, Object, Object)}
88       */
89      public ExecutionEvent(final Map   parameters, final Object   trigger,
90              final Object   applicationContext) {
91          this(null, parameters, trigger, applicationContext);
92      }
93  
94      /**
95       * Constructs a new instance of <code>ExecutionEvent</code>.
96       * 
97       * @param command
98       *            The command being executed; may be <code>null</code>.
99       * @param parameters
100      *            The parameters to qualify the execution; must not be
101      *            <code>null</code>. This must be a map of parameter ids (<code>String</code>)
102      *            to parameter values (<code>String</code>).
103      * @param trigger
104      *            The object that triggered the execution; may be
105      *            <code>null</code>.
106      * @param applicationContext
107      *            The state of the application at the time the execution was
108      *            triggered; may be <code>null</code>.
109      * @since 3.2
110      */
111     public ExecutionEvent(final Command command, final Map   parameters,
112             final Object   trigger, final Object   applicationContext) {
113         if (parameters == null) {
114             throw new NullPointerException  (
115                     "An execution event must have a non-null map of parameters"); //$NON-NLS-1$
116         }
117 
118         this.command = command;
119         this.parameters = parameters;
120         this.trigger = trigger;
121         this.applicationContext = applicationContext;
122     }
123 
124     /**
125      * Returns the state of the application at the time the execution was
126      * triggered.
127      * 
128      * @return The application context; may be <code>null</code>.
129      */
130     public final Object   getApplicationContext() {
131         return applicationContext;
132     }
133 
134     /**
135      * Returns the command being executed.
136      * 
137      * @return The command being executed.
138      * @since 3.2
139      */
140     public final Command getCommand() {
141         return command;
142     }
143 
144     /**
145      * Returns the object represented by the string value of the parameter with
146      * the provided id.
147      * <p>
148      * This is intended to be used in the scope of an
149      * {@link IHandler#execute(ExecutionEvent)} method, so any problem getting
150      * the object value causes <code>ExecutionException</code> to be thrown.
151      * </p>
152      * 
153      * @param parameterId
154      *            The id of a parameter to retrieve the object value of.
155      * @return The object value of the parameter with the provided id.
156      * @throws ExecutionException
157      *             if the parameter object value could not be obtained for any
158      *             reason
159      * @since 3.2
160      */
161     public final Object   getObjectParameterForExecution(final String   parameterId)
162             throws ExecutionException {
163         if (command == null) {
164             throw new ExecutionException(
165                     "No command is associated with this execution event"); //$NON-NLS-1$
166         }
167 
168         try {
169             final ParameterType parameterType = command
170                     .getParameterType(parameterId);
171             if (parameterType == null) {
172                 throw new ExecutionException(
173                         "Command does not have a parameter type for the given parameter"); //$NON-NLS-1$
174             }
175             final AbstractParameterValueConverter valueConverter = parameterType
176                     .getValueConverter();
177             if (valueConverter == null) {
178                 throw new ExecutionException(
179                         "Command does not have a value converter"); //$NON-NLS-1$
180             }
181             final String   stringValue = getParameter(parameterId);
182             final Object   objectValue = valueConverter
183                     .convertToObject(stringValue);
184             return objectValue;
185         } catch (final NotDefinedException e) {
186             throw new ExecutionException("Command is not defined", e); //$NON-NLS-1$
187         } catch (final ParameterValueConversionException e) {
188             throw new ExecutionException(
189                     "The parameter string could not be converted to an object", e); //$NON-NLS-1$
190         }
191     }
192 
193     /**
194      * Returns the value of the parameter with the given id.
195      * 
196      * @param parameterId
197      *            The id of the parameter to retrieve; may be <code>null</code>.
198      * @return The parameter value; <code>null</code> if the parameter cannot
199      *         be found.
200      */
201     public final String   getParameter(final String   parameterId) {
202         return (String  ) parameters.get(parameterId);
203     }
204 
205     /**
206      * Returns all of the parameters.
207      * 
208      * @return The parameters; never <code>null</code>, but may be empty.
209      */
210     public final Map   getParameters() {
211         return parameters;
212     }
213 
214     /**
215      * Returns the object that triggered the execution
216      * 
217      * @return The trigger; <code>null</code> if there was no trigger.
218      */
219     public final Object   getTrigger() {
220         return trigger;
221     }
222 
223     /**
224      * The string representation of this execution event -- for debugging
225      * purposes only. This string should not be shown to an end user.
226      * 
227      * @return The string representation; never <code>null</code>.
228      */
229     public final String   toString() {
230         final StringBuffer   stringBuffer = new StringBuffer  ();
231         stringBuffer.append("ExecutionEvent("); //$NON-NLS-1$
232         stringBuffer.append(command);
233         stringBuffer.append(',');
234         stringBuffer.append(parameters);
235         stringBuffer.append(',');
236         stringBuffer.append(trigger);
237         stringBuffer.append(',');
238         stringBuffer.append(applicationContext);
239         stringBuffer.append(')');
240         return stringBuffer.toString();
241     }
242 }
243
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags