@Flow注解的含义

Question

在Intellij IDEA 14中有一个名为自动契约推断的功能[1]。

那么推断的@Flow注释到底是什么意思呢？

例如对于Collection的boolean addAll(Collection c)，推断的契约是boolean addAll(@NotNull @Flow Collection c)。

在这个上下文中，@Flow是什么意思呢？

[1] http://blog.jetbrains.com/idea/2014/10/automatic-notnullnullablecontract-inference-in-intellij-idea-14/

- lukstei

Answer 1

免责声明：我无法找到任何详细的描述或示例，因此大部分都是推测。

到目前为止我找到的 @Flow 最好的文档，就是在注释本身上可以看到的内容，可以在这里查看（链接）。

引用如下：

此注解通过描述从方法参数流向相应容器（例如 ArrayList.add(item)）或从容器流向方法返回值（例如 Set.toArray()）或方法参数之间的数据流（例如 System.arraycopy(array1, 0, array2, length)）来协助“数据流到此”功能。

简而言之，@Flow 是一种元数据，IntelliJ 需要使用它对数据进入和退出集合等情况进行某些类型的代码分析。不确定使用这个做了什么类型的分析，但我认为 IntelliJ 的某些检查会利用它。

我推测，可以基于此元数据制作类似以下的检查（如果尚未存在）：

• 根据 @Flow，传递给 void push(Object) 的数据最终可以从 Object pull() 中返回
• 如果从 pull 返回值取消引用而不检查 null，则在 null 传递到 push 时发出警告。

在添加 @Flow 之前，这可能需要硬编码到 IntelliJ 中，因此只能用于 Java 的标准容器类、数组和其他东西（假设在此之前已经进行了这种特定类型的分析）。添加 @Flow 将使它更加灵活，并允许以相同的方式分析自定义容器。

如果有关于 @Flow 的更实际的信息及其用法示例，请与我分享。

- BambooleanLogic

Answer 2

延续Smallhacker的回答：我假设@Flow注释用于静态分析，以启用以下警告：

1. “列表”集合的内容已更新，但从未查询

List<Integer> list = new ArrayList<>();
list.add(3);

2. 查询集合“队列”的内容，但从不更新

Queue<Integer> queue = new PriorityQueue<>();
Integer i = queue.peek();

很遗憾，我没有找到任何支持此说法的文档，并且在我的发行版中 @Flow 在 附加下载的 org.jetbrains.annotations 和 org.intellij.lang.annotations 包中都无法使用。它在编写方法参数时出现提示，但在JDK源代码中不可用。

顺便说一下，与数据流相关的注释是 @Contract。

- TheOperator