Patch: fix handling of AWT alias methods

[Thomas Fitzsimmons]

Hello,

This patch fixes the way we handle "alias" methods in the AWT, where a
public or protected method has been deprecated in favour of a new one
that has the same function but a different name.  Sun does this a fair
amount to fix cases where the original method's name did not follow
their naming conventions.

Unfortunately, this practise complicates class library code that calls
these aliased methods.  Library code must still call the deprecated
method so that old client code that overrides it continues to work.  But
library code must also call the new version, because new code is
expected to override the new method.

The correct way to handle this (and the way Sun does it) may seem
counterintuitive because it means that new code is less efficient than
old code: the new method must call the deprecated method, and throughout
the library code calls to the old method must be replaced with calls to
the new one.

Take the example of a newly-written container laying out a component and
wanting to know its preferred size.  The Component class has a
deprecated preferredSize method and a new method, getPreferredSize. 
Assume that the container is laying out an old component that overrides
preferredSize and a new component that overrides getPreferredSize.  If
the container calls getPreferredSize and the default implementation of
getPreferredSize calls preferredSize, then the old component will have
its preferredSize method called and new code will have its
getPreferredSize method called.

Even using this calling scheme, an old component may still be laid out
improperly if it implements a method, getPreferredSize, that has the
same signature as the new Component.getPreferredSize.  But that is a
general problem -- adding new public or protected methods to a
widely-used class that calls those methods internally is risky, because
existing client code may have already declared methods with the same
signature.

The solution may still seem counterintuitive -- why not have the
deprecated method call the new method, then have the library always call
the old method.  One problem with that, using the preferred size example
again, is that new containers, which will use the non-deprecated
getPreferredSize, will not get the preferred size of old components.

Jeroen Frijters provides a good explanation of the problem in his IKVM
web log [1].

Comments?

Tom

[1] GridBagLayout and more AWT, 
http://weblog.ikvm.net/commentview.aspx?guid=8B14C003-E16A-4E99-A52E-AD776CBB8CBF

2004-02-02  Thomas Fitzsimmons  <address@hidden>

        * gnu/java/awt/peer/gtk/GtkListPeer.java,
        java/awt/BorderLayout.java, java/awt/CardLayout.java,
        java/awt/CheckboxGroup.java, java/awt/Choice.java,
        java/awt/Component.java, java/awt/Container.java,
        java/awt/FontMetrics.java, java/awt/GridBagLayout.java,
        java/awt/LayoutManager2.java, java/awt/List.java,
        java/awt/Menu.java, java/awt/MenuBar.java,
        java/awt/MenuItem.java, java/awt/Polygon.java,
        java/awt/Rectangle.java, java/awt/ScrollPane.java,
        java/awt/Scrollbar.java, java/awt/TextArea.java,
        java/awt/TextField.java,
        java/awt/image/renderable/RenderContext.java,
        javax/swing/JApplet.java: Fix handling of alias methods, where a
        method has been deprecated in favour of a new one with the same
        funtion but a different name.  Put the method implementation in
        the deprecated method and have the new method call the
        deprecated one.  Make all other code call the new method.

fix-aliases.patch
Description: Text Data