Java's BlockingQueue design question

Question

the method java.util.concurrent.BlockingQueue.add(E e)'s JavaDoc reads:

boolean add(E e)

Inserts the specified element into this queue if it is possible to do so immediately without violating capacity restrictions, returning true upon success and throwing an IllegalStateException if no space is currently available. When using a capacity-restricted queue, it is generally preferable to use offer.

My question is: will it ever return false? if not, why does this method return a boolean? It seems weird to me. What is the design decision behind this?

Thanks for your knowledge!
Manuel

Answer 1

It follows the contract of Collection.add(E e) (since BlockingQueue is a subtype of Collection):

If a collection refuses to add a particular element for any reason other than that it already contains the element, it must throw an exception (rather than returning false). This preserves the invariant that a collection always contains the specified element after this call returns.