A DESCRIPTION OF THE PROBLEM :
Applet stop/destroy methods do not work as advertised when minimizing window or leaving page.

  Description of the problem:

The invokation of the stop() and destroy() method in java.applet.Applet and javax.swing.JApplet does not seem to work as advertised. According to the API documentation, the java applet  tutorial and the general information available on the web, the stop() method should be called when the page containing the applet is minimized and destroy() when the web-page is closed  (i.e., not replaced by visiting another page in the same window). This is not the case, however, in for the plugin/browser combinations I use. Minimizing the window never leads to a call of stop() and replacing the page in the same window always leads to stop()+destroy(). In fact, stop() is always called in conjuction with destroy(), never by itself. A sample program and the output onto the plugin console is given at the end of this message.

I use the following environment, both with Mozilla 1.7 and Internet Explorer 6.0

j2re 1.4.2-05
jvm 1.4.2-05-b04
plugin 1.4.2-05

(I have tried several other plugin and j2re versions as well.)

Possible cases:
1) The plugin does not work properly.
2) The plugin works properly but is not used correctly by the browser.
3) Everything works properly but is documented insufficently.

I currently believe that the java API documentation is not clear enough. It should point out that the browser is not required to keed the applet in memory when  the user changes to another web page, and that minimizing the window does not guarantee that stop() will be called. Also, the tutorial http://java.sun.com/docs/books/tutorial/applet/overview/lifeCycle.html (see also the documentation list below) does not describe the behavior correctly, at least for my environment. The section "Documents of interest" contains links and remarks to the weak documentation as  well as links to messages showing that the documentation actually does confuse people.


------------------------------------------
DOCUMENTS OF INTEREST

---------------------------------
  Description of the stop() and destroy() methods
http://java.sun.com/j2se/1.4.2/docs/api/java/applet/Applet.html#stop()
http://java.sun.com/j2se/1.4.2/docs/api/java/applet/Applet.html#destroy()
http://java.sun.com/j2se/1.5.0/docs/api/java/applet/Applet.html#stop()
http://java.sun.com/j2se/1.5.0/docs/api/java/applet/Applet.html#destroy()

  Remark: The description of stop() says: "A subclass of Applet should
  override this method if it has any operation that it wants to perform each time
  the Web page containing it is no longer visible.  For example, an applet with
  animation might want to use the start method to resume animation,
  and the stop method to suspend the animation." This would imply that any
  conforming browser should call stop() when the web page become invisible,
  e.g., because the window was minimized.

--------------------------------
Life Cycle of an Applet:
http://java.sun.com/docs/books/tutorial/applet/overview/lifeCycle.html

 Remark: The applet in this site does not behave as they describe it.  In fact, leaving the page destroys the applet and returning creates a new  instance.

---------------------------------
  Bug report ("not a bug") that describes the observed behavior.
http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4274743

  Remark: The answer to this report is that Sun does not have any control over the lifetime management of the browser. This indicates that the API documentation is lacking a note  pointing out that the specific behavior of stop() and destroy() is browser dependent.

-------------------------------
Sun developer forum, message: "Why can't I get the Applet stop method to invoke?" http://forum.java.sun.com/thread.jsp?forum=47&thread=501145&tstart=75&trange=15

  Remark: The user seems to have made a similar observation that the stop method is not called when minimizing but no reply has been posted.

------------------------------
A similar message is here:
http://forum.java.sun.com/thread.jsp?forum=421&thread=340075



--------------------------------------------------------------------------
TEST PROGRAM AND OUTPUT

Remark: the following test file does not draw anything. However, it is only a simplified version of a larger project that does draw something and shows identical behavior.

<START FILE BrowserTest.java>
import javax.swing.JApplet;
import java.awt.HeadlessException;

public class BrowserTest extends JApplet {
  
  public BrowserTest() throws HeadlessException {
    id = currentID;
    currentID++;
    System.out.println("APPLET CREATED #"+id);
  }
  
  public void init(){System.out.println("APPLET INITED #"+id);}
  public void start(){System.out.println("APPLET STARTS #"+id);}
  public void stop(){System.out.println("APPLET STOPS #"+id);}
  public void destroy(){System.out.println("APPLET DESTROYED #"+id);}
  protected void finalize(){System.out.println("APPLET FINALIZED #"+id);}
  
  //The behavior can be reproduced without the following members as well.
  private final int id;
  static private int currentID = 0;
}
<END FILE BrowserTest.java>


----------------------------------------------------------------------------
The following is copied from the log of the plugin console
<BEGIN LOG PLUGIN>
//Here I launch the plugin the first time, starting the first browser window.
APPLET CREATED #0
APPLET INITED #0
APPLET STARTS #0
//Here I leave the page, visit a different one.
APPLET STOPS #0
APPLET DESTROYED #0
//Here I go back to the page containing the applet.
APPLET CREATED #1
APPLET INITED #1
APPLET FINALIZED #0
APPLET STARTS #1
//Here I reload the page containing the applet.
APPLET STOPS #1
APPLET DESTROYED #1
APPLET CREATED #2
APPLET INITED #2
APPLET FINALIZED #1
APPLET STARTS #2
//Here I open another window with the same page, creating a second instance of the applet.
APPLET CREATED #3
APPLET INITED #3
APPLET STARTS #3
//Here I close the second page.
APPLET STOPS #3
APPLET DESTROYED #3
//Here I minimize the browser window.
//(nothing happens)
//Here I restore the browser window.
//(nothing happens)
<END LOG PLUGIN>
--------------------------------------------------------------------------------------


EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
A subclass of Applet should override this method if it has any operation that it wants to perform each time the Web page containing it is no longer visible.  For example, an applet with animation might want to use the start method to resume animation,  and the stop method to suspend the animation. The browser is not required to call this method. The only time this method is guaranteed to be called is before destroy() is called.
ACTUAL -
A subclass of Applet should override this method if it has any operation that it wants to perform each time the Web page containing it is no longer visible.  For example, an applet with animation might want to use the start method to resume animation, and the stop method to suspend the animation.

URL OF FAULTY DOCUMENTATION :
http://java.sun.com/j2se/1.5.0/docs/api/java/applet/Applet.html#stop()
###@###.### 2005-04-11 10:52:42 GMT