Meaning of @Flow annotation

contract, inference, intellij-idea, java

Solution

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.

Problem

Original source