//////////////////////////////////////////
* Copyright (c) 2015, 2016 Eclipse Foundation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
*    Wayne Beaton (Eclipse Foundation)- initial API and implementation
//////////////////////////////////////////

[[java]]
== Java(TM)

Eclipse Neon includes numerous bug fixes and improvements in the Java 8
support, along with a lot of other useful features.

=== Java 9

==== Launching on Java 9

Launching Eclipse with recent Java 9 previews fails with `NoClassDefFoundErrors` for 
`javax/annotation/PostConstruct` and similar types.

The workaround is to add the VM arguments

 -addmods java.se.ee

either on the command line after `-vmargs`, or at the end of the eclipse.ini file on 
two separate lines.

=== Java Editor

==== ifNotNull/ifNull templates

The Java editor now offers default templates for creating "== null" and "!= null" checks.

image::images/if-null-template.png[]

==== New Info severity level

You can now specify _Info_ as a severity level for the problems detected by the Eclipse 
Java compiler.

image::images/info-severity.png[]

A new decorator has been added to indicate information severity problems detected by the 
Eclipse Java Compiler.

image::images/info-problem-decorator.png[]

You can now configure the severity of a compiler problem by invoking the new _Quick Fix_ 
(`Ctrl+1`) which opens the `Java > Compiler > Errors/Warnings` preference page and 
highlights the configurable problem.

image::images/configure-problem-severity.png[]

==== Substring code completion

Content Assist now supports substring patterns. Enter any part of the desired proposal's 
text, and Content Assist will find it! For example, completing on `selection` proposes 
all results containing `selection` as a substring.

image::images/substring-code-completion.png[]

This feature can be disabled using the `Show substring matches` option on the 
`Java > Editor > Content Assist` preference page.

==== Clean Up to remove redundant type arguments

A new option to remove redundant type arguments has been added under the 
_Unnecessary Code_ group of the Clean Up profile.

image::images/remove-redundant-type-arguments.png[]

==== New options in code formatter

In the new _Parentheses_ tab, you can order the formatter to keep 
parentheses of various Java elements on separate lines, i.e. put a 
line break after the opening parenthesis and before the closing 
parenthesis. This can be done always, only when parentheses are 
not empty, or when their content is wrapped. There's also an option 
to preserve existing positions, if you want to manually manage parentheses 
positions on a case-by-case basis.

image::images/formatter-parentheses.png[]

In the _Line Wrapping_ tab, you can set the wrapping policy for parameterized 
types, you can decide to wrap before or after operators in assignments and 
conditional expressions, and you can control the wrapping policy of 
`'for' loop headers`.

image::images/formatter-wrap-for.png[]

The _Align fields in columns_ feature in the _Indentation_ section can now 
be configured to _recognize groups separated by empty lines_ and align them 
independently.

image::images/formatter-align-groups.png[]

In the _New lines_ section, you can control if new lines should be added 
after annotations on `enum` constants.

image::images/formatter-enum-constants.png[]

==== Create new fields from method parameters

You can now assign all parameters of a method or constructor to new fields 
at once using the new _Quick Assist_ (`Ctrl+1`):

image::images/assign-all-params-to-new-fields.png[]

=== Java Views, Wizards, and Other UI

==== Project Explorer Improvements

The _Project Explorer_ view now groups referenced libraries in a new container node.

image::images/show-referenced-libraries-node-project-explorer.png[]

You can now hide empty library containers in the _Project Explorer_ view by selecting 
the new filter in its _Customize View..._ dialog.

image::images/hide-empty-library-containers-project-explorer.png[]

==== Add meta-annotations while creating a new Java annotation type

You can now choose to add `@Retention`, `@Target` and `@Documented` meta-annotations 
along with their applicable values while creating a new Java annotation type.

image::images/add-meta-annotations.png[]

==== Search on multi-selections

You can now select multiple elements in views like _Package Explorer_ and 
_Outline_ and then search for _References_, _Declarations_, _Implementors_, 
and _Read/Write Access_ (where applicable):

image::images/search-on-multi-selections.png[]

You can even select results in the _Search_ view and start a new search for those 
elements. To follow method call chains, you'd probably use _Open Call Hierarchy_, 
though.

==== JUnit Support

Assertions are now enabled by default for new JUnit launch configurations. You can 
disable this on the `Preferences > Java > JUnit` page.

=== Debug

==== Installing breakpoints from unrelated projects

Multiple versions of the same Java type can be available in a workspace, and 
each version can have breakpoints configured at different source locations. When 
debugging, JDT tries to determine the "right" set of breakpoints to install in 
the target VM. This analysis now uses Java project dependencies by default.

To always install all enabled breakpoints, you can disable the new option 
`Preferences > Java > Debug > Do not install breakpoints from unrelated projects`.

=== Null Analysis

==== Multiple sets of null annotations

You can now configure annotation-based null analysis to use multiple sets of 
annotation types. This is relevant if your project uses 3rd party libraries 
that already use null annotations in their API, where the annotations used in 
a library may be different from those used in the current project.

Please open the dialog for configuring null annotation types from the project 
properties at `Java Compiler > Errors/Warnings > Null analysis`:

image::images/prefs-errors-warnings.png[]

In the dialog that opens, only one primary set of annotations is supported; 
these are the annotations which JDT actively uses in _Quick Fixes_, error 
messages etc. These annotations must be present on the project's build path.

You can now add an arbitrary number of secondary `null` annotation types, to 
be evaluated when reading class files external to the project. Within the 
configuration dialog, Content Assist is offered based on accessible annotation 
types, but for secondary annotation types unresolved names will be tolerated. 
This avoids the need to bloat the build path with transitive compile-time 
dependencies.

image::images/annotation-selection.png[]

==== Improved `null` analysis with generics

The interplay of `null` annotations and generics has been improved in several 
regards.

The basic concepts had already been documented in the online help, but not 
all that was documented was actually checked by `null` analysis. With 
the changes outlined below, null analysis based on type annotations is even 
more capable than previous versions.

(1) The first batch of contributed improvements implements what we call 
_pessimistic analysis for free type variables_, which affects implementors 
of generic types.

image::images/pessimistic-analysis.png[]

In order to allow clients to instantiate such a generic class with either 
a `@NonNull` or a `@Nullable` type as substitution for the "free type variable" 
`<T>`, the implementation of that class must account for the worst in both 
directions:

* To anticipate a `@NonNull` type, each field typed to a free type variable 
must be initialized with a non-`null` value, and passing `null` where `T` is
expected is illegal; and
* To anticipate a `@Nullable` type, each dereference must be preceded by a `null` check.

At the bottom of each problem hover, you will find a link to the corresponding 
configuration option, should you like to change the severity of this diagnostic. 
Note that configurability is mainly given for smooth migration from previous 
JDT version; conceptually, problems detected by pessimistic analysis should be 
treated as errors, because they invalidate the null-guarantees given by a generic 
type.

image::images/configure-pessimistic-analysis.png[]

(2) The second improvement concerns consumption of generic types from a library, 
more specifically: invocations of library methods whose return type is given by 
a free type variable.

If the library type is instantiated with a `@NonNull` type as the type argument, 
we generally want to interpret the mentioned return type as non-`null`, too. 
This is problematic only for some "legacy" methods, which may return `null` 
without declaring so. The most prominent example is `java.util.Map.get(K)`.

The analysis cannot see whether absence of a null annotation for such a return 
type is intentional (in the above sense of "free type variables"), or an omission 
that should be fixed. For that reason a new warning has been implemented to alert 
about this situation.

image::images/unsafe-nonnull-interpretation.png[]

In the above example, both fields list and map provide `@NonNull` `String` as a type 
argument, hence the return types of both _get_ methods are interpreted as non-`null`. 
For `List` this is desired, for `Map` it is a bug.

The dilemma can be resolved by adding a (possibly empty) external annotation file 
(`.eea`) to each affected library class. By using an empty annotation file, the user 
signals that all types in this class should be interpreted verbatim (like in the 
`List` case - use with care). In the other case, the missing `@Nullable` annotation 
should be added as an external annotation (like in the `Map` case).

In a project that is not yet configured to use external annotations for the 
library in question, the warning is demoted to level "information". Generally, the 
severity of this problem is configured using the option right below the one mentioned 
above, titled `Unsafe '@NonNull'` interpretation of free type variable from library.

(3) Finally, a small utility class, `org.eclipse.jdt.annotation.Checks`, has been 
included in the bundle `org.eclipse.jdt.annotation_2.1.0` containing helper methods 
for typical idioms for improving and documenting `null` safety.

==== Quick Fix to add `@NonNull` to local variable

When a "potential null pointer access" problem is raised against a local variable, 
the reason is not always obvious. Perhaps `null` is assigned somewhere deep inside 
a complex control flow. If annotation-based `null` analysis is enabled, a new 
_Quick Fix_ is offered (`Ctrl+1`), that adds a `@NonNull` annotation to the local 
variable.

image::images/add-nonnull1.png[]

While this may not produce correct code, it tells the compiler your intention to 
not allow `null` in this variable, and subsequently the compiler will answer with more 
helpful warnings or errors pointing to the root problem. In the given example, 
it will alert you of subtleties about using unconstrained type variables.