org.apache.derby.impl.sql.catalog
Class SequenceGenerator

java.lang.Object
  extended by org.apache.derby.impl.sql.catalog.SequenceGenerator

public class SequenceGenerator
extends java.lang.Object

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:

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().


Field Summary
private  boolean _CAN_CYCLE
           
private  long _currentValue
           
private  long _INCREMENT
           
private  boolean _isExhausted
           
private  long _MAX_VALUE
           
private  long _MIN_VALUE
           
private  long _remainingPreallocatedValues
           
private  long _RESTART_VALUE
           
private  java.lang.String _SEQUENCE_NAME
           
private  boolean _STEP_INCREASES
           
private  long _valuesPerAllocation
           
static int CVAA_CURRENT_VALUE
           
static int CVAA_LAST_ALLOCATED_VALUE
           
static int CVAA_LENGTH
           
static int CVAA_NUMBER_OF_VALUES_ALLOCATED
           
static int CVAA_STATUS
           
static int DEFAULT_PREALLOCATION_COUNT
          Default number of values to pre-allocate.
private static int PREALLOCATION_THRESHHOLD
          If pre-allocation drops below this level, then we need to grab another chunk of numbers
static int RET_ALLOCATE_NEW_VALUES
           
static int RET_I_AM_CONFUSED
           
static int RET_MARK_EXHAUSTED
           
static int RET_OK
           
 
Constructor Summary
SequenceGenerator(java.lang.Long currentValue, boolean canCycle, long increment, long maxValue, long minValue, long restartValue, java.lang.String sequenceName)
          Normal constructor
 
Method Summary
private  void advanceValue(long[] retval)
           Advance the sequence generator.
 void allocateNewRange(long expectedCurrentValue, long numberOfAllocatedValues)
           Allocate a new range.
private  void computeNewAllocation(long oldCurrentValue, long[] 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.
 long[] getCurrentValueAndAdvance()
           Get the next sequence number managed by this generator and advance the number.
private static LanguageConnectionContext getLCC()
           
 java.lang.String getName()
           Get the name 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.
 java.lang.Long peekAtCurrentValue()
           Peek at the current value of the sequence generator without advancing the generator.
private  StandardException unimplementedFeature()
          Report an unimplemented feature
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_PREALLOCATION_COUNT

public static final int DEFAULT_PREALLOCATION_COUNT
Default number of values to pre-allocate. In the future, we may want to provide something more sophisticated. For instance, we might want to make Derby tune this number per sequence generator or give the user the power to override Derby's decision.

See Also:
Constant Field Values

PREALLOCATION_THRESHHOLD

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

See Also:
Constant Field Values

RET_I_AM_CONFUSED

public static final int RET_I_AM_CONFUSED
See Also:
Constant Field Values

RET_OK

public static final int RET_OK
See Also:
Constant Field Values

RET_MARK_EXHAUSTED

public static final int RET_MARK_EXHAUSTED
See Also:
Constant Field Values

RET_ALLOCATE_NEW_VALUES

public static final int RET_ALLOCATE_NEW_VALUES
See Also:
Constant Field Values

CVAA_STATUS

public static final int CVAA_STATUS
See Also:
Constant Field Values

CVAA_CURRENT_VALUE

public static final int CVAA_CURRENT_VALUE
See Also:
Constant Field Values

CVAA_LAST_ALLOCATED_VALUE

public static final int CVAA_LAST_ALLOCATED_VALUE
See Also:
Constant Field Values

CVAA_NUMBER_OF_VALUES_ALLOCATED

public static final int CVAA_NUMBER_OF_VALUES_ALLOCATED
See Also:
Constant Field Values

CVAA_LENGTH

public static final int CVAA_LENGTH
See Also:
Constant Field Values

_CAN_CYCLE

private final boolean _CAN_CYCLE

_STEP_INCREASES

private final boolean _STEP_INCREASES

_INCREMENT

private final long _INCREMENT

_MAX_VALUE

private final long _MAX_VALUE

_MIN_VALUE

private final long _MIN_VALUE

_RESTART_VALUE

private final long _RESTART_VALUE

_SEQUENCE_NAME

private final java.lang.String _SEQUENCE_NAME

_isExhausted

private boolean _isExhausted

_currentValue

private long _currentValue

_valuesPerAllocation

private long _valuesPerAllocation

_remainingPreallocatedValues

private long _remainingPreallocatedValues
Constructor Detail

SequenceGenerator

public SequenceGenerator(java.lang.Long currentValue,
                         boolean canCycle,
                         long increment,
                         long maxValue,
                         long minValue,
                         long restartValue,
                         java.lang.String sequenceName)
Normal constructor

Method Detail

getName

public java.lang.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.


allocateNewRange

public 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.


peekAtCurrentValue

public java.lang.Long peekAtCurrentValue()

Peek at the current value of the sequence generator without advancing the generator. Returns null if the generator is exhausted.


getCurrentValueAndAdvance

public 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:
Returns an array of longs indexed by the CVAA_* constants.
Throws:
StandardException

advanceValue

private void advanceValue(long[] retval)
                   throws StandardException

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

Parameters:
retval - Array of return values to fill in: see CVAA_* constants
Throws:
StandardException

markExhausted

private void markExhausted(long[] retval)

Mark the generator as exhausted.


overflowed

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.


computeNewAllocation

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

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

Parameters:
oldCurrentValue - INPUT Used to compute how many values need to be allocated
retval - OUTPUT Array of values to fill in (see CVAA_* constants)
Throws:
StandardException - if any error occurs.

computeRemainingValues

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.


computePreAllocationCount

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.


getLCC

private static LanguageConnectionContext getLCC()

unimplementedFeature

private StandardException unimplementedFeature()
Report an unimplemented feature


Built on Thu 2011-03-10 11:54:14+0000, from revision ???

Apache Derby V10.6 Internals - Copyright © 2004,2007 The Apache Software Foundation. All Rights Reserved.