Deprecated Methods in the 1.1 AWT - JDK 5 Documentation v1.1.8, Java 2 SDK 英文文档

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

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