[concurrency-interest] Javadoc for offer method in ConcurrentLinkedQueue

David Holmes dholmes@dltech.com.au
Fri, 12 Sep 2003 09:29:16 +1000


> Actually I'm looking at the current version.

Well now I'm really confused. The online docs give the following for
ConcurrentLinkedQueue.offer:

public boolean offer(E o)
  Adds the specified element to this queue.
Specified by:
  offer in interface Queue
Parameters:
  o - the element to add.
Returns:
  true (as per the general contract of Queue.offer).
Throws:
  NullPointerException - if the specified element is null

And this is what I referred to yesterday.

But my cvs copy does not contain this. Doug?

> 2. Btw: Why do some of the queues throw IllegalStateException (if
this
> queue is full) on add() when it can just return false?
>
> The contract of Collection.add says
>  Returns:
>    true if this collection changed as a result of the call
>
> So I can't see why we just can't indicate that a queue is full by
> returning false.

The contract for Collection.add also states:

"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."

Hence it cannot return false on full.

David Holmes