
	Corporate Info \| News \| Solutions \| Products \| Partners \| Services \| Events \| Download \| How To Buy
	e-docs \| Site Map \| Search \| Contact \| Glossary \| WebLogic Server Documentation

Using applets with WebLogic

Introduction to applets: The pros and cons of applets; How applets work
Using WebLogic classes in applets: Serving applet classes from a WebLogic Server; Serving applet classes from a non-WebLogic server; Verifying access to the WebLogic classes
Tips on developing applets: Using the Java Plugin; Testing your applet

Introduction to applets

The pros and cons of applets

You may use applets as part of your distributed application running on WebLogic to provide a more interactive client-side interface in a web browser. Applets provide the advantage of running safe client-side code without the need to distribute software.

Applets have a bad reputation and are not popular with end-users due to the length of time they require to download, and the stability of the Java VM implementations in many popular web browsers. They are not popular with application developers due to the security restrictions imposed by the web browser JVMs and the maintenance cost for compatibility.

You should think carefully before you use applets in your distrubuted applications, and be aware of your options. Often, a well designed series of interactive web pages using HTML forms and HTTP servlets will yeild a faster and more reliable website. For information on which browsers and plug-ins have have been tested with applets and WebLogic Server, see the platform support page.

How applets work

This section describes the bare-bones of how applets work for the purpose of this document. For a more in-depth introduction to applets, see Sun's Java Tutorial.

Applets are usually embedded within an HTML page using an <APPLET> tag such as:

  <APPLET CODE="HelloWorld.class"
          CODEBASE="/classes/" WIDTH=150 HEIGHT=25>
  </APPLET>

When a web browser requests the HTML page containing the <APPLET> tag, it attempts to find the main applet class referenced by the CODE attribute. The web browser requests the class from the URL specified by the CODEBASE attribute. Any other classes that the applet uses are requested from the URL specified by CODEBASE.

You should be careful when testing your applet, that the web browser classpath does not contain any of your applet classes. If the borwser cannot retrieve the requested class from the HTTP server, it looks in its local classpath. This may fool you into thinking that you have configured you applet deployment correctly since it works on your local host machine. Yet, when someone attempts to use the applet from a remote client it will fail if you have not deployed all of the requires applet classes on your web server.

Any class that is loaded over the network is checked by the web browser's SecurityManager. If the applet class attempts to violate the restrictions of the SecurityManager, it will throw a SecurityException. The following restrictions are common policies on popular web browsers (taken from the Java Tutorial):

An applet cannot load libraries or define native methods.
It cannot ordinarily read or write files on the host that's executing it.
It cannot make network connections except to the host that it came from.
It cannot start any program on the host that's executing it.
It cannot read certain system properties.
Windows that an applet brings up look different than windows that an application brings up.

Finally, the applet is initialized, and executes in the web browser window.

Using WebLogic classes in applets

Often, your applets need to call client-side WebLogic classes such as JDBC, RMI, or EJB. You must make those classes, and all classes they rely upon, available to the web browser running the applet.

Web browsers identify where to obtain classes via the CODEBASE attribute of the <APPLET> tag. The following two sections describe how to serve your applet classes and the WebLogic classes if your HTTP server is a WebLogic Server, or a non-WebLogic HTTP server.

Remember that all of the classes that your applet needs must be located on the host that serves the applet, since an applet can only talk back to the IP address from which it was originally loaded.

Serving applet classes from a WebLogic Server

WebLogic provides a special servlet called the ClasspathServlet that can serve class files over HTTP. These include classes found in the system classpath set by the CLASSPATH variable, and the WebLogic classpath, set via the weblogic.class.path property.

The advantage of using the ClasspathServlet is that you do not need to duplicate the WebLogic classes that your applet requires since they are taken directly from the WebLogic classpath, eliminating redundancy, and keeping your classes synchronized and organized. You can place your applet classes in the /weblogic/myserver/serverclasses directory that is located by the %SERVER_CLASSES% environment variable when you set your development environment. This directory is included in the weblogic.class.path in the startWebLogic script.

You register the ClasspathServlet against a virtual servlet name, and specify this virtual name as the CODEBASE in the applet tag. When the browser requests the applet classes from this URL, the ClasspathServlet is invoked, it searches for the classes in the WebLogic classpath, and serves the classes back to the browser.

By default, the ClasspathServlet is registered against the virtual name classes in the weblogic.properties file, like so:

  weblogic.httpd.register.classes=weblogic.servlet.ClasspathServlet

To instruct the web browser to request the applet classes from the same WebLogic Server that served the HTML file containing the applet, you set the CODEBASE attribute as it appears in the following example:

  <APPLET CODE="mainApplet"
          CODEBASE="/classes/">
  </APPLET>

For instructions on configuring the ClasspathServlet, see Setting up the ClasspathServlet, in the Administrators Guide document Setting up WebLogic as an HTTP server.

Serving applet classes from a non-WebLogic server

Most HTTP servers serve applet classes as regular HTTP content, where the applet classes live beneath the document root of your HTTP server. We recommend that you create a directory called classes/ in the document root directory of your HTTP server, and copy the entire contents of the /weblogic/classes/ directory there. You should also copy your applet classes to this directory, as though it were your classpath.

For example, if your applet class has the full package name

  myco.mypackage.myapplet

you place the applet class file at:

  .../document_root/classes/myco/mypackage/myapplet.class

Where .../document_root is the directory that's configured at your document root on your HTTP server.

In your <APPLET> tag, you set a fully-qualified CODEBASE that follows the pattern:

  http://HttpServerHost:HttpPort/classes/

Note that you do not need to specify HttpPort unless it is different from the default port 80, over which most HTTP servers listen for HTTP requests.

Note that the classes referenced in the CODEBASE URL is not an absolute path on the HTTP machine, but rather a path relative to and below the HTTP document root.

Verifying access to the WebLogic classes

You can verify that you have loaded the classes into the proper directory by testing the expected URL with an HTML page in your browser. With the URL that is the combination of your CODEBASE, plus full-package-name.class, the class should properly load into the browser or Appletviewer.

To test this, copy the URL from the CODEBASE of your applet, paste it into the Open or Go To space in a browser window, and then open the location. If your CODEBASE is correct, the URL should open the directory on the HTTP server that contains your classes.

You should refer to the WebLogic classes by the full package name, relative to the CODEBASE. If you need more information on how packages are created and used, see Creating and Using Packages in the Java tutorial at Sun. All of the WebLogic classes are bundled into sets of packages, and you must reference classes with the full package name. Using the full package name ensures that classes names are never ambiguous.

This example shows the HTML APPLET tag for an applet to retrieve and display records from a database with a class called "dbretrieve" in the package "mypackage.applets":

<APPLET
  CODEBASE="http://bigbox/classes"
  CODE="mypackage.applets.dbretrieve"
  WIDTH=700
  HEIGHT=300>

If you have problems running your applet code, it may be due to a variety of reasons. If you have copied the WebLogic classes into the wrong directory, or set your CODEBASE incorrectly, or if you do not use the full package name of the class, you will get a File Not Found error in the browser. It may also be because you have not installed the weblogic/classes in the right place, because the weblogic/classes are not in your CLASSPATH, or because loading the classes is causing security violations.

Tips on developing applets

Using the Java Plugin

WebLogic recommends that you always use the Java Plugin for your applets.

Sun now provide a browser plugin that allows your applets to run within the standard Java Runtime Environment, instead of the browser's default virtual machine. This ensures consistency in any browser that supports the plugin, which means compatibility and reliability for your applets. The plugin also allows you to conveniently determine which JRE is used on the client machine.

The Java Plugin provides essential compatibility for your applets if they need to communicate with the WebLogic Server. In most cases, the version of the Java virtual machine (JVM) on the client must match the version of the JVM on the server. That is, if the server is running under Java1.1.x, then you must use the Java 1.1.x Plugin. If the server is running under Java1.2.x, you must use the Java 1.2.x Plugin.

You can find more details about the plugin on Sun's website at: The Java Plugin homepage. The Java Plugin is a native plugin for the Internet Explorer or Netscape browsers. When a user first hits a page that requires the plugin, they are directed to Sun's website to download it. The plugin need only be downloaded once. The plugin runs the applet on a stable release of a specific JRE from Sun, yet can run inside the browser like a regular applet.

The plugin can be tricky to embed into your HTML pages since Internet Explorer and Netscape use different syntax from each other. At Sun's website are instructions on how to hack both syntax formats into the same HTML file, or you can download the HTML-converter, which will automatically convert your existing <APPLET> tags. As you will see, the workaround is quite ingenious, but contrived and difficult to maintain. Thankfully, JavaServer pages have a better solution...

In JSP, you use the <jsp:plugin> tag to include an applet into a JSP generated web page. The generated servlet detects the type of client web browser, and sends the appropriate plugin tags in the response. For more details see the Developers Guide, Using WebLogic JSP.

Testing your applet

There are many reasons why an applet can fail, and it can be a daunting task to debug your applets. These tips may help you track down the cause of your problems.

Testing the applet logic

When you are debugging an applet problem, it is useful to run the applet in the appletviewer utility, that is part of the JDK. This eliminates problems caused by the web browsers, or your HTTP distribution set up.

The simplest test case is using Appletviewer with the applet and WebLogic classes in your CLASSPATH. You can easily set this up by running the setEnv script, as described in Setting up your development environment.

Since Appletviewer is not restrictive on what classes it loads, you should have no problem with security violations. The applet classes are loaded from the local classpath, and are not deployed from the HTTP server. You should be able to request the HTML file referencing your applet straight from the local file system, such as:

 $  appletviewer /myapplets/testapp.html

If your applet does not work under these circumstances, you have something wrong with either:

your applet code
server-side code or services that the applet interacts with
the HTML file referencing your applet (but not the CODEBASE attribute).

Testing your applet deployment

You can test the deployment set up of your applet from your HTTP server using the appletviewer to request the HTML file that references your applet from the HTTP server. Open a new command prompt, and ensure that the system classpath is empty by setting:

 $  set CLASSPATH=""

Then run the appletviewer, giving it the URL of the HTML file on your HTTP server where the applet is deployed.

If your applet fails, but did work in the Testing your applet logic scenario, then you have a problem with the deployment of your applet classes. You may see an error message such as:

  java.lang.NoClassDefFoundError: mycom/mypackage/AnAppletClass

If the class not found is a WebLogic class, check that your HTTP server is set up correctly, as described in the above section Using WebLogic classes in applets.

Testing your applet from a web browser

The final test for your applet is within a web browser. You should test your applets from all browsers you intend to support. It is a common practice to define a subset of compatible browsers for a web-application, especially within an intranet.

When testing from a browser, it is important to ensure that the browser is running in an environment where the classpath is empty. This guarantees that the browser must retrieve all required classes from the HTTP server, and not from the local file system.

Note: Early versions of Netscape warned you of security violations when loading classes from the local classpath, but still loaded the classes; however, versions of Netscape after 4.0 do not allow loading of any classes locally, and will throw security exceptions.

If your applet fails, you can inspect the applet log in the browser's Java Console. In Netscape, you start the console by selecting

Communicator->Tools->Java Console

In Internet Explorer, you have to enable the Java Console, and Java logging first. Open the 'Internet Options' dialog from the 'Tools' menu; on the 'Avanced' panel, scroll down to 'Java VM', and check the boxes next to 'Java console enabled' and 'Java logging enabled', then close all IE windows and restart IE. You should then see the 'Java Console' option under the 'View' menu.

Optimizing your applet's performance

Using an archive file

You can pack the classes that your applet requires into a compressed archive file to speed up the download time. When applet classes are requested individually, much time is wasted opening and closing a new connection for each class file. By packing the required classes into a single file, they can all be downloaded in a single HTTP request.

WebLogic provides a useful tool for packaging all of the classes required to run an applet into a JAR or CAB archive. For instructions on how to use the Applet Atchiver, see Using the AppletArchiver to create a .jar or .cab archive.