You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@commons.apache.org by "Glen Mazza (JIRA)" <ji...@apache.org> on 2009/12/17 03:34:18 UTC
[jira] Created: (DBCP-312) BasicDataSource.close() method needs
JavaDoc clarification
BasicDataSource.close() method needs JavaDoc clarification
----------------------------------------------------------
Key: DBCP-312
URL: https://issues.apache.org/jira/browse/DBCP-312
Project: Commons Dbcp
Issue Type: Bug
Affects Versions: 1.3
Reporter: Glen Mazza
Priority: Minor
Hello, the JavaDoc could use clarification for the BasicDataSource.close() method.
Link: http://commons.apache.org/dbcp/apidocs/org/apache/commons/dbcp/BasicDataSource.html#close()
Text: "Close and release all connections that are currently stored in the connection pool associated with our data source. All open (active) connection remain open until closed. Once the data source has been closed, no more connections can be obtained."
I'm unsure if this method closes just idle, or both idle and active connections. This is a important distinction, because you wouldn't want to call close() if you still have some needed active connections open on various threads. The first sentence seems to indicate both active and idle threads will be closed, but the second sentence indicates that only the idle threads will be explicitly closed.
Recommend changing text to:
"Close and release all connections, whether active or idle, that are currently stored in the connection pool associated with our data source. Once the data source has been closed, no more connections can be obtained."
or (if this method closes just idle connections):
"Close and release all idle connections that are currently stored in the connection pool associated with our data source. All open (active) connections will still remain open until they are closed via the Connection close() method. Once the data source has been closed, no more connections can be obtained."
Note that, for the latter case, if BasicDataSource.close() only closes and releases idle connections, and an active DBCP Connection object subsequently has its close() method called, it's not clear whether its underlying actual JDBC connection will be released. I.e., how do you release JDBC connections on previously active DBCP Connections after BasicDataSource.close() is called?
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DBCP-312) BasicDataSource.close() method needs
JavaDoc clarification
Posted by "Glen Mazza (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DBCP-312?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12793845#action_12793845 ]
Glen Mazza commented on DBCP-312:
---------------------------------
What you've written above is absolute music to my ears, and would be excellent to replace what you presently have in the JavaDoc. I have a main program that launches many threads, each requesting/returning a connection. The main thread then closes the connection pool and exits while several of the threads may still be running. This means (1) those threads can still work with their live connection even though the main thread closed the pool, and (2) once each spawned thread is finished and closes its connection, it becomes a "real" close of the underlying JDBC connection. Great to hear. Thanks!
> BasicDataSource.close() method needs JavaDoc clarification
> ----------------------------------------------------------
>
> Key: DBCP-312
> URL: https://issues.apache.org/jira/browse/DBCP-312
> Project: Commons Dbcp
> Issue Type: Bug
> Affects Versions: 1.3
> Reporter: Glen Mazza
> Priority: Minor
>
> Hello, the JavaDoc could use clarification for the BasicDataSource.close() method.
> Link: http://commons.apache.org/dbcp/apidocs/org/apache/commons/dbcp/BasicDataSource.html#close()
> Text: "Close and release all connections that are currently stored in the connection pool associated with our data source. All open (active) connection remain open until closed. Once the data source has been closed, no more connections can be obtained."
> I'm unsure if this method closes just idle, or both idle and active connections. This is a important distinction, because you wouldn't want to call close() if you still have some needed active connections open on various threads. The first sentence seems to indicate both active and idle threads will be closed, but the second sentence indicates that only the idle threads will be explicitly closed.
> Recommend changing text to:
> "Close and release all connections, whether active or idle, that are currently stored in the connection pool associated with our data source. Once the data source has been closed, no more connections can be obtained."
> or (if this method closes just idle connections):
> "Close and release all idle connections that are currently stored in the connection pool associated with our data source. All open (active) connections will still remain open until they are closed via the Connection close() method. Once the data source has been closed, no more connections can be obtained."
> Note that, for the latter case, if BasicDataSource.close() only closes and releases idle connections, and an active DBCP Connection object subsequently has its close() method called, it's not clear whether its underlying actual JDBC connection will be released. I.e., how do you release JDBC connections on previously active DBCP Connections after BasicDataSource.close() is called?
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DBCP-312) BasicDataSource.close() method needs
JavaDoc clarification
Posted by "Phil Steitz (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DBCP-312?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12793834#action_12793834 ]
Phil Steitz commented on DBCP-312:
----------------------------------
Thanks for reporting this. I agree that the javadoc should be clearer. Your second option above is correct - close has no effect on checked out connections. What close does is close the underlying object pool. This destroys the objects contained in the pool - in this case database connections. So the physical connections corresponding to objects in the idle connection pool get closed when the datasource is closed. When checked out connections are returned to the pool (i.e., when pool clients execute close on them), they are destroyed, so the physical connections get closed at that time.
> BasicDataSource.close() method needs JavaDoc clarification
> ----------------------------------------------------------
>
> Key: DBCP-312
> URL: https://issues.apache.org/jira/browse/DBCP-312
> Project: Commons Dbcp
> Issue Type: Bug
> Affects Versions: 1.3
> Reporter: Glen Mazza
> Priority: Minor
>
> Hello, the JavaDoc could use clarification for the BasicDataSource.close() method.
> Link: http://commons.apache.org/dbcp/apidocs/org/apache/commons/dbcp/BasicDataSource.html#close()
> Text: "Close and release all connections that are currently stored in the connection pool associated with our data source. All open (active) connection remain open until closed. Once the data source has been closed, no more connections can be obtained."
> I'm unsure if this method closes just idle, or both idle and active connections. This is a important distinction, because you wouldn't want to call close() if you still have some needed active connections open on various threads. The first sentence seems to indicate both active and idle threads will be closed, but the second sentence indicates that only the idle threads will be explicitly closed.
> Recommend changing text to:
> "Close and release all connections, whether active or idle, that are currently stored in the connection pool associated with our data source. Once the data source has been closed, no more connections can be obtained."
> or (if this method closes just idle connections):
> "Close and release all idle connections that are currently stored in the connection pool associated with our data source. All open (active) connections will still remain open until they are closed via the Connection close() method. Once the data source has been closed, no more connections can be obtained."
> Note that, for the latter case, if BasicDataSource.close() only closes and releases idle connections, and an active DBCP Connection object subsequently has its close() method called, it's not clear whether its underlying actual JDBC connection will be released. I.e., how do you release JDBC connections on previously active DBCP Connections after BasicDataSource.close() is called?
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Updated: (DBCP-312) BasicDataSource.close() method needs
JavaDoc clarification
Posted by "Phil Steitz (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DBCP-312?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Phil Steitz updated DBCP-312:
-----------------------------
Fix Version/s: 1.4.1
> BasicDataSource.close() method needs JavaDoc clarification
> ----------------------------------------------------------
>
> Key: DBCP-312
> URL: https://issues.apache.org/jira/browse/DBCP-312
> Project: Commons Dbcp
> Issue Type: Bug
> Affects Versions: 1.3
> Reporter: Glen Mazza
> Priority: Minor
> Fix For: 1.4.1
>
>
> Hello, the JavaDoc could use clarification for the BasicDataSource.close() method.
> Link: http://commons.apache.org/dbcp/apidocs/org/apache/commons/dbcp/BasicDataSource.html#close()
> Text: "Close and release all connections that are currently stored in the connection pool associated with our data source. All open (active) connection remain open until closed. Once the data source has been closed, no more connections can be obtained."
> I'm unsure if this method closes just idle, or both idle and active connections. This is a important distinction, because you wouldn't want to call close() if you still have some needed active connections open on various threads. The first sentence seems to indicate both active and idle threads will be closed, but the second sentence indicates that only the idle threads will be explicitly closed.
> Recommend changing text to:
> "Close and release all connections, whether active or idle, that are currently stored in the connection pool associated with our data source. Once the data source has been closed, no more connections can be obtained."
> or (if this method closes just idle connections):
> "Close and release all idle connections that are currently stored in the connection pool associated with our data source. All open (active) connections will still remain open until they are closed via the Connection close() method. Once the data source has been closed, no more connections can be obtained."
> Note that, for the latter case, if BasicDataSource.close() only closes and releases idle connections, and an active DBCP Connection object subsequently has its close() method called, it's not clear whether its underlying actual JDBC connection will be released. I.e., how do you release JDBC connections on previously active DBCP Connections after BasicDataSource.close() is called?
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DBCP-312) BasicDataSource.close() method needs
JavaDoc clarification
Posted by "Phil Steitz (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DBCP-312?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12793849#action_12793849 ]
Phil Steitz commented on DBCP-312:
----------------------------------
Thanks again for pointing out the weakness in the docs. The unit tests are better - see testClose in TestBasicDataSource ;)
> BasicDataSource.close() method needs JavaDoc clarification
> ----------------------------------------------------------
>
> Key: DBCP-312
> URL: https://issues.apache.org/jira/browse/DBCP-312
> Project: Commons Dbcp
> Issue Type: Bug
> Affects Versions: 1.3
> Reporter: Glen Mazza
> Priority: Minor
> Fix For: 1.4.1
>
>
> Hello, the JavaDoc could use clarification for the BasicDataSource.close() method.
> Link: http://commons.apache.org/dbcp/apidocs/org/apache/commons/dbcp/BasicDataSource.html#close()
> Text: "Close and release all connections that are currently stored in the connection pool associated with our data source. All open (active) connection remain open until closed. Once the data source has been closed, no more connections can be obtained."
> I'm unsure if this method closes just idle, or both idle and active connections. This is a important distinction, because you wouldn't want to call close() if you still have some needed active connections open on various threads. The first sentence seems to indicate both active and idle threads will be closed, but the second sentence indicates that only the idle threads will be explicitly closed.
> Recommend changing text to:
> "Close and release all connections, whether active or idle, that are currently stored in the connection pool associated with our data source. Once the data source has been closed, no more connections can be obtained."
> or (if this method closes just idle connections):
> "Close and release all idle connections that are currently stored in the connection pool associated with our data source. All open (active) connections will still remain open until they are closed via the Connection close() method. Once the data source has been closed, no more connections can be obtained."
> Note that, for the latter case, if BasicDataSource.close() only closes and releases idle connections, and an active DBCP Connection object subsequently has its close() method called, it's not clear whether its underlying actual JDBC connection will be released. I.e., how do you release JDBC connections on previously active DBCP Connections after BasicDataSource.close() is called?
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Closed: (DBCP-312) BasicDataSource.close() method needs
JavaDoc clarification
Posted by "Phil Steitz (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DBCP-312?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Phil Steitz closed DBCP-312.
----------------------------
> BasicDataSource.close() method needs JavaDoc clarification
> ----------------------------------------------------------
>
> Key: DBCP-312
> URL: https://issues.apache.org/jira/browse/DBCP-312
> Project: Commons Dbcp
> Issue Type: Bug
> Affects Versions: 1.3
> Reporter: Glen Mazza
> Priority: Minor
> Fix For: 1.4.1
>
>
> Hello, the JavaDoc could use clarification for the BasicDataSource.close() method.
> Link: http://commons.apache.org/dbcp/apidocs/org/apache/commons/dbcp/BasicDataSource.html#close()
> Text: "Close and release all connections that are currently stored in the connection pool associated with our data source. All open (active) connection remain open until closed. Once the data source has been closed, no more connections can be obtained."
> I'm unsure if this method closes just idle, or both idle and active connections. This is a important distinction, because you wouldn't want to call close() if you still have some needed active connections open on various threads. The first sentence seems to indicate both active and idle threads will be closed, but the second sentence indicates that only the idle threads will be explicitly closed.
> Recommend changing text to:
> "Close and release all connections, whether active or idle, that are currently stored in the connection pool associated with our data source. Once the data source has been closed, no more connections can be obtained."
> or (if this method closes just idle connections):
> "Close and release all idle connections that are currently stored in the connection pool associated with our data source. All open (active) connections will still remain open until they are closed via the Connection close() method. Once the data source has been closed, no more connections can be obtained."
> Note that, for the latter case, if BasicDataSource.close() only closes and releases idle connections, and an active DBCP Connection object subsequently has its close() method called, it's not clear whether its underlying actual JDBC connection will be released. I.e., how do you release JDBC connections on previously active DBCP Connections after BasicDataSource.close() is called?
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Resolved: (DBCP-312) BasicDataSource.close() method needs
JavaDoc clarification
Posted by "Phil Steitz (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DBCP-312?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Phil Steitz resolved DBCP-312.
------------------------------
Resolution: Fixed
Fixed in trunk as of r893360
> BasicDataSource.close() method needs JavaDoc clarification
> ----------------------------------------------------------
>
> Key: DBCP-312
> URL: https://issues.apache.org/jira/browse/DBCP-312
> Project: Commons Dbcp
> Issue Type: Bug
> Affects Versions: 1.3
> Reporter: Glen Mazza
> Priority: Minor
> Fix For: 1.4.1
>
>
> Hello, the JavaDoc could use clarification for the BasicDataSource.close() method.
> Link: http://commons.apache.org/dbcp/apidocs/org/apache/commons/dbcp/BasicDataSource.html#close()
> Text: "Close and release all connections that are currently stored in the connection pool associated with our data source. All open (active) connection remain open until closed. Once the data source has been closed, no more connections can be obtained."
> I'm unsure if this method closes just idle, or both idle and active connections. This is a important distinction, because you wouldn't want to call close() if you still have some needed active connections open on various threads. The first sentence seems to indicate both active and idle threads will be closed, but the second sentence indicates that only the idle threads will be explicitly closed.
> Recommend changing text to:
> "Close and release all connections, whether active or idle, that are currently stored in the connection pool associated with our data source. Once the data source has been closed, no more connections can be obtained."
> or (if this method closes just idle connections):
> "Close and release all idle connections that are currently stored in the connection pool associated with our data source. All open (active) connections will still remain open until they are closed via the Connection close() method. Once the data source has been closed, no more connections can be obtained."
> Note that, for the latter case, if BasicDataSource.close() only closes and releases idle connections, and an active DBCP Connection object subsequently has its close() method called, it's not clear whether its underlying actual JDBC connection will be released. I.e., how do you release JDBC connections on previously active DBCP Connections after BasicDataSource.close() is called?
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.