Cascade Tutorial
Cascade is a Type Qualifier Inference (TQI) tool. It proposes a set of changes each of which annotates part of the code.
To run Cascade, right-click on the Eclipse project that you want to annotate and select Type Qualifier Inference > Infer Nullness Qualifiers. The following screenshot shows how to run Cascade.
When you run Cascade, it initiates several jobs to compute the changes that would annotate the code. You can see the progress of these jobs in the Progress view (See the screenshot below).
The jobs shown in the Progress view update the Cascade view (See figure below). We recommend that you wait until all the jobs in the Progress view are finished and then start using the Cascade view.
The Cascade view shows a tree (See the screenshot below). The root of the tree is the set of error messages that the Nullness Checkers reports for the Eclipse project that you run Cascade on.
To expand a tree node, click on the triangle icon besides it. When you click on the triangle icon the tree will expand to show the children of the tree node that you expanded. If you click the triangle icon again, the tree will collapse the children of that tree node.
The tree in the Cascade view is similar to other trees in Eclipse, e.g., the Package Explorer view. However, Unlike standard Eclipse views that use trees to show hierarchies of program elements, Cascade uses a tree to show future states of the source code.
- Expanding an error message shows a change (if any) that Cascade proposes to resolve that error message.
- Expanding a change shows the new error messages that will appear if the change is applied.
Expanding the Cascade tree doesn't change the code. Rather, it allows you to explore the future state of the source code in case a number of the proposed changes are applied to the code.
Expanding an error message shows a change (if any) that Cascade proposes to resolve that error message. For example, if you expand the first error message shown in the screenshot below, the tree will expand to propose a change described as Change field left to @Nullable TreeNode (2). The screenshot below shows the shape of the tree after expanding the tree node of the first error message.
Expanding a change shows the new error messages that will appear if the change is applied. The screenshot below highlights the following error message:
incompatible types in argument.
this(1, null, null)
found : null
required: @Initialized @NonNull TreeNode
To resolve the above error message, Cascade proposes the change Change parameter l to @Nullable TreeNode. Moreover, the screenshot shows the following error message as a child of this change, which means that performing the change will introduce the following error message:
incompatible types in argument.
left = l;
found : @Initialized @Nullable TreeNode
required: @Initialized @NonNull TreeNode
In addition, further expansion of the above error message shows that Cascade proposes the change Change field left to @Nullable TreeNode (1) to fix this error message. Once again, note that expanding the Cascade tree doesn't change the code.
If you single-click on an error message, Cascade will open and highlight the piece of code related to the error message (See the screenshot below for an example).
Cascade proposes changes to resolve some of the error messages. Children of an error message node in the tree are the changes that Cascade proposes to resolve the error message.
Description. The description of the change tree node explains how the change is going to annotate the program. The change description includes a number in parentheses at the end. This number indicates the number of error messages that will go away if this change is applied. For example, the change description shown in the tree above indicates that it will remove two error messages.
Viewing. If you single-click on a change tree node, Cascade will open and highlight the piece of the code that the change will annotate. In addition, will mark the error messages that the change will resolve by green check mark icons (See the screenshot below for an example).
If you double-click on a change tree node, Cascade will apply the change on the code and open the affected code in the editor (See the screenshot below).
