This page shows an example of how to create and locally install a simple protocol handler in the HotJavaTM Browser.

For example, suppose your company (called foo) wants to install a protocol handler called run. Once installed, this protocol will enable your HotJava Browser users to specify a URL of the form run:applet in order to run an applet in a new HTML page.

For this example, let's assume a developer at foo.com is building this new protocol handler. Before installing it in foo.com's main Java class library, she wants to test it locally. To do so, she puts it in a convenient place in her local file system, adjusts her java.protocol.handler.pkgs property to include the package prefix (all but the run part of the package), and makes sure that the location of her local protocol handler is reachable through the CLASSPATH environment variable. Here are the steps the developer would follow in more detail:

1.  Create directories.

Create the directory structure where your protocol handler will live, such as: classes/COM/foo/protocol/run.

By convention, (but not a requirement), the directory structure starts with a directory named classes. The next three directories, COM/foo/protocol, are used to create a package called COM.foo.protocol. The convention is to prefix packages produced by company fred.flintstone.COM with COM.flintstone.fred, so two different vendors creating the same class are unlikely to have name collisions.

The final directory must have the same name as the new protocol (without the trailing ':'). In this example, this is run. The only strict requirement about the directory structure is that the name of the protocol is the last part of the package name.

2.  Create the Java source file(s) for the protocol handler.

In the run directory, create a file named Handler.java with these contents.

This file defines a class named Handler that is a subclass of URLStreamHandler (a class in the java.net package). A HotJava Browser protocol handler must be called Handler, and it must be a subclass of URLStreamHandler.

In the same directory, you'll also need to create a file named RunURLConnection.java with these contents.

3.  Put an applet in the classes directory.

You can use any applet that is reachable through your CLASSPATH environment variable. For the purposes of this example, put an applet in the classes directory. You can use the HelloWorld applet, saving the source code in a file named HelloWorld.java.

4.  Compile the Java source files.

Compile the protocol handler and applet using the Java compiler.

On UNIX systems: 

    cd <your-classes-directory>
    javac HelloWorld.java 
    cd COM/foo/protocol/run
    javac Handler.java
    javac RunURLConnection.java
In a DOS shell (Windows 95/NT): 
    cd <your-classes-directory>
    javac HelloWorld.java
    cd COM\foo\protocol\run
    javac Handler.java
    javac RunURLConnection.java

If compilation succeeds, the compiler creates files named Handler.class and RunURLConnection.class for the protocol handler, and HelloWorld.class for the applet. If compilation fails, make sure you typed in and named the programs exactly as shown.

5.  Set the java.protocol.handler.pkgs property

In the HotJava Browser properties file, set the java.protocol.handler.pkgs property to include your new protocol package, COM.foo.protocol. This property is a vertical bar (|) separated list of package prefixes that defines a search path for protocol handlers.

See Customizing the HotJava Browser for information about where to find the properties files for your platform. If you're installing a protocol handler for all users of the HotJava Browser in your environment, update the system properties file. Otherwise, add the java.protocol.handler.pkgs property to your personal properties file.

For this example, you would add the following line to your HotJava Browser properties file: 

   java.protocol.handler.pkgs=COM.foo.protocol

If you have other protocol handlers defined, use a vertical bar (|) separated list as the value of the property. For example: 

   java.protocol.handler.pkgs=COM.foo.protocol|other.protocol

6.  Set the CLASSPATH environment variable.

Set the CLASSPATH environment variable to include your classes directory, so that HotJava can find the run protocol handler and the test applet.

On UNIX systems, the method of setting environment variables depends on your shell. For C shell, you can enter something like the following at the shell prompt, or put it in your .cshrc file: 

   setenv CLASSPATH .:/home/developer/classes

On Windows sytems, enter something like the following in a DOS shell, the Windows NT Control Panel, or your AUTOEXEC.BAT file: 

   set CLASSPATH=.;C:\developer\classes

7.  Start the HotJava Browser

Even if the HotJava Browser is already running, you need to restart it so that it can read the new values of the java.protocol.handler.pkgs property and CLASSPATH environment variable.

8.  Load the protocol handler

Load the "run:" protocol handler and the applet, using a URL such as this: 
   run:HelloWorld
You should see the applet running in the page that appears. Now you can use your new protocol handler wherever you can specify a URL (for example, links in HTML pages, the Place type-in field, etc.).

Back to HotJava User's Guide Table of Contents

Back to Content and Protocol Handlers

Back to Local Content Handlers (previous topic)