With RWDBInserter, inserted rows may be cached locally and sent to the database in one operation. This procedure allows more optimal use of network packet sizes and server resources than sending individual rows separately.
When the caching feature of RWDBInserter is enabled, individual rows are stored in the RWDBInserter's internal buffers and then sent all at once to the database, typically by using the database vendor's array binding interface. To enable the caching features when producing an RWDBInserter, we pass a cache size of n > 1 to its producer method. The following example shows how to use an inserter with a cache size of 5.
RWDBConnection aConn = aDb.connection(); RWDBInserter inserter = myTable.inserter(5); // 1 inserter << 0; // 2 inserter.execute(aConn); // 3 inserter << 1; // 4 inserter.execute(aConn); // 5 inserter << 2; // 6 inserter.execute(aConn); // 7 inserter << 3; // 8 inserter.execute(aConn); // 9 inserter << 4; //10 inserter.execute(aConn); //11 inserter.flush(); //12 |
In //1, we produce an inserter, with a cache size of 5, from an existing RWDBTable object. In //2 - //11, we execute the inserter, inserting a new value between each execution as we would with an inserter that does no caching. There are only two differences between coding this example and coding an example that does not use a cached inserter: in //1, we set the cache size, and in //12, we flush the contents of the cache.
Now let us see what happens to the inserter internally. In //1, when we create the inserter with a cache size of 5, the inserter creates an internal buffer big enough to hold five rows of data. In //2, we shift a row of data into the inserter. This row is stored in the first location in the inserter's internal buffers, and the inserter notes that it has cached one row.
When we execute in //3, the inserter doesn't send the row that was just shifted into itself to the database. Instead, the inserter compares the number of rows already cached to the cache size it was assigned at construction. Since the cache is not at capacity — in fact, it holds only one row at this point--the inserter returns immediately to the application.
In //6 - //7, the value of 2 is shifted into the inserter, and the inserter is executed again. The inserter notes that it has now cached two rows, and returns to the application. This pattern is repeated in //8 - //11. By the time we reach //11, the inserter has cached five rows. At this point, the number of rows cached is equal to the cache size, and the inserter sends all five cached rows to the database server at once. By using the inserter in this way, the application saves the cost of four network round trips.
As we mentioned previously, the inserter's flush() method is invoked in //12. Actually, the flush operation was performed in //11 because the method is invoked automatically whenever the cache reaches its assigned capacity. In this example, the cache reached capacity in //11. But what if it didn't? Or what if the cache size in //1 was 10? We invoke flush() in //12 because we recommend explicit invocation as good programming practice. Explicit invocation ensures that all data is sent to the server.
Copyright © Rogue Wave Software, Inc. All Rights Reserved.
The Rogue Wave name and logo, and SourcePro, are registered trademarks of Rogue Wave Software. All other trademarks are the property of their respective owners.
Provide feedback to Rogue Wave about its documentation.