Documentation promotes questionable practices regarding resource closure

[peter-gergely-horvath]

• Framework version: 1.1.4
• Implementations: Jersey / Spring / Spring Boot

Scenario

The documentation shows the following approach as sample for creating a handler. Based on the description, if my understanding is correct the stream might not be closed properly, if an exception is thrown from handler.proxyStream :

@Override
public void handleRequest(InputStream inputStream, OutputStream outputStream, Context context)
        throws IOException {
    handler.proxyStream(inputStream, outputStream, context);

    // just in case it wasn't closed by the mapper
    outputStream.close();
}

The whole issue boils down to one question: who is in charge of the closing/handling of the lifecycle of the streams passed to a RequestStreamHandler? Is it the application code or the container? If it's the application's responsibility to close the steam, then you should probably show a more stable sample using a finally block or an ARM try block (and e.g. clarify why one does NOT have to close the input stream); if it is the container, then you should state that the application code does not have to deal with this issue and show a sample without closing the stream.

Expected behavior

Actual behavior

Steps to reproduce

Full log output

[sapessi]

Technically all Exceptions should be caught and handled here. The application code should not need to do anything with the stream. I'll fix the samples/archetypes to reflect this.

[sapessi]

This is ready for the next release. Closing this issue.