Iterable: may iterator() returns null in case there is nothing to iterate over?

Question

An object implementing Iterable interface must have a method with this signature:

Iterator<T> iterator()

o being an Iterable, is this code safe?

while(o.iterator().hasNext()) { ... }

In other terms, may iterator() returns null in case there is nothing to iterate over?

EDIT:

1- As some of you point out, the iterator returned is different each time o.iterator() is executed. Fair enough! I must agree that I had forgotten this point when writing the question.

Let's say this line is rewritten:

Iterator<String> it = o.iterator();
....
....
while(it.hasNext() {...}

2- As some of you point out, this is bad programming practice to return null when the documentation for Iterable.iterator() says: "Returns an iterator over a set of elements of type T."

However my question is about whether returning null is prevented directly or indirectly by some 'contract' in the Java API documentation. To me "Returns an iterator over a set of elements of type T" doesn't prevent returning null. I may be wrong.

Conclusion from your answers and additional research

Overall: Java API has no mean to say if the iterator value may be null or not, unless by stating it explicitly in the documentation. In this case, nothing is stated, however good sense allows to think that a null iterator value will never be returned from Java API methods. This may be different for API written by individuals.

• Nothing in the documentation prevents the returned value to be null (e.g. @NotNull)
• In the Javadoc, many @Return are explicit when null is also to be anticipated
• This question is about null return values in general, interesting.
• I've found an attempt for a language to describe APIs, though it for .NET

Answer 1

may iterator() returns null in case there is nothing to iterate over?

null may be returned (there are no tools in Java to prevent you from doing that) but it never should be. Instead return Iterator which hasNext() method returns false.

You need to know that purpose of Iterable objects is to be used with for-each loop

for (Type item : IterableInstance){
    //handle 'item'
    System.out.println(item);
}

which is translated to something like

for(Iterator<Type> i = someList.iterator(); i.hasNext(); ) {
    Type item = i.next();

    //handle 'item'
    System.out.println(item);
}

So if iterator() returns null you will get NullPointerException at i.hasNext() (since i would hold null). To avoid NPE you need proper iterator instance which for hasNext() will return false (if there are no elements to iterate). This will prevent loop iterations.

---

Aside form that there is other problem in your code

while(o.iterator().hasNext()) { ... }

What you are doing here is that each time condition is checked new iterator is created because you are calling o.iterator() which will start to iterate from first element. In other words you are checking each time if first element exists, which can cause infinite loop if o is not empty.

What you need is

Iterator<SomeType> it = o.iterator();
while(it.hasNext()) { ... }

Answer 2

In other terms, may iterator() returns null in case there is nothing to iterate over?

No. A correct implementation of the Iterable interface will never return null from its iterator() method. It will return a non-null Iterator whose hasNext() method immediately returns false.

However:

is this code safe?

Sure, but it doesn't do what you think it does, because the contract of iterator() is to return a different iterator every time iterator() is called.