What is the difference between the add and offer methods in a Queue in Java?

Question

Take the PriorityQueue for example http://java.sun.com/j2se/1.5.0/docs/api/java/util/PriorityQueue.html#offer(E)

Can anyone give me an example of a Queu

Answer 1

The Queue interface specifies that add() will throw an IllegalStateException if no space is currently available (and otherwise return true) while offer() will return false if the element couldn't be inserted due to capacity restrictions.

The reason they are the same in a PriorityQueue is that this queue is specified to be unbounded, i.e. there are no capacity restrictions. In the case of no capacity restrictions, the contracts of add() and offer() display the same behaviour.

Answer 2

I guess the difference is in the contract, that when element can not be added to collection the add method throws an exception and offer doesn't.

From: http://java.sun.com/j2se/1.5.0/docs/api/java/util/Collection.html#add%28E%29

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.

From: http://java.sun.com/j2se/1.5.0/docs/api/java/util/Queue.html#offer%28E%29

Inserts the specified element into this queue, if possible. When using queues that may impose insertion restrictions (for example capacity bounds), method offer is generally preferable to method Collection.add(E), which can fail to insert an element only by throwing an exception.

Answer 3

from the source code in jdk 7 as follow:

public boolean add(E e) {
    if (offer(e))
        return true;
    else
        throw new IllegalStateException("Queue full");
}

we can easily know that the add function will return true when successfully add a new element into the queue, but throw a exception when failed .

Answer 4

I will write the java contract example code for offer method and add method showing how they differ.

BlockingQueue<String> queue = new ArrayBlockingQueue<>(2);
        queue.add("TestQuue1");     
        queue.add("TestQuue2"); 
        queue.add("TestQuue3");  // will throw "java.lang.IllegalStateException: Queue full

BlockingQueue<String> queue = new ArrayBlockingQueue<>(2);
        queue.offer("TestQuue1");       
        queue.offer("TestQuue2");   
        queue.offer("TestQuue3"); // will not throw any exception

Answer 5

The difference between offer and add is explained by these two excerpts from the javadocs:

From the Collection interface:

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.

From the Queue interface

When using queues that may impose insertion restrictions (for example capacity bounds), method offer is generally preferable to method Collection.add(E), which can fail to insert an element only by throwing an exception.

PriorityQueue is a Queue implementation that does not impose any insertion restrictions. Therefore the add and offer methods have the same semantics.

By contrast, ArrayBlockingQueue is an implementation in which offer and add behave differently, depending on how the queue was instantiated.

Answer 6

There is no difference for the implementation of PriorityQueue.add:

public boolean add(E e) {
    return offer(e);
}

---

For AbstractQueue there actually is a difference:

public boolean add(E e) {
    if (offer(e))
        return true;
    else
        throw new IllegalStateException("Queue full");
}