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

[Aleksander Adamowski (JIRA)]

    [ http://opensource.atlassian.com/projects/hibernate/browse/HHH-4871?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=35417#action_35417 ] 

Aleksander Adamowski commented on HHH-4871:
-------------------------------------------

For the record, here's the current javadoc grabbed from https://www.hibernate.org/hib_docs/v3/api/org/hibernate/id/SequenceHiLoGenerator.html :

public class SequenceHiLoGenerator
extends SequenceGenerator
seqhilo

An IdentifierGenerator that combines a hi/lo algorithm with an underlying oracle-style sequence that generates hi values. The user may specify a maximum lo value to determine how often new hi values are fetched.

If sequences are not available, TableHiLoGenerator might be an alternative.

Mapping parameters supported: sequence, max_lo, parameters.

Author:
Gavin King
See Also:
TableHiLoGenerator


It doesn't mention what a hi/lo algorithm is and how does it behave in this specific implementation, nor how to make it behave in a simple 1:1 fashion WRT actual database sequence.


> 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