|
Kim, thanks for looking at this. See my comments below.
----- The only user-visible API change for this feature seems to be the addition of the maxStatements property to ClientConnectionPoolDataSource. Is that correct? ----- Yes, and it is also true for ClientConnectionPoolDataSource40. ------ I assume that a developer must use these data sources in order to use statement caching. ----- Correct. ----- I'm assuming that you'd also have to set various other connection properties before calling getPooledConnection(). ---- Yes, you also have to set whatever other properties you need to connect to your database. getPooledConnection creates the physical connection to the database, PooledConnection.getConnection() creates a logical connection. The typical usage is that you create many logical connections off the physical one, but only one can be active at any given time. Also, as soon as a new logical connection is created, the previous one is closed. ----- This new feature belongs in the Admin Guide, since that is where the client driver is discussed. ----- That makes sense, currently the feature is for the client driver only. A user will (transparently) interact with the cache through Connection.prepareStatement/-Call and PreparedStatement/CallableStatement.close. The former possibly takes a statement out of the cache, the latter possibly puts a statement into the cache. Thanks for your help confirming what needs to be covered here, Kristiaan.
I'm attaching I think the documentation looks good.
The following sentence caught my attention though: "Next, use a javax.sql.PooledConnection object to obtain a physical connection, and a javax.sql.Connection object to obtain a logical connection." You use ClientConnectionPoolDataSource.getPooledConnection to obtain the physical connection, the PooledConnection object is the physical connection. Then you use PooledConnection.getConnection to obtain the logical connection, which will implement java.sql.Connection just as a "normal" connection would. Do you see a way to rewrite the sentence? The piece of information that you need to use getPooledConnection is important, because I think Derby has a getConnection method on the ClientConnectionPoolDataSource object. Using the latter method will not enable statement caching. BTW; PooledConnection is in the package javax.sql, whereas Connection is in java.sql. Thanks, Thanks very much, Kristiaan, for catching those things. I hope this patch fixes them. I'm attaching
I also put the steps in a numbered list to make them clearer, added a link to the example, and fixed the vertical spacing at the top of the example (the problem only showed up in the PDF and one-file HTML). Revision 2 of the patch looks good, Kim.
+1 to commit. Thanks very much, Kristiaan.
Committed patch Merged to 10.4 branch at revision 681689. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
 |
|
Task
Closed
Minor
Add client side JDBC statement pool documentation
I would expect this feature also to work for ClientConnectionPoolDataSource40, though I don't see any explicit statement to this effect in
DERBY-3313or its subtasks (I might have missed it, though). Is that true?I assume that a developer must use these data sources in order to use statement caching.
The package.html file has sample code that does the following (comments removed):
ClientConnectionPoolDataSource cpds = new ClientConnectionPoolDataSource();
cpds.setMaxStatements(20);
PooledConnection pc = cpds.getPooledConnection();
I'm assuming that you'd also have to set various other connection properties before calling getPooledConnection().
This new feature belongs in the Admin Guide, since that is where the client driver is discussed. (The Developer's Guide deals almost entirely with the embedded driver.) The information should probably be added to cadminnsdatasources.dita (Accessing the Network Server by using a DataSource), and another example should be added to the subtopic radminnsdatasourcexmp.dita (DataSource access example) showing the use of the statement cache. Does this make sense? I'll see if there are other places where it would make sense to mention statement caching.