/*
 * 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();

}