01: /*
02: * ContextProvider.java
03: *
04: * Created on January 24, 2004, 1:29 AM
05: */
06:
07: package org.netbeans.actions.api;
08:
09: import java.util.Map;
10:
11: /** A ContextProvider is supplied to the engine. When the engine needs
12: * to produce or update presenters, it will request the context from the
13: * current contextProvider. This context will be passed in calls to
14: * the system ActionProvider when fetching the enablement & visibility
15: * of actions. The Map's contents is a private contract defined by
16: * an implementation of the actions framework.
17: *
18: * @author Tim Boudreau
19: */
20: public interface ContextProvider {
21: /** Key for an object which can be fetched from the context map,
22: * representing the identity of the context in some unique way.
23: * If non null, the Engine will compare the result of this with
24: * the previous result to determine if it needs to do any work
25: * at all, or if nothing has changed, and any previous state it
26: * set on presenters is still valid.
27: * getContext().get(IDENTITY).equals(previousContext.get(IDENTITY)) if
28: * the keysets of the last-fetched map and the current map contain the
29: * same elements (which must be strings). This makes it possible to
30: * avoid updating actions if a context change has not made any change
31: * that would affect the enablement of actions - i.e. selecting one
32: * text file, then selecting another should cause the engine to be advised
33: * that it may need to update actions, but in fact, no change in state
34: * is needed. So the engine will first test if the last identity equals
35: * the current identity, and if so, never iterate the visible presenters
36: * and try to change their state to the state they're already in.
37: */
38: static String IDENTITY = "identity"; //NOI18N
39:
40: /** Get a map representing the current application context. All the keys
41: * in this map must be Strings. The values are up to the application. In
42: * determining if an action should be enabled, only the presence of a key
43: * is used as the test. Objects needed for the invocation of actions
44: * should be put into the map as values, with a well-defined key to test
45: * against for whether the action should be enabled. The invoker can
46: * then retrieve the object whose method should be called and invoke
47: * the method.
48: * <p>
49: * Implementations should preferably return a meaningful value from
50: * getContext(IDENTITY) which will be the same if the key set is the
51: * same.
52: * <p>
53: * Note that the actions framework reserves the string "identity"
54: * (ContextProvider.IDENTITY) as a map key - implementations of ContextProvider
55: * should not use it as a map key or unpredictable things may happen.
56: */
57: public Map getContext();
58: }
|