ArrayBlockingQueue and add vs put vs capacity

Question

From Javadoc of ArrayBlockingQueue ArrayBlockingQueue:

add

public boolean add(E e)

Inserts the specified element at the tail of this queue if it is possible 
to do so immediately without exceeding the queue's capacity, returning true 
upon success and throwing an IllegalStateException if this queue is full.

I always interpretted this statement (the part if it is possible to do so immediattely) as follows:

If the queue has free capacity, then the insert will succeed. If there is no empty space then it will not succeed.

But my understanding was wrong here.

In a simple case that I decided to use an ArrayBlockingQueue for e.g. 20 elements (small queue) and having one thread doing:

queue.take()

the other thread did not add an element to the queue via the add method despite the queue was almost empty.

I verified it also via debugging.

Once I replaced the call of queue.add(element) to queue.put(element) the element was indeed added to the queue.

So what is so different in these to methods?

For what other reason (besides capacity) could the addition not happen?

---

UPDATE:

public class ConnectionListener implements Observer {

  public static BlockingQueue<ConnectionObject> queueConnections = new   ArrayBlockingQueue<ConnectionObject>(10);

  @Override
  public void update(Observable arg0, Object arg1) {
      ConnectionObject con = ((ConnectionObject)arg1);
      queueConnections.add(con);
  }

}  

ConnectionObject is just a holder for String values.

public class ConnectionObject {
  private String user;  
  private String ip;
   //etc  
}

And the consumer:

public class ConnectionTreeUpdater extends Thread {  
  @Override
  public void run() {
    while(true){  
    try {  
    final ConnectionObject con = ConnectionListener.queueConnections.take();

If I use add no exception is thrown but element does not get added to the queue.

Just a thought: perhaps since the consumer is "waiting" on the queue, if for some internal housekeeping the element can not be added it will not be added and no exception is thrown.Could that be the case.

Otherwise I can not understand why there is no exception and with put the code works.

Are put and add meant to be used differently?

Answer 1

It's quite simple really:

• if the queue is not full, both methods succeed;
• if the queue is full, add() fails with an exception whereas put() blocks.

I think the documentation is pretty clear on the above. If you don't agree, and would like a second opinion, you could examine the source code for ArrayBlockingQueue:

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

public boolean offer(E e) {
    if (e == null) throw new NullPointerException();
    final ReentrantLock lock = this.lock;
    lock.lock();
    try {
        if (count == items.length)
            return false;
        else {
            insert(e);
            return true;
        }
    } finally {
        lock.unlock();
    }
}

public void put(E e) throws InterruptedException {
    if (e == null) throw new NullPointerException();
    final E[] items = this.items;
    final ReentrantLock lock = this.lock;
    lock.lockInterruptibly();
    try {
        try {
            while (count == items.length)
                notFull.await();
        } catch (InterruptedException ie) {
            notFull.signal(); // propagate to non-interrupted thread
            throw ie;
        }
        insert(e);
    } finally {
        lock.unlock();
    }
}