Question

我不知道在哪里寻求有关Java API文档和Java代码的澄清和确认，所以我在这里做。

在FileChannel的API文档中，我发现了w.r.t的一个错误。提交position并将文件size存放在多个地方。

这只是一个例子。 transferFrom(...)州的API文档：

“如果给定的位置大于文件的当前大小，则不会传输任何字节。”

我确认OpenJDK代码也包含此代码......

public long transferFrom(ReadableByteChannel src, long position, long count)
    throws IOException
{
    // ...
    if (position > size())
        return 0;
    // ...
}

...在文件FileChannelImpl.java中与文档一致。

现在，虽然上面的代码段和API文档看起来相互一致，但我觉得上面应该'大于或等于'而不仅仅是'大于'因为position是基于0的文件数据索引，所以position == size()的读数将没有数据返回给调用者！（在position == size() - 1，至少1个字节 - 文件的最后一个字节 - 可以返回给调用者。）

以下是同一API文档页面中的其他类似实例：

position(...)：“将位置设置为大于的值，文件的当前大小是合法的，但不会更改文件的大小。” （应该是'大于或等于'。）
transferTo(...)：“如果给定的位置大于文件的当前大小，则不会传输任何字节。”（应该是'大于或等于'。）
read(...)：“如果给定的位置大于文件的当前大小，则不会读取任何字节。”（应该是'大于或等于'。）

最后，read(...)的返回值的文档部分甚至无法与其他文档保持一致。以下是它所说的内容：

read(...)

返回：

如果给定位置大于或等于文件的当前大小，则读取的字节数，可能为零或-1;

所以，在这个单独的例子中，我确实看到他们提到正确的事情。

总的来说，我不知道该怎么做。如果我今天编写的代码与本文档相匹配，那么Java（代码或文档）中的未来错误修复将导致我的代码错误，需要我方面的修复。如果我今天自己做正确的事情，就像他们今天所做的那样，那么我的代码就会开始变得错误！

Answer 1

这不是一个一个一个错误，因为没有行为问题吗？充其量是一个doc问题。这里的文档并没有错，也许只是不完整。

但是我不确定他们是否遗漏了什么。 position == size()并非特殊情况。根据定义，可以读取0字节的情况。 position > size()是例外：可以读取少于0个字节。它需要一个注释。抛出异常？或无。 read()是不同的，因为它必须返回一个字节，因此读取0也是异常条件。

我个人认为你问的事实意味着文档可以更明确。还不清楚为什么该方法不会短路而不是尝试传输0字节。但看起来它背后可能存在逻辑。

（或者你的意思是它做了没有记录的事情？）

Answer 2

这在javadoc中可能会更加清晰，现在可以在这里进行跟踪：

https://bugs.openjdk.java.net/browse/JDK-8029370

请注意，澄清javadoc不应该改变FileChannel的实现（例如，传输方法返回传输的字节数，因此当位置大小或超出大小时，这是0）。

这是Java 7中的一个错误吗？

2 个答案: