Documenting Effective Immutability

Matthias Ernst writes:

Often I neither want a huge (number of) constructor(s) nor want to jump through hoops of using a Builder to guarantee final-ness of my object's dependencies but want to rely on effective immutability instead. I want to rely on my clients' common sense that anything that is not documented as changeable should not be changed during use, i.e., a number of setters that they may only call a) before starting to use the object and b) before publishing it to other threads.

Is there a concise term to document this? I don't want to repeat that sermon above all over. @SetupMethod?

Tim Peierls responds:  There doesn't seem to be a consensus, so maybe it's best to pull together past and current proposals. Please feel free to add to this list and comment on them.

• @SetupMethod [method]
  
• @SetterInjected [field, method]
  
• @EffectivelyImmutable [field, method, type?]
  
• @Immutable [field, method -- type already has different meaning]
• @Implementation [field,method] -- public because of packaging

Isn't this JSR-305 territory?

 Gregg Wonderly adds: @Implementation is one way to say this is not an API method.  One of the things that I do sometimes, is instead make the method or field package visible, and then add another class to the package that is a delegating publication of those APIs.  That other class is just never put in the JavaDoc or otherwise made visible as the public API.

    package my.package;

    public class WorkClass {

       private AtomicLong counter = new AtomicLong();

       long incCounter() {

          return counter.incrementAndGet();

       }

    }

package my.package;

public class MyPackageAccess {

     WorkClass workClassInst = ...some initialization ...

     public long incCounter() {

     return workClassInst.incCounter();

     }

}

This allows other packages to use an instance or static reference to MyPackageAccess to get to package implementation details which are not public API pieces.