MumbleCloseable

[Brian Goetz]

> 1. What happens if close needs to throw an exception?  Why is this form
> of close different from others?

It was a mistake from Day 1 to allow Reader.close() and friends to throw 
anything checked.  I mean, what could a caller *possibly do* to respond 
to such an exception?  Close it again?  OK, live and learn.

When AutoCloseable came along, it would have been preferable for AC to 
support no exceptions on its close.  But since Closeable has to extend 
AC, and AC didn't want to be tied to IOException, its only option was to 
throw Exception.  Which no one wanted, but such is the price of 
compatibility with previous mistakes.

New AC-style interfaces have the option to make this better by throwing 
nothing.  This was our first opportunity to do so.

> 2. Why is this a close() method instead of a dispose() or release() method?

Because doing so would require a language change, and reopening a number 
of issues with try-with-resources.  If we want to build on TWR, our only 
choice right now is AutoCloseable.

> Concerning names, I've lost track of what the expected programming style
> for this is.  It would be a great aid if I could see three exemplary
> snippets.

Remember this is mostly for the StreamSupport crowd, who are building 
libraries to return streams.  Users will rarely call close() or 
onClose() or use MumbleCloseable.

Here's two: concat and Files.lines.

     public static IntStream concat(IntStream a, IntStream b) {
         Objects.requireNonNull(a);
         Objects.requireNonNull(b);

         Spliterator.OfInt split = new Streams.ConcatSpliterator.OfInt(
                 a.spliterator(), b.spliterator());
         IntStream stream = (a.isParallel() || b.isParallel())
                            ? StreamSupport.intParallelStream(split)
                            : StreamSupport.intStream(split);
         return stream.onClose(() -> { try { a.close(); }
                                       finally { b.close(); }});
     }

     public static Stream<String> lines(Path path, Charset cs) throws 
IOException {
         BufferedReader br = Files.newBufferedReader(path, cs);
         return br.lines().onClose(Closeable.asRunnable(br));
     }