When should I accept a parameter of Iterable<T> vs. Collection<T> in Java?
JavaCollectionsJava Problem Overview
What are the considerations of using Iterable<T>
vs. Collection<T>
in Java?
For example, consider implementing a type that is primarily concerned with containing a collection of Foo
s, and some associated metadata. The constructor of this type allows one-time initialisation of the object list. (The metadata can be set later.) What type should this constructor accept? Iterable<Foo>
, or Collection<Foo>
?
What are the considerations for this decision?
Following the pattern set forth by library types such as ArrayList
(which can be initialised from any Collection
, but not an Iterable
) would lead me to use Collection<Foo>
.
But why not accept Iterable<Foo>
, given that this is is sufficient for the initialisation needs? Why demand a higher level of functionality (Collection
) from the consumer, than what is strictly necessary (Iterable
)?
Java Solutions
Solution 1 - Java
Many of the collection types existed before Iterable<T>
(which was only introduced in 1.5) - there was little reason to add a constructor to accept Iterable<T>
as well as Collection<T>
but changing the existing constructor would have been a breaking change.
Personally I would use Iterable<T>
if that allows you to do everything you want it to. It's more flexible for callers, and in particular it lets you do relatively easy filtering/projection/etc using the Google Java Collections (and no doubt similar libraries).
Solution 2 - Java
An Iterable
produces Iterator
objects. An Iterator
object, by definition, iterates. Notice, that the Iterator
interface makes no promise as to how many times next()
can be called before hasNext()
returns false
. An Iterator
could possibly iterate over Integer.MAX_VALUE + 1
values before its hasNext()
method returns false
.
However, a Collection
is a special form of Iterable
. Because a Collection
cannot have more than Integer.MAX_VALUE
elements (by virtue of the size()
method), it is naturally presumed that its Iterator
objects will not iterate over this many elements.
Therefore, by accepting a Collection
rather than an Iterable
, your class can have some guarantee over how many elements are being passed in. This is especially desirable if your class is itself a Collection
.
Just my two cents...
Solution 3 - Java
Users of Spring Data JPA
will find that the Repositories
return collections of type Iterable<T>.
On projects I've worked on in the past that use Spring
, I've found that the need to operate on a Collection after retrieval has often dictated that Iterable<T>
is used in the business layer rather than Collection<T>
in order to select an Object T
from the collection.
All Collections are Iterable
(that is the interfaces which extend the Collection
interface, so not Map
!), so using Iterable
in the business layer is merely a case of referring to a Collection by its super type and still allows the use of for-each
to iterate.
If you need to manipulate the contents of a collection, a convenience method would allow you to populate a new Collection
, so you can make use of contains()
, remove()
, etc with the original collection data.
Alternatively, convenience methods are provided for this purpose by popular third party APIs such as Google Guava and Apache Commons.
Solution 4 - Java
Use the most general interface that you can. Since all you're going to do is iterate, then I would say Iterable
is the way to go (since it allows lazy iterators, etc.). You don't care where the iterator is coming from, so don't restrict it more than you have to.
Solution 5 - Java
Some constructors, e.g. ArrayList(Collection c), use the toArray() method of Collection for efficiency.
Solution 6 - Java
See "Why so much emphasis on Iterators and Iterables?" on the Google Collection FAQ for a decent argument for preferring Iterators, especially when dealing with a lot of data. One analogy that might help is to think the difference between forward-only read-only cursors and scrollable cursors.
Solution 7 - Java
If you go for Collection, then your class can be initialised from a collection only, if you go for Iterable, then you can initialise from either collection or iterable.
As the effort and performance for both is going to be the same, it makes total sense to accept Iterable in the constructor.
Solution 8 - Java
According to the principle of least surprise, you should emulate the Java collection pattern and take a Collection constructor arg. It will make the people who come after you slightly less puzzled.
Solution 9 - Java
You're correct, as it's considered good practice to ask for the most general form of what you need.