Meaning of @Flow annotation

Question

In Intellij IDEA 14 there is a feature called Automatic Contract inference [1].

What exactly does the inferred @Flow annotation mean?

For example for Collection's boolean addAll(Collection<? extends E> c)the inferred contract is boolean addAll(@NotNull @Flow Collection<? extends E> c).

What does @Flow mean in this context?

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

Answer 1

Disclaimer: I haven't been able to find any massively detailed descriptions or examples of this, so most of this is speculation.

The best documentation I've found for @Flow so far is what one can read in the comments on the annotation itself, as one can see here.

Excerpt:

This annotation assists the 'Data flow to this' feature by describing data flow from the method parameter to the corresponding container (e.g. ArrayList.add(item)) or from the container to the method return value (e.g. Set.toArray()) or between method parameters (e.g. System.arraycopy(array1, 0, array2, length))

In a nutshell, it's a form of metadata IntelliJ needs to do some types of code analysis on how data enters and exits a collection or similar. Not sure exactly what type of analysis is done using this, but I assume that some of IntelliJ's inspections make use of it.

I speculate that an inspection similar to the following could theoretically be made using this metadata (if it doesn't already exist):

• According to @Flow, data passed to void push(Object) can eventually be returned from Object pull()
• If the return value from pull is dereferenced without checking for null, give a warning if null is ever passed into push.

Before @Flow was added, this presumably had to be hardcoded into IntelliJ and would thus only work for Java's standard container classes, arrays and stuff (assuming this specific type of analysis was even done before). Adding @Flow would thus make it more flexible and also allow custom containers to be analyzed in the same way.

If anyone has more solid information about @Flow and some real world examples of how it's used, I too would be interested in seeing it.

Answer 2

To extend on Smallhacker's answer: I assume the @Flow annotation is used in static analysis to enable the following warnings:

1. Contents of collection 'list' are updated, but never queried

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

2. Contents of collection 'queue' are queried, but never updated

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

Unfortunately, I have not found any documentation backing this up, and @Flow seems to be unavailable in both additionally downloaded org.jetbrains.annotations and org.intellij.lang.annotations packages of my distribution. It appears as a hint when writing a method's arguments, but is not available in the JDK's source code.

By the way, an annotation related to data flow is @Contract.