Enumeration or Array as return type

[Stephen Suen]

Hi, all,

When a method need return an object list as result, I notice that two implementations exist in JDK. Some take java.util.Enumeration as return type (java.sql.DriverManager.getDrivers), and some take arrays (java.awt.Container.getComponents) instead. Of cource, other choices also there, for example, java.util.Iterator, etc. But, here, my question is on Enumeration and array: I wonder whether there's any resonable consideration when determining which is the appropriate return type?

Any advice will be appreciated.

Stephen Suen

[Dirk Schreckmann]

Moving this to the Intermediate forum...

[Ernest Friedman-Hill]

There are a number of considerations:

-- If you return an array, the user may modify it and corrupt your internal state; thus it's prudent to return a copy -- but this can be expensive computationally and for large arrays may take up too much space.

-- If you return an array, the array has to be exactly the right size. Many times your internal data structure will be an array plus a count of real items in the array (with zeros or nulls at the end). If you return an array, it had better be exactly the right size, as you can't return a count as well.

-- If you return an array, you have to have computed everything in advance to fill the array. The neat thing about an Iterator (don't use Enumeration in new code, use Iterator instead) is that it can compute each item it returns on the fly -- therefore if the user only wants the first three items out of 100, only the first three will be computed.

There are other reasons, but I hope I've shown you why, in general, returning an Iterator is better.

[Ilja Preuss]

I often prefer to return Arrays, simply because it communicates better the type of the objects in the collection. Of course this will change with Tiger's generics - then I would prefer iterators because they provide better decoupling.

[Stephen Suen]

Originally posted by Ilja Preuss:
I often prefer to return Arrays, simply because it communicates better the type of the objects in the collection. Of course this will change with Tiger's generics - then I would prefer iterators because they provide better decoupling.

Thanks for your advice, and can you give me more information about "change with Tiger's generics"?

Stephen Suen

[Stephen Suen]

Hi, Ernest Friedman-Hill,

Thanks for your reply.

I'm confused by some implementations in JDK. For example, java.util.logging.Logger.getHandlers, it returns an array instead of Iterator or Enumeration. The package is since 1.4, so, it's absolutely new code. Based on my limited experience and understanding, I would take Enumeration (not Iterator, because of synchronizing consideration). So, you know, I'm really interested why Sun chose array instead of Enumeration. Is it possible that it's just a personal favor? Otherwise, what's the serious consideration?

Thanks for any advice.

Stephen Suen

[Jim Yingst]

Ilja correctly identifies the one good reason why returning an array is sometimes preferable to returning an Iterator/Enumeration/Collection type, prior to JDK 1.5. I don't always prefer to use an array, because the reasons given by Ernest are also good. But I think that documenting and enforcing the type of the returned objects is a very good thing, and for me it often outweighs the concerns Ernet lists. Under JDK 1.5, we can instead return a List<Foo>, which means a List of objects of type Foo. Which has all the advantages cited by both Ilja and Ernest.

Note also that, unlike Ernest, I would never advocate returning an Iterator or Enumeration - only a Collection (or List or Set or other subinterface). There are many useful existing Java classes that make use of Collections but not Iterators: e.g. the methods of the Collections class, and many of the constructors of Collection implementations. So if you have a listlike thingy in Collection form, you can use it right away. And if you need an Iterator instead, you can get one instantly with a single call to iterator(). Conversely, if you have an Iterator and you need a Collection, you need three or more lines of code:

List list = new ArrayList();
while (iter.hasNext())
    list.add(iter.next());

Yuck. Collections are more convenient to work with, IMO.

Most importantly now: if you want to use the new foreach syntax from JDK 1.5, you can't use an Iterator - but you can use any Collection:

for (Foo f : list)
    doSomethingWith(f);

That's because Iterator (believe it or not) does not implement the Iterable interface. Strange, but true. Perhaps it's an oversight. Or perhaps they wanted to discourage poor misguided programmers from returning Iterators.
[ July 09, 2004: Message edited by: Jim Yingst ]

[Peter den Haan]

You might want to return an Iterator instead of a Collection (or array) if you want to process things in streaming mode. For example, the amount of data returned by the Iterator may be larger than you can afford to keep in memory. A Collection is not viable in such a case. Sometimes, if the data being processed is being streamed in from the network or a file, processing it on the fly may reduce the time to first response; when displaying all 10,000 results from a database query in a JTable, users will not appreciate having to wait until you've stuffed them all in a Collection

- Peter

[Ernest Friedman-Hill]

Originally posted by Peter den Haan:
You might want to return an Iterator instead of a Collection (or array) if you want to process things in streaming mode.

Indeed, this is the third bullet in my original post.

[Jim Yingst]

A Collection is not viable in such a case.

Depends if you're willing to throw an UnsupportedOperationException for methods which aren't marked as optional (e.g. contains() and size()). Or if the elements are all Serializable we could make a file-backed implementation of Collection which allows us to support all the Collection operations we might want to, though maybe not as efficiently as iteration is supported. It is true that this would be more work than returning an Iterator, and may be more confusing to people who don't carefully read the javadoc that we would of course thoughtfully provide. I'm tempted to make some reusable classes to alleviate the work for this.

So OK, I shouldn't say I'd never return an Iterator - but I haven't yet.

I suppose under 1.5 the best solution would be to return an Iterable rather than an Iterator. Well, aside from confusing people who don't know about Iterable yet - but they've got to learn eventually.
[ July 09, 2004: Message edited by: Jim Yingst ]

[Jim Yingst]

Thought some more about this. I guess in cases where you don't want to have everything in memory, there's no real use for the Collections methods and constructors I cited previously. So pre-1.5, returning an Iterator seems best if (and only if) you want to enforce iteration as the only way to access elements. As of 1.5, returning Iterable is preferable. IMO of course. Does that make sense?

[Helen Thomas]

A survey showing how many sites are using 1.5 would be very useful. I guess not many as it's still in beta Tiger Children's Survey
[ July 09, 2004: Message edited by: Helen Thomas ]