org.exolab.castor.persist.spi

Interface KeyGenerator

All Known Implementing Classes:

HighLowKeyGenerator, IdentityKeyGenerator, MaxKeyGenerator, SequenceKeyGenerator, UUIDKeyGenerator

public interface KeyGenerator

Interface for a key generator. The key generator is used for producing identities for objects before they are created in the database.

All the key generators belonging to the same database share the same non-transactional connection to the database.

The key generator is configured from the mapping file using Bean-like accessor methods.

Version:

$Revision: 5951 $ $Date: 2005-04-25 15:33:21 -0600 (Mon, 25 Apr 2005) $

Author:

Assaf Arkin, Oleg Nitz, Bruce Snyder

Field Summary

Fields

Modifier and Type	Field and Description
static byte	AFTER_INSERT For the key generators of AFTER_INSERT style generateKey(java.sql.Connection, java.lang.String, java.lang.String, java.util.Properties) is called after INSERT.
static byte	BEFORE_INSERT For the key generators of BEFORE_INSERT style generateKey(java.sql.Connection, java.lang.String, java.lang.String, java.util.Properties) is called before INSERT.
static byte	DURING_INSERT For the key generators of DURING_INSERT style generateKey(java.sql.Connection, java.lang.String, java.lang.String, java.util.Properties) is never called, all work is done by patchSQL(java.lang.String, java.lang.String).

Method Summary

Modifier and Type	Method and Description
java.lang.Object	generateKey(java.sql.Connection conn, java.lang.String tableName, java.lang.String primKeyName, java.util.Properties props) Generate a new key for the specified table.
byte	getStyle() Style of the key generator: BEFORE_INSERT, DURING_INSERT or AFTER_INSERT.
boolean	isInSameConnection() Is key generated in the same connection as INSERT? For DURING_INSERT style this method is never called.
java.lang.String	patchSQL(java.lang.String insert, java.lang.String primKeyName) Gives a possibility to patch the Castor-generated SQL statement for INSERT (indended mainly for DURING_INSERT style of key generators, other key generators usually simply return the passed parameter).
void	supportsSqlType(int sqlType) Determine if the key generator supports a given sql type.

Field Detail

BEFORE_INSERT

static final byte BEFORE_INSERT

For the key generators of BEFORE_INSERT style generateKey(java.sql.Connection, java.lang.String, java.lang.String, java.util.Properties) is called before INSERT. patchSQL(java.lang.String, java.lang.String) may be used but usually doesn't.

See Also:

Constant Field Values

DURING_INSERT

static final byte DURING_INSERT

For the key generators of DURING_INSERT style generateKey(java.sql.Connection, java.lang.String, java.lang.String, java.util.Properties) is never called, all work is done by patchSQL(java.lang.String, java.lang.String).

See Also:

Constant Field Values

AFTER_INSERT

static final byte AFTER_INSERT

For the key generators of AFTER_INSERT style generateKey(java.sql.Connection, java.lang.String, java.lang.String, java.util.Properties) is called after INSERT. patchSQL(java.lang.String, java.lang.String) may be used but usually doesn't.

See Also:

Constant Field Values

Method Detail

generateKey

java.lang.Object generateKey(java.sql.Connection conn,
                             java.lang.String tableName,
                             java.lang.String primKeyName,
                             java.util.Properties props)
                      throws PersistenceException

Generate a new key for the specified table. This method is called when a new object is about to be created. In some environments the name of the owner of the object is known, e.g. the principal in a J2EE server. This method is never called for DURING_INSERT key generators.

Parameters:

conn - An open connection within the given transaction

tableName - The table name

primKeyName - The primary key name

props - A temporary replacement for Principal object

Returns:

A new key

Throws:

PersistenceException - An error occured talking to persistent storage

supportsSqlType

void supportsSqlType(int sqlType)
              throws MappingException

Determine if the key generator supports a given sql type.

Parameters:

sqlType -

Throws:

MappingException

getStyle

byte getStyle()

Style of the key generator: BEFORE_INSERT, DURING_INSERT or AFTER_INSERT.

patchSQL

java.lang.String patchSQL(java.lang.String insert,
                          java.lang.String primKeyName)
                   throws MappingException

Gives a possibility to patch the Castor-generated SQL statement for INSERT (indended mainly for DURING_INSERT style of key generators, other key generators usually simply return the passed parameter). The original statement contains primary key column on the first place for BEFORE_INSERT style and doesn't contain it for the other styles. This method is called once for each class and must return String with '?' that can be passed to CallableStatement (for DURING_INSERT style) or to PreparedStatement (for the others). Then for each record being created actual field values are substituted, starting from the primary key value for BEFORE_INSERT style, of starting from the first of other fields for the other styles. The DURING_INSERT key generator must add one OUT parameter to the end of the parameter list, which will return the generated identity. For example, ReturningKeyGenerator for Oracle8i transforms "INSERT INTO tbl (pk, fld1, ...,fldN) VALUES (?,?...,?)" to "INSERT INTO tbl (pk, fld1, ...) VALUES (seq.nextval,?....,?) RETURNING pk INTO ?". DURING_INSERT key generator also may be implemented as a stored procedure.

Parameters:

insert - Castor-generated INSERT statement

primKeyName - The primary key name

Throws:

MappingException

isInSameConnection

boolean isInSameConnection()

Is key generated in the same connection as INSERT? For DURING_INSERT style this method is never called.