@Immutable annotation

[Louis Wasserman]

I notice that we're using the @Immutable annotation in a few places -- e.g. MediaType.

Should we be using it more broadly?  Would it be appropriate to use it on the immutable collections, since elements themselves may be mutable?

I'm not really deeply familiar with the use of @Immutable, but it seemed worth asking.

Louis Wasserman
wasserm...@gmail.com
http://profiles.google.com/wasserman.louis

[John Sirois]

On Sat, Apr 21, 2012 at 4:42 PM, Louis Wasserman <wasserm...@gmail.com> wrote:

I notice that we're using the @Immutable annotation in a few places -- e.g. MediaType.

Should we be using it more broadly?  Would it be appropriate to use it on the immutable collections, since elements themselves may be mutable?

The docs, although focused on the fields of a marked class do strongly imply recursive applicability must hold.  So it would seem - as given - that @Immutable is not appropriate for generic container types.

 

I'm not really deeply familiar with the use of @Immutable, but it seemed worth asking.

Louis Wasserman
wasserm...@gmail.com
http://profiles.google.com/wasserman.louis

--
guava-...@googlegroups.com
Project site: http://guava-libraries.googlecode.com
This group: http://groups.google.com/group/guava-discuss
 
This list is for general discussion.
To report an issue: http://code.google.com/p/guava-libraries/issues/entry
To get help: http://stackoverflow.com/questions/ask (use the tag "guava")

[Louis Wasserman]

Hmmmmmkay.  Granting that, there are a number of other immutable classes in Guava besides containers -- Joiner and Splitter for example -- that are immutable.

Where does the @Immutable annotation get used, out of curiosity?  Do FindBugs or any other common annotation processors make use of it somehow?

Louis Wasserman
wasserm...@gmail.com
http://profiles.google.com/wasserman.louis

[Kevin Bourrillion]

The answer is that it gets used on classes written by Greg Kick. :-)

--
Kevin Bourrillion @ Google

Java Core Libraries Team
http://guava-libraries.googlecode.com

[Tim Peierls]

On Sat, Apr 21, 2012 at 7:10 PM, Louis Wasserman <wasserm...@gmail.com> wrote:

Hmmmmmkay.  Granting that, there are a number of other immutable classes in Guava besides containers -- Joiner and Splitter for example -- that are immutable.

Those seem like good candidates for @Immutable.

It has been a while since we finalized those javadocs (for net.jcip.annotations.Immutable), and I was surprised to be reminded of how strong the @Immutable claim is. In retrospect, I think it might have been a mistake. I've been using Guava ImmutableXxx classes heavily, and at no point has the fact that they do not capture the stronger claim of @Immutable been an issue, to the point where I had essentially merged the two concepts in my own mind. (That could be a sign that I'm being sloppy or that the strong @Immutable claim isn't useful in practice. Or both.)

 

Where does the @Immutable annotation get used, out of curiosity?  Do FindBugs or any other common annotation processors make use of it somehow?

FindBugs does, but not in very interesting ways. 

--tim

[Tim Peierls]

On Sun, Apr 22, 2012 at 9:35 AM, Tim Peierls <t...@peierls.net> wrote:

and at no point has the fact that they do not capture the stronger claim of @Immutable 

... are not captured by the stronger claim ...

--tim 

[Kevin Bourrillion]

For me, the notion of annotating immutability will only become useful once we can also signify that a method returns an immutable object.

(And, I think shallow immutability should be enough.)

--

guava-...@googlegroups.com
Project site: http://guava-libraries.googlecode.com
This group: http://groups.google.com/group/guava-discuss
 
This list is for general discussion.
To report an issue: http://code.google.com/p/guava-libraries/issues/entry
To get help: http://stackoverflow.com/questions/ask (use the tag "guava")

[Graham Allan]

Hope you don't mind the discussion becoming further removed from Guava (this is for my curiosity more than anything else)...

On 22 April 2012 20:54, Kevin Bourrillion <kev...@google.com> wrote:

For me, the notion of annotating immutability will only become useful once we can also signify that a method returns an immutable object.

In what respect is that different from a method returning a type which is annotated with @Immutable? Do you mean, for example, when a method returns java.util.List, making the distinction where the actual concrete instance returned will be an immutable subclass?

Kind regards,

Graham

 

 

[Kevin Bourrillion]

On Mon, Apr 23, 2012 at 2:00 PM, Graham Allan <grundl...@gmail.com> wrote:

In what respect is that different from a method returning a type which is annotated with @Immutable? Do you mean, for example, when a method returns java.util.List, making the distinction where the actual concrete instance returned will be an immutable subclass?

Right, that kind of thing, although we of course try to just return ImmutableList when we can and thus avoid the problem.

[Tim Peierls]

I see that JSR 308 had a second EDR in January-February (4 years after the first!) so maybe there's hope for this.

--tim

[Emily Soldal]

I certainly hope so! @Immutable is also defined in JSR-305 AND JSR-107. I even filed an issue about this a while back because I wrote some dynamic tests for @Immutable contracts. 

http://code.google.com/p/jsr-305/  reference impl.

https://github.com/jsr107/jsr107spec  reference impl.

[Gregory Kick]

As you might guess, I'm +1 for adding @Immutable to classes that have that contract, since it is simple, consistent documentation of that behavior.  Joiner for instance mentions its immutability in the context of a warning, which IMO, is somewhat dubious.

I wouldn't expect anything else out of it other than the documentation.

The Immutable* collections could have it, but it's less clear that it is worthwhile since there is TONS of documentation about their behavior.  Plus, it's in the name.  We get it.  I would think that adding @Immutable there would just be for consistency rather than adding anything of value.

--
guava-...@googlegroups.com
Project site: http://guava-libraries.googlecode.com
This group: http://groups.google.com/group/guava-discuss
 
This list is for general discussion.
To report an issue: http://code.google.com/p/guava-libraries/issues/entry
To get help: http://stackoverflow.com/questions/ask (use the tag "guava")

--
Greg Kick
Java Core Libraries Team

[Emily Soldal]

I am a big fan of contractual annotations. My main issue was that the one provided by JSR-305 does not have a runtime retention policy, making it more of a sugar annotation that something you could check on. At any rate, I'm +1 too.

[Gregory Kick]

Oh, I don't think that you _should_ attempt to check them.  It's not actually a useful guarantee of anything (without some strong static analysis perhaps…).  They're documentation of an intention.  That's it.

[Torbjorn Gannholm]

+1 

[Raymond Rishty]

Emily, I think the point of the JSR-305 annotations' retention
policies is that by using them you can do the check at compile time
rather than having to wait until runtime. FindBugs makes use of these
so you can prove that your contract is held.
I always use the @Immutable annotation on my DTOs, but I haven't seen
FindBugs tell me anything more than it would tell me if I didn't
annotate it—it seems to want me to make my DTOs immutable whether
annotated or not.
Regardless, I'm +1 annotating in case better use of this is made in the future

[Louis Wasserman]

Just to be clear, can we have separate +1s for annotating the immutable collections, and annotating Joiner/Splitter/deeply immutable types?

I'm +1 on deeply immutable types, +0.5 on the immutable collections.

Louis Wasserman
wasserm...@gmail.com
http://profiles.google.com/wasserman.louis

[Raymond Rishty]

Have to be honest, I don't quite see the point of annotating methods
@Immutable. If the return type is already @Immutable, why does the
method need to reiterate it? The guarantee is already communicated.

[Colin Decker]

That would be for methods with return types that are not @Immutable.

-- 

Colin

[Louis Wasserman]

How many methods do we have that return immutable values without specifying an immutable return type?  I can't think of any, off the top of my head.

Louis Wasserman
wasserm...@gmail.com
http://profiles.google.com/wasserman.louis

[Benjamin Manes]

+1 for deeply immutable types only. A shallow immutable type could be more confusing for documenting purposes, since I'd expect to be able to use CAS operations without risk of other modifications / side-effects / visibility issues.

[Louis Wasserman]

To be fair, the immutable collections are deeply immutable if their element type is?  That said, I'm inclined to take Ben's word for it that it'd be a bad idea to annotate e.g. ImmutableList as @Immutable.

Louis Wasserman
wasserm...@gmail.com
http://profiles.google.com/wasserman.louis

[Benjamin Manes]

Effectively immutable objects where mutations can't be performed by others would also be okay imho. An example is java.lang.String, which has a benign race condition on the hash code.

[morten hattesen]

Methods that are declared to return j.u.Collection/j.u.List, but is
documented to return "... an immutable list/collection ..." would
benefit from communicating that fact using a @Immutable annotation.

> How many methods do we have that return immutable values without specifying
> an immutable return type?  I can't think of any, off the top of my head.

One example: Collections2.permutations() - see
http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/collect/Collections2.html#permutations(java.util.Collection)
Excerpt from JavaDoc:
Returns:
an immutable Collection containing all the different permutations
of the original collection.


On Apr 23, 10:04 pm, Louis Wasserman <wasserman.lo...@gmail.com>
wrote:

> How many methods do we have that return immutable values without specifying
> an immutable return type?  I can't think of any, off the top of my head.
>
> Louis Wasserman

> wasserman.lo...@gmail.comhttp://profiles.google.com/wasserman.louis

>
>
>
>
>
>
>
> On Mon, Apr 23, 2012 at 3:03 PM, Colin Decker <cgdec...@gmail.com> wrote:
> > That would be for methods with return types that are not @Immutable.
>
> > --
> > Colin
>

> > On Mon, Apr 23, 2012 at 3:58 PM, Raymond Rishty <raymond.ris...@gmail.com>wrote:
>
> >> Have to be honest, I don't quite see the point of annotating methods
> >> @Immutable. If the return type is already @Immutable, why does the
> >> method need to reiterate it? The guarantee is already communicated.
>
> >> On Sun, Apr 22, 2012 at 3:54 PM, Kevin Bourrillion <kev...@google.com>
> >> wrote:
> >> > For me, the notion of annotating immutability will only become useful
> >> once
> >> > we can also signify that a method returns an immutable object.
>
> >> > (And, I think shallow immutability should be enough.)
>
> >> > On Sun, Apr 22, 2012 at 3:37 PM, Tim Peierls <t...@peierls.net> wrote:
>
> >> >> On Sun, Apr 22, 2012 at 9:35 AM, Tim Peierls <t...@peierls.net> wrote:
>
> >> >>> and at no point has the fact that they do not capture the stronger
> >> claim
> >> >>> of @Immutable
>
> >> >> ... are not captured by the stronger claim ...
>
> >> >> --tim
>
> >> >> --
> >> >> guava-...@googlegroups.com
> >> >> Project site:http://guava-libraries.googlecode.com
> >> >> This group:http://groups.google.com/group/guava-discuss
>
> >> >> This list is for general discussion.
> >> >> To report an issue:
> >>http://code.google.com/p/guava-libraries/issues/entry

> >> >> To get help:http://stackoverflow.com/questions/ask(use the tag

> >> "guava")
>
> >> > --
> >> > Kevin Bourrillion @ Google
> >> > Java Core Libraries Team
> >> >http://guava-libraries.googlecode.com
>
> >> > --
> >> > guava-...@googlegroups.com
> >> > Project site:http://guava-libraries.googlecode.com
> >> > This group:http://groups.google.com/group/guava-discuss
>
> >> > This list is for general discussion.
> >> > To report an issue:
> >>http://code.google.com/p/guava-libraries/issues/entry

> >> > To get help:http://stackoverflow.com/questions/ask(use the tag

[Raymond Rishty]

So, to be more specific, you might annotate methods that return an
object where the immutable implementation is private, and thus can't
communicate that guarantee by the return type alone.
I make the distinction because we have plenty of cases where folks are
using List or Collection as the return type when the object being
returned is ImmutableList—if immutability was to be communicated here,
I would prefer using ImmutableList as the return type over annotating.