FileInputStream, FileOutputStream, and RandomAccessFile can have assocated FileChannel.

When close() is invoked on one of these classes, it in turn invokes close() on the associated channel (if any). But when the associated channel's close() method is invoked, it in turn invokes close() on the associated stream (if any).

As a result, these I/O stream close() methods invoke themselves re-entrantly when there is an associated channel.

This is not a problem for these classes because they are written to handle this (i.e., they are idempotent), but it can be surprising (or worse, just silently bug-inducing) for subclasses that override close().

The Javadoc mentions none of this. Instead, there should be some kind of note/warning for subclass implementors.