Batch insert operations are intended to be used whenever a large amount of records are to be inserted into the database. By batching operations together, the number of round trips to the database is reduced and performance is improved.
Batch insert operations have a similar signature to non-standard insert operations and can be called in the same way. However, when a batch insert is invoked the record is not written immediately to the database. The insert statement is instead added to a batch of statements stored locally by the Cúram infrastructure by calling the java.sql.PreparedStatement. addBatch method. Once the batch has reached the desired size, it must be executed by calling the $execute method of the operation.
This means that batched inserts or modifies cannot be spread across multiple client invocations in an online environment because all entity objects are destroyed at the end of each invocation (transaction).
The $execute method of the operation calls the executeBatch method of java.sql.PreparedStatement and returns the result of this call which is an array of integers (int []). Each entry in this array corresponds to one statement in the batch and indicates how many records were affected by that statement. For example, for a successful batch of inserts, each entry of the array should be 1 to indicate that each statement caused one record to be written to the database. If one statement violated a unique constraint, its corresponding array entry would contain a zero. A returned value of java.sql.Statement.EXECUTE_FAILED indicates that the command failed to execute successfully.
The JDK documentation for java.sql.PreparedStatement provides further details regarding the information in this array, and how queued statements are executed.
The maximum number of statements in a batch is determined by the application property curam.db.batch.limit (default value = 30), or can be set for an individual operation by calling its $setBatchSize(int) method. The optimal size of a batch depends on many factors such as record size, database configuration and database vendor and can be different for each individual batch operation. It is the responsibility of the developer or DBA to determine this value.
If the batch limit is exceeded, an AppException (INFRASTRUCTURE.ID_BATCH_SIZE_LIMIT_HAS_BEEN_REACHED) is thrown by the batch insert operation. In this case the developer should simply call the $execute method of the operation, and then continue as before.