RFR: 8250625: Compiler implementation of Pattern Matching for instanceof (Final)

[Jan Lahoda]

This is the current proposed patch for the upcoming JEP 394, for pattern matching for instanceof.

A summary of changes:
-making the feature permanent (non-preview)
-making the binding variables non-final (as per current specification proposal)
-producing a compile-time error for the case where the expression's type is a subtype of the type test pattern's type
 (as per current specification proposal)
-changing the AST structure so that the binding variable has a VariableTree in the AST. BindingPatternTree is preserved
 and encloses the VariableTree. The reason is better consistency in the API, with nodes like CatchTree, EnhancedForLoop
 Tree, etc.

This change will not be integrated until JEP 394 is targetted.

-------------

Commit messages:
 - Fixing more tests.
 - Correcting positions.
 - Improve the AST model.
 - Merge branch 'master' into patterns-instanceof3
 - Updating @since tags.
 - Merge branch 'master' into patterns-instanceof3
 - Cleaning up preview comments in javadoc.
 - Merge branch 'master' into patterns-instanceof3
 - Updating tests.
 - Cleanup.
 - ... and 3 more: https://git.openjdk.java.net/jdk/compare/97ff38ca...69c7dce8

Changes: https://git.openjdk.java.net/jdk/pull/559/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=559&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8250625
  Stats: 655 lines in 90 files changed: 242 ins; 302 del; 111 mod
  Patch: https://git.openjdk.java.net/jdk/pull/559.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/559/head:pull/559

PR: https://git.openjdk.java.net/jdk/pull/559