oracle.toplink.essentials.sequencing

Class Sequence

java.lang.Object

oracle.toplink.essentials.sequencing.Sequence

All Implemented Interfaces:

Serializable, Cloneable

Direct Known Subclasses:

DefaultSequence, StandardSequence

public abstract class Sequence
extends Object
implements Serializable, Cloneable

Purpose: Define an interface for sequencing customization.

Description: Customary sequencing behavior could be achieved by implementing this interface and passing the instance to DatabaseSession.getSequencingControl().setValueGenerationPolicy(..). TopLink internally uses the same method to set its default implementation of this interface, which provides native sequencing and table sequencing. Note that the following methods: shouldAcquireValueAfterInsert(); shouldUsePreallocation(); shouldUseSeparateConnection(); shouldUseTransaction(); are called only once - during creation of the sequencing object. Therefore during the lifetime of sequencing object these methods should return the same values as when called for the first time. If this is not true - resetSequencing (call SequencingControl.resetSequencing()).

Responsibilities:

• Define the APIs for customary sequencing.

See Also:

SequencingControl, Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
protected int	depth
protected int	initialValue
protected String	name
protected Platform	platform
protected int	size

Constructor Summary

Constructors

Constructor and Description
Sequence()
Sequence(String name)
Sequence(String name, int size)
Sequence(String name, int size, int initialValue)

Method Summary

Modifier and Type	Method and Description
Object	clone()
static boolean	equalNameAndSize(Sequence seq1, Sequence seq2)
boolean	equals(Object obj)
Platform	getDatasourcePlatform()
Object	getGeneratedValue(Accessor accessor, AbstractSession writeSession) INTERNAL: Return the newly-generated sequencing value.
abstract Object	getGeneratedValue(Accessor accessor, AbstractSession writeSession, String seqName) INTERNAL: Return the newly-generated sequencing value.
Vector	getGeneratedVector(Accessor accessor, AbstractSession writeSession) INTERNAL: Return a Vector of newly-generated sequencing values.
abstract Vector	getGeneratedVector(Accessor accessor, AbstractSession writeSession, String seqName, int size) INTERNAL: Return a Vector of newly-generated sequencing values.
int	getInitialValue()
String	getName()
int	getPreallocationSize()
boolean	isConnected() PUBLIC: Indicates that Sequence is connected.
protected abstract void	onConnect() INTERNAL: This method is called when Sequencing object is created.
void	onConnect(Platform platform) INTERNAL: This method is called when Sequencing object is created.
protected abstract void	onDisconnect() INTERNAL: This method is called when Sequencing object is destroyed.
void	onDisconnect(Platform platform) INTERNAL: This method is called when Sequencing object is destroyed.
protected void	setDatasourcePlatform(Platform platform)
void	setInitialValue(int initialValue)
void	setName(String name)
void	setPreallocationSize(int size)
abstract boolean	shouldAcquireValueAfterInsert() INTERNAL: Indicates whether sequencing value should be acquired after INSERT.
boolean	shouldOverrideExistingValue(Object existingValue) INTERNAL: Indicates whether existing attribute value should be overridden.
abstract boolean	shouldOverrideExistingValue(String seqName, Object existingValue) INTERNAL: Indicates whether existing attribute value should be overridden.
boolean	shouldUsePreallocation() INTERNAL: Indicates whether several sequencing values should be acquired at a time and be kept by TopLink.
abstract boolean	shouldUseTransaction() INTERNAL: Indicates whether TopLink should internally call beginTransaction() before getGeneratedValue/Vector, and commitTransaction after.
protected void	verifyPlatform(Platform otherPlatform) INTERNAL: Make sure that the sequence is not used by more than one platform.

Methods inherited from class java.lang.Object

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

Field Detail

name

protected String name

size

protected int size

platform

protected Platform platform

initialValue

protected int initialValue

depth

protected int depth

Constructor Detail

Sequence

public Sequence()

Sequence

public Sequence(String name)

Sequence

public Sequence(String name,
                int size)

Sequence

public Sequence(String name,
                int size,
                int initialValue)

Method Detail

getName

public String getName()

setName

public void setName(String name)

getPreallocationSize

public int getPreallocationSize()

setPreallocationSize

public void setPreallocationSize(int size)

getInitialValue

public int getInitialValue()

setInitialValue

public void setInitialValue(int initialValue)

clone

public Object clone()

Overrides:

clone in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

equalNameAndSize

public static boolean equalNameAndSize(Sequence seq1,
                                       Sequence seq2)

setDatasourcePlatform

protected void setDatasourcePlatform(Platform platform)

getDatasourcePlatform

public Platform getDatasourcePlatform()

shouldAcquireValueAfterInsert

public abstract boolean shouldAcquireValueAfterInsert()

INTERNAL: Indicates whether sequencing value should be acquired after INSERT. Note that preallocation could be used only in case sequencing values should be acquired before insert (this method returns false). In default implementation, it is true for table sequencing and native sequencing on Oracle platform, false for native sequencing on other platforms.

shouldUsePreallocation

public boolean shouldUsePreallocation()

INTERNAL: Indicates whether several sequencing values should be acquired at a time and be kept by TopLink. This in only possible in case sequencing numbers should be acquired before insert (shouldAcquireValueAfterInsert()==false). In default implementation, it is true for table sequencing and native sequencing on Oracle platform, false for native sequencing on other platforms.

shouldUseTransaction

public abstract boolean shouldUseTransaction()

INTERNAL: Indicates whether TopLink should internally call beginTransaction() before getGeneratedValue/Vector, and commitTransaction after. In default implementation, it is true for table sequencing and false for native sequencing.

shouldOverrideExistingValue

public abstract boolean shouldOverrideExistingValue(String seqName,
                                                    Object existingValue)

INTERNAL: Indicates whether existing attribute value should be overridden. This method is called in case an attribute mapped to PK of sequencing-using descriptor contains non-null value.

Parameters:

seqName - String is sequencing number field name

existingValue - Object is a non-null value of PK-mapped attribute.

shouldOverrideExistingValue

public boolean shouldOverrideExistingValue(Object existingValue)

INTERNAL: Indicates whether existing attribute value should be overridden. This method is called in case an attribute mapped to PK of sequencing-using descriptor contains non-null value.

Parameters:

existingValue - Object is a non-null value of PK-mapped attribute.

getGeneratedValue

public abstract Object getGeneratedValue(Accessor accessor,
                                         AbstractSession writeSession,
                                         String seqName)

INTERNAL: Return the newly-generated sequencing value. Used only in case preallocation is not used (shouldUsePreallocation()==false). Accessor may be non-null only in case shouldUseSeparateConnection()==true. Even in this case accessor could be null - if SequencingControl().shouldUseSeparateConnection()==false; Therefore in case shouldUseSeparateConnection()==true, implementation should handle both cases: use a separate connection if provided (accessor != null), or get by without it (accessor == null).

Parameters:

accessor - Accessor is a separate sequencing accessor (may be null);

writeSession - Session is a Session used for writing (either ClientSession or DatabaseSession);

seqName - String is sequencing number field name

getGeneratedValue

public Object getGeneratedValue(Accessor accessor,
                                AbstractSession writeSession)

INTERNAL: Return the newly-generated sequencing value. Used only in case preallocation is not used (shouldUsePreallocation()==false). Accessor may be non-null only in case shouldUseSeparateConnection()==true. Even in this case accessor could be null - if SequencingControl().shouldUseSeparateConnection()==false; Therefore in case shouldUseSeparateConnection()==true, implementation should handle both cases: use a separate connection if provided (accessor != null), or get by without it (accessor == null).

Parameters:

accessor - Accessor is a separate sequencing accessor (may be null);

writeSession - Session is a Session used for writing (either ClientSession or DatabaseSession);

getGeneratedVector

public abstract Vector getGeneratedVector(Accessor accessor,
                                          AbstractSession writeSession,
                                          String seqName,
                                          int size)

INTERNAL: Return a Vector of newly-generated sequencing values. Used only in case preallocation is used (shouldUsePreallocation()==true). Accessor may be non-null only in case shouldUseSeparateConnection()==true. Even in this case accessor could be null - if SequencingControl().shouldUseSeparateConnection()==false; Therefore in case shouldUseSeparateConnection()==true, implementation should handle both cases: use a separate connection if provided (accessor != null), or get by without it (accessor == null).

Parameters:

accessor - Accessor is a separate sequencing accessor (may be null);

writeSession - Session is a Session used for writing (either ClientSession or DatabaseSession);

seqName - String is sequencing number field name

size - int number of values to preallocate (output Vector size).

getGeneratedVector

public Vector getGeneratedVector(Accessor accessor,
                                 AbstractSession writeSession)

INTERNAL: Return a Vector of newly-generated sequencing values. Used only in case preallocation is used (shouldUsePreallocation()==true). Accessor may be non-null only in case shouldUseSeparateConnection()==true. Even in this case accessor could be null - if SequencingControl().shouldUseSeparateConnection()==false; Therefore in case shouldUseSeparateConnection()==true, implementation should handle both cases: use a separate connection if provided (accessor != null), or get by without it (accessor == null).

Parameters:

accessor - Accessor is a separate sequencing accessor (may be null);

writeSession - Session is a Session used for writing (either ClientSession or DatabaseSession);

onConnect

public void onConnect(Platform platform)

INTERNAL: This method is called when Sequencing object is created. Don't override this method.

Parameters:

ownerSession - DatabaseSession

onConnect

protected abstract void onConnect()

INTERNAL: This method is called when Sequencing object is created. If it requires initialization, subclass should override this method.

Parameters:

ownerSession - DatabaseSession

onDisconnect

public void onDisconnect(Platform platform)

INTERNAL: This method is called when Sequencing object is destroyed. Don't overridethis method.

onDisconnect

protected abstract void onDisconnect()

INTERNAL: This method is called when Sequencing object is destroyed. If it requires deinitialization, subclass should override this method.

isConnected

public boolean isConnected()

PUBLIC: Indicates that Sequence is connected.

verifyPlatform

protected void verifyPlatform(Platform otherPlatform)

INTERNAL: Make sure that the sequence is not used by more than one platform.