[concurrency-interest] LinkedBlockingQueue does not throwClassCastException

David Holmes dcholmes at optusnet.com.au
Tue Apr 17 05:18:18 EDT 2007

My apologies, seems someone has (perhaps unintentionally) changed the
specification, as I was looking at the Java 5 documentation:


where ClassCastException (and IllegalArgumentException) are not redeclared
to be thrown.

Given the use of generics, it is not unreasonable to infer that trying to
add anything other than an E will indeed cause ClassCastException to be

Arguably the Java 6 documentation is more correct, as until offer() et al
are defined you don't know whether or not the exceptions will be thrown. But
overall I have to say this is a bit of a mess. The base class is trying to
allow for a range of conditions that a subclass might impose and so
documenting the possible/potential exceptions, but the subclasses are
leaving open the possibility for their own subclasses to strengthen the
conditions, and so still declare exceptions that they themselves will never

There's really no way to fix this - the existing specifications will never
be changed - even though is a documentation issue more than anything, as
none of the exceptions involved are (or could be) checked exceptions.

David Holmes

> -----Original Message-----
> From: Szabolcs Ferenczi [mailto:szabolcs.ferenczi at gmail.com]
> Sent: Tuesday, 17 April 2007 6:23 PM
> To: dholmes at ieee.org
> Cc: Concurrency-interest at cs.oswego.edu
> Subject: Re: [concurrency-interest] LinkedBlockingQueue does not
> throwClassCastException
> On 17/04/07, David Holmes <dcholmes at optusnet.com.au> wrote:
> > If you check the documentation ...
> That is what I did.
> > ... you will see that LinkedBlockingQueue.add is
> > inherited from AbstractQueue.add, and the latter does *not* throw
> > ClassCastException.
> On the contrary to what you claim, this is what I found:
> http://java.sun.com/javase/6/docs/api/java/util/AbstractQueue.html#add(E)
> add
> public 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.
>     This implementation returns true if offer succeeds, else throws an
> IllegalStateException.
>     Specified by:
>         add in interface Collection<E>
>     Specified by:
>         add in interface Queue<E>
>     Overrides:
>         add in class AbstractCollection<E>
>     Parameters:
>         e - the element to add
>     Returns:
>         true (as specified by Collection.add(E))
>     Throws:
>         IllegalStateException - if the element cannot be added at this
> time due to capacity restrictions
>         ClassCastException - if the class of the specified element
> prevents it from being added to this queue
>         NullPointerException - if the specified element is null and
> this queue does not permit null elements
>         IllegalArgumentException - if some property of this element
> prevents it from being added to this queue
> End of doc
> Now, what I can see from the above document is that the inherited
> method can throw four types of exceptions and among them is the
> ClassCastException. Why do you claim that `AbstractQueue.add, and the
> latter does *not* throw
> ClassCastException'? Is is not the right documentation? If this is the
> correct documentation, how can one reproduce a ClassCastException?
> That was all I wanted to know all along.
> Besides, I would be interested in creating an
> IllegalArgumentException as well.
> Best Regards,
> Szabolcs

More information about the Concurrency-interest mailing list