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

java.lang.Object
  extended by org.apache.derby.impl.sql.catalog.SequenceUpdater
All Implemented Interfaces:
Cacheable
Direct Known Subclasses:
SequenceUpdater.SyssequenceUpdater

public abstract class SequenceUpdater
extends java.lang.Object
implements Cacheable

An object cached in the data dictionary which manages new values for sequences. Note that this class must be public and have a 0-arg constructor in order to satisfy the Cacheable contract.

This is the abstract superclass of specific implementations for specific sequences. For instance, one subclass handles the ANSI/ISO sequences stored in SYSSEQUENCES. Another subclass could handle the sequences stored in Derby's identity columns.

This class does a couple tricky things:

Here is the algorithm pursued when the caller asks for the next number in a sequence:

If applications start seeing exceptions complaining that there is too much contention on a sequence generator, then we should improve this algorithm. Here are some options based on the idea that contention should go down if we increase the number of pre-allocated numbers:


Nested Class Summary
static class SequenceUpdater.SyssequenceUpdater
           Specific implementation of SequenceUpdater for the sequences managed by SYSSEQUENCES.
 
Field Summary
protected  DataDictionaryImpl _dd
           
private  long _lockTimeoutInMillis
           
protected  SequenceGenerator _sequenceGenerator
           
protected  java.lang.String _uuidString
           
 
Constructor Summary
SequenceUpdater()
          No-arg constructor to satisfy the Cacheable contract
SequenceUpdater(DataDictionaryImpl dd)
          Normal constructor
 
Method Summary
 void clean(boolean forRemove)
          Clean the object.
 void clearIdentity()
          Put the object into the No Identity state.
 Cacheable createIdentity(java.lang.Object key, java.lang.Object createParameter)
          Create a new item.
protected abstract  SequenceGenerator createSequenceGenerator(TransactionController readOnlyTC)
           Initialize the sequence generator.
 void getCurrentValueAndAdvance(NumberDataValue returnValue)
           Get the next sequence number managed by this generator and advance the number.
 java.lang.Object getIdentity()
          Get the identity of this object.
private static LanguageConnectionContext getLCC()
           
protected  int getLockTimeout()
          Get the time we wait for a lock, in milliseconds--overridden by unit tests
 boolean isDirty()
          Returns true of the object is dirty.
private  java.lang.Long peekAtCurrentValue()
           Get the current value of the sequence generator without advancing it.
 Cacheable setIdentity(java.lang.Object key)
          Set the identity of the object.
private  StandardException unimplementedFeature()
          Report an unimplemented feature
 boolean updateCurrentValueOnDisk(java.lang.Long oldValue, java.lang.Long newValue)
           Update the value on disk.
protected abstract  boolean updateCurrentValueOnDisk(TransactionController tc, java.lang.Long oldValue, java.lang.Long newValue, boolean wait)
           Update the sequence value on disk.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

_dd

protected DataDictionaryImpl _dd

_uuidString

protected java.lang.String _uuidString

_sequenceGenerator

protected SequenceGenerator _sequenceGenerator

_lockTimeoutInMillis

private long _lockTimeoutInMillis
Constructor Detail

SequenceUpdater

public SequenceUpdater()
No-arg constructor to satisfy the Cacheable contract


SequenceUpdater

public SequenceUpdater(DataDictionaryImpl dd)
Normal constructor

Method Detail

createSequenceGenerator

protected abstract SequenceGenerator createSequenceGenerator(TransactionController readOnlyTC)
                                                      throws StandardException

Initialize the sequence generator. Work is done inside a read-only subtransaction of the session's execution transaction.

Throws:
StandardException

updateCurrentValueOnDisk

protected abstract boolean updateCurrentValueOnDisk(TransactionController tc,
                                                    java.lang.Long oldValue,
                                                    java.lang.Long newValue,
                                                    boolean wait)
                                             throws StandardException

Update the sequence value on disk. This method is first called with a read/write subtransaction of the session's execution transaction. If work can't be done there immediately, this method is called with the session's execution transaction.

Parameters:
tc - The transaction to use
oldValue - Expected value on disk for this sequence
newValue - The value to poke into the system table backing this sequence
wait - Whether to wait for a lock
Returns:
Returns true if the value was successfully updated, false if we lost a race with another session.
Throws:
StandardException - May throw an exception if a lock can't be obtained.

clean

public void clean(boolean forRemove)
           throws StandardException
Description copied from interface: Cacheable
Clean the object. It is up to the object to ensure synchronization of the isDirty() and clean() method calls.
If forRemove is true then the object is being removed due to an explict remove request, in this case the cache manager will have called this method regardless of the state of the isDirty()
If an exception is thrown the object must be left in the clean state.
MT - thread safe - Can be called at any time by the cache manager, it is the responsibility of the object implementing Cacheable to ensure any users of the object do not conflict with the clean call.

Specified by:
clean in interface Cacheable
Throws:
StandardException - Standard Derby error policy.

isDirty

public boolean isDirty()
Description copied from interface: Cacheable
Returns true of the object is dirty. May be called when the object is kept or unkept.
MT - thread safe

Specified by:
isDirty in interface Cacheable

getIdentity

public java.lang.Object getIdentity()
Description copied from interface: Cacheable
Get the identity of this object.
MT - thread safe.

Specified by:
getIdentity in interface Cacheable

clearIdentity

public void clearIdentity()
Description copied from interface: Cacheable
Put the object into the No Identity state.
MT - single thread required - Method must only be called be cache manager and the cache manager will guarantee only one thread can be calling it.

Specified by:
clearIdentity in interface Cacheable

createIdentity

public Cacheable createIdentity(java.lang.Object key,
                                java.lang.Object createParameter)
                         throws StandardException
Description copied from interface: Cacheable
Create a new item.

Create a new item and set the identity of the object to represent it. The object will be in the No Identity state, ie. it will have just been created or clearIdentity() was just called.
The object must copy the information out of key, not just store a reference to key if the key is not immutable. After this call the expression getIdentity().equals(key) must return true.

If the class of the object needs to change (e.g. to support a different format) then the object should create a new object, call its initParameter() with the parameters the original object was called with, set its identity and return a reference to it. The cache manager will discard the reference to the old object.
If an exception is thrown the object must be left in the no-identity state.
MT - single thread required - Method must only be called be cache manager and the cache manager will guarantee only one thread can be calling it.

Specified by:
createIdentity in interface Cacheable
Returns:
an object reference if the object can take on the identity, null otherwise.
Throws:
StandardException - If forCreate is true and the object cannot be created.
See Also:
CacheManager.create(java.lang.Object, java.lang.Object)

setIdentity

public Cacheable setIdentity(java.lang.Object key)
                      throws StandardException
Description copied from interface: Cacheable
Set the identity of the object.

Set the identity of the object to represent an item that already exists, e.g. an existing container. The object will be in the No Identity state, ie. it will have just been created or clearIdentity() was just called.
The object must copy the information out of key, not just store a reference to key. After this call the expression getIdentity().equals(key) must return true.
If the class of the object needs to change (e.g. to support a different format) then the object should create a new object, call its initParameter() with the parameters the original object was called with, set its identity and return a reference to it. The cache manager will discard the reference to the old object.
If an exception is thrown the object must be left in the no-identity state.
MT - single thread required - Method must only be called be cache manager and the cache manager will guarantee only one thread can be calling it.

Specified by:
setIdentity in interface Cacheable
Returns:
an object reference if the object can take on the identity, null otherwise.
Throws:
StandardException - Thrown on error
See Also:
Cacheable.setIdentity(java.lang.Object)

getCurrentValueAndAdvance

public void getCurrentValueAndAdvance(NumberDataValue returnValue)
                               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. Only one thread at a time is allowed through here. That synchronization is performed by the sequence generator itself.

Parameters:
returnValue - This value is stuffed with the new sequence number.
Throws:
StandardException

peekAtCurrentValue

private java.lang.Long peekAtCurrentValue()
                                   throws StandardException

Get the current value of the sequence generator without advancing it. May return null if the generator is exhausted.

Throws:
StandardException

updateCurrentValueOnDisk

public boolean updateCurrentValueOnDisk(java.lang.Long oldValue,
                                        java.lang.Long newValue)
                                 throws StandardException

Update the value on disk. First tries to update the value in a subtransaction. If that fails, falls back on the execution transaction. This is a callback method invoked by the sequence generator.

Returns:
Returns true if the value was successfully updated, false if we lost a race with another session.
Throws:
StandardException

getLockTimeout

protected int getLockTimeout()
Get the time we wait for a lock, in milliseconds--overridden by unit tests


getLCC

private static LanguageConnectionContext getLCC()

unimplementedFeature

private StandardException unimplementedFeature()
Report an unimplemented feature


Built on Thu 2010-12-23 20:49:13+0000, from revision ???

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