| /* |
| * Copyright 2009 Google Inc. |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); you may not |
| * use this file except in compliance with the License. You may obtain a copy of |
| * the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT |
| * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the |
| * License for the specific language governing permissions and limitations under |
| * the License. |
| */ |
| package com.google.gwt.core.client; |
| |
| import com.google.gwt.core.client.impl.SchedulerImpl; |
| |
| /** |
| * This class provides low-level task scheduling primitives. Any exceptions |
| * thrown by the command objects executed by the scheduler will be passed to the |
| * {@link GWT.UncaughtExceptionHandler} if one is installed. |
| * |
| * <p> |
| * NOTE: If you are using a timer to schedule a UI animation, use |
| * {@link com.google.gwt.animation.client.AnimationScheduler} instead. The |
| * browser can optimize your animation for maximum performance. |
| * </p> |
| * |
| * @see com.google.gwt.core.client.testing.StubScheduler |
| */ |
| public abstract class Scheduler { |
| |
| /** |
| * General-purpose Command interface for tasks that repeat. |
| */ |
| public interface RepeatingCommand { |
| /** |
| * Returns true if the RepeatingCommand should be invoked again. |
| */ |
| boolean execute(); |
| } |
| |
| /** |
| * General-purpose Command interface. |
| */ |
| public interface ScheduledCommand { |
| /** |
| * Invokes the command. |
| */ |
| void execute(); |
| } |
| |
| /** |
| * Returns the default implementation of the Scheduler API. |
| */ |
| public static Scheduler get() { |
| return SchedulerImpl.INSTANCE; |
| } |
| |
| /** |
| * A deferred command is executed after the browser event loop returns. |
| */ |
| public abstract void scheduleDeferred(ScheduledCommand cmd); |
| |
| /** |
| * An "entry" command will be executed before GWT-generated code is invoked by |
| * the browser's event loop. The {@link RepeatingCommand} will be called once |
| * per entry from the event loop until <code>false</code> is returned. This |
| * type of command is appropriate for instrumentation or code that needs to |
| * know when "something happens." |
| * <p> |
| * If an entry command schedules another entry command, the second command |
| * will be executed before control flow continues to the GWT-generated code. |
| */ |
| public abstract void scheduleEntry(RepeatingCommand cmd); |
| |
| /** |
| * An "entry" command will be executed before GWT-generated code is invoked by |
| * the browser's event loop. This type of command is appropriate for code that |
| * needs to know when "something happens." |
| * <p> |
| * If an entry command schedules another entry command, the second command |
| * will be executed before control flow continues to the GWT-generated code. |
| */ |
| public abstract void scheduleEntry(ScheduledCommand cmd); |
| |
| /** |
| * A "finally" command will be executed before GWT-generated code returns |
| * control to the browser's event loop. The {@link RepeatingCommand#execute()} |
| * method will be called once per exit to the event loop until |
| * <code>false</code> is returned. This type of command is appropriate for |
| * instrumentation or cleanup code. |
| * <p> |
| * If a finally command schedules another finally command, the second command |
| * will be executed before control flow returns to the browser. |
| */ |
| public abstract void scheduleFinally(RepeatingCommand cmd); |
| |
| /** |
| * A "finally" command will be executed before GWT-generated code returns |
| * control to the browser's event loop. This type of command is used to |
| * aggregate small amounts of work before performing a non-recurring, |
| * heavyweight operation. |
| * <p> |
| * If a finally command schedules another finally command, the second command |
| * will be executed before control flow returns to the browser. |
| * <p> |
| * Consider the following: |
| * |
| * <pre> |
| * try { |
| * nativeEventCallback(); // Calls scheduleFinally one or more times |
| * } finally { |
| * executeFinallyCommands(); |
| * } |
| * </pre> |
| * |
| * @see com.google.gwt.dom.client.StyleInjector |
| */ |
| public abstract void scheduleFinally(ScheduledCommand cmd); |
| |
| /** |
| * Schedules a repeating command that is scheduled with a constant delay. That |
| * is, the next invocation of the command will be scheduled for |
| * <code>delayMs</code> milliseconds after the last invocation completes. |
| * <p> |
| * For example, assume that a command takes 30ms to run and a 100ms delay is |
| * provided. The second invocation of the command will occur at 130ms after |
| * the first invocation starts. |
| * |
| * @param cmd the command to execute |
| * @param delayMs the amount of time to wait after one invocation ends before |
| * the next invocation |
| */ |
| public abstract void scheduleFixedDelay(RepeatingCommand cmd, int delayMs); |
| |
| /** |
| * Schedules a repeating command that is scheduled with a constant |
| * periodicity. That is, the command will be invoked every |
| * <code>delayMs</code> milliseconds, regardless of how long the previous |
| * invocation took to complete. |
| * |
| * @param cmd the command to execute |
| * @param delayMs the period with which the command is executed |
| */ |
| public abstract void scheduleFixedPeriod(RepeatingCommand cmd, int delayMs); |
| |
| /** |
| * Schedules a repeating command that performs incremental work. This type of |
| * command is encouraged for long-running processes that perform computation |
| * or that manipulate the DOM. The commands in this queue are invoked many |
| * times in rapid succession and are then deferred to allow the browser to |
| * process its event queue. |
| * |
| * @param cmd the command to execute |
| */ |
| public abstract void scheduleIncremental(RepeatingCommand cmd); |
| } |