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

[Aleksander Adamowski (JIRA)]

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.

-- 
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://opensource.atlassian.com/projects/hibernate/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira