One of the best parts of writing frameworks around Java’s Swing GUI toolkit is how often components don’t actually follow the component contract.
For example, JComponent defines a FocusListener which predictably enough fires an event when a component receives and loses focus. Yet, many components in Swing and its ecosystem (e.g., JComboBox) simply fail to fire a focus event. Why? Because they are composite components (i.e., they are comprised of several components mashed up together) and they expect you to get some of the internal components and register the FocusListener on one of them. Mind, this is rarely documented, adding to the fun.
No no no no! I wish Swing’s team published some kind of “requirements to be a component” document or “best practices” document that did away with this foolishness. Writing a framework that treats components generically is next to impossible (i.e., requires a special adapter layer that makes all components obey some kind of contract) thanks to all of this–to say nothing of the poor newbie.