PHD Computer Consultants Ltd ... Practical Java article

Last modified: 1 November 1996.

Reconstructed. Approx 4600 words, including code snippets.

Referenced pages: sidebars/figures in article.

• Figure1: HelpIndex screen shot
• Doing anything useful. In bordered table
• Java pros and cons. In bordered table
• Java APIs. In bordered table
• GridBagForm.java code
• Figure 2: GridBagForm
• Figure 3: HelpIndexFrame
• Development environments. In bordered table

Text in <CODE> tags are class names, while those in <TT> tags are methods.

When published, HTML links in the text can be removed.

Practical Java

Introduction

This article is a collection of useful - some important - tips for using Java picked up when writing my HelpIndex applet for use in World Wide Web browsers. I assume some basic familiarity with Java.

When writing an applet from scratch, you will want to decide which base classes to use, how best to use the windowing classes AWT, what techniques are appropriate when programming an applet and the differences between the main PC browsers. Sidebars discuss how to do anything useful, Java pros and cons, APIs and IDEs.

PHD's HelpIndex applet reads a list of index keywords (and their links to web pages) from the host. Like various help systems, the user can type in the first few letters of their search string. The matching indices and their pages are listed automatically. The selected page can be displayed. The companion MakeHelpIndex Java application lets you build a help index file from your existing web pages.

Figure 1 shows a screen shot showing that the user has typed in J and all the matching keyword indices have been found. Java applet has been selected and various matching pages have been found. HelpIndex Java Applet is selected, so pressing Display Page will show this page. A standard server based search for Java on the PHD site threw up over 200 hits; it would be difficult to know which page to go to.

Figure 1.

Incidentally, one good use of HelpIndex is to provide an index for all the fields and methods of an API. The standard JDK javadoc program is used to produce web page documentation for an API from suitable source code comments. One of its standard outputs is an alphabetical listing of all fields and methods. If you want to look up the getAddress() method, then you have to click on the G short-cut link at the top of the page, then scroll down through all the get() methods until finally you get to where you want. PHD HelpIndex allows you simply to type in get; then the get() and getAddress() methods are listed as indices - much easier.

Before you start

If something goes wrong remember that Java is a young language and its API classes are relatively new too. So, always remember to check Sun's known bugs at http://java.sun.com/products/JDK/CurrentRelease/KnownBugs.html and the FAQs (eg http://www.www-net.com/java/faq/) before resorting to the comp.lang.java.* newsgroups, etc. For other resources, check out Gamelan in USA and the UK's Java Centre. Familiarise yourself with the language by looking at the examples and writing your own simple applications. See the sidebar for some Java pros and cons.

Getting an applet to do anything useful is not quite as simple as it may seem as browser security is so tight. See the sidebar for the range of possible options.

For a new development you will have to decide what technology to use. HelpIndex is based on the original 1.0x Java Development Kit (JDK) from Sun. However that soon will have an improved 1.1 version. Then many suppliers have alternatives, which usually build on top of the JDK, mainly to improve the AWT windowing classes. For example, some may choose Netscape's Internet Foundation Classes as the baseline for new development soon (see its separate review) . See the sidebar for a full discussion of APIs.

However you must ask which people out there will have all these latest classes. Unless Netscape's IFC, for example, is built into all browsers, particularly Microsoft's Internet Explorer (IE3.0), then you will be restricting yourself to Netscape Navigator 4 users. No one will want to download the 500kB classes on-line. For intranet applications you can, of course, ensure that your chosen extension classes are available on all user computers.

You will also have to work out how best to test your new applet. As a minimum I suggest that you that you try it out using IE3.0 and N3.0 browsers at a couple of screen resolutions. Ideally you should try other platforms and earlier browser versions.

Be warned that Java runs s-l-o-w-l-y.

Objects

As a C/C++ person, I am used to tracking allocated memory carefully. All this goes out the window with Java, as you allocate willy-nilly, relying on Java to garbage collect. Let's hope it does it efficiently.

I was fooled a bit at first by object variables. Now I tend to think of them as pointers (technically "references"). For instance, I wanted to make a bit of room around one of my screen components. To do this, I tried to override the insets() method as follows:

public Insets insets()
{
	Insets ri = super.insets();
	ri.left += 5;
	ri.right += 5;
	return ri;
}

The problem is that my ri Insets Object in effect points to the insets in the parent component, so my changes altered the parent's insets. This causes a problem as the insets() routine can be called many times. A better solution is to create your own new Insets instance to return.

public Insets insets()
{
	Insets ri = super.insets();
	return new Insets(ri.top,ri.bottom,ri.left+5,ri.right+5);
}

Using AWT

The JDK Abstract Window Toolkit (AWT) feels limited. It is nowhere near a document and view architecture. It has events and graphics contexts, along with forms and controls.

Despite improvements promised in JDK 1.1, the limitations are such that alternative windowing systems have emerged from other development tool suppliers. These are mostly built on top of AWT. No doubt each one will have its own resource format, eg Java Workshop has a .gui resource file. It is a shame that there cannot be one good system. java.awt will always be there, so it is best to get to know it. So, HelpIndex was based on AWT.

AWT does well to address the problem of each user having a different display. Its classes lay out Components (fields, etc.) in Containers (windows/dialog box forms). You are not supposed to give absolute locations, but tell one of the Layout classes the preferred size and order, and let it get on with the task of laying out the window.

There is some sort of event model, though I have found no event loop. There is no resource format and no printing. There is no tabbing between fields and no default buttons. HelpIndex uses its GridBagForm class to get round these last two problems.

There are standard ways of avoiding flicker in windows. update() makes an off-screen bitmap graphics context for paint() to use. update() then blasts the image onto the screen quickly. HelpIndex does not need to use this technique as it does not normally do any painting; it relies on AWT components which draw themselves, laid out automatically.

Event Handling

There are 30+ events, coming from user interactions with components.

Events are first passed to handleEvent(). Either handle them here and return true, or return super.handleEvent(). If super.handleEvent() is not called then the event is ignored by the actual component, eg the key press is ignored.

super.handleEvent() passes the event to the appropriate delegated applet event handler, then to Component. action() for button presses and menu selections, or one of these appropriately named routines: keyDown() keyUp() mouseEnter() mouseExit() mouseMove() mouseDown() mouseDrag() mouseUp() lostFocus() gotFocus(). You should return false from keyDown(), etc. if you want a component, eg a TextField, to receive the key.

Notice that you can either handle an event in handleEvent() or the appropriate delegated handler, eg keyDown().

I found for key events that the underlying component had not processed the event when you get to look at it. Eg when a key is pressed, if you get the TextField's text in keyDown() then the new character is not there. So to process a key (or succession of keys) HelpIndex gets the processed text in keyUp(), which is slightly naff. You could use keyDown() as a key filter, eg to implement a number only class derived from TextField.

Component Ids

Having received an event, how do you know which object it has come from?

The simplest technique is to have an applet variable for each component you create and see if the event target matches that component. Alternatively, the poor JDK examples actually rely on matching a button's text, eg if text is "OK" then do this. Change the button text and change your code; yuck!

A better technique (methinks) is to have an integer id for each component of your form. HelpIndex's GridBagForm class - see code box - provides this facility wrapped round the GridBagLayout class. GridBagForm.getIdFromComponent() and GridBagForm.getComponentFromId() are used in event handling. GridBagForm also has methods to handle tabbing between components, and to remember the current field when you mouse click to a new tab field.

Obviously you could subclass each component, eg MyButton derived from Button and have an id for each button.

Class reduction techniques

As mentioned above, currently it is advisable to cut down the number of classes that you use in applets - to reduce load time. This definitely goes against the grain, as it tends to make programs less understandable. OO enthusiasts will be turning in their swivel chairs, objecting.

Even a simple structure must be a class. If you want a simple class, it is difficult to initialise, as the ColourLookup example class showed earlier. The messier array-of-objects solution avoids generating a new class.

A new exception means a whole new class, so reuse existing exceptions.

Here is a sneaky way to avoid having an extra class in some situations. Have the static class represent a collection of instances of the class. For instance, I use this technique in GridBagForm where each instance is an individual form component, while the static class is used to manipulate the whole form. Obviously you could only have one such collection class in your program. This technique goes wrong with applets if there are multiple instances of an applet, as the static class will be the same for each applet instance.

Figure 2 shows how GridBagForm has a static Vector called itemList. The elements of this vector are each GridBagForm instances which store information about each component on the form.

Figure 2.

Another trick is to avoid having a class extending Thread. Get another class (eg your applet) to implement Runnable and do your thread stuff in run().

Applet Programming

You have to become familiar with a new programming paradigm. It used to be a cardinal sin to put up any sort of child window, even a message box, since these windows could lock up your computer. Even now it is best to try to work within your given bounds. HelpIndex now has two modes. You can either view its search form set within a page, "applet" mode. Or more usefully, you can have it as an icon initially; when you click the icon, the search form appears in a "floating child window" above the browser.

To make a child window you will need to make a Frame. You need not make it visible if you just want to then make a Dialog. You have to construct dialog boxes by hand. You can either have a class derived from Dialog, or just use Dialog in your frame, and handle all the events in the frame. Dialogs can be modal (with respect to their frame, but not the browser). Only child frame windows can have menu bars, ie applets cannot.

HelpIndex uses its HelpIndexForm class to cope with the two modes. The HelpIndexForm extends the JDK Panel class and contains all the form components. In applet mode, this form is simply added to the applet container. In floating window mode, when the user clicks the icon, a new HelpIndexFrame is first created and then the form is added to it, as shown in figure 3. This approach allows all the user interaction to be handled in HelpIndexForm whether in applet or window mode.

Figure 3.

The following simplified code shows the floating window is created. You can get the preferredSize() for the frame. It is not clear whether the preferred size is supposed to include the borders, but you do need to add something; so add the frame's insets, ie the size of its borders. For IE3.0 you have to do the resize() after the show().

	ourFrame = new HelpIndexFrame(this,FrameTitle);
	ourForm = new HelpIndexForm(this);
	ourFrame.add("Center",ourForm);
	ourFrame.show();
	Dimension frameSize = ourFrame.preferredSize();
	Insets frameInsets = ourFrame.insets();
	ourFrame.resize(frameSize.width+frameInsets.left+frameInsets.right,
					frameSize.height+frameInsets.top+frameInsets.bottom);

If working with your own visible frame, then you will need to derive your own class from Frame, at the very least to catch Event.WINDOW_DESTROY messages. HelpIndex has a small derived class HelpIndexFrame to do this. HelpIndexFrame also sets up the menus in its constructor.

Applets cannot resize themselves or be resized.

If you run an applet twice on the same page (or in different previous pages) then the static classes members are shared betwen the two instances. So be very very careful with you static variables. Note that this clobbers the class reduction technique described above where the static class has a per-applet meaning.

PC Browsers

It is worth while checking that your applet works with both common PC browsers N3.0 amd IE3.0, which do have some significant differences.

If you are developing an applet, then you usually need to stop and restart a browser if you want to test any changes. This is a bit of a bore. Changes in applet parameters generally are not visible without a restart. Setting the disk and memory cache size to zero solves this problem at the expense of performance.

IE3.0's Java implementation seems slightly behind N3.0.

In N3.0, you can set the foreground colour of Label components.

Perhaps more importantly, only N3.0 generates the MOUSE_ENTER, MOUSE_EXIT, GOT_FOCUS and LOST_FOCUS events.

In IE3.0, if you make a Java call to show a web page, where the URL is a local file with an anchor name, then the page is not displayed.

IE3.0 includes a font "ZapfDingbats" which has lots of useful symbols.

How browsers start and stop applets

How do browsers start and stop applets, eg when its page is selected or when the user moves to another page?

First, it needs to be said that applets seem to keep running when the user moves to another page, which is decidedly poor in my opinion. I think they try to keep the input focus if they have it. At the very least, I would have expected that an applet's threads are suspended.

All classes can have static initialisation and finalize() destructor methods. In addition, applets have init(), destroy(), start() and stop() methods.

When first run, an applet's static initialisation is called, a new instance of the Applet is created, init() is called, then start(). Fine.

If you leave the web page then stop() is called. If you then go back then the applet is still there and start() is called. So start() might be the appropriate place to put the input focus in the desired initial place. You might deem it necessary for all initialisation to happen in start().

In N3.0 but not IE3.0, if you reselect a link to the web page (as opposed to just going back to it) then the applet is sort-of-restarted. The static initialisation is not called, but a new Applet is created, init() and start() are called. All the applet's components need to be rebuilt. So be very careful to make sure that your init() handles this case as you would like. To be completely safe, you might want to initialise all your variables and other classes in init().

destroy() is supposedly only ever when the browser is shut down. I have not confirmed this yet.

Improving the User Interface with Threads

In applets, use threads to speed up the response time for users.

If there is a long task at start-up, then do it in a thread started in init(). Returning from init() lets the applet show itself. Obviously let the user know that some work is in progress.
Make sure you avoid problems that might occur if init() is called more than once, as explained above.

HelpIndex's init() starts another thread to read its help index from the server, which may take several seconds. A status message is displayed until the index has been read. The user can type in the applet's fields, but a lookup does not occur until the index has arrived.

HelpIndex also uses threads to do the lookup task, as this may take a second or so for large indices. The task is carefully designed so that it can be stopped and restarted when another key is pressed. Note that you should use the synchronized keyword to schedule operations. As well as synchronized methods you can have synchronized blocks, locking the class instance, as this simplified example from HelpIndex shows:

private Thread TaskThread = null;
private void DoLookup()
{
	synchronized(this)
	{
		if( TaskThread!=null)
			TaskThread.stop();
		TaskThread = new Thread(this);
		TaskThread.start();
	}
}
public void run()
{
	LookupIndices(QueryField.getText());
	synchronized(this)
	{
		TaskThread = null;
	}
}

HelpIndex's keyUp() routine simply calls DoLookup(). If there is a search in progress, then it is stopped and a fresh one started. The actual search is done in run(), as the applet implements Runnable to do the thread's work.

Conclusion

There is lots to get right in a fully functional Java program. Both the language and its APIs are new.

When your applet is complete, there are various places where you can get it registered to make it easy for others to find. Apart from Gamelan and the Java Centre, JARS rates applets. HelpIndex got in the top 25% for October 1996.

Author

© 1996 Chris Cant, PHD Computer Consultants Ltd

Chris Cant runs PHD Computer Consultants Ltd. You can try HelpIndex at http://www.phdcc.com/helpindex/index.html.

PHD Home page.