[hibernate-issues] [Hibernate-JIRA] Commented: (HHH-4871) Improve Javadoc (and possibly other) documentation for org.hibernate.id.SequenceHiLoGenerator

Improve Javadoc (and possibly other) documentation for org.hibernate.id.SequenceHiLoGenerator --------------------------------------------------------------------------------------------- Key: HHH-4871 URL: http://opensource.atlassian.com/projects/hibernate/browse/HHH-4871 Project: Hibernate Core Issue Type: Task Components: documentation Reporter: Aleksander Adamowski The org.hibernate.id.SequenceHiLoGenerator identifier generator is probably the most misunderstood generator due to poor documentation. Unfortunately, it's also the default for JPA, and this leads to serious problems for many people. See e.g.: ANN-354 this forum thread: https://forum.hibernate.org/viewtopic.php?f=9&t=967338&view=next Many misunderstandings would be avoided, if Javadoc for the org.hibernate.id.SequenceHiLoGenerator class would specify how exactly does the logic work and how should people get the most frequently desired behaviour of ordinary 1:1 sequence from the database (the answer being, use allocationSize=1). A good, but generic description of how hi/lo algorithm works is on stack overflow: http://stackoverflow.com/questions/282099/whats-the-hi-lo-algorithm The Hibernate's implementation, when used from a @SequenceGenerator, seems to get a hi value from corresponding database sequence, create an initial identifier by multiplying it by allocationSize, then works up from that, incrementing by 1 until the allocation is depleted - then it repeats the procedure by getting a new fresh sequence value, multiplying it etc. The docs should also explain how this strategy is beneficial to performance in distributed environments and why it has been chosen as the default over simple 1:1 sequence handling.