Applets

We have mostly been writing applications. These are stand alone Java programs, invoked directly on your machine. Java programs can also be run from inside a web page. These are called applets and have restrictions that applications do not. Applets cannot access files on the client machine. They cannot make network connections except to the machine they came from. In general, they are restricted from doing things that might damage the client machine.

When a web page is loaded that contains an applet, the needed class files are down loaded to the client along with the web page. The applet class is started by running the init() method. Applets also have start() and stop() methods. These are called when web page that holds the applet goes in and out of view. Here is a diagram that illustrates the flow of control. Applet Control Flow The init() method is called when the page is loaded. When it completes, the start() method is called. It is also called when we come back to this page after going somewhere else. When we follow a link, the stop() method is called on the applet first. When the browser is closed or the applet is stopped, the destroy() method is called. You only need to overwrite those of these methods that you actually need.

Here are a few examples. This first one is very short. It shows how parameters are passed to an applet from the web page and how to write to the graphics page that is created when the applet is initialized. 


import javax.swing.*;
import javax.swing.JOptionPane;
import javax.swing.JTextArea;
import java.awt.Graphics;

/**
 * A test applet that shows parameters and stuff
 *
 * @author Kent Archie
 * @version 1/27/2004
 */
// all applets extend the JApplet class
public class app1 extends JApplet {

    private String showStr; // used to hold a message to be displayed
    private int times;  // how many times to display the message
    JTextArea t;   // place to display the messages

    // the init() method is called when the applet is loaded into the
   // browser window.
   public void init() {
       String mesg = new String("");   // to hold the resulting message

      JOptionPane.showMessageDialog(null, "Init called", "Init",JOptionPane.INFORMATION_MESSAGE);
      // retrieve the value stored the in 'text' parameter from the < applet> tag
      showStr = getParameter("text");

      String timeStr = getParameter("times");
      if (showStr == null) showStr = "CIS435"; // use this if no 'text' parameter

      // use 3 as the default 'times' value otherwise convert the
      // string from the < param> tag into an integer.
      times = (timeStr == null) ? 3 : Integer.parseInt(timeStr);

      // we create a text area with times rows and enough columns to hold the string
       t = new JTextArea("",times,showStr.length());   // place to display the messages

      // now we write the string into the box several times
      for (int i = 0; i < times; i++) {
               mesg += showStr + '\n';   // put each copy of showStr on a new line
      }
      t.setText(mesg);   // display the message
      getContentPane().add(t);  // add the TextArea to the window

    } // init

   // called when the page is loaded after init() and
   // when the page is revisited after the initial load of the applet
   public void start() {
      JOptionPane.showMessageDialog(null, "start called", "start",JOptionPane.INFORMATION_MESSAGE);
   } // start

   // called when the page is left
   public void stop() {
      JOptionPane.showMessageDialog(null, "stop called", "stop",JOptionPane.INFORMATION_MESSAGE);
   } // stop

   // called when the browser is shutdown or the applet is stopped
   public void destroy() {
      JOptionPane.showMessageDialog(null, "destroy called", "destroy",JOptionPane.INFORMATION_MESSAGE);
   } // destroy
} // app1
And here is a small web page that runs it. 

<html>
<body>
<title>Applet Demo 1
<hr>
<applet code="app1.class" width=534 height=500>
<param name=text value="Applet Demo">
<param name=times value="5">
<applet>
<hr>
<a href="app1.java">The source.</a>
<body>
<html>
This page,which runs the applet above, shows the relationship between the applet states and demonstrates how the parameters are passed from the web page into the applet.

Appletviewer

To aid in testing the applet, there is a tool that comes with the JDK call appletviewer. To run it, you simply call it from the DOS command line using the HTML file as an argument. This is similar to running the compiler from the DOS prompt. 
		appletviewer app1.html
This opens a windows that only shows the part of the web page that contains the applet. You can runs some of the methods directly from the menu.

You can provide information about the applet to the appletviewer by implementing two additional methods. The getAppletInfo() method provides a string that contains some information about the applet. Commonly, this will include the author, the applet name, a few lines about its purpose, copyright info and such. It looks like 

public String getAppletInfo() {
        return "Title: Applet Demo\nAuthor: Kent Archie \nDisplays a text a few times .";
    } // getAppletInfo
The other is the getParameterInfo() method. This provides a two dimensional array of Strings. There is one row in the array for each parameter to the applet. Each row has three columns. The first column is the name of the parameter. the second is the parameters type and the third is a note about the purpose of the parameter. Here is an example. 
public String[][] getParameterInfo() {
        String pinfo[][] = {
            {"text", "string", "Text to display"},
            {"times", "int", "How many times"},
        };
        return pinfo;
    } // getParameterInfo

The applet tag

The applet tag has several attributes that describe the applet to the browser.
<applet code=appletname.class The name of the class file that was compiled from the applet. It cannot include a path to the file from the directory where the HTML page is. If the applet is in a different directory from the HTML file, use the codebase attribute.
width=applet width in pixels This is the width in pixels of the box on the screen that will contain the applet. Kind of like the space for an image.
height=applet height in pixels This is the height in pixels of the box on the screen that will contain the applet. Kind of like the space for an image.
codebase=URL to the directory holding the class file This is an URL that indicates where the directory that holds the .class file indicated by the code is. It can be a full URL or it can be a relative one. If the class files for you site are stored in a directory called code and the HTML pages in a directory called html, then the applet tag might look like 
		<applet codebase="../code" code="app1.class" width="500" height="300">
This applet tests the codebase attribute
		<applet>
Between the <applet> and the </applet> tags, you can put text. This will be displayed on the page when an applet cannot be loaded or in browsers where applets are either not supported or not allowed.

This is also where you put the <param> tags. If you applet takes parameters, then you need one param tag for each parameter you want passed in. Inside the applet, you use the getParameter() method to fetch the values of the parameters. If you call getParameter() asking for a parameter for which there is no tag, you get back a null String. The param tag looks like this:
<param name=Quoted parameter name This is the parameter name that is used in the call to getParameter() in the applet code.
value=parameter value as a quoted string This will be returned from getParameter() as a String. If it is supposed to be type other than String, it will have to be converted before use.

Now here is another applet that shows the use of GUI components and how to make the same program run as an applet and an application. 


import javax.swing.*;
import java.awt.*;
import java.awt.event.*;

/**
 * A test applet that shows GUI components
 *
 * @author Kent Archie
 * @version 3/6/2002
 */

// since its an applet, it extends JApplet
// This uses the listener technique of using the same class
// for the applet and the listener.
public class app2 extends JApplet implements ActionListener {

    private JLabel title;   // title at top of display
    private JLabel status;  // current value of the button counter
    private JButton click;  // the button to press
    private JPanel upper;   // holds the title and status
    private JPanel appPanel; // holds the whole display
    private int count=0;     // how many times has the button been pressed

	// by adding this method, we can run this applet by itself
	// without a web page
	public static void main(String[] args)
	{
		System.out.println("main started");
		app2 theapp = new app2();
		theapp.init();
		System.out.println("main ended");
	} // main

	// set up the display
    public void init() {
		System.out.println("init started");
        title = new JLabel ("Button Test", SwingConstants.CENTER);
        title.setFont (new Font ("Serif", Font.PLAIN, 12));

        click = new JButton("Press me");
        // set up the event handler for the button
		// this object is the applet and the listener
        click.addActionListener(this);
        
        status = new JLabel("",SwingConstants.CENTER); // nothing there to start

        upper = new JPanel();  // just the title and status lines
        upper.setLayout(new BorderLayout());
        upper.add(title,BorderLayout.NORTH);
        upper.add(status,BorderLayout.SOUTH);
    
        // the this holds the whole display
        getContentPane().setLayout(new BorderLayout());
        getContentPane().add( upper,BorderLayout.NORTH);
        getContentPane().add( click, BorderLayout.SOUTH);
		System.out.println("init ended");
    } // init

	// this is the method from the listener interface
	public void actionPerformed (ActionEvent event)
	{
        Object source = event.getSource();  // who sent the action?
        if(source == click) {  // was our button the source
           count++;
           if(count <= 1)
              status.setText("The button was pressed once");
           else
              status.setText("The button was pressed " + count + " times");
        }
        else
           status.setText("Something else happened");
	} // actionPerformed

	// the next two methods are used when the appplet is run inside
	// the appletviewer applictaion. They are not needed to run the 
	// applet in a browser
    // used in appletviewer to show information
    public String getAppletInfo() {
        return "Title: Applet Demo\nAuthor: Kent Archie \nDisplays a text a few times .";
    } // getAppletInfo

	// this tells appletviewer what the parameters are
    public String[][] getParameterInfo() {
        String pinfo[][] = {
            {"text", "string", "Text to display"},
            {"times", "int", "How many times"},
        };
        return pinfo;
    } // getParameterInfo
} // app2
And the web page to run it. 

<html>
<body>
<title>Applet Demo 2
<hr>
<applet code="app2.class" width=534 height=200>
<applet>
<hr>
<a href="app2.java">The source.<a>
<body>
<html>