noteworthy/jdt.adoc - www.eclipse.org/neon - Git at Google

 //////////////////////////////////////////
 * 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.
	//////////////////////////////////////////
	* 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.