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:[EMAIL PROTECTED]
Sent: Mon 8/15/2005 9:01 PM
To: Konstantin Komissarchik
Cc: [EMAIL PROTECTED]; 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: [EMAIL PROTECTED]
String})
* @return a table of ages keyed by name (key type: [EMAIL PROTECTED]
String}; value
type: [EMAIL PROTECTED] 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" <[EMAIL PROTECTED]>
08/15/2005 08:35 PM
To
Jim des Rivieres/Ottawa/[EMAIL PROTECTED]
cc
"Ted Bashor" <[EMAIL PROTECTED]>, <[EMAIL PROTECTED]>, Timothy
Deboer/Toronto/[EMAIL PROTECTED], "Thomas Yip" <[EMAIL PROTECTED]>
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
_______________________________________________
wtp-dev mailing list
[email protected]
https://dev.eclipse.org/mailman/listinfo/wtp-dev
