| /* |
| * Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved. |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| * |
| * This code is free software; you can redistribute it and/or modify it |
| * under the terms of the GNU General Public License version 2 only, as |
| * published by the Free Software Foundation. Oracle designates this |
| * particular file as subject to the "Classpath" exception as provided |
| * by Oracle in the LICENSE file that accompanied this code. |
| * |
| * This code is distributed in the hope that it will be useful, but WITHOUT |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| * version 2 for more details (a copy is included in the LICENSE file that |
| * accompanied this code). |
| * |
| * You should have received a copy of the GNU General Public License version |
| * 2 along with this work; if not, write to the Free Software Foundation, |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| * |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| * or visit www.oracle.com if you need additional information or have any |
| * questions. |
| */ |
| |
| package java.awt; |
| |
| /** |
| * A helper interface to run the nested event loop. |
| * <p> |
| * Objects that implement this interface are created with the |
| * {@link EventQueue#createSecondaryLoop} method. The interface |
| * provides two methods, {@link #enter} and {@link #exit}, |
| * which can be used to start and stop the event loop. |
| * <p> |
| * When the {@link #enter} method is called, the current |
| * thread is blocked until the loop is terminated by the |
| * {@link #exit} method. Also, a new event loop is started |
| * on the event dispatch thread, which may or may not be |
| * the current thread. The loop can be terminated on any |
| * thread by calling its {@link #exit} method. After the |
| * loop is terminated, the {@code SecondaryLoop} object can |
| * be reused to run a new nested event loop. |
| * <p> |
| * A typical use case of applying this interface is AWT |
| * and Swing modal dialogs. When a modal dialog is shown on |
| * the event dispatch thread, it enters a new secondary loop. |
| * Later, when the dialog is hidden or disposed, it exits |
| * the loop, and the thread continues its execution. |
| * <p> |
| * The following example illustrates a simple use case of |
| * secondary loops: |
| * |
| * <pre> |
| * SecondaryLoop loop; |
| * |
| * JButton jButton = new JButton("Button"); |
| * jButton.addActionListener(new ActionListener() { |
| * {@code @Override} |
| * public void actionPerformed(ActionEvent e) { |
| * Toolkit tk = Toolkit.getDefaultToolkit(); |
| * EventQueue eq = tk.getSystemEventQueue(); |
| * loop = eq.createSecondaryLoop(); |
| * |
| * // Spawn a new thread to do the work |
| * Thread worker = new WorkerThread(); |
| * worker.start(); |
| * |
| * // Enter the loop to block the current event |
| * // handler, but leave UI responsive |
| * if (!loop.enter()) { |
| * // Report an error |
| * } |
| * } |
| * }); |
| * |
| * class WorkerThread extends Thread { |
| * {@code @Override} |
| * public void run() { |
| * // Perform calculations |
| * doSomethingUseful(); |
| * |
| * // Exit the loop |
| * loop.exit(); |
| * } |
| * } |
| * </pre> |
| * |
| * @see Dialog#show |
| * @see EventQueue#createSecondaryLoop |
| * @see Toolkit#getSystemEventQueue |
| * |
| * @author Anton Tarasov, Artem Ananiev |
| * |
| * @since 1.7 |
| */ |
| public interface SecondaryLoop { |
| |
| /** |
| * Blocks the execution of the current thread and enters a new |
| * secondary event loop on the event dispatch thread. |
| * <p> |
| * This method can be called by any thread including the event |
| * dispatch thread. This thread will be blocked until the {@link |
| * #exit} method is called or the loop is terminated. A new |
| * secondary loop will be created on the event dispatch thread |
| * for dispatching events in either case. |
| * <p> |
| * This method can only start one new event loop at a time per |
| * object. If a secondary event loop has already been started |
| * by this object and is currently still running, this method |
| * returns {@code false} to indicate that it was not successful |
| * in starting a new event loop. Otherwise, this method blocks |
| * the calling thread and later returns {@code true} when the |
| * new event loop is terminated. At such time, this object can |
| * again be used to start another new event loop. |
| * |
| * @return {@code true} after termination of the secondary loop, |
| * if the secondary loop was started by this call, |
| * {@code false} otherwise |
| */ |
| public boolean enter(); |
| |
| /** |
| * Unblocks the execution of the thread blocked by the {@link |
| * #enter} method and exits the secondary loop. |
| * <p> |
| * This method resumes the thread that called the {@link #enter} |
| * method and exits the secondary loop that was created when |
| * the {@link #enter} method was invoked. |
| * <p> |
| * Note that if any other secondary loop is started while this |
| * loop is running, the blocked thread will not resume execution |
| * until the nested loop is terminated. |
| * <p> |
| * If this secondary loop has not been started with the {@link |
| * #enter} method, or this secondary loop has already finished |
| * with the {@link #exit} method, this method returns {@code |
| * false}, otherwise {@code true} is returned. |
| * |
| * @return {@code true} if this loop was previously started and |
| * has not yet been finished with the {@link #exit} method, |
| * {@code false} otherwise |
| */ |
| public boolean exit(); |
| |
| } |