One of the new features of Java 5.0 is the StringBuilder class, which is just like StringBuffer, but without synchronized methods.
Since StringBuilder and StringBuffer have so much in common, they both extend the same superclass: AbstractStringBuilder. You wouldn't know this from looking at the javadocs, however: they indicate that both classes extend Object.
Turns out that AbstractStringBuilder is not a public class, so in order to find out about it, you have to look at the source code (or the class files).
This is the first instance that I am aware of of a public class extending a non-public one, and it raises questions about documenting the public one. The javadoc team dealt with it by simply pretending that the non-public intermediary class does not exist. Now I have to figure out how to document this for Java in a Nutshell.
It seems to me that this was a real missed opportunity. If AbstractSt ringBuilder had been public we could write methods that would work with either a StringBuffer or a StringBuilder argument.
Update: AbstractStringBuilder and its subclasses demonstrate another new feature of Java 5.0: covariant returns. This is the ability to narrow the return type of a method when you override it in a subclass. It got added to the language along with generics. Many of the abstract methods in AbstractStringBuilder return an AbstractStringBuilder. When StringBuilder overrides those methods, it narrows the return type to StringBuilder. When StringBuffer overrides those methods it narrows the return type to StringBuffer. The compiler emits synthetic methods to make this work under the covers.
