Como devo anotar que uma classe é imutável em Java?

Recentemente, deparei com a utilidade de objetos imutáveis ​​e que, por exemplo, se você passa elementos para um construtor e sua classe deve ser imutável, você deve copiar esses elementos se eles não forem imutáveis.

Isso requer muita verificação ou conhecimento sobre o meu projeto, porque se eu tiver

public A(B foo)

e Bnão é imutável, Aeu teria que copiar B. Agora imagine Bparece imutável, mas ele próprio tem classes mutáveis ​​no construtor e assim por diante.

Existe um padrão ou prática recomendada para documentar se uma classe é imutável em Java? Parece que não há nenhuma @immutablepalavra-chave no Javadoc.

A anotação @Immutable parece ser algo totalmente diferente para a geração automática de classes e não faz parte do Java padrão.

Examinando a documentação da Stringclasse (texto em negrito é algo que eu fiz):

A classe String representa cadeias de caracteres. Todos os literais de cadeia de caracteres nos programas Java, como "abc", são implementados como instâncias dessa classe. Strings são constantes; seus valores não podem ser alterados após serem criados. Buffers de string suportam strings mutáveis. Como os objetos String são imutáveis, eles podem ser compartilhados.

Como você pode ver, não há rotulagem específica ou outros marcadores; no entanto, eles especificam no JavaDoc que descreve a classe que a Stringclasse representa um objeto constante e imutável.

Assim, assumindo que você seguiu as instruções fornecidas neste tutorial do Oracle para criar uma classe imutável, para garantir que a imutabilidade da classe esteja documentada, você deve mencionar nela o JavaDoc que descreve a classe e o que faz.

Se isso ainda não se adequar ao que você precisa, você pode dar uma olhada em como criar tags JavaDoc personalizadas aqui .

Você pode usar anotações:

@ javax.annotation.concurrent.Immutable de JSR-305

ou @ net.jcip.annotations.Immutable from Java Concurrency In Practice