Home » openjdk-7 » java » awt » [javadoc | source]

    1   /*
    2    * Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.
    3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
    4    *
    5    * This code is free software; you can redistribute it and/or modify it
    6    * under the terms of the GNU General Public License version 2 only, as
    7    * published by the Free Software Foundation.  Oracle designates this
    8    * particular file as subject to the "Classpath" exception as provided
    9    * by Oracle in the LICENSE file that accompanied this code.
   10    *
   11    * This code is distributed in the hope that it will be useful, but WITHOUT
   12    * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   13    * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   14    * version 2 for more details (a copy is included in the LICENSE file that
   15    * accompanied this code).
   16    *
   17    * You should have received a copy of the GNU General Public License version
   18    * 2 along with this work; if not, write to the Free Software Foundation,
   19    * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   20    *
   21    * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   22    * or visit www.oracle.com if you need additional information or have any
   23    * questions.
   24    */
   25   
   26   package java.awt;
   27   
   28   /**
   29    * A helper interface to run the nested event loop.
   30    * <p>
   31    * Objects that implement this interface are created with the
   32    * {@link EventQueue#createSecondaryLoop} method. The interface
   33    * provides two methods, {@link #enter} and {@link #exit},
   34    * which can be used to start and stop the event loop.
   35    * <p>
   36    * When the {@link #enter} method is called, the current
   37    * thread is blocked until the loop is terminated by the
   38    * {@link #exit} method. Also, a new event loop is started
   39    * on the event dispatch thread, which may or may not be
   40    * the current thread. The loop can be terminated on any
   41    * thread by calling its {@link #exit} method. After the
   42    * loop is terminated, the {@code SecondaryLoop} object can
   43    * be reused to run a new nested event loop.
   44    * <p>
   45    * A typical use case of applying this interface is AWT
   46    * and Swing modal dialogs. When a modal dialog is shown on
   47    * the event dispatch thread, it enters a new secondary loop.
   48    * Later, when the dialog is hidden or disposed, it exits
   49    * the loop, and the thread continues its execution.
   50    * <p>
   51    * The following example illustrates a simple use case of
   52    * secondary loops:
   53    *
   54    * <pre>
   55    *   SecondaryLoop loop;
   56    *
   57    *   JButton jButton = new JButton("Button");
   58    *   jButton.addActionListener(new ActionListener() {
   59    *       {@code @Override}
   60    *       public void actionPerformed(ActionEvent e) {
   61    *           Toolkit tk = Toolkit.getDefaultToolkit();
   62    *           EventQueue eq = tk.getSystemEventQueue();
   63    *           loop = eq.createSecondaryLoop();
   64    *
   65    *           // Spawn a new thread to do the work
   66    *           Thread worker = new WorkerThread();
   67    *           worker.start();
   68    *
   69    *           // Enter the loop to block the current event
   70    *           // handler, but leave UI responsive
   71    *           if (!loop.enter()) {
   72    *               // Report an error
   73    *           }
   74    *       }
   75    *   });
   76    *
   77    *   class WorkerThread extends Thread {
   78    *       {@code @Override}
   79    *       public void run() {
   80    *           // Perform calculations
   81    *           doSomethingUseful();
   82    *
   83    *           // Exit the loop
   84    *           loop.exit();
   85    *       }
   86    *   }
   87    * </pre>
   88    *
   89    * @see Dialog#show
   90    * @see EventQueue#createSecondaryLoop
   91    * @see Toolkit#getSystemEventQueue
   92    *
   93    * @author Anton Tarasov, Artem Ananiev
   94    *
   95    * @since 1.7
   96    */
   97   public interface SecondaryLoop {
   98   
   99       /**
  100        * Blocks the execution of the current thread and enters a new
  101        * secondary event loop on the event dispatch thread.
  102        * <p>
  103        * This method can be called by any thread including the event
  104        * dispatch thread. This thread will be blocked until the {@link
  105        * #exit} method is called or the loop is terminated. A new
  106        * secondary loop will be created on the event dispatch thread
  107        * for dispatching events in either case.
  108        * <p>
  109        * This method can only start one new event loop at a time per
  110        * object. If a secondary event loop has already been started
  111        * by this object and is currently still running, this method
  112        * returns {@code false} to indicate that it was not successful
  113        * in starting a new event loop. Otherwise, this method blocks
  114        * the calling thread and later returns {@code true} when the
  115        * new event loop is terminated. At such time, this object can
  116        * again be used to start another new event loop.
  117        *
  118        * @return {@code true} after termination of the secondary loop,
  119        *         if the secondary loop was started by this call,
  120        *         {@code false} otherwise
  121        */
  122       public boolean enter();
  123   
  124       /**
  125        * Unblocks the execution of the thread blocked by the {@link
  126        * #enter} method and exits the secondary loop.
  127        * <p>
  128        * This method resumes the thread that called the {@link #enter}
  129        * method and exits the secondary loop that was created when
  130        * the {@link #enter} method was invoked.
  131        * <p>
  132        * Note that if any other secondary loop is started while this
  133        * loop is running, the blocked thread will not resume execution
  134        * until the nested loop is terminated.
  135        * <p>
  136        * If this secondary loop has not been started with the {@link
  137        * #enter} method, or this secondary loop has already finished
  138        * with the {@link #exit} method, this method returns {@code
  139        * false}, otherwise {@code true} is returned.
  140        *
  141        * @return {@code true} if this loop was previously started and
  142        *         has not yet been finished with the {@link #exit} method,
  143        *         {@code false} otherwise
  144        */
  145       public boolean exit();
  146   
  147   }

Home » openjdk-7 » java » awt » [javadoc | source]