/*

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

}