Java NIO2 AsynchronousFileChannel returns Future with no documnetation on actual values

Question

So I came up with the following function based on the docs and examples I found online, to write files in async way:

    public static Future<Integer> createAndWriteToFile(String fullFileName, String content) throws IOException {
        Path file = Utils.createFile(fullFileName);
        AsynchronousFileChannel fileChannel = AsynchronousFileChannel.open(file, StandardOpenOption.WRITE, StandardOpenOption.CREATE);

        ByteBuffer buffer = ByteBuffer.wrap(content.getBytes());
        Future<Integer> operation = fileChannel.write(buffer, 0);
        buffer.clear();

        return operation;
}

However, there is absolutely no documentation on what to expect from calling operation.get().intValue()! In debug mode, successful file creation/writing returns Integer value 23. What are other possible values? Docs: https://docs.oracle.com/javase/8/docs/api/java/nio/channels/AsynchronousFileChannel.html#write-java.nio.ByteBuffer-long-

And here: https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/Future.html#get--

Returns: the computed result

Helpful, its not.

As an aside question - it surprised me, Java is considered one of the most well documented languages, how comes this function is not documented?

Paragraph 2 of the method description reads: "The method returns a Future representing the pending result of the write operation. The Future's get method returns the number of bytes written.". You have to read the javadoc to use an API like this, there is only so much that you can include in the return description. — Alan Bateman, Jun 27 '18 at 09:38
@AlanBateman why? I expect the return description to be complete and specific, not generic. — Carmageddon, Jun 27 '18 at 12:36

score 1 · Accepted Answer · answered Jun 26 '18 at 20:21

Even though not directly stated on the return type in the docs. If you look closely at the paragraph described there:

This method works in the same manner as the AsynchronousByteChannel.write(ByteBuffer) method, except that bytes are written starting at the given file position. If the given position is greater than the file's size, at the time that the write is attempted, then the file will be grown to accommodate the new bytes; the values of any bytes between the previous end-of-file and the newly-written bytes are unspecified.

So it says it behaves just like AsynchronousByteChannel.write(ByteBuffer) which redirects you to Future<Integer> write(ByteBuffer src). There it specifies what the Integer value means, which is basically the number of bytes written.

This method initiates an asynchronous write operation to write a sequence of bytes to this channel from the given buffer. The method behaves in exactly the same manner as the write(ByteBuffer,Object,CompletionHandler) method except that instead of specifying a completion handler, this method returns a Future representing the pending result. The Future's get method returns the number of bytes written.

Thanks! Wow, a way to obscure important bit in description. This should be part of the return documentation not hidden in long-winded description — Carmageddon, Jun 26 '18 at 20:29
@Carmageddon glad I could help. I agree, the docs could be a bit more clear on the return section, *`A Future object representing the pending result`* leaves a lot to the imagination =]. — StaticBeagle, Jun 26 '18 at 20:42

Java NIO2 AsynchronousFileChannel returns Future with no documnetation on actual values

1 Answers1