com.buzzsurf.sql
Class Insert

java.lang.Object
  com.buzzsurf.sql.BuzzSQL
      com.buzzsurf.sql.Update
          com.buzzsurf.sql.Insert

public class Insert
extends Update

An Insert object inserts new rows to a table and queries the number of rows inserted. It is a combination of the underlying JDBC classes;

• java.sql.Connection
• java.sql.PreparedStatement

After execution, you may get the number of rows inserted by calling getInsertCount() or getRowCount().

If the database table contains an auto increment column, the value can be retrieved using getGeneratedKey(). This method allows the retrieval of only the first auto increment column in the table, and only as an int. BuzzSQL always allows access to the underlying base JDBC object if you need more control, such as to retrieve other auto increment column values.

com.buzzsurf.sql.Insert extends com.buzzsurf.sql.Update, but add only minor functionality beyond that which is contained in the parent class; getGeneratedKey() being the primary addition. Therefore you may choose to use com.buzzsurf.sql.Update to perform inserts if it helps to streamline your object structure.

As an example, the following code fragment creates an Insert object using the automatic default connection to the database. The SQL statement is passed via constructor, and the arguments are passed using the setArgs(Object...) method. execute() is called to execute the database call, and then the primary key column value is retrieved using getGeneratedKey(). The object is then closed to cleanup any resources and return the connection to the pool.

 Insert insert = new Insert("insert into example.table_example1(col_str, col_int) values (?,?)")
 insert.setArgs("asdf", 123);
 insert.execute();
 int pk = insert.getGeneratedKey();
 System.out.println(pk);
 insert.close();
 

Note: This code does not handle exceptions. You normally should wrap your calls in try/catch/finally blocks to handle any problems. It is advisable to put your close() call in a finally block to insure the connection is always released.

Author:

Paul Cowan (www.buzzsurf.com/sql)

See Also:

BuzzSQL, Update

Field Summary

Fields inherited from class com.buzzsurf.sql.Update

rowCount

Fields inherited from class com.buzzsurf.sql.BuzzSQL

args, con, DATABASE_FORMATTER, dataSourceName, sql, stmt, usingExplicitConnection

Constructor Summary

Insert()
A zero argument constructor is provided for simplified operation with JavBeans, SOAP, and reflection scenarios where having such a constructor is necessary or convenient.

Insert(java.lang.String sql)
A single argument constructor that accepts your SQL statement and uses the default DataSource.

Insert(java.lang.String sql, java.sql.Connection con)
A dual argument constructor that accepts your SQL statement and a java.sql.Connection object.

Insert(java.lang.String sql, java.lang.String dataSourceName)
A dual argument constructor that accepts your SQL statement and the explicit name of a DataSource to use.

Method Summary

Insert	execute() During execution a database connection is obtained (if needed), SQL and arguments are merged, and the PreparedStatement is executed against the database.
int	getGeneratedKey() If the database table contains an auto increment column, the value can be retrieved using getGeneratedKey().
int	getInsertCount() Get the number of rows inserted.

Methods inherited from class com.buzzsurf.sql.Update

getRowCount, getUpdateCount

Methods inherited from class com.buzzsurf.sql.BuzzSQL

addArgs, close, close, getArgs, getConnection, getDataSourceName, getReleaseInfo, getSQL, getStatement, merge, prepare, queryToString, setArgs, setConnection, setDataSourceName, setSQL, usingExplicitConnection

Methods inherited from class java.lang.Object

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

Constructor Detail

Insert

public Insert()

A zero argument constructor is provided for simplified operation with JavBeans, SOAP, and reflection scenarios where having such a constructor is necessary or convenient. At a minimum, you must call setSQL(String) before execution when using this constructor.

Insert

public Insert(java.lang.String sql)

A single argument constructor that accepts your SQL statement and uses the default DataSource.

Parameters:

sql - The SQL statement

Insert

public Insert(java.lang.String sql,
              java.lang.String dataSourceName)

A dual argument constructor that accepts your SQL statement and the explicit name of a DataSource to use.

Parameters:

sql - The SQL statement

dataSourceName - The explicit name of the dataSource to obtain a connecton from in DataSourceManager.

Insert

public Insert(java.lang.String sql,
              java.sql.Connection con)

A dual argument constructor that accepts your SQL statement and a java.sql.Connection object. This constructor provides a great deal of flexibility by allowing the use of "explicit" connections that are supplied by the user rather than being obtained automatically by BuzzSQL. Using a explicit connection also allows BuzzSQL to support database transactions.

Parameters:

sql - The SQL statement

con - The explicit database Connection

Method Detail

getInsertCount

public int getInsertCount()

Get the number of rows inserted.

Returns:

Number of rows inserted

getGeneratedKey

public int getGeneratedKey()
                    throws java.sql.SQLException

If the database table contains an auto increment column, the value can be retrieved using getGeneratedKey(). This method allows the retrieval of only the first auto increment column in the table, and only as an int. BuzzSQL always allows access to the underlying base JDBC object if you need more control, such as to retrieve other auto increment column values.

Returns:

The value or -1 if the Object is not executing or the table had no auto-increment columns.

Throws:

java.sql.SQLException - if a database access error occurs

execute

public Insert execute()
               throws java.sql.SQLException

During execution a database connection is obtained (if needed), SQL and arguments are merged, and the PreparedStatement is executed against the database. execute() throws an exception if any of these steps fails for any reason.

Typical post-execution steps are slightly different depending on the object subtype. Select based objects will obtain a ResultSet and ResultSetMetaData, while Update based objects will query and save the updated row count to a local variable.

execute() returns a reference to the current object to support method chaining. See Method Chaining for more information. You can assume execution succeeded if no exception is thrown.

Overrides:

execute in class Update

Throws:

java.sql.SQLException - if any of the executing JDBC operations failed