jdk-sandbox: src/java.desktop/share/classes/java/awt/doc-files/AWTThreadIssues.html@1ba28f0dbc33 (annotated)

48264 efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html serb parents: 47216 diff changeset	1	<!doctype html>
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html serb parents: 47216 diff changeset	2	<html lang="en">
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html serb parents: 47216 diff changeset	3	<head>
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html serb parents: 47216 diff changeset	4	<meta charset="utf-8"/>
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html serb parents: 47216 diff changeset	5	<title>AWT Threading Issues</title>
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html serb parents: 47216 diff changeset	6	</head>
2 90ce3da70b43 Initial load duke parents: diff changeset	7	<!--
50358 1ba28f0dbc33 8199150: Accessibility issues in java.desktop serb parents: 48264 diff changeset	8	Copyright (c) 2002, 2018, Oracle and/or its affiliates. All rights reserved.
2 90ce3da70b43 Initial load duke parents: diff changeset	9	DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
90ce3da70b43 Initial load duke parents: diff changeset	10
90ce3da70b43 Initial load duke parents: diff changeset	11	This code is free software; you can redistribute it and/or modify it
90ce3da70b43 Initial load duke parents: diff changeset	12	under the terms of the GNU General Public License version 2 only, as
5506 202f599c92aa 6943119: Rebrand source copyright notices ohair parents: 2 diff changeset	13	published by the Free Software Foundation. Oracle designates this
2 90ce3da70b43 Initial load duke parents: diff changeset	14	particular file as subject to the "Classpath" exception as provided
5506 202f599c92aa 6943119: Rebrand source copyright notices ohair parents: 2 diff changeset	15	by Oracle in the LICENSE file that accompanied this code.
2 90ce3da70b43 Initial load duke parents: diff changeset	16
90ce3da70b43 Initial load duke parents: diff changeset	17	This code is distributed in the hope that it will be useful, but WITHOUT
90ce3da70b43 Initial load duke parents: diff changeset	18	ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
90ce3da70b43 Initial load duke parents: diff changeset	19	FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
90ce3da70b43 Initial load duke parents: diff changeset	20	version 2 for more details (a copy is included in the LICENSE file that
90ce3da70b43 Initial load duke parents: diff changeset	21	accompanied this code).
90ce3da70b43 Initial load duke parents: diff changeset	22
90ce3da70b43 Initial load duke parents: diff changeset	23	You should have received a copy of the GNU General Public License version
90ce3da70b43 Initial load duke parents: diff changeset	24	2 along with this work; if not, write to the Free Software Foundation,
90ce3da70b43 Initial load duke parents: diff changeset	25	Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
90ce3da70b43 Initial load duke parents: diff changeset	26
5506 202f599c92aa 6943119: Rebrand source copyright notices ohair parents: 2 diff changeset	27	Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
202f599c92aa 6943119: Rebrand source copyright notices ohair parents: 2 diff changeset	28	or visit www.oracle.com if you need additional information or have any
202f599c92aa 6943119: Rebrand source copyright notices ohair parents: 2 diff changeset	29	questions.
2 90ce3da70b43 Initial load duke parents: diff changeset	30	-->
90ce3da70b43 Initial load duke parents: diff changeset	31
48264 efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html serb parents: 47216 diff changeset	32	<body>
50358 1ba28f0dbc33 8199150: Accessibility issues in java.desktop serb parents: 48264 diff changeset	33	<main role="main">
48264 efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html serb parents: 47216 diff changeset	34	<h1>AWT Threading Issues</h1>
2 90ce3da70b43 Initial load duke parents: diff changeset	35
48264 efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html serb parents: 47216 diff changeset	36	<a id="ListenersThreads"></a>
2 90ce3da70b43 Initial load duke parents: diff changeset	37	<h2>Listeners and threads</h2>
90ce3da70b43 Initial load duke parents: diff changeset	38
90ce3da70b43 Initial load duke parents: diff changeset	39	Unless otherwise noted all AWT listeners are notified on the event
90ce3da70b43 Initial load duke parents: diff changeset	40	dispatch thread. It is safe to remove/add listeners from any thread
90ce3da70b43 Initial load duke parents: diff changeset	41	during dispatching, but the changes only effect subsequent notification.
90ce3da70b43 Initial load duke parents: diff changeset	42	<br>For example, if a key listeners is added from another key listener, the
90ce3da70b43 Initial load duke parents: diff changeset	43	newly added listener is only notified on subsequent key events.
90ce3da70b43 Initial load duke parents: diff changeset	44
48264 efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html serb parents: 47216 diff changeset	45	<a id="Autoshutdown"></a>
2 90ce3da70b43 Initial load duke parents: diff changeset	46	<h2>Auto-shutdown</h2>
90ce3da70b43 Initial load duke parents: diff changeset	47
9266 121fb370f179 7032960: API files in java.awt need to be updated for references to JVM Spec with editions/hyperlinks jjh parents: 5506 diff changeset	48	According to
121fb370f179 7032960: API files in java.awt need to be updated for references to JVM Spec with editions/hyperlinks jjh parents: 5506 diff changeset	49	<cite>The Java™ Virtual Machine Specification</cite>,
121fb370f179 7032960: API files in java.awt need to be updated for references to JVM Spec with editions/hyperlinks jjh parents: 5506 diff changeset	50	sections 2.17.9 and 2.19,
2 90ce3da70b43 Initial load duke parents: diff changeset	51	the Java virtual machine (JVM) initially starts up with a single non-daemon
90ce3da70b43 Initial load duke parents: diff changeset	52	thread, which typically calls the <code>main</code> method of some class.
90ce3da70b43 Initial load duke parents: diff changeset	53	The virtual machine terminates all its activity and exits when
90ce3da70b43 Initial load duke parents: diff changeset	54	one of two things happens:
90ce3da70b43 Initial load duke parents: diff changeset	55	<ul>
90ce3da70b43 Initial load duke parents: diff changeset	56	<li> All the threads that are not daemon threads terminate.
48264 efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html serb parents: 47216 diff changeset	57	<li> Some thread invokes the <code>exit</code> method of class
2 90ce3da70b43 Initial load duke parents: diff changeset	58	<code>Runtime</code> or class <code>System</code>, and the exit
90ce3da70b43 Initial load duke parents: diff changeset	59	operation is permitted by the security manager.
90ce3da70b43 Initial load duke parents: diff changeset	60	</ul>
90ce3da70b43 Initial load duke parents: diff changeset	61	<p>
90ce3da70b43 Initial load duke parents: diff changeset	62	This implies that if an application doesn't start any threads itself,
90ce3da70b43 Initial load duke parents: diff changeset	63	the JVM will exit as soon as <code>main</code> terminates.
90ce3da70b43 Initial load duke parents: diff changeset	64	This is not the case, however, for a simple application
90ce3da70b43 Initial load duke parents: diff changeset	65	that creates and displays a <code>java.awt.Frame</code>:
90ce3da70b43 Initial load duke parents: diff changeset	66	<pre>
90ce3da70b43 Initial load duke parents: diff changeset	67	public static void main(String[] args) {
90ce3da70b43 Initial load duke parents: diff changeset	68	Frame frame = new Frame();
90ce3da70b43 Initial load duke parents: diff changeset	69	frame.setVisible(true);
90ce3da70b43 Initial load duke parents: diff changeset	70	}
90ce3da70b43 Initial load duke parents: diff changeset	71	</pre>
90ce3da70b43 Initial load duke parents: diff changeset	72	The reason is that AWT encapsulates asynchronous event dispatch
90ce3da70b43 Initial load duke parents: diff changeset	73	machinery to process events AWT or Swing components can fire. The
90ce3da70b43 Initial load duke parents: diff changeset	74	exact behavior of this machinery is implementation-dependent. In
90ce3da70b43 Initial load duke parents: diff changeset	75	particular, it can start non-daemon helper threads for its internal
90ce3da70b43 Initial load duke parents: diff changeset	76	purposes. In fact, these are the threads that prevent the example
90ce3da70b43 Initial load duke parents: diff changeset	77	above from exiting. The only restrictions imposed on the behavior of
90ce3da70b43 Initial load duke parents: diff changeset	78	this machinery are as follows:
90ce3da70b43 Initial load duke parents: diff changeset	79	<ul>
90ce3da70b43 Initial load duke parents: diff changeset	80	<li> <a href="../EventQueue.html#isDispatchThread()"><code>EventQueue.isDispatchThread</code></a>
90ce3da70b43 Initial load duke parents: diff changeset	81	returns <code>true</code> if and only if the calling thread is the
90ce3da70b43 Initial load duke parents: diff changeset	82	event dispatch thread started by the machinery;
90ce3da70b43 Initial load duke parents: diff changeset	83	<li> <code>AWTEvents</code> which were actually enqueued to a
90ce3da70b43 Initial load duke parents: diff changeset	84	particular <code>EventQueue</code> (note that events being
90ce3da70b43 Initial load duke parents: diff changeset	85	posted to the <code>EventQueue</code> can be coalesced) are
90ce3da70b43 Initial load duke parents: diff changeset	86	dispatched:
90ce3da70b43 Initial load duke parents: diff changeset	87	<ul>
48264 efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html serb parents: 47216 diff changeset	88	<li>
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html serb parents: 47216 diff changeset	89	<dl><dt>Sequentially.
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html serb parents: 47216 diff changeset	90	<dd> That is, it is not permitted that several events from
21254 f6d36ee3f269 8025824: [cleanup] Fix tidy errors and warnings in preformatted HTML files related to 2d/awt/swing yan parents: 9275 diff changeset	91	this queue are dispatched simultaneously. </dd></dl>
48264 efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html serb parents: 47216 diff changeset	92	<li>
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html serb parents: 47216 diff changeset	93	<dl><dt>In the same order as they are enqueued.
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html serb parents: 47216 diff changeset	94	<dd> That is, if <code>AWTEvent</code> A is enqueued
2 90ce3da70b43 Initial load duke parents: diff changeset	95	to the <code>EventQueue</code> before
48264 efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html serb parents: 47216 diff changeset	96	<code>AWTEvent</code> B then event B will not be
21254 f6d36ee3f269 8025824: [cleanup] Fix tidy errors and warnings in preformatted HTML files related to 2d/awt/swing yan parents: 9275 diff changeset	97	dispatched before event A.</dd></dl>
2 90ce3da70b43 Initial load duke parents: diff changeset	98	</ul>
90ce3da70b43 Initial load duke parents: diff changeset	99	<li> There is at least one alive non-daemon thread while there is at
90ce3da70b43 Initial load duke parents: diff changeset	100	least one displayable AWT or Swing component within the
90ce3da70b43 Initial load duke parents: diff changeset	101	application (see
90ce3da70b43 Initial load duke parents: diff changeset	102	<a href="../Component.html#isDisplayable()"><code>Component.isDisplayable</code></a>).
90ce3da70b43 Initial load duke parents: diff changeset	103	</ul>
48264 efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html serb parents: 47216 diff changeset	104	The implications of the third restriction are as follows:
2 90ce3da70b43 Initial load duke parents: diff changeset	105	<ul>
90ce3da70b43 Initial load duke parents: diff changeset	106	<li> The JVM will exit if some thread invokes the <code>exit</code>
90ce3da70b43 Initial load duke parents: diff changeset	107	method of class <code>Runtime</code> or class <code>System</code>
90ce3da70b43 Initial load duke parents: diff changeset	108	regardless of the presence of displayable components;
90ce3da70b43 Initial load duke parents: diff changeset	109	<li> Even if the application terminates all non-daemon threads it
90ce3da70b43 Initial load duke parents: diff changeset	110	started, the JVM will not exit while there is at least one
90ce3da70b43 Initial load duke parents: diff changeset	111	displayable component.
90ce3da70b43 Initial load duke parents: diff changeset	112	</ul>
90ce3da70b43 Initial load duke parents: diff changeset	113	It depends on the implementation if and when the non-daemon helper
48264 efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html serb parents: 47216 diff changeset	114	threads are terminated once all components are made undisplayable.
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html serb parents: 47216 diff changeset	115	The implementation-specific details are given below.
2 90ce3da70b43 Initial load duke parents: diff changeset	116
90ce3da70b43 Initial load duke parents: diff changeset	117	<h3>
90ce3da70b43 Initial load duke parents: diff changeset	118	Implementation-dependent behavior.
90ce3da70b43 Initial load duke parents: diff changeset	119	</h3>
90ce3da70b43 Initial load duke parents: diff changeset	120
90ce3da70b43 Initial load duke parents: diff changeset	121	Prior to 1.4, the helper threads were never terminated.
90ce3da70b43 Initial load duke parents: diff changeset	122	<p>
90ce3da70b43 Initial load duke parents: diff changeset	123	Starting with 1.4, the behavior has changed as a result of the fix for
50358 1ba28f0dbc33 8199150: Accessibility issues in java.desktop serb parents: 48264 diff changeset	124	<a href="https://bugs.java.com/view_bug.do?bug_id=4030718">
2 90ce3da70b43 Initial load duke parents: diff changeset	125	4030718</a>. With the current implementation, AWT terminates all its
90ce3da70b43 Initial load duke parents: diff changeset	126	helper threads allowing the application to exit cleanly when the
90ce3da70b43 Initial load duke parents: diff changeset	127	following three conditions are true:
90ce3da70b43 Initial load duke parents: diff changeset	128	<ul>
90ce3da70b43 Initial load duke parents: diff changeset	129	<li> There are no displayable AWT or Swing components.
90ce3da70b43 Initial load duke parents: diff changeset	130	<li> There are no native events in the native event queue.
90ce3da70b43 Initial load duke parents: diff changeset	131	<li> There are no AWT events in java EventQueues.
90ce3da70b43 Initial load duke parents: diff changeset	132	</ul>
90ce3da70b43 Initial load duke parents: diff changeset	133	Therefore, a stand-alone AWT application that wishes to exit
90ce3da70b43 Initial load duke parents: diff changeset	134	cleanly without calling <code>System.exit</code> must:
90ce3da70b43 Initial load duke parents: diff changeset	135	<ul>
90ce3da70b43 Initial load duke parents: diff changeset	136	<li> Make sure that all AWT or Swing components are made
90ce3da70b43 Initial load duke parents: diff changeset	137	undisplayable when the application finishes. This can be done
90ce3da70b43 Initial load duke parents: diff changeset	138	by calling
90ce3da70b43 Initial load duke parents: diff changeset	139	<a href="../Window.html#dispose()"><code>Window.dispose</code></a>
90ce3da70b43 Initial load duke parents: diff changeset	140	on all top-level <code>Windows</code>. See
90ce3da70b43 Initial load duke parents: diff changeset	141	<a href="../Frame.html#getFrames()"><code>Frame.getFrames</code></a>.
90ce3da70b43 Initial load duke parents: diff changeset	142	<li> Make sure that no method of AWT event listeners registered by
90ce3da70b43 Initial load duke parents: diff changeset	143	the application with any AWT or Swing component can run into an
90ce3da70b43 Initial load duke parents: diff changeset	144	infinite loop or hang indefinitely. For example, an AWT listener
90ce3da70b43 Initial load duke parents: diff changeset	145	method triggered by some AWT event can post a new AWT event of
90ce3da70b43 Initial load duke parents: diff changeset	146	the same type to the <code>EventQueue</code>.
90ce3da70b43 Initial load duke parents: diff changeset	147	The argument is that methods
90ce3da70b43 Initial load duke parents: diff changeset	148	of AWT event listeners are typically executed on helper
90ce3da70b43 Initial load duke parents: diff changeset	149	threads.
90ce3da70b43 Initial load duke parents: diff changeset	150	</ul>
90ce3da70b43 Initial load duke parents: diff changeset	151	Note, that while an application following these recommendations will
90ce3da70b43 Initial load duke parents: diff changeset	152	exit cleanly under normal conditions, it is not guaranteed that it
48264 efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html serb parents: 47216 diff changeset	153	will exit cleanly in all cases. Two examples:
2 90ce3da70b43 Initial load duke parents: diff changeset	154	<ul>
90ce3da70b43 Initial load duke parents: diff changeset	155	<li> Other packages can create displayable components for internal
90ce3da70b43 Initial load duke parents: diff changeset	156	needs and never make them undisplayable. See
50358 1ba28f0dbc33 8199150: Accessibility issues in java.desktop serb parents: 48264 diff changeset	157	<a href="https://bugs.java.com/view_bug.do?bug_id=4515058">
2 90ce3da70b43 Initial load duke parents: diff changeset	158	4515058</a>,
50358 1ba28f0dbc33 8199150: Accessibility issues in java.desktop serb parents: 48264 diff changeset	159	<a href="https://bugs.java.com/view_bug.do?bug_id=4671025">
2 90ce3da70b43 Initial load duke parents: diff changeset	160	4671025</a>, and
50358 1ba28f0dbc33 8199150: Accessibility issues in java.desktop serb parents: 48264 diff changeset	161	<a href="https://bugs.java.com/view_bug.do?bug_id=4465537">
48264 efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html serb parents: 47216 diff changeset	162	4465537</a>.
2 90ce3da70b43 Initial load duke parents: diff changeset	163	<li> Both Microsoft Windows and X11 allow an application to send native
90ce3da70b43 Initial load duke parents: diff changeset	164	events to windows that belong to another application. With this
90ce3da70b43 Initial load duke parents: diff changeset	165	feature it is possible to write a malicious program that will
90ce3da70b43 Initial load duke parents: diff changeset	166	continuously send events to all available windows preventing
90ce3da70b43 Initial load duke parents: diff changeset	167	any AWT application from exiting cleanly.
90ce3da70b43 Initial load duke parents: diff changeset	168	</ul>
90ce3da70b43 Initial load duke parents: diff changeset	169	On the other hand, if you require the JVM to continue running even after
90ce3da70b43 Initial load duke parents: diff changeset	170	the application has made all components undisplayable you should start a
48264 efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html serb parents: 47216 diff changeset	171	non-daemon thread that blocks forever.
2 90ce3da70b43 Initial load duke parents: diff changeset	172
90ce3da70b43 Initial load duke parents: diff changeset	173	<pre>
48264 efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html serb parents: 47216 diff changeset	174	<...>
2 90ce3da70b43 Initial load duke parents: diff changeset	175	Runnable r = new Runnable() {
90ce3da70b43 Initial load duke parents: diff changeset	176	public void run() {
90ce3da70b43 Initial load duke parents: diff changeset	177	Object o = new Object();
90ce3da70b43 Initial load duke parents: diff changeset	178	try {
90ce3da70b43 Initial load duke parents: diff changeset	179	synchronized (o) {
90ce3da70b43 Initial load duke parents: diff changeset	180	o.wait();
90ce3da70b43 Initial load duke parents: diff changeset	181	}
90ce3da70b43 Initial load duke parents: diff changeset	182	} catch (InterruptedException ie) {
90ce3da70b43 Initial load duke parents: diff changeset	183	}
90ce3da70b43 Initial load duke parents: diff changeset	184	}
90ce3da70b43 Initial load duke parents: diff changeset	185	};
90ce3da70b43 Initial load duke parents: diff changeset	186	Thread t = new Thread(r);
90ce3da70b43 Initial load duke parents: diff changeset	187	t.setDaemon(false);
90ce3da70b43 Initial load duke parents: diff changeset	188	t.start();
48264 efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html serb parents: 47216 diff changeset	189	<...>
2 90ce3da70b43 Initial load duke parents: diff changeset	190	</pre>
90ce3da70b43 Initial load duke parents: diff changeset	191
9266 121fb370f179 7032960: API files in java.awt need to be updated for references to JVM Spec with editions/hyperlinks jjh parents: 5506 diff changeset	192	<cite>The Java™ Virtual Machine Specification</cite>
121fb370f179 7032960: API files in java.awt need to be updated for references to JVM Spec with editions/hyperlinks jjh parents: 5506 diff changeset	193	guarantees
2 90ce3da70b43 Initial load duke parents: diff changeset	194	that the JVM doesn't exit until this thread terminates.
50358 1ba28f0dbc33 8199150: Accessibility issues in java.desktop serb parents: 48264 diff changeset	195	</main>
2 90ce3da70b43 Initial load duke parents: diff changeset	196	</body>
90ce3da70b43 Initial load duke parents: diff changeset	197	</html>

author	serb
	Thu, 31 May 2018 09:52:32 -0700
changeset 50358	1ba28f0dbc33
parent 48264	efda6932a433
child 58595	fa9f28a0e175
permissions	-rw-r--r--