com.jenkov.mrpersister.itf
Interface IObjectWriter

All Known Implementing Classes:

ObjectWriter

public interface IObjectWriter

The interface represents all the functions made available by the object writer of Mr. Persister. The object writer is responsible for all writing functions in the database (insert / updateBatch / delete).

Author:

Jakob Jenkov, Jenkov Development

Method Summary

UpdateResult	delete(IObjectMapping mapping, java.lang.Object object, java.lang.String sql, java.sql.Connection connection) Deletes the record in the database coresponding to the given object.
UpdateResult	deleteBatch(IObjectMapping mapping, java.util.Collection objects, java.lang.String sql, java.sql.Connection connection) Deletes the records in the database coresponding to the given objects.
UpdateResult	deleteByPrimaryKey(IObjectMapping mapping, java.lang.Object primaryKey, java.lang.String sql, java.sql.Connection connection) Deletes the record matching the given primary key, from the table referenced in the object mapping.
UpdateResult	deleteByPrimaryKeysBatch(IObjectMapping mapping, java.util.Collection primaryKeys, java.lang.String sql, java.sql.Connection connection) Deletes the records in the database coresponding to the given primary keys.
UpdateResult	insert(IObjectMapping mapping, java.lang.Object object, java.lang.String sql, java.sql.Connection connection) Inserts the given object into the table it is mapped to in the given object mapping.
UpdateResult	insertBatch(IObjectMapping mapping, java.util.Collection objects, java.lang.String sql, java.sql.Connection connection) Inserts the objects in the objects collection into the table they are mapped to, in the given object mapping.
void	setDatabase(Database database) Sets the database that this ObjectWriter is supposed to read objects from.
UpdateResult	update(IObjectMapping mapping, java.lang.Object object, java.lang.Object oldPrimaryKeyValue, java.lang.String sql, java.sql.Connection connection) Updates the record in the database matching the value of the oldPrimaryKeyValue, with the values present in the object at the time of calling this method, according to the given object mapping.
UpdateResult	update(IObjectMapping mapping, java.lang.Object object, java.lang.String sql, java.sql.Connection connection) Updates the record in the database corresponding to the given object, with the values present in the object at the time of calling this method, according to the given object mapping.
UpdateResult	updateBatch(IObjectMapping mapping, java.util.Collection objects, java.util.Collection oldPrimaryKeys, java.lang.String sql, java.sql.Connection connection) Updates the records in the database corresponding to the objects contained in the collection passed in parameter objects.
UpdateResult	updateBatch(IObjectMapping mapping, java.util.Collection objects, java.lang.String sql, java.sql.Connection connection) Updates the records in the database corresponding to the objects contained in the collection passed in parameter objects.
UpdateResult	updateOptimistic(IObjectMapping mapping, java.lang.Object object, java.lang.Object original, java.lang.String sql, java.sql.Connection connection) Updates the record in the database corresponding to the given object, with the values present in the object at the time of calling this method, according to the given object mapping.

Method Detail

setDatabase

void setDatabase(Database database)

Sets the database that this ObjectWriter is supposed to read objects from. The Database object contains information about the features the database supports.

Parameters:

database - The database to set on this object reader.

insert

UpdateResult insert(IObjectMapping mapping,
                    java.lang.Object object,
                    java.lang.String sql,
                    java.sql.Connection connection)
                    throws PersistenceException

Inserts the given object into the table it is mapped to in the given object mapping.

The SQL string is used to create a PreparedStatement and must be of the format insert into [table]( [field1], [field2], [field3] (etc.)) values (?, ?, ? etc). The object writer will insert the values in a PreparedStatement internally. Therefore the sequence of the fields must be the same as the one given by objectMapping.getColumns().iterator(). The SQLGenerator class can generate a suitable SQL string for use with the object writer, so you don't have to do it yourself.

Remember to close the Connection yourself when you are done with it. This method doesn't close it.

Parameters:

mapping - The object mapping to use to insert the object as a record in the database.

object - The object to insert into the database.

sql - The SQL string used to create a PreparedStatement. See description above.

connection - The connection to the database to insert the object into.

Returns:

The number of records affected, as returned by the PreparedStatement.executeUpdate() method.

Throws:

PersistenceException - If anything goes wrong during the insertion.

insertBatch

UpdateResult insertBatch(IObjectMapping mapping,
                         java.util.Collection objects,
                         java.lang.String sql,
                         java.sql.Connection connection)
                         throws PersistenceException

Inserts the objects in the objects collection into the table they are mapped to, in the given object mapping. This method uses JDBC batch updates to do the job, meaning all insert statements are batched and sent in one go to the database.

The SQL string is used to create a PreparedStatement and must be of the format insert into [table]( [field1], [field2], [field3] (etc.)) values (?, ?, ? etc). The object writer will insert the values in a PreparedStatement internally. Therefore the sequence of the fields must be the same as the one given by objectMapping.getColumns().iterator(). The SQLGenerator class can generate a suitable SQL string for use with the object writer, so you don't have to do it yourself.

Remember to close the Connection yourself when you are done with it. This method doesn't close it.

Parameters:

mapping - The object mapping to use to insert the object as a record in the database.

objects - The objects to insert into the database.

sql - The SQL string used to create a PreparedStatement. See description above.

connection - The connection to the database to insert the object into.

Returns:

An array containing the number of records affected by each insert in the batch, as returned by the PreparedStatement.executeBatch() method.

Throws:

PersistenceException - If anything goes wrong during the insertion.

update

UpdateResult update(IObjectMapping mapping,
                    java.lang.Object object,
                    java.lang.String sql,
                    java.sql.Connection connection)
                    throws PersistenceException

Updates the record in the database corresponding to the given object, with the values present in the object at the time of calling this method, according to the given object mapping. Do not use this method if the primary key value is also changed during the update, or this method will have no effect, or perhaps unintentional side effects. If you do use it for an update where the primary key has changed, the primary key value in the "where" clause of the SQL will contain the new primary key value. Since no records, or perhaps another existing record, matches the new, changed, primary key value, the update will have no effect. If you need to update a record including it's primary key, use the other update method.

The SQL string must be of the format update [table] set [field1]=?, [field2]=?, [field3]=? etc. where [primaryKeyField]=? The object writer will insert the values in a PreparedStatement internally. Therefore the sequence of the fields must be the same as the one given by objectMapping.getColumns().iterator(). The SQLGenerator class can generate a suitable SQL string for use with the object writer, so you don't have to do it yourself.

Remember to close the Connection yourself when you are done with it. This method doesn't close it.

Parameters:

mapping - The object mapping to use to update the objects record in the database.

object - The object to update the record for in the database, containing the values to be inserted.

sql - The SQL string to use to create the PreparedStatement.

connection - The connection to the database to update the object in.

Returns:

The number of affected records as returned by the PreparedStatement.executeUpdate()

Throws:

PersistenceException - If anything goes wrong during the update.

updateOptimistic

UpdateResult updateOptimistic(IObjectMapping mapping,
                              java.lang.Object object,
                              java.lang.Object original,
                              java.lang.String sql,
                              java.sql.Connection connection)
                              throws PersistenceException

Updates the record in the database corresponding to the given object, with the values present in the object at the time of calling this method, according to the given object mapping. The original object is used to identify the row using all values in the original. This implements optimistic locking, i.e., if the row was changed by another update, this update will return zero rows affected, and thus a signal to the invoking code that the row has been updated after the original object was read. Optimistic locking allows high concurrency without explicit locking, useful in situations where there is a low probability of the same row being updated concurrently. The original object must be of the same class as the object being updated.

The SQL string must be of the format update [table] set [field1]=?, [field2]=?, [field3]=? etc. where [primaryKey]= ? and [field1]=? and [field2]=? etc. etc The object writer will insert the values in a PreparedStatement internally. Therefore the sequence of the fields must be the same as the one given by objectMapping.getColumns().iterator(). The SQLGenerator class can generate a suitable SQL string for use with the object writer, so you don't have to do it yourself.

Remember to close the Connection yourself when you are done with it. This method doesn't close it.

Parameters:

mapping - The object mapping to use to update the objects record in the database.

object - The object to update the record for in the database, containing the values to be inserted.

orignial - The original object read from the database, containing the values to be used as update WHERE qualifiers.

sql - The SQL string to use to create the PreparedStatement.

connection - The connection to the database to update the object in.

Returns:

The number of affected records as returned by the PreparedStatement.executeUpdate()

Throws:

PersistenceException - If anything goes wrong during the update.

update

UpdateResult update(IObjectMapping mapping,
                    java.lang.Object object,
                    java.lang.Object oldPrimaryKeyValue,
                    java.lang.String sql,
                    java.sql.Connection connection)
                    throws PersistenceException

Updates the record in the database matching the value of the oldPrimaryKeyValue, with the values present in the object at the time of calling this method, according to the given object mapping. Use this method when updating records in which you also change the primary key value. This method inserts the old primary key value into the "where" clause of the PreparedStatement, so the correct record is updated.

The SQL string must be of the format update [table] set [field1]=?, [field2]=?, [field3]=? etc. where [primaryKeyField]=? The object writer will insert the values in a PreparedStatement internally. Therefore the sequence of the fields must be the same as the one given by objectMapping.getColumns().iterator(). The SQLGenerator class can generate a suitable SQL string for use with the object writer, so you don't have to do it yourself.

Remember to close the Connection yourself when you are done with it. This method doesn't close it.

Parameters:

mapping - The object mapping to use to update the objects record in the database.

object - The object to update the record for in the database, containing the values to be inserted.

oldPrimaryKeyValue - The primary key value of the record to update, meaning the value of the primary key before it was changed in the object to update.

sql - The SQL string to use to create the PreparedStatement.

connection - The connection to the database to update the object in.

Returns:

The number of affected records as returned by the PreparedStatement.executeUpdate()

Throws:

PersistenceException - If anything goes wrong during the update.

updateBatch

UpdateResult updateBatch(IObjectMapping mapping,
                         java.util.Collection objects,
                         java.lang.String sql,
                         java.sql.Connection connection)
                         throws PersistenceException

Updates the records in the database corresponding to the objects contained in the collection passed in parameter objects. The values in the objects are written to the corresponding records, according to the object mapping passed as parameter. This method uses JDBC batch updates to do the update, meaning the SQL sentences are sent to the database in larger batches/chunks, instead of sending them individually. This increases test_config of updates radically.

Do not use this method if the primary key values of the objects/records are also changed during the update. If you do, this method may have no or a wrong effect. If you do use it for updates where the primary key has changed, the primary key value in the "where" clause of the SQL will contain the new primary key value, and not the old value. Since no records, or perhaps another existing record, matches the new, changed, primary key value, the update will either have no effect, or may cause an update to the wrong record. If you need to update a record including it's primary key, use the other batch update method.

The SQL string must be of the format update [table] set [field1]=?, [field2]=?, [field3]=? etc. where [primaryKeyField]=? The object writer will insert the values in a PreparedStatement internally. Therefore the sequence of the fields must be the same as the one given by objectMapping.getColumns().iterator(). The SQLGenerator class can generate a suitable SQL string for use with the object writer, so you don't have to do it yourself.

Remember to close the Connection yourself when you are done with it. This method doesn't close it.

Parameters:

mapping - The object mapping to use to update the objects record in the database.

objects - The objects to update the records for in the database.

sql - The SQL string to use to create the PreparedStatement.

connection - The connection to the database to update the object in.

Returns:

An array containing the number of records affected by each update in the batch, as returned by the PreparedStatement.executeBatch() method.

Throws:

PersistenceException - If anything goes wrong during the update.

updateBatch

UpdateResult updateBatch(IObjectMapping mapping,
                         java.util.Collection objects,
                         java.util.Collection oldPrimaryKeys,
                         java.lang.String sql,
                         java.sql.Connection connection)
                         throws PersistenceException

Updates the records in the database corresponding to the objects contained in the collection passed in parameter objects. The values in the objects are written to the corresponding records, according to the object mapping passed as parameter. This method uses JDBC batch updates to do the update, meaning the SQL sentences are sent to the database in larger batches/chunks, instead of sending them individually. This increases test_config of updates radically.

Use this method if the primary key values of the objects/records are changed during the update. The old primary keys are used to identify the records to update. The values of the primary keys in the objects are the values the the primary keys of the records will have after the update.

The SQL string must be of the format update [table] set [field1]=?, [field2]=?, [field3]=? etc. where [primaryKeyField]=? The object writer will insert the values in a PreparedStatement internally. Therefore the sequence of the fields must be the same as the one given by objectMapping.getColumns().iterator(). The SQLGenerator class can generate a suitable SQL string for use with the object writer, so you don't have to do it yourself.

Remember to close the Connection yourself when you are done with it. This method doesn't close it.

Parameters:

mapping - The object mapping to use to update the objects record in the database.

objects - The objects to update the records for in the database.

oldPrimaryKeys - The old primary key values of the objects to update the records for in the database. The primary key value must be returned by this collection's iterator in the same sequence the objects in the objects collection's iterator. Otherwise the old primary key values will be matched with the wrong objects. By keeping objects and old primary keys in each their java.util.List this works fine.

sql - The SQL string to use to create the PreparedStatement.

connection - The connection to the database to update the object in.

Returns:

An array containing the number of records affected by each update in the batch, as returned by the PreparedStatement.executeBatch() method.

Throws:

PersistenceException - If anything goes wrong during the update.

delete

UpdateResult delete(IObjectMapping mapping,
                    java.lang.Object object,
                    java.lang.String sql,
                    java.sql.Connection connection)
                    throws PersistenceException

Deletes the record in the database coresponding to the given object. The SQL string is used to create a PreparedStatement must be of the format delete from [table] where [primaryKeyField]=?. The SQLGenerator class can generate a suitable SQL string for use with the object writer, so you don't have to do it yourself.

Remember to close the Connection yourself when you are done with it. This method doesn't close it.

Parameters:

mapping - The object mapping to use to delete this object.

object - The object to delete the record for from the database.

sql - The SQL string used to create the PreparedStatement.

connection - The connection to the database to delete the objects record from.

Returns:

The number of affected records as returned by PreparedStatement.executeUpdate()

Throws:

PersistenceException - If anything goes wrong during the deletion.

deleteBatch

UpdateResult deleteBatch(IObjectMapping mapping,
                         java.util.Collection objects,
                         java.lang.String sql,
                         java.sql.Connection connection)
                         throws PersistenceException

Deletes the records in the database coresponding to the given objects. This method uses JDBC batch updates to do the job, meaning all delete statements are batched and sent in one go to the database. The SQL string is used to create a PreparedStatement must be of the format delete from [table] where [primaryKeyField]=?. The SQLGenerator class can generate a suitable SQL string for use with the object writer, so you don't have to do it yourself.

Remember to close the Connection yourself when you are done with it. This method doesn't close it.

Parameters:

mapping - The object mapping to use to delete this object.

objects - The object to delete the record for from the database.

sql - The SQL string used to create the PreparedStatement.

connection - The connection to the database to delete the objects record from.

Returns:

The number of affected records as returned by PreparedStatement.executeUpdate()

Throws:

PersistenceException - If anything goes wrong during the deletion.

deleteByPrimaryKey

UpdateResult deleteByPrimaryKey(IObjectMapping mapping,
                                java.lang.Object primaryKey,
                                java.lang.String sql,
                                java.sql.Connection connection)
                                throws PersistenceException

Deletes the record matching the given primary key, from the table referenced in the object mapping. The SQL string is used to create a PreparedStatement must be of the format delete from [table] where [primaryKeyField]=?. The SQLGenerator class can generate a suitable SQL string for use with the object writer, so you don't have to do it yourself.

Remember to close the Connection yourself when you are done with it. This method doesn't close it.

Parameters:

mapping - The object mapping to use to delete this object.

primaryKey - The value of the primary key as an object, for instance new Integer(2) or "xyz123" etc.

sql - The SQL string used to create the PreparedStatement.

connection - The connection to the database to delete the objects record from.

Returns:

An array containing the number of records affected by each insert in the batch, as returned by the PreparedStatement.executeBatch() method.

Throws:

PersistenceException - If anything goes wrong during the deletion.

deleteByPrimaryKeysBatch

UpdateResult deleteByPrimaryKeysBatch(IObjectMapping mapping,
                                      java.util.Collection primaryKeys,
                                      java.lang.String sql,
                                      java.sql.Connection connection)
                                      throws PersistenceException

Deletes the records in the database coresponding to the given primary keys. This method uses JDBC batch updates to do the job, meaning all delete statements are batched and sent in one go to the database. The SQL string is used to create a PreparedStatement must be of the format delete from [table] where [primaryKeyField]=?. The SQLGenerator class can generate a suitable SQL string for use with the object writer, so you don't have to do it yourself.

Remember to close the Connection yourself when you are done with it. This method doesn't close it.

Parameters:

mapping - The object mapping to use to delete this object.

primaryKeys - The object to delete the record for from the database.

sql - The SQL string used to create the PreparedStatement.

connection - The connection to the database to delete the objects record from.

Returns:

The number of affected records as returned by PreparedStatement.executeUpdate()

Throws:

PersistenceException - If anything goes wrong during the deletion.