001: /*
002: * Copyright (c) 1998 - 2005 Versant Corporation
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * Versant Corporation - initial API and implementation
010: */
011: package com.versant.core.jdbc;
012:
013: import com.versant.core.jdbc.metadata.JdbcTable;
014:
015: import java.sql.Connection;
016: import java.sql.SQLException;
017: import java.sql.Statement;
018: import java.util.HashSet;
019:
020: /**
021: * These generate primary keys for new rows in tables. Instances must be
022: * thread safe.
023: */
024: public interface JdbcKeyGenerator {
025:
026: /**
027: * Add any JdbcTable instances that this key generator requires to the
028: * supplied set. This method is called once per key generator during meta
029: * data generation. Any tables returned will be added to the meta data and
030: * will get into SQL scripts and so on. If the same key generator
031: * instance is returned more than once by a factory then this method
032: * will still only be called once on the instance.
033: */
034: public void addKeyGenTables(HashSet set, JdbcMetaDataBuilder mdb);
035:
036: /**
037: * If the new key can only be detirmined after the new row has been
038: * inserted (e.g. if using a database autoincrement column) then this
039: * should return true.
040: */
041: public boolean isPostInsertGenerator();
042:
043: /**
044: * Initialize this key generator. This is called when the JDO Genie
045: * server initializes before any keys are generated. Key
046: * generators should use this to avoid popular race conditions and
047: * deadlock opportunities (e.g. multiple 'select max(id) from table'
048: * statements executing at the same time). If the same key generator
049: * instance is used on more than one class this will be called once
050: * for each class.
051: *
052: * @param className The name of the class
053: * @param classTable The table for the class
054: * @param con Connection to the DataSource for the class
055: */
056: public void init(String className, JdbcTable classTable,
057: Connection con) throws SQLException;
058:
059: /**
060: * Does this key generator require its own connection? If it does then
061: * one will be obtained to generate the key and committed after the
062: * key has been generated. This is called prior to every key generation
063: * call.
064: */
065: public boolean isRequiresOwnConnection();
066:
067: /**
068: * Generate a new primary key value for a new instance of the supplied
069: * class prior to the row being inserted. The values generated will be used
070: * to populate a new OID and then set on a PreparedStatement for the
071: * insert. This is called if isPostInsertGenerator returns false.<p>
072: * <p/>
073: * The newObjectCount parameter indicates the number of new objects that
074: * will be inserted (including this one) in the same transaction using
075: * this key generator. This may be used to optimize the behavior of the
076: * key generator or be ignored. The highlow key generator uses this value
077: * instead of its grabSize to avoid executing redundant updates and
078: * selects.<p>
079: *
080: * @param className The name of the class
081: * @param classTable The table for the class
082: * @param newObjectCount The number of new objects being created
083: * @param data The array to store the key values in.
084: * @param con Connection to the DataSource for the class.
085: * @throws SQLException on errors
086: */
087: public void generatePrimaryKeyPre(String className,
088: JdbcTable classTable, int newObjectCount, Object[] data,
089: Connection con) throws SQLException;
090:
091: /**
092: * Get extra SQL to be appended to the insert statement. This is only
093: * called for post insert key generators. Return null if no extra SQL
094: * is required. Key generators can use this as an alternative to running
095: * a separate query to get the primary key for the just inserted row.
096: */
097: public String getPostInsertSQLSuffix(JdbcTable classTable);
098:
099: /**
100: * Generate a new primary key value for a new instance of the supplied
101: * class after the row has been inserted. The values generated will be used
102: * to populate a new OID and then set on a PreparedStatement for the
103: * insert. This is called if isPostInsertGenerator returns true.
104: *
105: * @param className The name of the class
106: * @param classTable The table for the class
107: * @param data The array to store the key values in.
108: * @param con Connection to the DataSource for the class.
109: * @param stat Statement created from con. Do not close it. This will have
110: * just been used to insert the new row.
111: * @throws SQLException on errors
112: */
113: public void generatePrimaryKeyPost(String className,
114: JdbcTable classTable, Object[] data, Connection con,
115: Statement stat) throws SQLException;
116:
117: }
|