1 /*
   2  * Copyright (c) 1998, 2017, 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 /**
  27  * Provides a set of "lightweight" (all-Java language) components
  28  * that, to the maximum degree possible, work the same on all platforms. For a
  29  * programmer's guide to using these components, see
  30  * <a href="http://docs.oracle.com/javase/tutorial/uiswing/index.html"
  31  * target="_top">Creating a GUI with JFC/Swing</a>, a trail in
  32  * <em>The Java Tutorial</em>. For other resources, see
  33  * <a href="#related">Related Documentation</a>.
  34  *
  35  * <h2><a name="threading">Swing's Threading Policy</a></h2>
  36  * In general Swing is not thread safe. All Swing components and related
  37  * classes, unless otherwise documented, must be accessed on the event
  38  * dispatching thread.
  39  * <p>
  40  * Typical Swing applications do processing in response to an event generated
  41  * from a user gesture. For example, clicking on a {@code JButton} notifies all
  42  * {@code ActionListeners} added to the {@code JButton}. As all events generated
  43  * from a user gesture are dispatched on the event dispatching thread, most
  44  * developers are not impacted by the restriction.
  45  * <p>
  46  * Where the impact lies, however, is in constructing and showing a Swing
  47  * application. Calls to an application's {@code main} method, or methods in
  48  * {@code Applet}, are not invoked on the event dispatching thread. As such,
  49  * care must be taken to transfer control to the event dispatching thread when
  50  * constructing and showing an application or applet. The preferred way to
  51  * transfer control and begin working with Swing is to use {@code invokeLater}.
  52  * The {@code invokeLater} method schedules a {@code Runnable} to be processed
  53  * on the event dispatching thread. The following two examples work equally well
  54  * for transferring control and starting up a Swing application:
  55  * <pre>
  56  * import javax.swing.SwingUtilities;
  57  *
  58  * public class MyApp implements Runnable {
  59  *     public void run() {
  60  *         // Invoked on the event dispatching thread.
  61  *         // Construct and show GUI.
  62  *     }
  63  *
  64  *     public static void main(String[] args) {
  65  *         SwingUtilities.invokeLater(new MyApp());
  66  *     }
  67  * }</pre>
  68  * Or:<pre>
  69  * import javax.swing.SwingUtilities;
  70  *
  71  * public class MyApp {
  72  *     MyApp(String[] args) {
  73  *         // Invoked on the event dispatching thread.
  74  *         // Do any initialization here.
  75  *     }
  76  *
  77  *     public void show() {
  78  *         // Show the UI.
  79  *     }
  80  *
  81  *     public static void main(final String[] args) {
  82  *         // Schedule a job for the event-dispatching thread:
  83  *         // creating and showing this application's GUI.
  84  *         SwingUtilities.invokeLater(new Runnable() {
  85  *             public void run() {
  86  *                 new MyApp(args).show();
  87  *             }
  88  *         });
  89  *     }
  90  * }</pre>
  91  * This restriction also applies to models attached to Swing components. For
  92  * example, if a {@code TableModel} is attached to a {@code JTable}, the
  93  * {@code TableModel} should only be modified on the event dispatching thread.
  94  * If you modify the model on a separate thread you run the risk of exceptions
  95  * and possible display corruption.
  96  * <p>
  97  * As all events are delivered on the event dispatching thread, care must be
  98  * taken in event processing. In particular, a long running task, such as
  99  * network io or computational intensive processing, executed on the event
 100  * dispatching thread blocks the event dispatching thread from dispatching any
 101  * other events. While the event dispatching thread is blocked the application
 102  * is completely unresponsive to user input. Refer to
 103  * {@link javax.swing.SwingWorker} for the preferred way to do such processing
 104  * when working with Swing.
 105  * <p>
 106  * More information on this topic can be found in the
 107  * <a href="http://docs.oracle.com/javase/tutorial/uiswing/">Swing tutorial</a>,
 108  * in particular the section on
 109  * <a
 110  * href="http://docs.oracle.com/javase/tutorial/uiswing/concurrency/index.html">
 111  * Concurrency in Swing</a>.
 112  *
 113  * <h2><a name="related">Related Documentation</a></h2>
 114  * For overviews, tutorials, examples, guides, and other documentation,
 115  * please see:
 116  * <ul>
 117  *     <li><a href="http://www.oracle.com/technetwork/java/javase/tech/articles-jsp-139072.html"
 118  *     target="_top">The Swing Connection</a></li>
 119  *     <li><a href="http://docs.oracle.com/javase/tutorial/"
 120  *     target="_top">The Java Tutorial</a></li>
 121  *     <li><a href="http://www.oracle.com/technetwork/java/javase/training/index.html"
 122  *     target="_top">Online Training</a>
 123  *     at the Java Developer Connection <sup>SM</sup></li>
 124  *     <li><a href="http://www.oracle.com/technetwork/java/javase/tech/index-jsp-142216.html"
 125  *     target="_top">Java Foundation Classes (JFC)</a> home page</li>
 126  * </ul>
 127  *
 128  * @serial exclude
 129  */
 130 package javax.swing;