Deprecated Methods in the 1.1 AWT

This document consists of three sections to help you deal with deprecated methods in the 1.1 AWT.

Overview
Introduces you to the wonderful world of deprecation, as it pertains to the AWT.
Overriding Deprecated Methods
Discusses how to override a method that has been deprecated without sacrificing backwards compatibility and without seeing unnecessary compilation warnings.
Table of AWT 1.1 Deprecated Methods
Lists AWT methods that have been deprecated and gives the recommended replacements.

Overview

The AWT changed significantly between the 1.0.2 and 1.1 releases. Certain old ways of doing things are deprecated -- no longer recommended -- and might not be supported in a future major release. To help you convert your programs well ahead of time, the Java compiler warns you whenever you compile a program that uses deprecated API.

For the curious: The AWT marks deprecated API using the @deprecated tag in documentation comments in the AWT source code. These tags were not present in the beta 1.1 releases.

When you use the 1.1 compiler to compile a class that calls deprecated API, you'll see a warning like the following:

% javac Test.java Note: Test.java uses a deprecated API. Recompile with "-deprecation" for details. 1 warning %

To see a list of everywhere your program uses deprecated API, use javac -deprecation. You might see many warnings. Don't panic! Your program will continue to work for a long time. However, you might want to make plans to convert it. And any new code you write should use the new API, if at all possible.

For complete information on how and why to convert your AWT programs, see How to Convert Programs to the 1.1 AWT API.

Note: As of 1.1.1, the Java compiler warns you whenever a program calls or overrides a deprecated method (with one exception described in the following section). The 1.1 compiler, on the other hand, only warned when deprecated methods were called -- not when they were overridden. For example, the 1.1 compiler wouldn't usually warn you if a program overrode the action method, since most implementations of action don't call the superclass's implementation.

Overriding Deprecated Methods

You might find yourself in the following situation:

You're writing 1.1-based code.
It can be called by 1.0 code.
You need to override a method that has been deprecated.

In this situation, you might wonder which version of the method you should override -- the deprecated method or its replacement. If you simply override the replacement, then your code won't work correctly with 1.0 code that calls it. (If no 1.0 code will call the method, then this solution is fine.) If you simply override the deprecated version, then you'll see compilation warnings and you'll have 1.0 dependencies embedded in your code.

The solution is to override both methods. Override the deprecated method so that it calls the replacement method, and override the replacement method to provide the appropriate functionality. In your implementation of the deprecated method, use the @deprecated documentation tag to indicate that you are intentionally overriding the method to provide backwards compatibility. For example:

/** @deprecated */ public Dimension preferredSize() { return getPreferredSize(); } public Dimension getPreferredSize() { ...//implementation goes here }

This solution takes advantage of a loophole: The compiler doesn't warn you when you override a deprecated method and you mark the overriding method as deprecated. For example, the preceding code results in no warnings when compiled. However, if code that calls the preceding code is compiled, a deprecation warning occurs.

The solution described in this section helps you write code that is backwards compatible, compiles cleanly, and is easy to understand. When you no longer have to provide 1.0 compatibility, it'll be easy to find and remove the deprecated code.

Table of AWT 1.1 Deprecated Methods

This section lists all the deprecated AWT methods and their 1.1 replacements. A script named updateAWT can make the simplest replacements for you. See How to Convert Programs to the 1.1 AWT API for instructions and examples of using the script.

A table similar to this one is in Simple Name Changes. That table contains a bit less information than this one, and it's alphabetized by the 1.1 column to help you easily undo incorrect changes that the script has made.

In the following table, method names in bold font are the preferred method names. Some of the valid 1.1 substitutes for event-handling methods are less preferable than other 1.1 solutions. For example, although gotFocus can be replaced by processFocusEvent, we'd rather you replaced it with focusGained implemented in a FocusListener, as described in How to Convert Event-Handling Code.

Deprecated Method	Class Where Deprecated	1.1 Replacement
`action`	`Component`	See How to Convert Event-Handling Code for examples of handling action events.
`allowsMultipleSelections`	`List`	`isMultipleMode`
`appendText`	`TextArea`	`append`
`bounds`	`Component`	`getBounds`
`clear`	`List`	`removeAll`
`countComponents`	`Container`	`getComponentCount`
`countItems`	`Choice, List, Menu`	`getItemCount`
`countMenus`	`MenuBar`	`getMenuCount`
`deliverEvent`	`Component, Container`	`dispatchEvent`
`disable()`	`MenuItem`	`setEnabled(false)`
`enable()`	`Component, MenuItem`	`setEnabled(true)`
`enable(expression)`	`Component`	`setEnabled(expression)`
`getBoundingBox`	`Polygon`	`getBounds`
`getClipRect`	`Graphics`	`getClipBounds`
`getCurrent`	`CheckboxGroup`	`getSelectedCheckbox`
`getCursorType`	`Frame`	`getCursor` method in `Component`
`getLineIncrement`	`Scrollbar`	`getUnitIncrement`
`getPageIncrement`	`Scrollbar`	`getBlockIncrement`
`getPeer`	`Component`	No replacement.
`getVisible`	`Scrollbar`	`getVisibleAmount`
`gotFocus`	`Component`	`processFocusEvent` See How to Convert Event-Handling Code for information on preferred ways to handle events.
`handleEvent`	`Component`	`processEvent` See How to Convert Event-Handling Code for information on preferred ways to handle events.
`hide`	`Component`	`setVisible(false)`
`insertText`	`TextArea`	`insert`
`insets`	`Container`	`getInsets`
`inside`	`Component, Polygon, Rectangle`	`contains`
`isSelected`	`List`	`isIndexSelected`
`keyDown`	`Component`	`processKeyEvent` See How to Convert Event-Handling Code.
`keyUp`	`Component`	`processKeyEvent` See How to Convert Event-Handling Code.
`layout`	`Component, Container, ScrollPane`	`doLayout`
`locate`	`Component, Container`	`getComponentAt`
`location`	`Component`	`getLocation`
`lostFocus`	`Component`	`processFocusEvent` See How to Convert Event-Handling Code.
`minimumSize`	`Component, Container, TextArea, TextField`	`getMinimumSize`
`mouseDown`	`Component`	`processMouseEvent` See How to Convert Event-Handling Code.
`mouseDrag`	`Component`	`processMouseMotionEvent` See How to Convert Event-Handling Code.
`mouseEnter`	`Component`	`processMouseEvent` See How to Convert Event-Handling Code.
`mouseExit`	`Component`	`processMouseEvent` See How to Convert Event-Handling Code.
`mouseMove`	`Component`	`processMouseMotionEvent` See How to Convert Event-Handling Code.
`mouseUp`	`Component`	`processMouseEvent` See How to Convert Event-Handling Code.
`move`	`Component, Rectangle`	`setLocation`
`nextFocus`	`Component, Container, Window`	`transferFocus`
`postEvent`	`Component, Window`	`dispatchEvent`
`preferredSize`	`Component, Container, TextArea, TextField`	`getPreferredSize`
`replaceText`	`TextArea`	`replaceRange`
`reshape`	`Component, Rectangle`	`setBounds`
`resize`	`Component, Rectangle`	`setSize`
`setCurrent`	`CheckboxGroup`	`setSelectedCheckbox`
`setCursor`	`Frame`	`setCursor` method in `Component`
`setEchoCharacter`	`TextField`	`setEchoChar`
`setLineIncrement`	`Scrollbar`	`setUnitIncrement`
`setMultipleSelections`	`List`	`setMultipleMode`
`setPageIncrement`	`Scrollbar`	`setBlockIncrement`
`show()`	`Component`	`setVisible(true)`
`show(expression)`	`Component`	`setVisible(expression)`
`size`	`Component`	`getSize`

Back to "How to Convert..."

By Kathy Walrath