When does Java Collections throw a NullPointerException while using Collections.addAll()

Question

Under what condition does the Collections.addAll() method throw a NullPointerException? The official docs mention:

NullPointerException - if the specified collection contains a null element and this collection does not permit null elements, or if the specified collection is null

How do I make sure that this "Collection does not permit null elements"

public class CollectionImpl {

public void checkList(){

    List<String> var1 = new ArrayList<String>();
     var1.add("One");
     var1.add("Two");
     var1.add("Three");

     System.out.println("var1 : " + var1);

     try{
         if(Collections.addAll(var1,"Four" , "Five" , null , "1")){
            System.out.println("True"); 
         }
     }
     catch(NullPointerException e){
         System.out.println("Caught Null Pointer Exception" + e);
     }
     catch(IllegalArgumentException e){
         System.out.println("Caught IllegalArgument Exception" + e);
     }
     finally{
         System.out.println("var1 : " + var1);
     }
}

OUTPUT

var1 : [1, 2, null]
True
var1 : [1, 2, null, 4, 5, null, 6]

Answer 1

When does Java Collections throw a NullPointerException while using Collections.addAll()

The Collections.addAll documentation tells us:

NullPointerException - if elements contains one or more null values and c does not permit null elements, or if c or elements are null

Answering your second question:

How do I make sure that this "Collection does not permit null elements"

By referring to the documentation for the class you're using. In this case (ArrayList), it's the second sentence:

Implements all optional list operations, and permits all elements, including null.

(My emphasis.)

If you don't know what class you're dealing with (you just receive a List from other code and don't/can't know what kind of list it may be), you need to document in the method accepting it whether it needs to support null (since List doesn't have something that tells you; other than trying to add one and catching the exception if it doesn't).

Answer 2

Whether a collection supports null elements is a property of the collection implementation itself. It's not a setting that can be changed on a particular instance of a collection. As others have mentioned, whether a collection permits null should always be documented in the class's specification.

Your example uses ArrayList, which permits null elements, so calling addAll() with null values will always successfully add them to the list.

An example of a Collection that doesn't permit null values is ArrayDeque. If you change your declaration of var1 as follows:

Collection<String> var1 = new ArrayDeque<String>();

then you'll get a NullPointerException thrown from the call to addAll().