--- a/src/java.base/share/classes/java/lang/Thread.java	Thu Apr 06 09:33:47 2017 +0800
+++ b/src/java.base/share/classes/java/lang/Thread.java	Thu Apr 06 09:00:47 2017 +0100
@@ -927,7 +927,7 @@
      *       for example), the <code>interrupt</code> method should be used to
      *       interrupt the wait.
      *       For more information, see
-     *       <a href="{@docRoot}/../technotes/guides/concurrency/threadPrimitiveDeprecation.html">Why
+     *       <a href="{@docRoot}/java/lang/doc-files/threadPrimitiveDeprecation.html">Why
      *       are Thread.stop, Thread.suspend and Thread.resume Deprecated?</a>.
      */
     @Deprecated(since="1.2")
@@ -960,7 +960,7 @@
      *        could be used to generate exceptions that the target thread was
      *        not prepared to handle.
      *        For more information, see
-     *        <a href="{@docRoot}/../technotes/guides/concurrency/threadPrimitiveDeprecation.html">Why
+     *        <a href="{@docRoot}/java/lang/doc-files/threadPrimitiveDeprecation.html">Why
      *        are Thread.stop, Thread.suspend and Thread.resume Deprecated?</a>.
      *        This method is subject to removal in a future version of Java SE.
      */
@@ -1082,7 +1082,7 @@
      *     If another thread ever attempted to lock this resource, deadlock
      *     would result. Such deadlocks typically manifest themselves as
      *     "frozen" processes. For more information, see
-     *     <a href="{@docRoot}/../technotes/guides/concurrency/threadPrimitiveDeprecation.html">
+     *     <a href="{@docRoot}/java/lang/doc-files/threadPrimitiveDeprecation.html">
      *     Why are Thread.stop, Thread.suspend and Thread.resume Deprecated?</a>.
      *     This method is subject to removal in a future version of Java SE.
      * @throws NoSuchMethodError always
@@ -1122,7 +1122,7 @@
      *   monitor prior to calling <code>resume</code>, deadlock results.  Such
      *   deadlocks typically manifest themselves as "frozen" processes.
      *   For more information, see
-     *   <a href="{@docRoot}/../technotes/guides/concurrency/threadPrimitiveDeprecation.html">Why
+     *   <a href="{@docRoot}/java/lang/doc-files/threadPrimitiveDeprecation.html">Why
      *   are Thread.stop, Thread.suspend and Thread.resume Deprecated?</a>.
      */
     @Deprecated(since="1.2")
@@ -1148,7 +1148,7 @@
      * @deprecated This method exists solely for use with {@link #suspend},
      *     which has been deprecated because it is deadlock-prone.
      *     For more information, see
-     *     <a href="{@docRoot}/../technotes/guides/concurrency/threadPrimitiveDeprecation.html">Why
+     *     <a href="{@docRoot}/java/lang/doc-files/threadPrimitiveDeprecation.html">Why
      *     are Thread.stop, Thread.suspend and Thread.resume Deprecated?</a>.
      */
     @Deprecated(since="1.2")

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/java.base/share/classes/java/lang/doc-files/threadPrimitiveDeprecation.html	Thu Apr 06 09:00:47 2017 +0100
@@ -0,0 +1,364 @@
+<!--
+ Copyright (c) 2005, 2017, 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.
+-->
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html lang="en">
+<head>
+  <title>Java Thread Primitive Deprecation</title>
+  <link rel="stylesheet" type="text/css" href="../../../stylesheet.css" title="Style">
+</head>
+<body>
+<h2>Java Thread Primitive Deprecation</h2>
+<hr size="3" noshade="noshade" />
+<h3>Why is <code>Thread.stop</code> deprecated?</h3>
+<p>Because it is inherently unsafe. Stopping a thread causes it to
+unlock all the monitors that it has locked. (The monitors are
+unlocked as the <code>ThreadDeath</code> exception propagates up
+the stack.) If any of the objects previously protected by these
+monitors were in an inconsistent state, other threads may now view
+these objects in an inconsistent state. Such objects are said to be
+<i>damaged</i>. When threads operate on damaged objects, arbitrary
+behavior can result. This behavior may be subtle and difficult to
+detect, or it may be pronounced. Unlike other unchecked exceptions,
+<code>ThreadDeath</code> kills threads silently; thus, the user has
+no warning that his program may be corrupted. The corruption can
+manifest itself at any time after the actual damage occurs, even
+hours or days in the future.</p>
+<hr />
+<h3>Couldn't I just catch the <code>ThreadDeath</code> exception
+and fix the damaged object?</h3>
+<p>In theory, perhaps, but it would <em>vastly</em> complicate the
+task of writing correct multithreaded code. The task would be
+nearly insurmountable for two reasons:</p>
+<ol>
+<li>A thread can throw a <code>ThreadDeath</code> exception
+<i>almost anywhere</i>. All synchronized methods and blocks would
+have to be studied in great detail, with this in mind.</li>
+<li>A thread can throw a second <code>ThreadDeath</code> exception
+while cleaning up from the first (in the <code>catch</code> or
+<code>finally</code> clause). Cleanup would have to be repeated till
+it succeeded. The code to ensure this would be quite complex.</li>
+</ol>
+In sum, it just isn't practical.
+<hr />
+<h3>What about <code>Thread.stop(Throwable)</code>?</h3>
+<p>In addition to all of the problems noted above, this method may
+be used to generate exceptions that its target thread is unprepared
+to handle (including checked exceptions that the thread could not
+possibly throw, were it not for this method). For example, the
+following method is behaviorally identical to Java's
+<code>throw</code> operation, but circumvents the compiler's
+attempts to guarantee that the calling method has declared all of
+the checked exceptions that it may throw:</p>
+<pre>
+    static void sneakyThrow(Throwable t) {
+        Thread.currentThread().stop(t);
+    }
+</pre>
+<hr />
+<h3>What should I use instead of <code>Thread.stop</code>?</h3>
+<p>Most uses of <code>stop</code> should be replaced by code that
+simply modifies some variable to indicate that the target thread
+should stop running. The target thread should check this variable
+regularly, and return from its run method in an orderly fashion if
+the variable indicates that it is to stop running. To ensure prompt
+communication of the stop-request, the variable must be
+<tt>volatile</tt> (or access to the variable must be
+synchronized).</p>
+<p>For example, suppose your applet contains the following
+<code>start</code>, <code>stop</code> and <code>run</code>
+methods:</p>
+<pre>
+    private Thread blinker;
+
+    public void start() {
+        blinker = new Thread(this);
+        blinker.start();
+    }
+
+    public void stop() {
+        blinker.stop();  // UNSAFE!
+    }
+
+    public void run() {
+        while (true) {
+            try {
+                Thread.sleep(interval);
+            } catch (InterruptedException e){
+            }
+            repaint();
+        }
+    }
+</pre>
+You can avoid the use of <code>Thread.stop</code> by replacing the
+applet's <code>stop</code> and <code>run</code> methods with:
+<pre>
+    private volatile Thread blinker;
+
+    public void stop() {
+        blinker = null;
+    }
+
+    public void run() {
+        Thread thisThread = Thread.currentThread();
+        while (blinker == thisThread) {
+            try {
+                Thread.sleep(interval);
+            } catch (InterruptedException e){
+            }
+            repaint();
+        }
+    }
+</pre>
+<hr />
+<h3>How do I stop a thread that waits for long periods (e.g., for
+input)?</h3>
+<p>That's what the <code>Thread.interrupt</code> method is for. The
+same "state based" signaling mechanism shown above can be used, but
+the state change (<code>blinker = null</code>, in the previous
+example) can be followed by a call to
+<code>Thread.interrupt</code>, to interrupt the wait:</p>
+<pre>
+    public void stop() {
+        Thread moribund = waiter;
+        waiter = null;
+        moribund.interrupt();
+    }
+</pre>
+For this technique to work, it's critical that any method that
+catches an interrupt exception and is not prepared to deal with it
+immediately reasserts the exception. We say <em>reasserts</em>
+rather than <em>rethrows</em>, because it is not always possible to
+rethrow the exception. If the method that catches the
+<code>InterruptedException</code> is not declared to throw this
+(checked) exception, then it should "reinterrupt itself" with the
+following incantation:
+<pre>
+    Thread.currentThread().interrupt();
+</pre>
+This ensures that the Thread will reraise the
+<code>InterruptedException</code> as soon as it is able.
+<hr />
+<h3>What if a thread doesn't respond to
+<code>Thread.interrupt</code>?</h3>
+<p>In some cases, you can use application specific tricks. For
+example, if a thread is waiting on a known socket, you can close
+the socket to cause the thread to return immediately.
+Unfortunately, there really isn't any technique that works in
+general. <em>It should be noted that in all situations where a
+waiting thread doesn't respond to <code>Thread.interrupt</code>, it
+wouldn't respond to <code>Thread.stop</code> either.</em> Such
+cases include deliberate denial-of-service attacks, and I/O
+operations for which thread.stop and thread.interrupt do not work
+properly.</p>
+<hr />
+<h3>Why are <code>Thread.suspend</code> and
+<code>Thread.resume</code> deprecated?</h3>
+<p><code>Thread.suspend</code> is inherently deadlock-prone. If the
+target thread holds a lock on the monitor protecting a critical
+system resource when it is suspended, no thread can access this
+resource until the target thread is resumed. If the thread that
+would resume the target thread attempts to lock this monitor prior
+to calling <code>resume</code>, deadlock results. Such deadlocks
+typically manifest themselves as "frozen" processes.</p>
+<hr />
+<h3>What should I use instead of <code>Thread.suspend</code> and
+<code>Thread.resume</code>?</h3>
+<p>As with <code>Thread.stop</code>, the prudent approach is to
+have the "target thread" poll a variable indicating the desired
+state of the thread (active or suspended). When the desired state
+is suspended, the thread waits using <code>Object.wait</code>. When
+the thread is resumed, the target thread is notified using
+<code>Object.notify</code>.</p>
+<p>For example, suppose your applet contains the following
+mousePressed event handler, which toggles the state of a thread
+called <code>blinker</code>:</p>
+<pre>
+    private boolean threadSuspended;
+
+    Public void mousePressed(MouseEvent e) {
+        e.consume();
+
+        if (threadSuspended)
+            blinker.resume();
+        else
+            blinker.suspend();  // DEADLOCK-PRONE!
+
+        threadSuspended = !threadSuspended;
+    }
+</pre>
+You can avoid the use of <code>Thread.suspend</code> and
+<code>Thread.resume</code> by replacing the event handler above
+with:
+<pre>
+    public synchronized void mousePressed(MouseEvent e) {
+        e.consume();
+
+        threadSuspended = !threadSuspended;
+
+        if (!threadSuspended)
+            notify();
+    }
+</pre>
+and adding the following code to the "run loop":
+<pre>
+                synchronized(this) {
+                    while (threadSuspended)
+                        wait();
+                }
+</pre>
+The <code>wait</code> method throws the
+<code>InterruptedException</code>, so it must be inside a <code>try
+... catch</code> clause. It's fine to put it in the same clause as
+the <code>sleep</code>. The check should follow (rather than
+precede) the <code>sleep</code> so the window is immediately
+repainted when the thread is "resumed." The resulting
+<code>run</code> method follows:
+<pre>
+    public void run() {
+        while (true) {
+            try {
+                Thread.sleep(interval);
+
+                synchronized(this) {
+                    while (threadSuspended)
+                        wait();
+                }
+            } catch (InterruptedException e){
+            }
+            repaint();
+        }
+    }
+</pre>
+Note that the <code>notify</code> in the <code>mousePressed</code>
+method and the <code>wait</code> in the <code>run</code> method are
+inside <code>synchronized</code> blocks. This is required by the
+language, and ensures that <code>wait</code> and
+<code>notify</code> are properly serialized. In practical terms,
+this eliminates race conditions that could cause the "suspended"
+thread to miss a <code>notify</code> and remain suspended
+indefinitely.
+<p>While the cost of synchronization in Java is decreasing as the
+platform matures, it will never be free. A simple trick can be used
+to remove the synchronization that we've added to each iteration of
+the "run loop." The synchronized block that was added is replaced
+by a slightly more complex piece of code that enters a synchronized
+block only if the thread has actually been suspended:</p>
+<pre>
+                if (threadSuspended) {
+                    synchronized(this) {
+                        while (threadSuspended)
+                            wait();
+                    }
+                }
+</pre>
+<p>In the absence of explicit synchronization,
+<tt>threadSuspended</tt> must be made <tt>volatile</tt> to ensure
+prompt communication of the suspend-request.</p>
+The resulting <code>run</code> method is:
+<pre>
+    private volatile boolean threadSuspended;
+
+    public void run() {
+        while (true) {
+            try {
+                Thread.sleep(interval);
+
+                if (threadSuspended) {
+                    synchronized(this) {
+                        while (threadSuspended)
+                            wait();
+                    }
+                }
+            } catch (InterruptedException e){
+            }
+            repaint();
+        }
+    }
+</pre>
+<hr size="3" noshade="noshade" />
+<h3>Can I combine the two techniques to produce a thread that may
+be safely "stopped" or "suspended"?</h3>
+Yes, it's reasonably straightforward. The one subtlety is that the
+target thread may already be suspended at the time that another
+thread tries to stop it. If the <tt>stop</tt> method merely sets
+the state variable (<tt>blinker</tt>) to null, the target thread
+will remain suspended (waiting on the monitor), rather than exiting
+gracefully as it should. If the applet is restarted, multiple
+threads could end up waiting on the monitor at the same time,
+resulting in erratic behavior.
+<p>To rectify this situation, the <tt>stop</tt> method must ensure
+that the target thread resumes immediately if it is suspended. Once
+the target thread resumes, it must recognize immediately that it
+has been stopped, and exit gracefully. Here's how the resulting
+<tt>run</tt> and <tt>stop</tt> methods look:</p>
+<pre>
+    public void run() {
+        Thread thisThread = Thread.currentThread();
+        while (blinker == thisThread) {
+            try {
+                Thread.sleep(interval);
+
+                synchronized(this) {
+                    while (threadSuspended &amp;&amp; blinker==thisThread)
+                        wait();
+                }
+            } catch (InterruptedException e){
+            }
+            repaint();
+        }
+    }
+
+    public synchronized void stop() {
+        blinker = null;
+        notify();
+    }
+</pre>
+If the <tt>stop</tt> method calls <tt>Thread.interrupt</tt>, as
+described above, it needn't call <tt>notify</tt> as well, but it
+still must be synchronized. This ensures that the target thread
+won't miss an interrupt due to a race condition.
+<hr />
+<h3>What about <code>Thread.destroy</code>?</h3>
+<code>Thread.destroy</code> was never implemented and has been
+deprecated. If it were implemented, it would be deadlock-prone in
+the manner of <code>Thread.suspend</code>. (In fact, it is roughly
+equivalent to <code>Thread.suspend</code> without the possibility
+of a subsequent <code>Thread.resume</code>.)
+<hr />
+<h3>Why is <code>Runtime.runFinalizersOnExit</code>
+deprecated?</h3>
+Because it is inherently unsafe. It may result in finalizers being
+called on live objects while other threads are concurrently
+manipulating those objects, resulting in erratic behavior or
+deadlock. While this problem could be prevented if the class whose
+objects are being finalized were coded to "defend against" this
+call, most programmers do <i>not</i> defend against it. They assume
+that an object is dead at the time that its finalizer is called.
+<p>Further, the call is not "thread-safe" in the sense that it sets
+a VM-global flag. This forces <i>every</i> class with a finalizer
+to defend against the finalization of live objects!</p>
+<p><!-- Body text ends here --></p>
+</body>
+</html>