IOEvent


1   /*
2    * The contents of this file are subject to the terms of the Common Development
3    * and Distribution License (the License). You may not use this file except in
4    * compliance with the License.
5    *
6    * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7    * or http://www.netbeans.org/cddl.txt.
8    *
9    * When distributing Covered Code, include this CDDL Header Notice in each file
10   * and include the License file at http://www.netbeans.org/cddl.txt.
11   * If applicable, add the following below the CDDL Header, with the fields
12   * enclosed by brackets [] replaced by your own identifying information:
13   * "Portions Copyrighted [year] [name of copyright owner]"
14   *
15   * The Original Software is NetBeans. The Initial Developer of the Original
16   * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17   * Microsystems, Inc. All Rights Reserved.
18   */
19  package org.netbeans.core.output2;
20  
21  import java.awt.*;
22  import java.util.Arrays  ;
23  
24  /**
25   * An event type which carries data about an operation performed on an
26   * instance of NbIO which an interested view must respond to on the
27   * event queue.
28   * <p>
29   * While this is an unusual approach, it is also using the event queue in
30   * exactly the way event queues are designed to be used.  It accomplishes
31   * complete decoupling of the IO implementation from the view implementation -
32   * the IO does not need to know anything about what component is rendering
33   * it, it just posts relevant events onto the event queue.
34   * <p>
35   * Unfortunately, it is impossible to use an AWTEventListener to get notification
36   * of custom event types (appears that it once was, and was optimized out in
37   * the biggest if/then clause in history - see Toolkit).  So we have the
38   * dispatch() method.
39   * <p>
40   * While all this could be done with SwingUtilities.invokeLater() and runnables,
41   * this approach works well and is somewhat more lightweight, so I see no need
42   * to change it.
43   * <p>
44   * Should someone want to make this package capable of supporting multiple
45   * output windows, for some reason, the only thing necessary to do is to
46   * add a registry of weakly referenced OutputContainers and iterate them all
47   * in <code>dispatch()</code> - the only static tie to the rest of the
48   * universe is the DEFAULT field of Controller.
49   *
50   * @author Tim Boudreau
51   */
52  final class IOEvent extends AWTEvent implements ActiveEvent {
53      static final int IO_EVENT_MASK = 0xF0000;
54      /**
55       * Command instructing the controller to create a new view for the IO.
56       * If getValue() returns true, it will try to find an existing closed tab
57       * with the same name and reuse it.
58       */
59      static final int CMD_CREATE = 0;
60      /**
61       * Command to set the output visible.  Output is always visible in the current
62       * implementation, so this command is provided for completeness but will be ignored.
63       */
64      static final int CMD_OUTPUT_VISIBLE=1;
65      /**
66       * Set the input area visible.
67       */
68      static final int CMD_INPUT_VISIBLE=2;
69      /**
70       * Command to set the error output visible.  Error output is interleaved in the current
71       * implementation, so this command is provided for completeness but will be ignored.
72       */
73      static final int CMD_ERR_VISIBLE=3;
74      /**
75       * Provided for completeness but will be ignored.
76       */
77      static final int CMD_ERR_SEPARATED=4;
78  
79      /**
80       * Evil and unwise but supported.
81       */
82      static final int CMD_FOCUS_TAKEN=5;
83      /**
84       * Command indicating that the IO should become the selected tab.
85       */
86      static final int CMD_SELECT=6;
87      /**
88       * Command indicating that the IO's tab should be closed.
89       */
90      static final int CMD_CLOSE=7;
91      /**
92       * Command indicating that the IO has been closed for writes and the UI should performe
93       * any needed state changes to reflect that.
94       */
95      static final int CMD_STREAM_CLOSED=8;
96      /**
97       * Command indicating that the output writer's reset() method has been called, and that any
98       * exiting output in the IO's tab should be discarded, and the closed flag reset.
99       */
100     static final int CMD_RESET=9;
101     /**
102      * Set the toolbar actions that should be displayed.
103      */
104     static final int CMD_SET_TOOLBAR_ACTIONS = 10;
105     /**
106      * XXX may not be supported - dispose of the default output window instance
107      */
108     static final int CMD_DETACH = 11;
109     
110     /**
111      * change the icon on the tab..
112      */
113     static final int CMD_ICON = 12;
114 
115     
116     /**
117      * Array of IDs for checking legal values and generating a string representing the event.
118      */
119     private static final int[] IDS = new int[] {
120         CMD_CREATE,
121         CMD_OUTPUT_VISIBLE,
122         CMD_INPUT_VISIBLE,
123         CMD_ERR_VISIBLE,
124         CMD_ERR_SEPARATED,
125         CMD_FOCUS_TAKEN,
126         CMD_SELECT,
127         CMD_CLOSE,
128         CMD_STREAM_CLOSED,
129         CMD_RESET,
130         CMD_SET_TOOLBAR_ACTIONS,
131         CMD_DETACH,
132         CMD_ICON
133     };
134 
135     /**
136      * Strings matching the values in the IDS array for generating a string representing the event.
137      */
138     private static final String  [] CMDS = new String  [] {
139         "CREATE", //NOI18N
140         "OUTPUT_VISIBLE", //NOI18N
141         "INPUT_VISIBLE", //NOI18N
142         "ERR_VISIBLE", //NOI18N
143         "ERR_SEPARATED", //NOI18N
144         "FOCUS_TAKEN", //NOI18N
145         "SELECT", //NOI18N
146         "CLOSE", //NOI18N
147         "STREAM_CLOSED", //NOI18N
148         "RESET", //NOI18N
149         "SET_TOOLBAR_ACTIONS", //NOI18N
150         "DETACH"  //NOI18N
151     };
152 
153     /**
154      * Boolean value associated with this event.
155      */
156     private boolean value = false;
157     /**
158      * Data associated with this event (used by set toolbar actions)
159      */
160     private Object   data = null;
161 
162     /**
163      * Used by unit tests to ensure all pending events have been processed before
164      * continuing.
165      */
166     static int pendingCount = 0;
167     /**
168      * Create an IOEvent with the specified source, command and boolean state for the command.
169      *
170      * @param source An instance of NbIO which something of interest has happened to; can be null
171      *        in the case that this is CMD_DETACH, an instruction to the default instance to
172      *        self-destruct (module uninstalled or winsys wants to install a new instance)
173      * @param command The ID of what has happened
174      * @param value The boolean state for the command to be performed
175      */
176     IOEvent(NbIO source, int command, boolean value) {
177         //Null source only for destroying the default instance
178         super(source == null ? new Object  () : source, command + IO_EVENT_MASK);
179         assert Arrays.binarySearch (IDS, command) >= 0 : "Unknown command: " + command; //NOI18N
180         consumed = false;
181         this.value = value;
182         pendingCount++;
183     }
184 
185     /**
186      * Construct a data-bearing IOEvent with the specified source, commmand and data
187      *
188      * @param source The command source
189      * @param command The ID of what has happened
190      * @param data Data required to process this command (i.e. toolbar actions added)
191      */
192     IOEvent(NbIO source, int command, Object   data) {
193         this (source, command, false);
194         this.data = data;
195     }
196 
197     /**
198      * Convenience getter for the command ID associated with this event.
199      * Equivalent to <code>getID() - IO_EVENT_MASK</code>.
200      *
201      * @return The command
202      */
203     public int getCommand() {
204         return getID() - IO_EVENT_MASK;
205     }
206 
207     /**
208      * Convenience getter for the NbIO associated with this
209      * command.  Equivalent to <code>(NbIO) getSource()</code>
210      * @return
211      */
212     public NbIO getIO() {
213         return getSource() instanceof NbIO ? (NbIO) getSource() : null;
214     }
215 
216     /**
217      * Get a boolean value associated with the event - most use cases involve
218      * some thread calling boolean setters/getters on an instance of NbIO.
219      *
220      * @return The boolean state associated with this command.
221      */
222     public boolean getValue() {
223         return value;
224     }
225 
226     /**
227      * Get data associated with the event.  This is only used for supplying
228      * toolbar actions.
229      *
230      * @return An object
231      */
232     public Object   getData() {
233         return data;
234     }
235 
236     /**
237      * Determine if the event is consumed.  Creation events will be.
238      *
239      * @return If the event is consumed
240      */
241     public boolean isConsumed() {
242         return consumed;
243     }
244 
245     /**
246      * Overridden to avoid a bit of work AWTEvent does that's not
247      * necessary for us.
248      */
249     public void consume() {
250         consumed = true;
251     }
252 
253     public String   toString() {
254         return "IOEvent@" + System.identityHashCode(this) + "-" + 
255             cmdToString(getCommand()) + " on " + getIO() +
256             " value= " + getValue() + " data=" + getData(); //NOI18N
257     }
258 
259     public void dispatch() {
260         //The only thing needed to make this package fully reentrant (capable of
261         //supporting multiple output windows, FWIW) is to replace this line with
262         //iterating a registry of OutputContainers, and calling eventDispatched on each.
263 
264         //Null check below so that if the module has been disabled (the only way
265         //this can be null), the dead module doesn't reopen its output window
266         if (OutputWindow.DEFAULT != null) {
267             //Can be null after CMD_DETACH
268             OutputWindow.DEFAULT.eventDispatched(this);
269         }
270         pendingCount--;
271     }
272 
273     public static String   cmdToString (int cmd) {
274         return CMDS[Arrays.binarySearch(IDS, cmd)];
275     }
276 }
277
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags