[wtp-dev] FW: Arrays vs. Collections in new API

["Ted Bashor" <tbashor@xxxxxxx>]

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