Apache Derby Database Engine and Embedded JDBC Driver 10.17.1.0 · org.apache.derby.impl.sql.catalog.SequenceGenerator

This is a generic machine for pre-allocating ranges of sequence numbers in order to improve concurrency. The public methods are synchronized and should be brief. The caller of the methods in this class is responsible for updating values on disk when the generator is exhausted or when it needs to allocate a new range of values.

The most used method in this class is getCurrentValueAndAdvance(). This method returns the next number in the range managed by the sequence generator. This method will raise an exception if the sequence generator is exhausted. Otherwise getCurrentValueAndAdvance() hands back a tuple of return values:

( status, currentValue, lastAllocatedValue, numberOfValuesAllocated )

The status field takes the following values:

RET_I_AM_CONFUSED - This value should never be returned. If this value comes back, then the sequence generator is confused.
RET_OK - This means that the generator has successfully obtained a next value. That value is currentValue.
RET_MARK_EXHAUSTED - This means that the generator has reached the end of its legal range and is handing back its very last value. The caller must mark the catalogs to indicate that the range is exhausted. The very last value being handed back is currentValue.
RET_ALLOCATE_NEW_VALUES - This means that the generator has come to the end of its pre-allocated values. The caller needs to update the catalog to grab a new range of legal values and then call allocateNewRange() to tell the generator that the range was successfully allocated. The remaining values in the return tuple have these meanings:
- currentValue - This is what is expected to be the current value in the catalog before allocating a new range. If, in fact, this is not the value in the catalog, then we are racing with another session to drain values from the generator and update the disk. Do not update the catalog if the value there is not currentValue. Instead, assume that another session got in ahead of us and grabbed a new range of values. Simply call getCurrentValueAndAdvance() again.
- lastAllocatedValue - This is the next value to write to the catalog.
- numberOfValuesAllocated - This is the number of values which were allocated if we successfully updated the catalog. If we successfully updated the catalog, then we should call allocateNewRange(), handing it this value so that it can reset its range. As a sanity check, we also hand allocateNewRange() the currentValue that we were given. The allocateNewRange() method will assume we're racing another session and will ignore us if its sense of currentValue does not agree with ours.

It may happen that getCurrentValueAndAdvance() tells its caller to allocate a new range of sequence numbers in the system catalog. If the caller successfully allocates a new range, the caller should call allocateNewRange() to tell the generator to update its internal memory of that range.

The peekAtCurrentValue() method is provided so that unused, pre-allocated values can be flushed when the sequence generator is being discarded. The caller updates the catalog with the value returned by peekAtCurrentValue(). The peekAtCurrentValue() method is also called by the syscs_peek_at_sequence() function which users should call rather than try to scan the underlying catalog themselves.

Field Summary

Modifier and Type	Field and Description
private final boolean	_CAN_CYCLE
private long	_currentValue
private final long	_INCREMENT
private boolean	_isExhausted
private final long	_MAX_VALUE
private final long	_MIN_VALUE
private final SequencePreallocator	_PREALLOCATOR
private long	_remainingPreallocatedValues
private final long	_RESTART_VALUE
private final String	_SCHEMA_NAME
private final String	_SEQUENCE_NAME
private final boolean	_STEP_INCREASES
public static final int	CVAA_CURRENT_VALUE
public static final int	CVAA_LAST_ALLOCATED_VALUE
public static final int	CVAA_LENGTH
public static final int	CVAA_NUMBER_OF_VALUES_ALLOCATED
public static final int	CVAA_STATUS
private static final int	PREALLOCATION_THRESHHOLD If pre-allocation drops below this level, then we need to grab another chunk of numbers
public static final int	RET_ALLOCATE_NEW_VALUES
public static final int	RET_I_AM_CONFUSED
public static final int	RET_MARK_EXHAUSTED
public static final int	RET_OK

Constructor Summary

Access	Constructor and Description
public	SequenceGenerator(Long currentValue, boolean canCycle, long increment, long maxValue, long minValue, long restartValue, String schemaName, String sequenceName, SequencePreallocator sequencePreallocator) Normal constructor

Method Summary

Modifier and Type	Method and Description
private void	advanceValue(long[] Array of return values to fill in: see CVAA_* constants retval) Advance the sequence generator.
public synchronized void	allocateNewRange(long expectedCurrentValue, long numberOfAllocatedValues) Allocate a new range.
public synchronized SequenceGenerator	clone(boolean True if the clone should be reset to start at the beginning instead of at the current value. restart) Clone this sequence generator.
public synchronized SequenceGenerator	clone(Long New value to start with. newStartValue) Clone this sequence generator.
private void	computeNewAllocation(long INPUT Used to compute how many values need to be allocated oldCurrentValue, long[] OUTPUT Array of values to fill in (see CVAA_* constants) retval) Compute the number of values to allocate.
private int	computePreAllocationCount() This method returns the number of values to pre-allocate when we grab a new chunk of values.
private long	computeRemainingValues(long oldCurrentValue) Get the number of values remaining until we bump against an endpoint of the legal range of values.
public synchronized long[]	Returns: Returns an array of longs indexed by the CVAA_* constants. getCurrentValueAndAdvance() Get the next sequence number managed by this generator and advance the number.
public synchronized String	getName() Get the name of this sequence generator.
public synchronized String	getSchemaName() Get the name of the schema of this sequence generator.
private void	markExhausted(long[] retval) Mark the generator as exhausted.
private boolean	overflowed(long originalValue, long incrementedValue) Return true if an overflow/underflow occurred.
public synchronized Long	peekAtCurrentValue() Peek at the current value of the sequence generator without advancing the generator.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

_CAN_CYCLE	back to summary
private final boolean _CAN_CYCLE

_currentValue	back to summary
private long _currentValue

_INCREMENT	back to summary
private final long _INCREMENT

_isExhausted	back to summary
private boolean _isExhausted

_MAX_VALUE	back to summary
private final long _MAX_VALUE

_MIN_VALUE	back to summary
private final long _MIN_VALUE

_PREALLOCATOR	back to summary
private final SequencePreallocator _PREALLOCATOR

_remainingPreallocatedValues	back to summary
private long _remainingPreallocatedValues

_RESTART_VALUE	back to summary
private final long _RESTART_VALUE

_SCHEMA_NAME	back to summary
private final String _SCHEMA_NAME

_SEQUENCE_NAME	back to summary
private final String _SEQUENCE_NAME

_STEP_INCREASES	back to summary
private final boolean _STEP_INCREASES

CVAA_CURRENT_VALUE	back to summary
public static final int CVAA_CURRENT_VALUE

CVAA_LAST_ALLOCATED_VALUE	back to summary
public static final int CVAA_LAST_ALLOCATED_VALUE

CVAA_LENGTH	back to summary
public static final int CVAA_LENGTH

CVAA_NUMBER_OF_VALUES_ALLOCATED	back to summary
public static final int CVAA_NUMBER_OF_VALUES_ALLOCATED

CVAA_STATUS	back to summary
public static final int CVAA_STATUS

PREALLOCATION_THRESHHOLD	back to summary
private static final int PREALLOCATION_THRESHHOLD If pre-allocation drops below this level, then we need to grab another chunk of numbers

RET_ALLOCATE_NEW_VALUES	back to summary
public static final int RET_ALLOCATE_NEW_VALUES

RET_I_AM_CONFUSED	back to summary
public static final int RET_I_AM_CONFUSED

RET_MARK_EXHAUSTED	back to summary
public static final int RET_MARK_EXHAUSTED

RET_OK	back to summary
public static final int RET_OK

Constructor Detail

SequenceGenerator	back to summary
public SequenceGenerator(Long currentValue, boolean canCycle, long increment, long maxValue, long minValue, long restartValue, String schemaName, String sequenceName, SequencePreallocator sequencePreallocator) Normal constructor

Method Detail

advanceValue	back to summary
private void advanceValue(long[] retval) throws StandardException Advance the sequence generator. Pre-allocate a range of new values if necessary. Parameters retval:long[] Array of return values to fill in: see CVAA_* constants

advanceValue

back to summary

private void advanceValue(long[] retval) throws StandardException

Advance the sequence generator. Pre-allocate a range of new values if necessary.

Parameters

retval:long[]: Array of return values to fill in: see CVAA_* constants

allocateNewRange	back to summary
public synchronized void allocateNewRange(long expectedCurrentValue, long numberOfAllocatedValues) Allocate a new range. Is a NOP if the current value is not what we expected. See the class header comment for more information on how this method is used.

clone	back to summary
public synchronized SequenceGenerator clone(boolean restart) Clone this sequence generator. This method supports the special bulk-insert optimization in InsertResultSet. Parameters restart:boolean True if the clone should be reset to start at the beginning instead of at the current value.

clone

back to summary

public synchronized SequenceGenerator clone(boolean restart)

Clone this sequence generator. This method supports the special bulk-insert optimization in InsertResultSet.

Parameters

restart:boolean: True if the clone should be reset to start at the beginning instead of at the current value.

clone	back to summary
public synchronized SequenceGenerator clone(Long newStartValue) Clone this sequence generator. This method supports the special bulk-insert optimization in InsertResultSet. Parameters newStartValue:Long New value to start with.

clone

back to summary

public synchronized SequenceGenerator clone(Long newStartValue)

Clone this sequence generator. This method supports the special bulk-insert optimization in InsertResultSet.

Parameters

newStartValue:Long: New value to start with.

computeNewAllocation	back to summary
private void computeNewAllocation(long oldCurrentValue, long[] retval) throws StandardException Compute the number of values to allocate. The range may wrap around. Parameters oldCurrentValue:long INPUT Used to compute how many values need to be allocated retval:long[] OUTPUT Array of values to fill in (see CVAA_* constants) Exceptions StandardException: if any error occurs.

computeNewAllocation

back to summary

private void computeNewAllocation(long oldCurrentValue, long[] retval) throws StandardException

Compute the number of values to allocate. The range may wrap around.

Parameters

oldCurrentValue:long: INPUT Used to compute how many values need to be allocated
retval:long[]: OUTPUT Array of values to fill in (see CVAA_* constants)

Exceptions

StandardException:: if any error occurs.

computePreAllocationCount	back to summary
private int computePreAllocationCount() This method returns the number of values to pre-allocate when we grab a new chunk of values. This is a bit of defensive coding to cover the case when the sequence's parameters are absurdly large.

computeRemainingValues	back to summary
private long computeRemainingValues(long oldCurrentValue) Get the number of values remaining until we bump against an endpoint of the legal range of values. This is a positive number and so may understate the number of remaining values if the datatype is BIGINT.

getCurrentValueAndAdvance	back to summary
public synchronized long[] getCurrentValueAndAdvance() throws StandardException Get the next sequence number managed by this generator and advance the number. Could raise an exception if the legal range is exhausted and wrap-around is not allowed--that is, if NO CYCLE was specified when the sequence was defined. See the class header comment for a description of how this method operates. Returns:long[] Returns an array of longs indexed by the CVAA_* constants.

getCurrentValueAndAdvance

back to summary

public synchronized long[] getCurrentValueAndAdvance() throws StandardException

Get the next sequence number managed by this generator and advance the number. Could raise an exception if the legal range is exhausted and wrap-around is not allowed--that is, if NO CYCLE was specified when the sequence was defined. See the class header comment for a description of how this method operates.

Returns:long[]: Returns an array of longs indexed by the CVAA_* constants.

getName	back to summary
public synchronized String getName() Get the name of this sequence generator. Technically, this doesn't need to be synchronized. But it is simpler to just maintain a rule that all public methods should be synchronized.

getSchemaName	back to summary
public synchronized String getSchemaName() Get the name of the schema of this sequence generator. Technically, this doesn't need to be synchronized. But it is simpler to just maintain a rule that all public methods should be synchronized.

markExhausted	back to summary
private void markExhausted(long[] retval) Mark the generator as exhausted.

overflowed	back to summary
private boolean overflowed(long originalValue, long incrementedValue) Return true if an overflow/underflow occurred. This happens if the originalValue and incrementedValue have opposite sign. Overflow also occurs if the incrementedValue falls outside the range of the sequence.

peekAtCurrentValue	back to summary
public synchronized Long peekAtCurrentValue() Peek at the current value of the sequence generator without advancing the generator. Returns null if the generator is exhausted.

public Class SequenceGenerator

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail