[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
[wtp-dev] FW: Arrays vs. Collections in new API
|
Jim des Rivieres wrote up this helpful response to an API question we had, and agreed to let me forward it to the list. Something to consider as we finalize api for 1.0.
-Ted
-----Original Message-----
From: Jim des Rivieres [mailto:Jim_des_Rivieres@xxxxxxxxxx]
Sent: Mon 8/15/2005 9:01 PM
To: Konstantin Komissarchik
Cc: cbridgha@xxxxxxxxxx; Ted Bashor; Timothy Deboer; Thomas Yip
Subject: Re: Arrays vs. Collections in new API
Hi Konstantin,
> Is there a plan for when Java 5.0 language constructs will be allowed
in Eclipse API?
The Eclipse 3.2 stream (HEAD) will continue compling with JDK 1.4 until
some time in the fall (date not set yet, but the JDT guys are shaking out
the last 1.5 bugs). At some point, we will start creating our builds using
the JDK 1.5 compiler and libraries. At this point committers will be able
to start using JDK 1.5 language features in the Eclipse code base,
including in the APIs.
> When that happens, what do you think the policy will be with regards to
Arrays vs. Collections? Will it be to stick with Arrays or will the new
API at that point be allowed to use parameterized Collections?
In 3.0 and 3.1, we already have parts of the API that are using untyped
Collections. So we're not entirely uniform. In general, collections offer
more flexibility in most regards. At the API boundary, the ability to
return an unmodifiable collection is very useful, and has no array
analogy. The only advantages that arrays have of Collections are strong
typing and lower memory requirements. Strongly typed collections in 1.5
makes collections more attractive.
> If in the future APIs will be allowed to use parameterized Collections,
does it make sense to start using Collections right now.
Yes. Given that you have a choice, I would generally start using
Collections. If the API is intended to be used in close conjuction with
some existing array-based APIs in another component, I would carefully
consider what will make it easier for clients. Converting back and forth
between arrays and collections is overhead, and being a slave to
consistency should not override common sense.
To document the essential element type info and to ease later migration, I
suggest using the same boilerplate used in the Eclipse API wherever
Collections and Maps are involved. e.g.
* @param names a list of names (element type: {@link String})
* @return a table of ages keyed by name (key type: {@link String}; value
type: {@link Integer})
*/
public Map dbNameLookup(List names)
That way the @param and @return tags carry enough info to infer that the
signature should really be:
public Map<String,Integer> dbNameLookup(List<String> names)
Since it is so easy to modify collections, the specs should be explicit as
to who is allowed to modify the collection. For instance, if I pass in a
List as a parameter, is the callee allowed to change it? (usually no, but
yes in some cases); is the caller allowed to modify the list after the
call has returned? is the caller allowed to modify the list in a separate
thread during the call? And analogous series of sharp questions can be
asked of any collection returned from an API method. There are lots of
opportunities for clients to misunderstand the specs, so it's wise to make
the specs exceedingly clear on these matters, and to make the
implementation enforce these rules as rigorously as possible so that
clients will quickly discover when they step out of bounds (whether
accidentally or intentionally).
> Collections can be later changed to use parameterized Collections
without breaking binary compatibility.
The 1.5 Collection library is indeed proof that it is possible in some
cases to change plain Collections into parameterized ones while preserving
binary compatibility. Bear in mind that the Collections library was
designed by John Bloch, and he was also in on the JDK 1.5 generics from
way back. So he knew back then how to design the Collction classes so that
they could later be parameterized. I'm not sure anyone else could have
pulled this feat off. On my list of things to do is to update Evolving
Java-based APIs (
http://www.eclipse.org/eclipse/development/java-api-evolution.html ) to
describe under what circumstances a type or method can be parameterized
after the fact without breaking binary compatibility. I haven't delved
into it yet, so I don't know what the "gotchas" and ugly surprises are.
Regards,
jim
"Konstantin Komissarchik" <kosta@xxxxxxx>
08/15/2005 08:35 PM
To
Jim des Rivieres/Ottawa/IBM@IBMCA
cc
"Ted Bashor" <tbashor@xxxxxxx>, <cbridgha@xxxxxxxxxx>, Timothy
Deboer/Toronto/IBM@IBMCA, "Thomas Yip" <tyip@xxxxxxx>
Subject
Arrays vs. Collections in new API
Jim,
A question came up at WTP with regards to Arrays vs. Collections. Is there
a plan for when Java 5.0 language constructs will be allowed in Eclipse
API? When that happens, what do you think the policy will be with regards
to Arrays vs. Collections? Will it be to stick with Arrays or will the new
API at that point be allowed to use parameterized Collections? If in the
future APIs will be allowed to use parameterized Collections, does it make
sense to start using Collections right now. API that uses un-parameterized
Collections can be later changed to use parameterized Collections without
breaking binary compatibility. The same is obviously not true about
converting from Arrays to Collections. We wanted to run this by you since
until API is frozen for the 1.0 release WTP is still in a good position to
go one way or the other on this. What are your thoughts?
- Konstantin