Untyped Collections vs. Typed Arrays for public API

Question

hi,
I'm just courious about hearing any tips or advice from you ragarding how to design a public API of a program that uses collections (like collections of Date-objects for example). In a first thought I'd go and implement it using the Collection-Framework by defining public accessor methods that take in a Collection of the desired objects, as well as (for the getters) return some Collection (for example here a concrete TreeSet when data is returned sorted). So far so good, but then I always end up using downcasts to the object I expected (checked using "instanceof" to avoid ClassCastException's). As I'd like to make the public part of the API as robust as possible I don't like to force the users to read the methods' javadocs in full detail in order to know what dsired objects to put in the collection they pass in, or to what interface-types they can downcast when fetching objects from such a collection from an accessor method.
The other idea might be - to overcome this untyped API - to use arrays here (as they're typed and bound during compile-time), but in the Java Tutorial I read that array-based interfaces are mostly legacy things and should be avoided (by using collections) in new systems. Personally I like the Collection-Framework very much, since it offers a lot of things like sorting, easy iteration, etc. Generally speaking I like them as they feel more like objects than arrays do. But it also always feels like they're untyped by using downcasts everywhere, which are only checked at runtime (of course) so that it is a potentially hard to detect risk of error for the API users. Even when subclassing the Collections (i.e. implementing java.util.Collection in an own collection-like class) we gain no compile-type checks here, since we have to implement the methods accepting and returning java.lang.Object's. I understand that the idea of the Collection-Framework is to keep things very general, but when using this generality we loose type-checks at compile-time yielding towards loosing robustness.
There are several good books out there with general recommendations and tips about how to write good, nice, and robust code, including ideoms and coding-styles, but none of them (at least none of mine) has covered this. The essence of what I could get out of them is that code (especially a public API) should be robust and we should re-use the wheel (like the Collections-Framework in java.util), but what about the thing of "Untyped Collections vs. Typed Arrays" when comparing code-reuse and interoperability with other collecion-based APIs against the robustness of compile-time checks of data-types in arrays.
Suppose you were about to use some API, what kind of interface (and for what reason) would you like? Typed Arrays which are not so nice to handle/use, or Untyped Collections where you've always got to read the API's docs about what to put in and what to downcast to... I know that it's easy (using the static convenience methods of java.util.Collections and java.util.Arrays) to convert between both, but what would you natively prefer?
Thank you very much for your answers, and I really look forward to any thoughts on this, as I personally have not decided on this...
X-Post from "Java Collections Framework" forum since I think it does not only belong to Collection Framework details, as it is more a general API-design topic...

Answer 1

Typically speaking, I prefer the Collections API to using arrays as well, although the specific needs often dictate the best choice. When developing type safe collections, I would suggest one of two design options:
1) extend SDK Collection classes to become type safe. For example, extend ArrayList with DateList and then over-ride all the add methods so that a ClassCastException is thrown when the argument is not assignable to java.util.Date. This design has less development over-head, since you inherit the collection management logic from the super class, but the type checks are obviously completed at run time, not compile time
2) make your own class that implement the Collections API. Basically, I would create one abstract class that manages the collection logic, holding an array of Objects that can be resized and then have your subclasses provide type-specific add methods to that array. Here you gain compile-time type checks, but have a higher development over-head.