Por mais vasta que a documentação do Hibernate seja, sempre ficam pontos da API que precisam de melhorias na documentação. Um exemplo claro disso é esclarecer qual a diferença entre dois métodos da Session, o save() e o persist(). Ambos tem a mesma função: tornar uma instância transient em persistent. Segundo a doc da API:

• persist() – Make a transient instance persistent.
• save() – Persist the given transient instance, first assigning a generated identifier.

O método persist(), não garante que será atribuito um id à instância imediatamente, sendo que a associação ocorrerá quando o flush ocorrer. Além disso, ele garante que só irá executar um insert se estiver dentro do contexto de uma transaction. Já o save(), atribui a chave imediatamente, não importando se isso exige um insert (no caso do identity generator) ou se existe um contexto de transação. Isso explica também porque o save() retorna o Id gerado e o persist() é void.

Mais informações podem ser encontradas no Jira e no fórum do Hibernate.

update: não é somente eu que acha que a documentação precisa de melhorias nesse caso: HHH-1682

update 2: acabei de comitar a alteração na documentação, para a próxima versão do Hibernate (3.2.5), a seção Making objects persistent irá trazer informações mais detalhadas sobre a diferença entre os dois métodos.

Popularity: 28% [?]