Documentation: To close or not to close?

[ghost]

Re: https://javadoc.io/doc/org.glassfish.grizzly/grizzly-http-server/2.3.4/org/glassfish/grizzly/http/server/Request.html#getReader()

The extras code for getNIOInputStream(); shows that the stream is to be closed when handling the data is complete:

https://github.com/javaee/grizzly/blob/master/extras/http-servlet-extras/src/main/java/org/glassfish/grizzly/servlet/extras/MultipartUploadFilter.java#L310

Recommend documenting the calls to getReader() and getNIOInputStream() and similar I/O methods to indicate what code is responsible for closing and under what conditions.

https://javadoc.io/doc/org.glassfish.grizzly/grizzly-http-server/latest/org/glassfish/grizzly/http/server/Request.html#getReader--

For example, if a reader object from a Request object will be closed automatically after the HTTP request completes, that would be good knowledge to capture in the Javadocs.

If you're open to using a convention, prefixing methods with open could give developers a clue to close them. Consider:

final var in = openNIOInputStream();

// As a developer, I see the open, so I know I need to close.
in.close();