10

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

在 API 文档中FileChannel，我发现要归档position并归档size在多个位置的错误。

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

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

我确认 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 文档页面中的其他一些类似实例：

  1. position(...): "将位置设置为大于文件当前大小的值是合法的，但不会改变文件的大小。" （应该是“大于或等于”。）

  2. transferTo(...): "如果给定位置大于文件的当前大小，则不传输任何字节。" （应该是“大于或等于”。）

  3. read(...)：“如果给定位置大于文件的当前大小，则不读取任何字节。” （应该是“大于或等于”。）

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

read(...)

回报：

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

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

总的来说，我不知道该怎么做。如果我今天编写与此文档匹配的代码，那么 Java 中的未来错误修复（代码或文档）将使我的代码出现错误，也需要我的修复。如果我今天自己按照今天的情况做正确的事情，那么我的代码一开始就会出错！

4

2 回答 2

2

这在 javadoc 中可能更清楚一些，现在在此处进行跟踪：

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

请注意，澄清 javadoc 不应该更改 FileChannel 的实现的任何内容（例如，传输方法返回传输的字节数，因此当位置为 size 或超出 size 时为 0）。

于 2013-12-01T11:23:57.147 回答
2

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

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

我个人认为您所问的事实意味着文档可能更明确。也不清楚为什么该方法不短路而不是尝试传输 0 字节。但它背后似乎有一个可能的逻辑。

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

于 2013-12-01T06:10:49.117 回答