On Feb 3, 2008 2:59 PM, William Pietri <[EMAIL PROTECTED]> wrote:
> Because of this, returning a collection can mean one of four things:
>
> 1. I'm giving you my copy of the data; please don't change it ("return
> foo").
> 2. I'm giving you my copy of the data; you may change it ("return foo").
> 3. I'm giving you data that you can't change (E.g.: "return
> Collections.unmodifiableList(foo)").
> 4. I'm giving you your own copy of the data, which you can do with as
> you please ("return new ArrayList(foo)").
>
> Here we mean #2, but I think the much more common case is #1.
#1 is bad practice, given that #3 is available.
Since it's hard to say what we mean in code, and since we're doing something
> unusual, we should certainly document it.
>
#2 is not unusual, but you have to be careful about specifying under what
conditions it is safe to modify the returned data.
In this case, since Request is not thread-safe, the documentation should
include something about not sharing the request or the collection returned
by getCookies(). Ideally, we would be able to add annotations to the return
type so we could say:
@NotThreadSafe Series<Cookie> getCookies();
But that capability is waiting on JSR 308. :-(
--tim
