I'm just keeping the new interface name similar to the interface it
extends.  I didn't choose the name Closeable.  We don't get any say in
the name of it.

Closeable is part of the JDK, and it's the responsibility of a Java
developer to know that Closeable objects should be closed somewhere.

But as I said, the point isn't really what sort of object this is, it's
about where you got it.  *If* you got it from calling this method, you
need to close it (or make sure someone else does).  Hence the doc comment.

If you got the iterator some other way, you may not need to close it.
(And if it does need to be closed there, it should be documented there too.)

On 2013-08-01 14:03, David Mason wrote:
> In zanata-war/src/main/java/org/zanata/dao/TextFlowStreamingDAO.java:
> 
>>     }
>>  
>>     /**
>>      * Returns all HTextFlows in all projects, eagerly fetches targets, document, iteration and project.  
>>      * Obsolete projects, iterations, documents and textflows are skipped.
>> +    * <p>
>> +    * NB: caller must close the iterator, or call next() until the iterator is exhausted,
>> +    * or else a database connection will be leaked.
> 
> Neither 'Closeable' nor 'Iterator' strongly suggest holding resources.
> How about |ResourceHoldingIterator|?
> 
> |LeakingResourcesIterator| might encourage people to bother looking at
> the javadoc to see how they can avoid leaking :laughing:
> 
> —
> Reply to this email directly or view it on GitHub
> <https://github.com/zanata/zanata-server/pull/78/files#r5522013>.
> 


-- 
Sean Flanigan

Senior Software Engineer
Engineering - Internationalisation
Red Hat