oracle.toplink.sequencing
Interface SequencingValueGenerationPolicy

public interface SequencingValueGenerationPolicy

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

Method Summary

java.lang.Object	getGeneratedValue(oracle.toplink.internal.databaseaccess.Accessor accessor, oracle.toplink.publicinterface.Session writeSession, java.lang.String seqName) ADVANCED: Return the newly-generated sequencing value.
java.util.Vector	getGeneratedVector(oracle.toplink.internal.databaseaccess.Accessor accessor, oracle.toplink.publicinterface.Session writeSession, java.lang.String seqName, int size) ADVANCED: Return a Vector of newly-generated sequencing values.
void	onConnect(oracle.toplink.publicinterface.DatabaseSession ownerSession) ADVANCED: This method is called when Sequencing object is created.
void	onDisconnect(oracle.toplink.publicinterface.DatabaseSession ownerSession) ADVANCED: This method is called when Sequencing object is destroyed..
boolean	shouldAcquireValueAfterInsert() ADVANCED: Indicates whether sequencing value should be acquired after INSERT.
boolean	shouldOverrideExistingValue(java.lang.String seqName, java.lang.Object existingValue) ADVANCED: Indicates whether existing attribute value should be overridden.
boolean	shouldUsePreallocation() ADVANCED: Indicates whether several sequencing values should be acquired at a time and be kept by TopLink.
boolean	shouldUseSeparateConnection() ADVANCED: Indicates whether sequencing would rather use a separate sequencing connection.
boolean	shouldUseTransaction() ADVANCED: Indicates whether TopLink should internally call beginTransaction() before getGeneratedValue/Vector, and commitTransaction after.

Method Detail

shouldAcquireValueAfterInsert

public boolean shouldAcquireValueAfterInsert()

ADVANCED: 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()

ADVANCED: 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.

shouldUseSeparateConnection

public boolean shouldUseSeparateConnection()

ADVANCED: Indicates whether sequencing would rather use a separate sequencing connection. Note that even in case this method returns true, there is no guarantee that separate sequencing connection will be provided unless getSequencingControl.shouldUseSeparateConnection()==true. In default implementation, it is true for table sequencing and false for native sequencing.

shouldUseTransaction

public boolean shouldUseTransaction()

ADVANCED: 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 boolean shouldOverrideExistingValue(java.lang.String seqName,
                                           java.lang.Object existingValue)

ADVANCED: 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.

getGeneratedValue

public java.lang.Object getGeneratedValue(oracle.toplink.internal.databaseaccess.Accessor accessor,
                                          oracle.toplink.publicinterface.Session writeSession,
                                          java.lang.String seqName)

ADVANCED: 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

getGeneratedVector

public java.util.Vector getGeneratedVector(oracle.toplink.internal.databaseaccess.Accessor accessor,
                                           oracle.toplink.publicinterface.Session writeSession,
                                           java.lang.String seqName,
                                           int size)

ADVANCED: 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).

onConnect

public void onConnect(oracle.toplink.publicinterface.DatabaseSession ownerSession)

ADVANCED: This method is called when Sequencing object is created. It's a chance to do initialization.

Parameters:

ownerSession - DatabaseSession

onDisconnect

public void onDisconnect(oracle.toplink.publicinterface.DatabaseSession ownerSession)

ADVANCED: This method is called when Sequencing object is destroyed.. It's a chance to do deinitialization.

Parameters:

ownerSession - DatabaseSession