001: /*******************************************************************************
002: * Copyright (c) 2000, 2005 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.ui.commands;
011:
012: import java.util.List;
013: import java.util.Map;
014:
015: /**
016: * <p>
017: * An instance of <code>ICommand</code> is a handle representing a command as
018: * defined by the extension point <code>org.eclipse.ui.commands</code>. The
019: * identifier of the handle is identifier of the command being represented.
020: * </p>
021: * <p>
022: * An instance of <code>ICommand</code> can be obtained from an instance of
023: * <code>ICommandManager</code> for any identifier, whether or not a command
024: * with that identifier defined in the plugin registry.
025: * </p>
026: * <p>
027: * The handle-based nature of this API allows it to work well with runtime
028: * plugin activation and deactivation. If a command is defined, that means that
029: * its corresponding plug-in is active. If the plug-in is then deactivated, the
030: * command will still exist but it will be undefined. An attempts to use an
031: * undefined command will result in a <code>NotDefinedException</code> being
032: * thrown.
033: * </p>
034: * <p>
035: * This interface is not intended to be extended or implemented by clients.
036: * </p>
037: *
038: * @since 3.0
039: * @see ICommandListener
040: * @see ICommandManager
041: * @see org.eclipse.core.commands.Command
042: * @deprecated Please use the "org.eclipse.core.commands" plug-in instead.
043: */
044: public interface ICommand extends Comparable {
045:
046: /**
047: * Registers an instance of <code>ICommandListener</code> to listen for
048: * changes to attributes of this instance.
049: *
050: * @param commandListener
051: * the instance of <code>ICommandListener</code> to register.
052: * Must not be <code>null</code>. If an attempt is made to
053: * register an instance of <code>ICommandListener</code> which
054: * is already registered with this instance, no operation is
055: * performed.
056: */
057: void addCommandListener(ICommandListener commandListener);
058:
059: /**
060: * Executes with the map of parameter values by name.
061: *
062: * @param parameterValuesByName
063: * the map of parameter values by name. Reserved for future use,
064: * must be <code>null</code>.
065: * @return the result of the execution. Reserved for future use, must be
066: * <code>null</code>.
067: * @throws ExecutionException
068: * if an exception occurred during execution.
069: * @throws NotHandledException
070: * if this is not handled.
071: */
072: Object execute(Map parameterValuesByName)
073: throws ExecutionException, NotHandledException;
074:
075: /**
076: * Returns the map of attribute values by name.
077: * <p>
078: * Notification is sent to all registered listeners if this property
079: * changes.
080: * </p>
081: *
082: * @return the map of attribute values by name. This map may be empty, but
083: * is guaranteed not to be <code>null</code>. If this map is not
084: * empty, its collection of keys is guaranteed to only contain
085: * instances of <code>String</code>.
086: * @throws NotHandledException
087: * if this is not handled.
088: */
089: Map getAttributeValuesByName() throws NotHandledException;
090:
091: /**
092: * <p>
093: * Returns the identifier of the category of the command represented by this
094: * handle.
095: * </p>
096: * <p>
097: * Notification is sent to all registered listeners if this attribute
098: * changes.
099: * </p>
100: *
101: * @return the identifier of the category of the command represented by this
102: * handle. May be <code>null</code>.
103: * @throws NotDefinedException
104: * if the command represented by this handle is not defined.
105: */
106: String getCategoryId() throws NotDefinedException;
107:
108: /**
109: * <p>
110: * Returns the description of the command represented by this handle,
111: * suitable for display to the user.
112: * </p>
113: * <p>
114: * Notification is sent to all registered listeners if this attribute
115: * changes.
116: * </p>
117: *
118: * @return the description of the command represented by this handle.
119: * Guaranteed not to be <code>null</code>.
120: * @throws NotDefinedException
121: * if the command represented by this handle is not defined.
122: */
123: String getDescription() throws NotDefinedException;
124:
125: /**
126: * Returns the identifier of this handle.
127: *
128: * @return the identifier of this handle. Guaranteed not to be
129: * <code>null</code>.
130: */
131: String getId();
132:
133: /**
134: * <p>
135: * Returns the list of key sequence bindings for this handle. This method
136: * will return all key sequence bindings for this handle's identifier,
137: * whether or not the command represented by this handle is defined.
138: * </p>
139: * <p>
140: * Notification is sent to all registered listeners if this attribute
141: * changes.
142: * </p>
143: *
144: * @return the list of key sequence bindings. This list may be empty, but is
145: * guaranteed not to be <code>null</code>. If this list is not
146: * empty, it is guaranteed to only contain instances of
147: * <code>IKeySequenceBinding</code>.
148: */
149: List getKeySequenceBindings();
150:
151: /**
152: * <p>
153: * Returns the name of the command represented by this handle, suitable for
154: * display to the user.
155: * </p>
156: * <p>
157: * Notification is sent to all registered listeners if this attribute
158: * changes.
159: * </p>
160: *
161: * @return the name of the command represented by this handle. Guaranteed
162: * not to be <code>null</code>.
163: * @throws NotDefinedException
164: * if the command represented by this handle is not defined.
165: */
166: String getName() throws NotDefinedException;
167:
168: /**
169: * <p>
170: * Returns whether or not the command represented by this handle is defined.
171: * </p>
172: * <p>
173: * Notification is sent to all registered listeners if this attribute
174: * changes.
175: * </p>
176: *
177: * @return <code>true</code>, iff the command represented by this handle
178: * is defined.
179: */
180: boolean isDefined();
181:
182: /**
183: * <p>
184: * Returns whether or not this command is handled. A command is handled if
185: * it currently has an <code>IHandler</code> instance associated with it.
186: * A command needs a handler to carry out the {@link ICommand#execute(Map)}
187: * method.
188: * </p>
189: * <p>
190: * Notification is sent to all registered listeners if this attribute
191: * changes.
192: * </p>
193: *
194: * @return <code>true</code>, iff this command is enabled.
195: */
196: boolean isHandled();
197:
198: /**
199: * Unregisters an instance of <code>ICommandListener</code> listening for
200: * changes to attributes of this instance.
201: *
202: * @param commandListener
203: * the instance of <code>ICommandListener</code> to unregister.
204: * Must not be <code>null</code>. If an attempt is made to
205: * unregister an instance of <code>ICommandListener</code>
206: * which is not already registered with this instance, no
207: * operation is performed.
208: */
209: void removeCommandListener(ICommandListener commandListener);
210: }
|