Index: cpa/src/main/java/org/castor/cpa/persistence/sql/keygen/HighLowKeyGenerator.java =================================================================== --- cpa/src/main/java/org/castor/cpa/persistence/sql/keygen/HighLowKeyGenerator.java (revision 8352) +++ cpa/src/main/java/org/castor/cpa/persistence/sql/keygen/HighLowKeyGenerator.java (working copy) @@ -77,8 +77,11 @@ private final Map> _handlers = new HashMap>(); + /** Persistence factory for the database engine the entity is persisted in. + * Used to format the SQL statement. */ private final PersistenceFactory _factory; + /** Databse engine type. */ private final int _sqlType; /** Sequence table name. */ @@ -105,6 +108,12 @@ /** * Initialize the HIGH-LOW key generator. + * + * @param factory A PersistenceFactory instance. + * @param params Database engine specific parameters. + * @param sqlType A SQLTypidentifier. + * @throws MappingException if this key generator is not compatible with the + * persistance factory. */ public HighLowKeyGenerator(final PersistenceFactory factory, final Properties params, final int sqlType) throws MappingException { Index: cpa/src/main/java/org/castor/cpa/persistence/sql/keygen/IdentityKeyGenerator.java =================================================================== --- cpa/src/main/java/org/castor/cpa/persistence/sql/keygen/IdentityKeyGenerator.java (revision 8352) +++ cpa/src/main/java/org/castor/cpa/persistence/sql/keygen/IdentityKeyGenerator.java (working copy) @@ -52,6 +52,7 @@ * Used to format the SQL statement. */ private final PersistenceFactory _factory; + /** Particular type handler instance. */ private KeyGeneratorTypeHandler _typeHandler; //----------------------------------------------------------------------------------- @@ -85,6 +86,11 @@ initSqlTypeHandler(sqlType); } + /** + * Initialize the Handler based on SQL Type. + * + * @param sqlType A SQLTypidentifier. + */ private void initSqlTypeHandler(final int sqlType) { if (sqlType == Types.INTEGER) { _typeHandler = new KeyGeneratorTypeHandlerInteger(true); Index: cpa/src/main/java/org/castor/cpa/persistence/sql/keygen/KeyGenerator.java =================================================================== --- cpa/src/main/java/org/castor/cpa/persistence/sql/keygen/KeyGenerator.java (revision 8354) +++ cpa/src/main/java/org/castor/cpa/persistence/sql/keygen/KeyGenerator.java (working copy) @@ -62,16 +62,19 @@ /** * Is key generated in the same connection as INSERT? * For DURING_INSERT style this method is never called. + * + * @return {code}True{code} If this instance is in same JDBC Connection. */ boolean isInSameConnection(); /** * Executes the SQL statement after preparing the PreparedStatement. * - * @param database + * @param database A database instance. * @param conn An Open JDBC connection. * @param identity Identity of the object to insert. - * @param entity + * @param entity Entity instance from which field values to be fetached to + * bind with sql insert statement. * @return Identity * @throws PersistenceException If failed to insert record into database. This could happen * if a database access error occurs, If identity size mismatches, unable to retrieve Index: cpa/src/main/java/org/castor/cpa/persistence/sql/keygen/MaxKeyGenerator.java =================================================================== --- cpa/src/main/java/org/castor/cpa/persistence/sql/keygen/MaxKeyGenerator.java (revision 8352) +++ cpa/src/main/java/org/castor/cpa/persistence/sql/keygen/MaxKeyGenerator.java (working copy) @@ -48,14 +48,22 @@ * Commons Logging instance used for all logging. */ private static final Log LOG = LogFactory.getLog(MaxKeyGenerator.class); + /** Persistence factory for the database engine the entity is persisted in. + * Used to format the SQL statement. */ private final PersistenceFactory _factory; + /** Particular type handler instance. */ private KeyGeneratorTypeHandler _typeHandler; //----------------------------------------------------------------------------------- /** * Initialize the MAX key generator. + * + * @param factory A PersistenceFactory instance. + * @param sqlType A SQLTypidentifier. + * @throws MappingException if this key generator is not compatible with the + * persistance factory. */ public MaxKeyGenerator(final PersistenceFactory factory, final int sqlType) throws MappingException { @@ -72,6 +80,11 @@ initSqlTypeHandler(sqlType); } + /** + * Initialize the Handler based on SQL Type. + * + * @param sqlType A SQLTypidentifier. + */ private void initSqlTypeHandler(final int sqlType) { if (sqlType == Types.INTEGER) { _typeHandler = new KeyGeneratorTypeHandlerInteger(false); Index: cpa/src/main/java/org/castor/cpa/persistence/sql/keygen/SequenceAfterKeyGenerator.java =================================================================== --- cpa/src/main/java/org/castor/cpa/persistence/sql/keygen/SequenceAfterKeyGenerator.java (revision 8352) +++ cpa/src/main/java/org/castor/cpa/persistence/sql/keygen/SequenceAfterKeyGenerator.java (working copy) @@ -31,16 +31,57 @@ import org.exolab.castor.mapping.MappingException; import org.exolab.castor.persist.spi.PersistenceFactory; +/** + * Extends AbstractAfterKeyGenerator and implements additional methods specific + * to Sequence Key generator. It invovles the fetching the Table ID after the + * record is inserted into the table. + * + * @author Ahmad Hassan + * @author Ralf Joachim + * @version $Revision$ $Date: 2009-07-13 17:22:43 (Tue, 28 Jul 2009) $ + */ public final class SequenceAfterKeyGenerator extends AbstractAfterKeyGenerator { //----------------------------------------------------------------------------------- + /** + * Implements database engine specific subclasses which generates the + * database specific query systex for fetching ID from the database and then + * SequenceKeyGetValueHandler runs that query using JDBC connection. + */ private abstract class SequenceKeyGenValueHandler { + + /** key generator for producing identities for objects after + * they are created in the database. + */ private KeyGenerator _keyGenerator; + + /** Particular type handler instance. */ private KeyGeneratorTypeHandler _typeHandler; + /** Abstract method that must be implemented by subclasses of this class and + * responsible for running query to get identity. + * + * @param conn An open JDBC connection. + * @param tableName Name of the table from which identity will be fetched. + * @param primKeyName Primary key of the table. + * @param props database engine specific properties. + * + * @return Identity. + * @throws Exception If fails to retrieve identity. + */ protected abstract Object getValue(Connection conn, String tableName, String primKeyName, Properties props) throws Exception; + /** + * Method that runs sql query using the provided JDBC connection. + * + * @param sql A sql query + * @param conn An open JDBC connection + * + * @return Query results containing the identity value. + * @throws PersistenceException If fails to retrive identity value from resultset or + * database error occurs. + */ public Object getValue(final String sql, final Connection conn) throws PersistenceException { PreparedStatement stmt = null; @@ -63,16 +104,42 @@ } } + /** + * Sets the KeyGenerator instance value. + * + * @param generator Provided keyGenerator instance. + */ public void setGenerator(final KeyGenerator generator) { _keyGenerator = generator; } + /** + * Sets typeHandler object with the value provided. + * + * @param typeHandler Provided typeHandler instance. + */ public void setTypeHandler(final KeyGeneratorTypeHandler typeHandler) { _typeHandler = typeHandler; } } + /** + * Implements SequenceKeyGenValueHandler that generates sql query used as + * a default query except for the particular database engine types. + */ private class DefaultType extends SequenceKeyGenValueHandler { + + /** + * Generates sql select query for fetching identity and then calss the + * base class getValue method of query execution. + * + * @param conn An open JDBC connection. + * @param tableName Name of the table from which identity will be fetched. + * @param primKeyName Primary key of the table. + * @param props database engine specific properties. + * @return ResutlSet containing identity. + * @throws Exception If database error occurs. + */ protected Object getValue(final Connection conn, final String tableName, final String primKeyName, final Properties props) throws Exception { return getValue("SELECT " @@ -81,7 +148,23 @@ } } + /** + * Implements SequenceKeyGenValueHandler that generates sql query for fetching + * identity from Postgressql database. + */ private class PostgresqlType extends SequenceKeyGenValueHandler { + + /** + * Generates sql select query for fetching identity and then calss the + * base class getValue method of query execution. + * + * @param conn An open JDBC connection. + * @param tableName Name of the table from which identity will be fetched. + * @param primKeyName Primary key of the table. + * @param props database engine specific properties. + * @return ResutlSet containing identity. + * @throws Exception If database error occurs. + */ protected Object getValue(final Connection conn, final String tableName, final String primKeyName, final Properties props) throws Exception { String sql = "SELECT currval('\"" + getSeqName(tableName, primKeyName) + "\"')"; @@ -95,16 +178,20 @@ * Commons Logging instance used for all logging. */ private static final Log LOG = LogFactory.getLog(SequenceAfterKeyGenerator.class); + /** Key length used for KeyGeneratorTypeHandlerString. */ private static final int STRING_KEY_LENGTH = 8; + /** Persistence factory for the database engine the entity is persisted in. + * Used to format the SQL statement. */ private PersistenceFactory _factory; - - private boolean _triggerPresent; + /** Sequence name associated with the table. */ private String _seqName; + /** Particular type handler instance. */ private KeyGeneratorTypeHandler _typeHandler; + /** Sequence Key handler type. */ private SequenceKeyGenValueHandler _type = null; //----------------------------------------------------------------------------------- @@ -114,7 +201,7 @@ * {@link #generateKey} is called after INSERT. * * @param factory A PersistenceFactory instance. - * @param params + * @param params Database engine specific parameters. * @param sqlType A SQLTypidentifier. * @throws MappingException if this key generator is not compatible with the * persistance factory. @@ -124,7 +211,6 @@ super(factory, params); _factory = factory; - _triggerPresent = "true".equals(params.getProperty("trigger", "false")); _seqName = params.getProperty("sequence", "{0}_seq"); initSqlTypeHandler(sqlType); @@ -148,10 +234,19 @@ } } + /** + * Formats the sequence name using name of the table and ID. + * + * @param tableName Name of the table. + * @param primKeyName ID of the table. + * @return Strign representing formatted sequence name. + */ private String getSeqName(final String tableName, final String primKeyName) { return MessageFormat.format(_seqName, new Object[] {tableName, primKeyName}); } + /** Instantiate class properties i.e type and typeHandler based on the + * factory type. */ private void initType() { if (PostgreSQLFactory.FACTORY_NAME.equals(_factory.getFactoryName())) { _type = new PostgresqlType(); Index: cpa/src/main/java/org/castor/cpa/persistence/sql/keygen/SequenceBeforeKeyGenerator.java =================================================================== --- cpa/src/main/java/org/castor/cpa/persistence/sql/keygen/SequenceBeforeKeyGenerator.java (revision 8352) +++ cpa/src/main/java/org/castor/cpa/persistence/sql/keygen/SequenceBeforeKeyGenerator.java (working copy) @@ -34,16 +34,57 @@ import org.exolab.castor.mapping.MappingException; import org.exolab.castor.persist.spi.PersistenceFactory; +/** + * Extends AbstractBeforeKeyGenerator and implements additional methods specific + * to Sequence Key generator. It invovles the fetching the Table ID before the + * record is inserted into the table. + * + * @author Ahmad Hassan + * @author Ralf Joachim + * @version $Revision$ $Date: 2009-07-13 17:22:43 (Tue, 28 Jul 2009) $ + */ public final class SequenceBeforeKeyGenerator extends AbstractBeforeKeyGenerator { //----------------------------------------------------------------------------------- + /** + * Implements database engine specific subclasses which generates the + * database specific query systex for fetching ID from the database and then + * SequenceKeyGetValueHandler runs that query using JDBC connection. + */ private abstract class SequenceKeyGenValueHandler { + + /** key generator for producing identities for objects after + * they are created in the database. + */ private KeyGenerator _keyGenerator; + + /** Particular type handler instance. */ private KeyGeneratorTypeHandler _typeHandler; + /** Abstract method that must be implemented by subclasses of this class and + * responsible for running query to get identity. + * + * @param conn An open JDBC connection. + * @param tableName Name of the table from which identity will be fetched. + * @param primKeyName Primary key of the table. + * @param props database engine specific properties. + * + * @return Identity. + * @throws Exception If fails to retrieve identity. + */ protected abstract Object getValue(Connection conn, String tableName, String primKeyName, Properties props) throws Exception; + /** + * Method that runs sql query using the provided JDBC connection. + * + * @param sql A sql query + * @param conn An open JDBC connection + * + * @return Query results containing the identity value. + * @throws PersistenceException If fails to retrive identity value from resultset or + * database error occurs. + */ public Object getValue(final String sql, final Connection conn) throws PersistenceException { PreparedStatement stmt = null; @@ -66,16 +107,42 @@ } } + /** + * Sets the KeyGenerator instance value. + * + * @param generator Provided keyGenerator instance. + */ public void setGenerator(final KeyGenerator generator) { _keyGenerator = generator; } + /** + * Sets typeHandler object with the value provided. + * + * @param typeHandler Provided typeHandler instance. + */ public void setTypeHandler(final KeyGeneratorTypeHandler typeHandler) { _typeHandler = typeHandler; } } + /** + * Implements SequenceKeyGenValueHandler that generates sql query used as + * a default query except for the particular database engine types. + */ private class DefaultType extends SequenceKeyGenValueHandler { + + /** + * Generates sql select query for fetching identity and then calss the + * base class getValue method of query execution. + * + * @param conn An open JDBC connection. + * @param tableName Name of the table from which identity will be fetched. + * @param primKeyName Primary key of the table. + * @param props database engine specific properties. + * @return ResutlSet containing identity. + * @throws Exception If database error occurs. + */ protected Object getValue(final Connection conn, final String tableName, final String primKeyName, final Properties props) throws Exception { return getValue("SELECT " @@ -84,7 +151,23 @@ } } + /** + * Implements SequenceKeyGenValueHandler that generates sql query for fetching + * identity from Postgressql database. + */ private class PostgresqlType extends SequenceKeyGenValueHandler { + + /** + * Generates sql select query for fetching identity and then calss the + * base class getValue method of query execution. + * + * @param conn An open JDBC connection. + * @param tableName Name of the table from which identity will be fetched. + * @param primKeyName Primary key of the table. + * @param props database engine specific properties. + * @return ResutlSet containing identity. + * @throws Exception If database error occurs. + */ protected Object getValue(final Connection conn, final String tableName, final String primKeyName, final Properties props) throws Exception { String sql = "SELECT nextval('\"" + getSeqName(tableName, primKeyName) + "\"')"; @@ -92,7 +175,23 @@ } } + /** + * Implements SequenceKeyGenValueHandler that generates sql query for fetching + * identity from DB2 database. + */ private class DB2Type extends SequenceKeyGenValueHandler { + + /** + * Generates sql select query for fetching identity and then calss the + * base class getValue method of query execution. + * + * @param conn An open JDBC connection. + * @param tableName Name of the table from which identity will be fetched. + * @param primKeyName Primary key of the table. + * @param props database engine specific properties. + * @return ResutlSet containing identity. + * @throws Exception If database error occurs. + */ protected Object getValue(final Connection conn, final String tableName, final String primKeyName, final Properties props) throws Exception { return getValue("SELECT nextval FOR " + getSeqName(tableName, primKeyName) @@ -100,7 +199,23 @@ } } + /** + * Implements SequenceKeyGenValueHandler that generates sql query for fetching + * identity from Interbase database. + */ private class InterbaseType extends SequenceKeyGenValueHandler { + + /** + * Generates sql select query for fetching identity and then calss the + * base class getValue method of query execution. + * + * @param conn An open JDBC connection. + * @param tableName Name of the table from which identity will be fetched. + * @param primKeyName Primary key of the table. + * @param props database engine specific properties. + * @return ResutlSet containing identity. + * @throws Exception If database error occurs. + */ protected Object getValue(final Connection conn, final String tableName, final String primKeyName, final Properties props) throws Exception { return getValue("SELECT gen_id(" + getSeqName(tableName, primKeyName) + "," @@ -108,7 +223,23 @@ } } + /** + * Implements SequenceKeyGenValueHandler that generates sql query for fetching + * identity from oracle database. + */ private class OracleType extends SequenceKeyGenValueHandler { + + /** + * Generates sql select query for fetching identity and then calss the + * base class getValue method of query execution. + * + * @param conn An open JDBC connection. + * @param tableName Name of the table from which identity will be fetched. + * @param primKeyName Primary key of the table. + * @param props database engine specific properties. + * @return ResutlSet containing identity. + * @throws Exception If database error occurs. + */ protected Object getValue(final Connection conn, final String tableName, final String primKeyName, final Properties props) throws Exception { return getValue("SELECT " @@ -123,18 +254,23 @@ * Commons Logging instance used for all logging. */ private static final Log LOG = LogFactory.getLog(SequenceBeforeKeyGenerator.class); + /** Key length used for KeyGeneratorTypeHandlerString. */ private static final int STRING_KEY_LENGTH = 8; + /** Persistence factory for the database engine the entity is persisted in. + * Used to format the SQL statement. */ private PersistenceFactory _factory; - - private boolean _triggerPresent; + /** Sequence name associated with the table. */ private String _seqName; + /** Value used in fetching identity from Interbase database. */ private int _increment; + /** Particular type handler instance. */ private KeyGeneratorTypeHandler _typeHandler; + /** Sequence Key Handler type. */ private SequenceKeyGenValueHandler _type = null; //----------------------------------------------------------------------------------- @@ -144,7 +280,7 @@ * {@link #generateKey} is called before INSERT. * * @param factory A PersistenceFactory instance. - * @param params + * @param params Database specific properties. * @param sqlType A SQLTypidentifier. * @throws MappingException if this key generator is not compatible with the * persistance factory. @@ -153,7 +289,6 @@ final int sqlType) throws MappingException { super(factory); _factory = factory; - _triggerPresent = "true".equals(params.getProperty("trigger", "false")); _seqName = params.getProperty("sequence", "{0}_seq"); try { @@ -166,6 +301,11 @@ initType(); } + /** + * Initialize the Handler based on SQL Type. + * + * @param sqlType A SQLTypidentifier. + */ protected void initSqlTypeHandler(final int sqlType) { if (sqlType == Types.INTEGER) { _typeHandler = new KeyGeneratorTypeHandlerInteger(true); @@ -178,10 +318,19 @@ } } + /** + * Formats the sequence name using name of the table and ID. + * + * @param tableName Name of the table. + * @param primKeyName ID of the table. + * @return Strign representing formatted sequence name. + */ private String getSeqName(final String tableName, final String primKeyName) { return MessageFormat.format(_seqName, new Object[] {tableName, primKeyName}); } + /** Instantiate class properties i.e type and typeHandler based on the + * factory type. */ private void initType() { String factoryName = _factory.getFactoryName(); if (InterbaseFactory.FACTORY_NAME.equals(factoryName)) { Index: cpa/src/main/java/org/castor/cpa/persistence/sql/keygen/SequenceDuringKeyGenerator.java =================================================================== --- cpa/src/main/java/org/castor/cpa/persistence/sql/keygen/SequenceDuringKeyGenerator.java (revision 8355) +++ cpa/src/main/java/org/castor/cpa/persistence/sql/keygen/SequenceDuringKeyGenerator.java (working copy) @@ -44,23 +44,55 @@ import org.exolab.castor.persist.spi.Identity; /** - * SEQUENCE key generator. + * Implements methods specific to Sequence During Key generator. It invovles the + * ID generation while constructing the sql statement. * - * @author Oleg Nitz - * @author Bruce Snyder - * @version $Revision: 8241 $ $Date: 2006-04-13 06:47:36 -0600 (Thu, 13 Apr 2006) $ - * @see SequenceKeyGeneratorFactory + * @author Ahmad Hassan + * @author Ralf Joachim + * @version $Revision$ $Date: 2009-07-13 17:22:43 (Tue, 28 Jul 2009) $ */ public final class SequenceDuringKeyGenerator extends AbstractKeyGenerator { //----------------------------------------------------------------------------------- + /** + * Implements database engine specific subclasses which generates the + * database specific query systex for fetching ID from the database and then + * SequenceKeyGetValueHandler runs that query using JDBC connection. + */ private abstract class SequenceKeyGenValueHandler { + + /** key generator for producing identities for objects after + * they are created in the database. + */ private KeyGenerator _keyGenerator; + + /** Particular type handler instance. */ private KeyGeneratorTypeHandler _typeHandler; + /** Abstract method that must be implemented by subclasses of this class and + * responsible for running query to get identity. + * + * @param conn An open JDBC connection. + * @param tableName Name of the table from which identity will be fetched. + * @param primKeyName Primary key of the table. + * @param props database engine specific properties. + * + * @return Identity. + * @throws Exception If fails to retrieve identity. + */ protected abstract Object getValue(Connection conn, String tableName, String primKeyName, Properties props) throws Exception; + /** + * Method that runs sql query using the provided JDBC connection. + * + * @param sql A sql query + * @param conn An open JDBC connection + * + * @return Query results containing the identity value. + * @throws PersistenceException If fails to retrive identity value from resultset or + * database error occurs. + */ public Object getValue(final String sql, final Connection conn) throws PersistenceException { PreparedStatement stmt = null; @@ -83,16 +115,41 @@ } } + /** + * Sets the KeyGenerator instance value. + * + * @param generator Provided keyGenerator instance. + */ public void setGenerator(final KeyGenerator generator) { _keyGenerator = generator; } + /** + * Sets typeHandler object with the value provided. + * + * @param typeHandler Provided typeHandler instance. + */ public void setTypeHandler(final KeyGeneratorTypeHandler typeHandler) { _typeHandler = typeHandler; } } + /** + * Implements SequenceKeyGenValueHandler that generates sql query used as + * a default query except for the particular database engine types. + */ private class DefaultType extends SequenceKeyGenValueHandler { + /** + * Generates sql select query for fetching identity and then calss the + * base class getValue method of query execution. + * + * @param conn An open JDBC connection. + * @param tableName Name of the table from which identity will be fetched. + * @param primKeyName Primary key of the table. + * @param props database engine specific properties. + * @return ResutlSet containing identity. + * @throws Exception If database error occurs. + */ protected Object getValue(final Connection conn, final String tableName, final String primKeyName, final Properties props) throws Exception { // used for orcale and sap after_insert @@ -108,16 +165,23 @@ * Commons Logging instance used for all logging. */ private static final Log LOG = LogFactory.getLog(SequenceDuringKeyGenerator.class); + /** Key length used for KeyGeneratorTypeHandlerString. */ private static final int STRING_KEY_LENGTH = 8; + /** Persistence factory for the database engine the entity is persisted in. + * Used to format the SQL statement. */ private PersistenceFactory _factory; + /** True if trigger is present for specific database engien. */ private boolean _triggerPresent; + /** Sequence name associated with the table. */ private String _seqName; + /** Particular type handler instance. */ private KeyGeneratorTypeHandler _typeHandler; + /** Databse engine type. */ private SequenceKeyGenValueHandler _type = null; /** SQL engine for all persistence operations at entities of the type this @@ -144,7 +208,7 @@ * {@link #generateKey} is never called. * * @param factory A PersistenceFactory instance. - * @param params + * @param params Database engine specific properties. * @param sqlType A SQLTypidentifier. * @throws MappingException if this key generator is not compatible with the * persistance factory. @@ -160,6 +224,11 @@ initType(); } + /** + * Initialize the Handler based on SQL Type. + * + * @param sqlType A SQLTypidentifier. + */ protected void initSqlTypeHandler(final int sqlType) { if (sqlType == Types.INTEGER) { _typeHandler = new KeyGeneratorTypeHandlerInteger(true); @@ -172,10 +241,19 @@ } } + /** + * Formats the sequence name using name of the table and ID. + * + * @param tableName Name of the table. + * @param primKeyName ID of the table. + * @return Strign representing formatted sequence name. + */ private String getSeqName(final String tableName, final String primKeyName) { return MessageFormat.format(_seqName, new Object[] {tableName, primKeyName}); } + /** Instantiate class properties i.e type and typeHandler based on the + * factory type. */ private void initType() { _type = new DefaultType(); _type.setGenerator(this); Index: src/doc/release-notes.xml =================================================================== --- src/doc/release-notes.xml (revision 8355) +++ src/doc/release-notes.xml (working copy) @@ -91,6 +91,26 @@ ]]> + + + Add missing javadoc to KeyGenerator interface and its implementations. + + + Ahmad Hassan + ahmad.hassan@gmail.com + + + Ralf Joachim + ralf.joachim@syscon.eu + + + Ahmad Hassan + ahmad.hassan@gmail.com + + Enh. + JDO + 20090811 + Improve SQL Insert class hierarchy to treat Sequence NextVal as an Expression.