All subsequent SQL statements that your application requests to run on the indicated connection are queued in memory. pureQuery returns dummy results to your application to indicate that each statement ran successfully, even though they did not in fact run yet. You call a method that indicates to pureQuery that you are ending a batch update. At that point, pureQuery runs all of the queued SQL statements.
data.startBatch(HeterogeneousBatchKind.heterogeneousModify_);
After
you call this method, pureQuery queues all SQL statements that your
application requests to run against the same implementation of the Data interface.
pureQuery continues to queue INSERT, UPDATE, and DELETE statements
until the application calls the endBatch() method.
As pureQuery queues the statements, it returns dummy results to your
application to indicate that the statements ran successfully.Your application can request to run only INSERT, UPDATE, and DELETE statements. pureQuery rejects all other types of SQL statement and those statements are not run against your connection. If your application submits another type of SQL statement, pureQuery throws an exception and clears all of the statements that is has queued for the batch. Also, pureQuery does not run the statement that caused the exception.
If your application calls the startBatch() method again before it calls the endBatch() method, pureQuery stops the batch process, erases the statements that are queued, and throws a RuntimeException.
int[][] batchResult = data.endBatch();
pureQuery
runs the queued statements in one network trip. The method returns
a two-dimensional integer array of the update counts that the update()
and updateMany() methods would have returned. The size of the first
dimension is equal to the number of requests that your application
submitted to run SQL statements. The size of the second dimension
is either:HeterogeneousBatchKind getBatchKind();
If
a batch is in progress, the method returns heterogeneousModify_. If
no batch is in progress, the method returns hetergeneousNone_.Your application can call the updateMany() method between calling the startBatch() and endBatch() methods. The updateMany() method can run a single SQL INSERT, UPDATE, or DELETE statement multiple times against a single database object. For more information about this method, see Batch updates against single database objects by means of the updateMany() method of the Data interface.
In order to be part of the batch update, all inline methods and annotated methods that run the SQL statements must share the same Data object. This is done slightly differently, depending on the mix of pureQuery methods the user application uses.
Data data = DataFactory.getData(jdbcConnection);
data.startBatch(...);
// other Data methods that use the Data instance "data"
int[][] batchResult = data.endBatch();
After the application
calls the endBatch() method, the application can
use the Data instance for different purposes, if
you want it to.Data data = DataFactory.getData (jdbcConnection);
// now use "data" to instantiate the interfaces that will be used
EmployeeInterface emp = DataFactory.getData (EmployeeInterface.class, data);
DepartmentInterface dept = DataFactory.getData (DepartmentInterface.class, data);
data.startBatch(...);
// other Data and Annotated (EmployeeInterface and DepartmentInterface) methods
int[][] batchResult = data.endBatch();
EmployeeInterface emp = DataFactory.getData (EmployeeInterface.class, jdbcConnection);
DepartmentInterface dept = DataFactory.getData (DepartmentInterface.class, (Data) emp);
Data data = (Data) emp;
data.startBatch(...);
// other Annotated (EmployeeInterface and DepartmentInterface) methods
int[][] batchResult = data.endBatch();
To the database, all of the SQL statements between startBatch() and endBatch() represent one transaction. Calling commit() or rollback() after startBatch() and before calling endBatch() causes the batch not to run and the queued requests are lost. Finally, pureQuery throws a RuntimeException.