[
https://issues.apache.org/jira/browse/LUCENE-4525?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13489365#comment-13489365
]
Michael Osipov commented on LUCENE-4525:
----------------------------------------
The patch is incomplete, @throws is missing on:
- acquire
- afterClose
- decRef
- refreshIfNeeded
- release
While most of them a checked exceptions and are visible anyway, unchecked
unexceptions aren't visible until you hit them or document properly.
The close() has some errors, here is a corrected version:
{noformat}
* <p>
* Close this ReferenceManager to prevent future {@link #acquire()
acquiring}. A
* reference manager should be closed if the reference to the managed
resource
* should be disposed or the application using the {@link ReferenceManager}
* is shutting down. The managed resource might not be released immediately,
* if the {@link ReferenceManager} user is holding on to a previously
* {@link #acquire() acquired} reference. The resource will be released once
* when the last reference is {@link #release(Object) released}. Those
* references can still be used as if the manager was still active.
* </p>
* <p>
* Applications should not {@link #acquire() acquire} references from this
* manager once this method has been called. {@link #acquire() Acquiring} a
* resource on a closed {@link ReferenceManager} will throw an
* {@link AlreadyClosedException}.
* </p>
*
* @throws IOException
* if the underlying reader of the current reference could not be
closed
{noformat}
I have changed especially the @throws tag because I do not see as a user any
connection between a decRef and an IOE w/o reading further JavaDocs.
Thanks!
> JavaDoc of SearcherManager#close is not crystal clear
> -----------------------------------------------------
>
> Key: LUCENE-4525
> URL: https://issues.apache.org/jira/browse/LUCENE-4525
> Project: Lucene - Core
> Issue Type: Improvement
> Components: core/search
> Affects Versions: 3.6.1, 4.0
> Reporter: Michael Osipov
> Assignee: Simon Willnauer
> Priority: Minor
> Attachments: LUCENE-4525.patch
>
>
> Raised from
> http://www.mail-archive.com/[email protected]/msg40064.html
> The JavaDoc says:
> {noformat}
> /**
> * Close this ReferenceManager to future {@link #acquire() acquiring}. Any
> * references that were previously {@link #acquire() acquired} won't be
> * affected, and they should still be {@link #release released} when they
> are
> * not needed anymore.
> */
> {noformat}
> The first sentence is not really clear. I would expect something like:
> {noformat}
> Close this ReferenceManager when the application is shutting down or the
> underlying index will be disposed. Any references that were previously
> {@link #acquire() acquired} won't be affected, and they should still be
> {@link #release released} when they are not needed anymore.
> {noformat}
> Further more, the JavaDoc does not declare that an exception will be thrown
> on any method.
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
