Java 7 API design best practice - return Array or return Collection

Question

I know this question has be asked before generic comes out. Array does win out a bit given Array enforces the return type, it's more type-safe.

But now, with latest JDK 7, every time when I design this type of APIs:

public String[] getElements(String type)
vs
public List<String> getElements(String type)

I am always struggling to think of some good reasons to return A Collection over An Array or another way around. What's the best practice when it comes to the case of choosing String[] or List as the API's return type? Or it's courses for horses.

I don't have a special case in my mind, I am more looking for a generic pros/cons comparison.

Answer 1

If you are writing a public API, then your clients will usually prefer collections because they are easier to manipulate and integrate with the rest of the codebase. On the other hand, if you expect your public API to be used in a highly performance-sensitive context, the raw array is preferred.

If you are writing this for your own use, it would be a best practice to start out with a collection type and only switch to an array if there is a definite performance issue involving it.

An array's element type can be determined at runtime through reflection, so if that particular feature is important to you, that would be another case to prefer an array.