revetkn/restfb — pull request #140 by marcelstoer (2014-09-28 21:29:35+00:00)
Title: NoIssue - deprecate the methods accepting an InputStream and add equivalents accepting byte[] instead

Answering https://groups.google.com/forum/#!topic/restfb/fY1ssk62Gls made me realize that `BinaryAttachment` has an odd API. IMO methods should neither accept nor return input/output streams - particularly if they're public library methods. Streams are something extremely fragile (they're serializable for one) and great care must be taken ensure that it's clear who manages the stream's lifecycle. Whichever piece of code creates the streams is responsible for closing it.
If I pass an `InputStream` to the `BinaryAttachment` constructor I effectively give up control over the stream's lifecycle. Even if RestFB behaves nicely and doesn't harm the stream it's still not clear for the callee in which state the stream is once RestFB is done.

While we keep both the old and new methods `BinaryAttachment.getData()` is a bit ugly. As soon as the deprecated methods are removed (with 1.7?) that method can be replaced with a Lombok `@Getter` and `DefaultWebRequestor.executePost(String, String, BinaryAttachment...)`/`DefaultWebRequestor.write(InputStream, OutputStream, int)` need to be slightly adjusted.

Let me know what you think of this proposal.