01: /*******************************************************************************
02: * Copyright (c) 2003, 2005 IBM Corporation and others.
03: * All rights reserved. This program and the accompanying materials
04: * are made available under the terms of the Eclipse Public License v1.0
05: * which accompanies this distribution, and is available at
06: * http://www.eclipse.org/legal/epl-v10.html
07: *
08: * Contributors:
09: * IBM Corporation - initial API and implementation
10: *******************************************************************************/package org.eclipse.ui.commands;
11:
12: import java.util.Map;
13:
14: /**
15: * A handler is the pluggable piece of a command that handles execution. Each
16: * command can have zero or more handlers associated with it (in general), of
17: * which only one will be active at any given moment in time. When the command
18: * is asked to execute, it will simply pass that request on to its active
19: * handler, if any.
20: * <p>
21: * This interface is not intended to be extended by clients.
22: * </p>
23: *
24: * @since 3.0
25: * @deprecated Please use the "org.eclipse.core.commands" plug-in instead.
26: * @see org.eclipse.core.commands.IHandler
27: */
28: public interface IHandler {
29:
30: /**
31: * Registers an instance of <code>IHandlerListener</code> to listen for
32: * changes to properties of this instance.
33: *
34: * @param handlerListener
35: * the instance to register. Must not be <code>null</code>. If
36: * an attempt is made to register an instance which is already
37: * registered with this instance, no operation is performed.
38: */
39: void addHandlerListener(IHandlerListener handlerListener);
40:
41: /**
42: * Disposes of this handler. This method is run once when the object is no
43: * longer referenced. This can be used as an opportunity to unhook listeners
44: * from other objects.
45: */
46: public void dispose();
47:
48: /**
49: * Executes with the map of parameter values by name.
50: *
51: * @param parameterValuesByName
52: * the map of parameter values by name. Reserved for future use,
53: * must be <code>null</code>.
54: * @return the result of the execution. Reserved for future use, must be
55: * <code>null</code>.
56: * @throws ExecutionException
57: * if an exception occurred during execution.
58: */
59: Object execute(Map parameterValuesByName) throws ExecutionException;
60:
61: /**
62: * Returns the map of attribute values by name.
63: * <p>
64: * Notification is sent to all registered listeners if this property
65: * changes.
66: * </p>
67: *
68: * @return the map of attribute values by name. This map may be empty, but
69: * is guaranteed not to be <code>null</code>. If this map is not
70: * empty, its collection of keys is guaranteed to only contain
71: * instances of <code>String</code>.
72: */
73: Map getAttributeValuesByName();
74:
75: /**
76: * Unregisters an instance of <code>IPropertyListener</code> listening for
77: * changes to properties of this instance.
78: *
79: * @param handlerListener
80: * the instance to unregister. Must not be <code>null</code>.
81: * If an attempt is made to unregister an instance which is not
82: * already registered with this instance, no operation is
83: * performed.
84: */
85: void removeHandlerListener(IHandlerListener handlerListener);
86: }
|