01: /*
02: * Copyright 2007 Google Inc.
03: *
04: * Licensed under the Apache License, Version 2.0 (the "License"); you may not
05: * use this file except in compliance with the License. You may obtain a copy of
06: * the License at
07: *
08: * http://www.apache.org/licenses/LICENSE-2.0
09: *
10: * Unless required by applicable law or agreed to in writing, software
11: * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12: * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13: * License for the specific language governing permissions and limitations under
14: * the License.
15: */
16: package com.google.gwt.user.client;
17:
18: /**
19: * This class allows you to execute code after all currently pending event
20: * handlers have completed, using the {@link #addCommand(Command)} or
21: * {@link #addCommand(IncrementalCommand)} methods. This is useful when you need
22: * to execute code outside of the context of the current stack.
23: */
24: public class DeferredCommand {
25: private static final CommandExecutor commandExecutor = new CommandExecutor();
26:
27: /**
28: * Enqueues a {@link Command} to be fired after all current events have been
29: * handled.
30: *
31: * @param cmd the command to be fired. If cmd is null, a "pause" will be
32: * inserted into the queue. Any events added after the pause will
33: * wait for an additional cycle through the system event loop before
34: * executing. Pauses are cumulative.
35: *
36: * @deprecated As of release 1.4, replaced by {@link #addCommand(Command)}
37: */
38: @Deprecated
39: public static void add(Command cmd) {
40: commandExecutor.submit(cmd);
41: }
42:
43: /**
44: * Enqueues a {@link Command} to be fired after all current events have been
45: * handled.
46: *
47: * Note that the {@link Command} should not perform any blocking operations.
48: *
49: * @param cmd the command to be fired
50: * @throws NullPointerException if cmd is <code>null</code>
51: */
52: public static void addCommand(Command cmd) {
53: if (cmd == null) {
54: throw new NullPointerException("cmd can not be null");
55: }
56:
57: commandExecutor.submit(cmd);
58: }
59:
60: /**
61: * Enqueues an {@link IncrementalCommand} to be fired after all current events
62: * have been handled.
63: *
64: * Note that the {@link IncrementalCommand} should not perform any blocking
65: * operations.
66: *
67: * @param cmd the command to be fired
68: * @throws NullPointerException if cmd is <code>null</code>
69: */
70: public static void addCommand(IncrementalCommand cmd) {
71: if (cmd == null) {
72: throw new NullPointerException("cmd can not be null");
73: }
74:
75: commandExecutor.submit(cmd);
76: }
77:
78: /**
79: * Adds a "pause" to the queue of {@link DeferredCommand}s. Any
80: * {@link DeferredCommand}s or pauses that are added after this pause will
81: * wait for an additional cycle through the system event loop before
82: * executing.
83: */
84: public static void addPause() {
85: commandExecutor.submit((Command) null);
86: }
87: }
|