ICommandService


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.ui.commands;
12  
13  import java.util.Collection  ;
14  import java.util.Map  ;
15  
16  import org.eclipse.core.commands.Category;
17  import org.eclipse.core.commands.Command;
18  import org.eclipse.core.commands.CommandManager;
19  import org.eclipse.core.commands.IExecutionListener;
20  import org.eclipse.core.commands.IHandler;
21  import org.eclipse.core.commands.ParameterType;
22  import org.eclipse.core.commands.ParameterizedCommand;
23  import org.eclipse.core.commands.SerializationException;
24  import org.eclipse.core.commands.common.NotDefinedException;
25  import org.eclipse.ui.menus.UIElement;
26  import org.eclipse.ui.services.IDisposable;
27  
28  /**
29   * <p>
30   * Provides services related to the command architecture within the workbench.
31   * This service can be used to access the set of commands and command
32   * categories.
33   * </p>
34   * <p>
35   * This interface should not be implemented or extended by clients.
36   * </p>
37   * 
38   * @since 3.1
39   */
40  public interface ICommandService extends IDisposable {
41  
42      /**
43       * The identifier of the category in which all auto-generated commands will
44       * appear. This value must never be <code>null</code>.
45       * 
46       * @since 3.2
47       */
48      public static final String   AUTOGENERATED_CATEGORY_ID = CommandManager.AUTOGENERATED_CATEGORY_ID;
49  
50      /**
51       * Adds an execution listener to the command service. This listener will be
52       * notified as commands are executed.
53       * 
54       * @param listener
55       *            The listener to add; must not be <code>null</code>.
56       */
57      public void addExecutionListener(IExecutionListener listener);
58  
59      /**
60       * Sets the name and description of the category for uncategorized commands.
61       * This is the category that will be returned if
62       * {@link #getCategory(String)} is called with <code>null</code>.
63       * 
64       * @param name
65       *            The name of the category for uncategorized commands; must not
66       *            be <code>null</code>.
67       * @param description
68       *            The description of the category for uncategorized commands;
69       *            may be <code>null</code>.
70       * @since 3.2
71       */
72      public void defineUncategorizedCategory(String   name, String   description);
73  
74      /**
75       * <p>
76       * Returns a {@link ParameterizedCommand} with a command and
77       * parameterizations as specified in the provided
78       * <code>serializedParameterizedCommand</code> string. The
79       * <code>serializedParameterizedCommand</code> must use the format
80       * returned by {@link ParameterizedCommand#serialize()} and described in the
81       * Javadoc for that method.
82       * </p>
83       * <p>
84       * If a parameter id encoded in the
85       * <code>serializedParameterizedCommand</code> does not exist in the
86       * encoded command, that parameter id and value are ignored. A given
87       * parameter id should not be used more than once in
88       * <code>serializedParameterizedCommand</code>. This will not result in
89       * an exception, but the value of the parameter when the command is executed
90       * cannot be specified here.
91       * </p>
92       * <p>
93       * This method will never return <code>null</code>, however it may throw
94       * an exception if there is a problem processing the serialization string or
95       * the encoded command is undefined.
96       * </p>
97       * 
98       * @param serializedParameterizedCommand
99       *            a <code>String</code> representing a command id and
100      *            parameter ids and values
101      * @return a <code>ParameterizedCommand</code> with the command and
102      *         parameterizations encoded in the
103      *         <code>serializedParameterizedCommand</code>
104      * @throws NotDefinedException
105      *             if the command indicated in
106      *             <code>serializedParameterizedCommand</code> is not defined
107      * @throws SerializationException
108      *             if there is an error deserializing
109      *             <code>serializedParameterizedCommand</code>
110      * @see ParameterizedCommand#serialize()
111      * @see CommandManager#deserialize(String)
112      * @since 3.2
113      */
114     public ParameterizedCommand deserialize(
115             String   serializedParameterizedCommand) throws NotDefinedException,
116             SerializationException;
117 
118     /**
119      * Retrieves the category with the given identifier. If no such category
120      * exists, then an undefined category with the given id is created.
121      * 
122      * @param categoryId
123      *            The identifier to find. If the category is <code>null</code>,
124      *            then a category suitable for uncategorized items is defined
125      *            and returned.
126      * @return A category with the given identifier, either defined or
127      *         undefined.
128      */
129     public Category getCategory(String   categoryId);
130 
131     /**
132      * Retrieves the command with the given identifier. If no such command
133      * exists, then an undefined command with the given id is created.
134      * 
135      * @param commandId
136      *            The identifier to find; must not be <code>null</code>.
137      * @return A command with the given identifier, either defined or undefined.
138      */
139     public Command getCommand(String   commandId);
140 
141     /**
142      * Returns the collection of all of the defined categories in the workbench.
143      * 
144      * @return The collection of categories (<code>Category</code>) that are
145      *         defined; never <code>null</code>, but may be empty.
146      * @since 3.2
147      */
148     public Category[] getDefinedCategories();
149 
150     /**
151      * Returns the collection of the identifiers for all of the defined
152      * categories in the workbench.
153      * 
154      * @return The collection of category identifiers (<code>String</code>)
155      *         that are defined; never <code>null</code>, but may be empty.
156      */
157     public Collection   getDefinedCategoryIds();
158 
159     /**
160      * Returns the collection of the identifiers for all of the defined commands
161      * in the workbench.
162      * 
163      * @return The collection of command identifiers (<code>String</code>)
164      *         that are defined; never <code>null</code>, but may be empty.
165      */
166     public Collection   getDefinedCommandIds();
167 
168     /**
169      * Returns the collection of all of the defined commands in the workbench.
170      * 
171      * @return The collection of commands (<code>Command</code>) that are
172      *         defined; never <code>null</code>, but may be empty.
173      * @since 3.2
174      */
175     public Command[] getDefinedCommands();
176 
177     /**
178      * Returns the collection of the identifiers for all of the defined command
179      * parameter types in the workbench.
180      * 
181      * @return The collection of command parameter type identifiers (<code>String</code>)
182      *         that are defined; never <code>null</code>, but may be empty.
183      * @since 3.2
184      */
185     public Collection   getDefinedParameterTypeIds();
186 
187     /**
188      * Returns the collection of all of the defined command parameter types in
189      * the workbench.
190      * 
191      * @return The collection of command parameter types (<code>ParameterType</code>)
192      *         that are defined; never <code>null</code>, but may be empty.
193      * @since 3.2
194      */
195     public ParameterType[] getDefinedParameterTypes();
196 
197     /**
198      * Gets the help context identifier for a particular command. The command's
199      * handler is first checked for a help context identifier. If the handler
200      * does not have a help context identifier, then the help context identifier
201      * for the command is returned. If neither has a help context identifier,
202      * then <code>null</code> is returned.
203      * 
204      * @param command
205      *            The command for which the help context should be retrieved;
206      *            must not be <code>null</code>.
207      * @return The help context identifier to use for the given command; may be
208      *         <code>null</code>.
209      * @throws NotDefinedException
210      *             If the given command is not defined.
211      * @since 3.2
212      */
213     public String   getHelpContextId(Command command) throws NotDefinedException;
214 
215     /**
216      * Gets the help context identifier for a particular command. The command's
217      * handler is first checked for a help context identifier. If the handler
218      * does not have a help context identifier, then the help context identifier
219      * for the command is returned. If neither has a help context identifier,
220      * then <code>null</code> is returned.
221      * 
222      * @param commandId
223      *            The identifier of the command for which the help context
224      *            should be retrieved; must not be <code>null</code>.
225      * @return The help context identifier to use for the given command; may be
226      *         <code>null</code>.
227      * @throws NotDefinedException
228      *             If the command with the given identifier is not defined.
229      * @since 3.2
230      */
231     public String   getHelpContextId(String   commandId) throws NotDefinedException;
232 
233     /**
234      * Retrieves the command parameter type with the given identifier. If no
235      * such parameter type exists, then an undefined parameter type with the
236      * given id is created.
237      * 
238      * @param parameterTypeId
239      *            The identifier to find; must not be <code>null</code>.
240      * @return A command parameter type with the given identifier, either
241      *         defined or undefined.
242      * @since 3.2
243      */
244     public ParameterType getParameterType(String   parameterTypeId);
245 
246     /**
247      * <p>
248      * Reads the command information from the registry and the preferences. This
249      * will overwrite any of the existing information in the command service.
250      * This method is intended to be called during start-up. When this method
251      * completes, this command service will reflect the current state of the
252      * registry and preference store.
253      * </p>
254      */
255     public void readRegistry();
256 
257     /**
258      * Removes an execution listener from the command service.
259      * 
260      * @param listener
261      *            The listener to remove; must not be <code>null</code>.
262      */
263     public void removeExecutionListener(IExecutionListener listener);
264 
265     /**
266      * Sets the help context identifier to associate with a particular handler.
267      * 
268      * @param handler
269      *            The handler with which to register a help context identifier;
270      *            must not be <code>null</code>.
271      * @param helpContextId
272      *            The help context identifier to register; may be
273      *            <code>null</code> if the help context identifier should be
274      *            removed.
275      * @since 3.2
276      */
277     public void setHelpContextId(IHandler handler, String   helpContextId);
278 
279     /**
280      * Register that this element accepts callbacks for this parameterized
281      * command.
282      * 
283      * @param command
284      *            The parameterized command that is already specialized. Must
285      *            not be <code>null</code>.
286      * @param element
287      *            The callback to register for this specialized command
288      *            instance. Must not be <code>null</code>.
289      * @return A reference for the registered element that can be used to
290      *         unregister it.
291      * @throws NotDefinedException
292      *             If the command included in the ParameterizedCommand is not
293      *             defined, or the element is <code>null</code>.
294      * @since 3.3
295      */
296     public IElementReference registerElementForCommand(
297             ParameterizedCommand command, UIElement element)
298             throws NotDefinedException;
299 
300     /**
301      * Re-register a callback element provided by the ICommandService. This
302      * element reference must not currently be held by the ICommandService. i.e.
303      * it must have been removed using
304      * {@link #unregisterElement(IElementReference)}.
305      * 
306      * @param elementReference
307      *            The reference to re-register. Must not be <code>null</code>.
308      * @since 3.3
309      */
310     public void registerElement(IElementReference elementReference);
311 
312     /**
313      * Unregister an element callback. It will be removed from the
314      * ICommandService. The same service that is used to register an element for
315      * a command <b>must</b> be used to unregister the element.
316      * 
317      * @param elementReference
318      *            The callback reference that was provided by the command
319      *            service on registration. Must not be <code>null</code>.
320      * @since 3.3
321      */
322     public void unregisterElement(IElementReference elementReference);
323 
324     /**
325      * Refresh any elements registered against the command with the given id.
326      * It allows the active handler the opportunity to provide user feedback. If
327      * the command is parameterized, some of the parameters can be specified to
328      * help narrow down which elements to refresh.
329      * <p>
330      * The service locator used in registering the element can also be used to
331      * scope the search. For example: if you wanted all elements for your
332      * command but only within the part's workbench window, you could use:
333      * 
334      * <pre>
335      * Map filter = new HashMap();
336      * filter.put(IServiceScopes.WINDOW_SCOPE, getSite().getPage()
337      *      .getWorkbenchWindow());
338      * commandService.refreshElements(commandId, filter);
339      * </pre>
340      * 
341      * </p>
342      * 
343      * @param commandId
344      *            The command id to refresh if it has registered eleemnts.
345      * @param filter
346      *            key-value pairs that can narrow down the callbacks to return.
347      *            The parameters are <b>AND</b>ed together. This may be
348      *            <code>null</code>.
349      * @since 3.3
350      */
351     public void refreshElements(String   commandId, Map   filter);
352 }
353
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags