Working with applets

If you have already tried to write applets and deploy them to a web site, you've probably discovered that, compared to applications, applets require dealing with additional issues to make them work. Deploying and testing applets outside the IDE is where difficulty usually begins, and if you have not handled some basic applet issues correctly, your applet will not work properly. To succeed, you need to know how applets work and how all the pieces fit together, especially when it comes to deploying and uploading them to an external web site.

For information on running applets in JBuilder, see also:
"Running Java programs"
"Runtime" topic in the "Release Notes" (Help|Release Notes)

For additional information on applets, see also:
"Tutorial: Building an applet" in the Quick Start
The Java tutorial on "Writing Applets" at http://www.java.sun.com/docs/books/tutorial/applet/index.html
Sun's web site at http://www.javasoft.com/applets/index.html
The Java FAQ at http://www.afu.com/javafaq.html
Charlie Calvert's home page at http://homepages.borland.com/ccalvert/JavaCourse/index.htm


How do applets work?

Applets are Java programs that are stored on an Internet/intranet server. They are downloaded to multiple client platforms where they are run in a Java Virtual Machine (JVM) provided by the browser running on the client machine. This delivery and execution is done under the supervision of a Security Manager, which can prevent applets from performing such tasks as formatting the hard drive or opening connections to "untrusted" machines.

When the browser encounters a web page with an applet, it starts the JVM and provides it with the information located in the APPLET tag. The class loader inside the JVM looks to see what classes are needed for the applet. As part of the class loading process, the class files are run through a verifier which makes sure they are valid class files and not malevolent code. Once verified, the applet runs. This is, of course, a simplified view of the process.

This delivery mechanism is the primary value of applets. However, there are some issues unique to applet development that need to be addressed to ensure successful implementation.

The APPLET tag

Everything an applet needs to know at runtime is determined from the contents of the APPLET tag in the HTML file. The tag attributes tell it what class to run, which (if any) archives it should search for classes, and the location of these archives and/or classes.

Unlike Java applications, which use an environment variable called CLASSPATH to search for classes, applets use only the CODEBASE attribute in the APPLET tag to specify where to look for classes needed by the applet.

The key to running an applet is its ability to find the classes it needs.

Sample APPLET Tag

Below is a simple APPLET tag that uses the most common attributes.
<APPLET
   CODEBASE = "."
   ARCHIVE = "test.jar"
   CODE = "test.Applet1.class"
   NAME = "TestApplet"
   WIDTH = 400
   HEIGHT = 300
   VSPACE = 0
   HSPACE = 0
   >
   <PARAM NAME = "param1"  VALUE = "xyz">
</APPLET>

APPLET tag attributes

The following table describes the most common attributes and parameters used in the APPLET tag. Notice that some items are required.

Item Description
CODEBASE(optional/required) Allows you to specify a different location for your classes or archive files than the location of the HTML file containing the APPLET tag. This path is relative to the location of the HTML file and is often limited to subdirectories of the location of the HTML file.

For example, if the applet classes are stored in a classes subdirectory, the CODEBASE attribute is CODEBASE = "classes".

A value of "." specifies the same directory as the HTML file running the applet.

Important: This attribute is required if the class or archive files are in a different directory than the applet's HTML file.

ARCHIVE (optional/required) Used to identify one or more archive files (ZIP, JAR, or CAB) that contain the classes needed for the applet. Archive files must be placed in the directory specified by CODEBASE. You can have multiple archive files and list them with commas: ARCHIVE="archive1.jar, archive2.jar".

Important: This attribute is required if your applet is deployed to archive files.

Note: Some of the older browsers only support ZIP archives.

CODE (required) The fully qualified name of the applet class that contains the init() method. For example, if the class Applet1.class is part of a package called test, then CODE would be CODE="test.Applet1.class".
NAME (optional) A string that describes your applet. This string shows up in the status bar of the browser.
WIDTH/HEIGHT (required) Defines the size in pixels allocated to the applet in the browser. This information is also passed to the applet's layout manager.
HSPACE/VSPACE (optional) Represents the horizontal or vertical padding in pixels around the applet. This is useful if you have text on the web page that wraps around the applet or if you have more than one applet in the page.
PARAM (optional) Allows you to specify parameters that can be read by the APPLET tag. These are similar to the argument list used by main() in applications.

Parameters have two parts, NAME and VALUE, both quoted strings. NAME is used inside the applet when you want to request a VALUE . You must handle any conversion from String to some other data type in your applet code. Be sure to match the case between the HTML parameter and the applet code that requests it.

Common mistakes in the APPLET tag

Most problems with the APPLET tag are due to the following errors:


Browser issues

One of the primary tasks in getting applets to work at runtime is solving the various issues with the browsers that host the applets. Browsers vary in the level of JDK support, and each browser approaches Java implementation differently. Below are the most frequent issues you'll encounter concerning browsers.

Java Support

A common problem with applets is a JDK mismatch between your applet and the browser running it. There are many users who have not upgraded or updated their browsers. These browsers support JDK 1.1.5 code and earlier but not the newer JDKs from Sun (which is what JBuilder generates). Swing, introduced in JDK 1.1.7, is not yet supported. The most common error will be NoClassDefFoundError on some class in the java.* packages because the ClassLoader determined it needed a Java class or method that the browser JDK does not support.

JDK 1.2 and 1.3 are still not fully supported in all browsers. While it is true that recent versions of the browsers support Java, you should know what specific version of Java is supported in the browsers that will run your applet. This is important so you can do whatever is necessary to create a match between the version of the JDK used in your applet and the JDK supported by the browsers. Browsers that do support JDK 1.1 are Netscape 4.06+ and Internet Explorer 4.01+. JDK version support may vary by platform.

To find out what JDK version the browser supports, check the Java Console in the browser or check the browser's web site.

To open the Java Console:

The JavaTM Plug-in from Sun easily solves the problem of JDK mismatch by permanently downloading the same version of the JDK to all the end-users' machines.

Getting the preferred browser to the end user

Initially you have to get your clients to install a minimum version of a browser. If they already have their favorite browser installed, you will need to convince them that any inconvenience caused by getting updates is offset by the value of your applet. Each browser upgrade requires downloading the browser update and/or installing a patch.

Supporting multiple browsers

If you've chosen to support more than one browser with your applet, you will have to support them in the field as well. This means that if users have browser-related trouble using your applet, they are going to call you for support.

Differences in Java implementation

There are guidelines and specifications for what browsers must provide but implementation of these and any extensions is left to the browser manufacturer.

One difference among browsers is in their implementation of the Security Manager and security levels. What is allowed in one browser at "medium" security may not be allowed in the other. Adjustment of security is done on the client side, and each browser does it differently. For example, the mechanism for relaxing some security for an applet is signing. Signing an applet and getting the browser to accept that signature allows you more flexibility in your applet. The mechanism for this is built into Java with the Javakey utility. Unfortunately, browsers aren't required to use thisf mechanism. In fact, some use their own proprietary mechanisms for signing which only work in their browser.

Another difference is that individual browser manufacturers make some adjustments to core Java functionality, including leaving some of it out. This can result in unexpected behavior at runtime. For example, you could have paint calls that do not happen, leaving the applet in an odd state, or even invisible. You can try to find a way to code around specific cases, but it is not always possible.

Also, there are often variations in Java support on different platforms from within the same browser. For example, a multi-threaded applet may run on one platform, but because of problems in the threading model on a different platform, threads may run sequentially on a different platform. Often, browsers are not updated across platforms at the same time, and a browser update for a less popular platform may be released later.

These differences increase the amount of time you have to spend testing and debugging in a particular browser.


Solutions to browser issues


Additional tips for making applets work

Below are a few more tips for avoiding problems when developing and deploying applets:


Security and the Security Manager

An important concern about running programs over the Internet is security. Users are rightly cautious about downloading and running unknown programs on their machines without a guarantee of security to prevent things like programs deleting files or uploading personal information from their computers.

Security is advantageous for the developer because without it many end users would not allow applets to run at all. However, it also has several disadvantages for the developer, especially if the developer is unaware of the restrictions when the project is started. Many activities that you take for granted in an application will be denied in an applet.

The sandbox

Applets address this concern by running all untrusted code in a safe environment called the sandbox.While they are in the sandbox, they are under the watchful eye of a Security Manager. The Security Manager protects the client machine from harmful programs that might delete files, read secure information, or do anything that is a violation of the security model being used. The restrictions placed by the Security Manager, in turn, limit what an applet can do.

Understanding these limitations before writing your applets can save time and money. Applets, like any tool, accomplish certain tasks very well. But, trying to use an applet in the wrong context only leads to problems.

Applet restrictions

By default, all applets are "untrusted" and are blocked from specific activities, such as:

There are other activities taken for granted by application developers, such as running local system programs to save time, which are not allowed in applets. Any good Java book will list the restrictions placed on applets.

If you find that you are trying to bypass the Security Manager at any point in your planning or development, consider using an application instead. Sun has done a very good job of defining their security model and identifying the key bits of information, or data types, on which entire sets of functionality depend. As a result, it is very difficult to trick the security model.


Solutions to security problems


Using third-party libraries

Third-party libraries are a great benefit for the developer. Often, these libraries contain a variety of components that save time and money. However, it is important to weigh the advantages of the component libraries to the disadvantages to your end user.

With applets, all referenced classes have to be sent across the Net to the client machine. If the third-party library has a large interwoven architecture, it can substantially increase the applet's file size. You should also be aware of the redistribution license for the library. Some libraries require you to redistribute the library in its entirety (not just the pieces you use).

Remember: The larger the applet, the longer it takes to download and run.


Testing applets

The main purpose of an IDE is to enable you to develop and test your code locally. When you run an application or an applet in JBuilder, if the the program needs a particular class, JBuilder goes to great lengths to find that class. This actually allows you to focus on developing your application or applet and making sure it works.

However, it does not give you accurate runtime behavior for applets. To properly test an applet, you need to test it with the applet deployed to the web server in its actual running environment. This is the only way to make sure all the classes the applet needs are available on the server running it.

When you run your applet in a browser, the applet needs to have enough information inside the APPLET tag of the HTML file to allow the applet loader to find all the classes, images, and other assorted files your applet needs. This environment is the entire "real world" of your applet and is the only place the applet gets the information it needs for finding the files.

For the first tests of your deployed applet, consider using the JDK appletviewer test "browser." This command-line tool included in the JDK provides useful displays of error messages and stack traces. As demonstrated in the following steps, remove the CLASSPATH in the testing session.

Basic testing steps

Below are the basic steps for testing your applet:

  1. Deploy the necessary applet files to the server.

    Check the following:

    Deployment is covered in depth in "Deploying Java programs" in the JBuilder Professional and Enterprise documentation.

  2. Open a command-line window.

  3. Remove any CLASSPATH you may have set for that session. appletviewer knows were to find the core Java files.

  4. Change to the directory containing the HTML file and the JAR file (or class files).

  5. Run appletviewer.

    /jbuilder/jdk/bin/appletviewer TestApplet.html

    Note: If JBuilder is on another drive, include the drive letter. For Windows, use a backslash (\).

    If this is the first time you've run appletviewer, you'll get a license agreement screen. Click Yes.

    If all is well, you will see your applet running in appletviewer. If not, look in appletviewer's console to read the error messages.

Testing in the browsers

Always test your applet in the browsers after deploying it to the server. This is critical to ensure that all the classes you need for the applet are deployed properly to the server and that the APPLET tag and server deployment match.

Here are a few tips for testing in the browser:

See also:
"Solving Common Applet Problems" in the Java Tutorial, "Writing Applets"


Deployment

Deployment is the process of gathering the applet's classes and their dependents in the correct hierarchy for deployment to a server. JBuilder Professional and Enterprise provide the Archive Builder for deployment within JBuilder's IDE after applet development. Sun provides the jar tool in the JDK.

There are several things you can do to make deployment easier:

For details on deployment, see "Deploying Java programs" in the JBuilder Professional and Enterprise documentation.