KickJava   Java API By Example, From Geeks To Geeks.

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


1 /*******************************************************************************
2  * Copyright (c) 2004, 2005 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
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  *
21  * @see AbstractHandler
22  * @since 3.1
23  */
24 public interface IHandler {
25
26     /**
27      * Registers an instance of <code>IHandlerListener</code> to listen for
28      * changes to properties of this instance.
29      *
30      * @param handlerListener
31      * the instance to register. Must not be <code>null</code>. If
32      * an attempt is made to register an instance which is already
33      * registered with this instance, no operation is performed.
34      */
35     void addHandlerListener(IHandlerListener handlerListener);
36
37     /**
38      * Disposes of this handler. This method is run once when the object is no
39      * longer referenced. This can be used as an opportunity to unhook listeners
40      * from other objects.
41      */
42     public void dispose();
43
44     /**
45      * Executes with the map of parameter values by name.
46      *
47      * @param event
48      * An event containing all the information about the current
49      * state of the application; must not be <code>null</code>.
50      * @return the result of the execution. Reserved for future use, must be
51      * <code>null</code>.
52      * @throws ExecutionException
53      * if an exception occurred during execution.
54      */
55     Object JavaDoc execute(ExecutionEvent event) throws ExecutionException;
56
57     /**
58      * Returns whether this handler is capable of executing at this moment in
59      * time.
60      *
61      * @return <code>true</code> if the command is enabled; <code>false</code>
62      * otherwise.
63      */
64     public boolean isEnabled();
65
66     /**
67      * Returns whether this handler is really capable of handling delegation. In
68      * the case of a handler that is a composition of other handlers, this reply
69      * is intended to indicate whether the handler is truly capable of receiving
70      * delegated responsibilities at this time.
71      *
72      * @return <code>true</code> if the handler is handled; <code>false</code>
73      * otherwise.
74      */
75     public boolean isHandled();
76
77     /**
78      * Unregisters an instance of <code>IHandlerListener</code> listening for
79      * changes to properties of this instance.
80      *
81      * @param handlerListener
82      * the instance to unregister. Must not be <code>null</code>.
83      * If an attempt is made to unregister an instance which is not
84      * already registered with this instance, no operation is
85      * performed.
86      */
87     void removeHandlerListener(IHandlerListener handlerListener);
88 }
89
Popular Tags