sirius.biz.sequences

Class Sequences

java.lang.Object

sirius.biz.sequences.Sequences

public class Sequences
extends Object

Provides a facility to generate unique consecutive numbers.

For each sequence name, a call to generateId(String) will return a unique number. The initial or next number being returned can be specified by setNextValue(String, long, boolean).

Note that these sequences are global and not tenant aware. Therefore care must be taken to generate unique names for sequences. A viable option is to use BaseEntity.getUniqueName() of the entity which utilizes this generator.

Field Summary

Fields

Modifier and Type	Field and Description
static String	FRAMEWORK_SEQUENCES Names the framework which must be enabled to activate the sequences feature.
static sirius.kernel.health.Log	LOG

Constructor Summary

Constructors

Constructor and Description
Sequences()

Method Summary

Modifier and Type	Method and Description
long	generateId(String sequence) Returns the next value in the given sequence.
List<String>	getKnownSequences() Enumerates all sequences known to the framework.
long	peekNextValue(String sequence) Identifies the next value for the given sequence without using it.
void	setNextValue(String sequence, long nextValue, boolean force) Sets the initial or next value of the given sequence.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FRAMEWORK_SEQUENCES

public static final String FRAMEWORK_SEQUENCES

Names the framework which must be enabled to activate the sequences feature.

See Also:

Constant Field Values

LOG

public static final sirius.kernel.health.Log LOG

Constructor Detail

Sequences

public Sequences()

Method Detail

generateId

public long generateId(String sequence)

Returns the next value in the given sequence.

Note that this method doesn't use locks or transactions. It rather utilizes optimistic locking, which scales extremely well. However, the algorithm used is not intended for extreme parallel usage. In such scenarios, it will not content but rather give up after some tries and report an appropriate exception.

Parameters:

sequence - the name of the sequence which is counted up.

Returns:

the next value (which has not yet been returned). If the sequence is unknown, 1 is returned.

Throws:

sirius.kernel.health.HandledException - If the system was unable to generate a unique sequence number. This might happen in extreme load conditions, as internally an optimistic locking algorithm is employed.

setNextValue

public void setNextValue(String sequence,
                         long nextValue,
                         boolean force)

Sets the initial or next value of the given sequence.

Unless force is set to true, the value has to be higher than the current counter value to prevent non unique numbers from being generated.

Parameters:

sequence - the sequence to update

nextValue - the next value that will be returned when calling generateId(String) for this sequence.

force - if true, no sanity checks are performed and the sequence can be reset to ANY value. This is rather dangerous, as it might lead to the generation of duplicate ids. If set to false, the given nextValue has to be higher than the current sequence value.

peekNextValue

public long peekNextValue(String sequence)

Identifies the next value for the given sequence without using it.

Note that this method is only used for reporting and statistics and must never be called by production code, as there is no guarantee that there isn't a parallel thread which currently acquires the returned value while this method is running.

Parameters:

sequence - the sequence to peek the next value for

Returns:

the next value for the sequence (unless already acquired by another thread)

getKnownSequences

public List<String> getKnownSequences()

Enumerates all sequences known to the framework.

This must be only used by reporting systems. There is no guarantee that this list is complete.

Returns:

a list of known sequences.