This page shows an example of how to create and locally install a simple content handler in the HotJava^TM Browser.

Content handlers are Java programs that the HotJava Browser loads when it needs to display files of a particular MIME type/subtype combination within the browser. Some examples of MIME type/subtype combinations are text/plain, text/richtext, image/gif, and so on. (You can download the official list of MIME types.)

For example, suppose your company (whose main Internet domain name is "foo.COM") wants to install a content handler to insert a message at the top of all content of MIME type text/plain. To set this up, follow these steps.

1.  Create directories.

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

By convention (but not a requirement), the directory structure starts with a directory named classes. The next four directories, COM/foo/content/text, are used to create a package called COM.foo.content.text. 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 MIME type of data. In this example, this is text. In the next step, you'll create a Java source file named after the MIME subtype of the data (plain).

2.  Create the Java source file for the content handler

In the text directory, create a file named plain.java with these contents.

This file defines a class named plain that is a subclass of ContentHandler (a class in the java.net package). A HotJava Browser content handler must be a subclass of ContentHandler. The name of each ContentHandler subclass must match the name of the MIME subtype it handles (in this case, plain).

3.  Compile the Java source file.

Compile the content handler using the Java compiler:

   javac plain.java

If compilation succeeds, the compiler creates a file named plain.class. If compilation fails, make sure you typed in and named the program exactly as shown.

4.  Set the java.content.handler.pkgs property.

In the HotJava Browser properties file, set the property java.content.handler.pkgs to include the prefix of your new content package, COM.foo.content. This property is a vertical bar (|) separated list of package prefixes that defines a search path for content handlers. A package prefix in this list should not include the main MIME type (such as "text") as part of its definition.

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

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

   java.content.handler.pkgs=COM.foo.content

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

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

5.  Set the CLASSPATH environment variable.

Set your CLASSPATH environment variable to include the classes directory, so that HotJava can find your new content handler.

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

6.  Make sure the Plain Text Action setting on the HotJava Browser's Edit->Preferences->Viewer Applications page is set to "View in HotJava."

This is the default setting for how to handle the Plain Text Content Type. If you've changed this to tell HotJava to launch an external application to view Plain Text, HotJava will use that application instead of your new content handler.

If you don't have a Content Type called Plain Text (e.g. if it's been deleted or overridden), look for a Content Type with the MIME type/subtype setting of Text/plain. If you don't have one, create one. The Action for this Content Type should be View in HotJava.

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.content.handler.pkgs property and CLASSPATH environment variable.

8.  Load the content handler.

The content handler is automatically loaded the first time you visit a plain text document.

Load the content handler by viewing a plain text document, such as this one. You should see the following text followed by the contents of the file in the HotJava Browser:

    [Content of ...]

    [This opening message brought to you by your plain text
    content handler. To remove this content handler, delete the
    COM.foo.content.text directory from your class path and
    the java.content.handler.pkgs property from your HotJava
    properties file.]
    ----------------------------------------------------------------

Back to HotJava User's Guide Table of Contents

Back to Content and Protocol Handlers

Continue to Local Protocol Handlers (next topic)