What's New in 3.1

This document contains descriptions of some of the more interesting or significant changes made to the Java development tools for the 3.1 release of Eclipse since 3.0. It is broken into several sections:

J2SE 5.0


J2SE 5.0

Eclipse 3.1 includes full support for the new features of J2SE 5.0 (aka "Tiger"). One of the most important consequences of this support is that you may not notice it at all -- everything that you expect to work with J2SE 1.4, including editing, code assist, compiling, debugging, quick fixes, refactorings, source actions, searching, etc. will work seamlessly with J2SE 5.0's new types and syntax.

In order to develop code compliant with J2SE 5.0, you will need a 5.0 Java Runtime Environment (JRE). If you start Eclipse for the first time using a 5.0 JRE, then it will use it by default. Otherwise, you will need to use the Installed JREs dialog to register one with Eclipse. You can reach this dialog either via the preference Java > Installed JREs or by following the Configure default... link on the New Java Project wizard.

New Java Project wizard


Quick Fix to
update JRE and compiler compliance to 5.0

A new quick fix helps you change the compliance settings when you try to enter 5.0 constructs in a 1.4 project. Note that a 1.5 JRE is required, which can be added in the 'Installed JRE's' preference page.

Change compliance quick fix


New Type wizards support generics

The New Type wizards support J2SE 5.0 generic types in various fields:
  • The Name field can include type parameter declarations.
  • The Superclass and the implemented Interfaces can include generic type arguments.

Picture of New Type wizard


Creating Enumerations and Annotations

Enumerations and Annotations can be created with the new Enum or Annotation wizard:

Enum wizard


Guessing for type arguments

Code Assist inserts the correct type arguments when completing a type in the Java editor. Type arguments that cannot be disambiguated will be selected, and the Tab key will move from one argument to the next.

In this example String is inserted as the first type argument, while Number is proposed for the second:

Screenshot: a 'HashMap' is returned from a method declaring 'Map<String, ? extends Number>' as return type. String is inserted as the first type argument, while 'Number' is proposed for the second

To try out this feature, you need to enable Fill argument names on the Java > Editor > Code Assist preference page.


Type parameter declaration hiding another type diagnosis

The Java compiler can optionally flag a type parameter declaration hiding another type.

picture of Java editor with type parameter hiding another type warning


Rename refactoring

The Rename refactoring has been extended to handle renaming of type parameters.

Screenshot showing the renaming of a type parameter in a generic class


Infer Generic Type Arguments
refactoring

With J2SE 5.0, your code can use generics to enhance readability and static type safety. Refactor > Infer Generic Type Arguments is a new refactoring that helps clients of generic class libraries, like the Java Collections Framework, to migrate their code.

Augment Raw Container Clients - Before

The refactoring infers type parameters for generic types, and will remove any unnecessary casts. It works on single compilation units as well as on whole packages and Java projects.

Augment Raw Container Clients - After


Quick fixes for Generics

For unresolved Java types, you now also get a proposal to create a new type parameter:

Add type parameter quick fix

Support for Javadoc tags for type parameters has been added. In J2SE 5.0, you document type parameters using the existing @param tag but with the name enclosed in angle brackets.

Javadoc quick fix for type parameter


New search result filters for reference search for parameterized types

When searching for references to a parameterized type such as List<Integer>, the search result will contain references to all occurrences of List as well. The search result view now offers two additional filters to hide matches:

  • Filter incompatible matches: this filter hides all results that are not assignment compatible with the search pattern. For example when searching for List<Integer> filtering incompatible matches will hide List<String>, but not List<? extends Number>.
  • Filter inexact matches: this filter hides all results that don't exactly match the pattern. For the example above the filter will also hide List<? extends Number>.

Add type parameter quick fix


Completion on annotations

Code completion inside a single member annotation or annotation attribute value is supported.

picture of Java editor completing on an annotation attribute


Usage of annotation type as super interface diagnosis

In J2SE 5.0, the Java language allows a class to implement an annotation type. However this should be discouraged. The Java compiler optionally flags such usage.

picture of Java editor with usage of annotation type as super interface warning


Support for @SuppressWarnings annotation

The J2SE 5.0 @SuppressWarnings annotation is supported. Recognized warning token names are: "all", "boxing", "dep-ann", "deprecation", "incomplete-switch", "hiding", "finally", "static-access", "nls", "serial", "synthetic-access", "unqualified-field-access", "unchecked", "unused" and "warningToken". In the example below, the first field is tagged with the @SuppressWarnings("deprecation") annotation and no deprecation warning is reported. The second field is not tagged and a deprecation warning is reported.

picture of Java editor showing @SuppressWarnings usage

Note that a compiler option controls whether @SuppressWarnings annotations are active or not. See the preference Java > Compiler > Errors/Warnings > J2SE 5.0 options > Enable '@SuppressWarnings' annotations

By default, unhandled warning tokens are signaled by a warning. This warning can also be suppressed using the @SuppressWarnings("warningToken") annotation.

picture of Java editor showing warningToken usage


Quick fix
support for
@SuppressWarnings

Warnings that can be suppressed using a @SuppressWarning annotation offer a quick fix to do so. Applying quick fix to the unused local warning below

Suppress Warning quick fix

results in:

Suppressed unused warning problem


Missing @Override annotation diagnosis

The Java compiler can optionally flag a method overriding a superclass method, but missing a proper @Override annotation. Missing @Override annotations can be added using Quick Fix.

picture of Java editor with method missing @Override warning

See the preference Java > Compiler > Errors/Warnings > J2SE 5.0 options > Missing '@Override annotation

Missing @Deprecated annotation diagnosis

The Java compiler recognizes the @Deprecated annotations, and treats them equivalent to the doc comment /** @deprecated */. It can optionally flag deprecated constructs missing a proper @Deprecated annotation (to encourage using annotations instead of doc comment tag).

picture of Java editor with missing @Deprecated annotation warning

See preference under Java > Compiler > Errors/Warnings > J2SE 5.0 options > Missing '@Deprecated' annotation

Incomplete enum switch statement diagnosis

The Java compiler can optionally flag incomplete enum switch statements.

picture of Java editor with incomplete enum switch statement warning

See preference under Java > Compiler > Errors/Warnings > J2SE 5.0 options > Not all enum constants covered on 'switch'

Compiler diagnosis for 'enum' identifier

The Java compiler can find and flag where 'enum' is used as an identifier. While 'enum' is a legal identifier up to source level 1.4, but a reserved keyword in 5.0 source. Enabling this warning helps to anticipate source migration issues. See the preference Java > Compiler > JDK Compliance > Disallow identifier called 'enum'.

Compiler optional diagnosis for 'enum' identifier


Quick Fix to
create enum constants

Quick Fix supports creation of enumeration constants. In the example below the constant BLUE is missing from the enumeration Colors

Compiler optional diagnosis for 'enum' identifier


Autoboxing parameter
proposals

Proposed parameters include auto(un-)boxing proposals:

Screenshot showing autoboxing proposals

Note: The Java > Editor > Code Assist > Fill argument names on completion preference has to be enabled.


Boxing/
unboxing diagnosis

The J2SE 5.0 autoboxing capability is powerful but it can lead to unexpected behavior especially when passing arguments. The compiler introduces an optional diagnosis that indicates when autoboxing or autounboxing is performed. In the following example, one might think that foo(Integer) would be called, but since autounboxing is performed, foo(int) is called.

picture of Java editor with unboxing warning

See preference under Java > Compiler > Errors/Warnings > J2SE 5.0 options > Boxing and unboxing conversions.

Support for J2SE 5.0 in Java editor

The Java editor provides syntax coloring for the new J2SE 5.0 language features. Go to the Java > Editor > Syntax Coloring preference page to change the colors or to enable semantic coloring of type variables, annotation elements and auto(un-)boxed expressions:

Screenshot showing syntax coloring of enum, annotations, annotation elements, type variables, and autoboxed expressions


New for loop template

The foreach template inserts a new 'for' loop into the code, proposing local Iterable instances you may want to iterate over:

Screenshot showing an inserted for-loop template


Convert to enhanced for loop

A new Quick Assist (Ctrl+1) offers to convert old-style for loops over arrays and collections to J2SE 5.0 enhanced for loops:

Picture convert to enhanced for loop example

The Quick Fix simplifies the loop to:

Picture demonstrating the result of enhanced for loop quick assist


Varargs argument
needing a cast

The Java compiler can optionally flag suspicious varargs method invocations. A null last argument is not wrapped as a 1-element array as one might expect; adding an explicit cast makes the intention of the code clear.

Compiler diagnoses required cast for varargs argument

The preference setting can be found at Java > Compiler > Errors/Warnings > J2SE 5.0 Options > Inexact type match for vararg arguments.


Completion uses static imports

Code completion in the Java editor is able to process static imports when inferring context-sensitive completions.

picture of Java editor completing and finding method from static import Math.*


Static import
groups

To organize your static imports, create groups for the static imports and place them where you prefer. You can define an 'others' group to collect up all imports not matched by any other group:

Static imports group

The 'others' group feature is also available for non-static imports.


Support for
package-info.java

Support has been added for the special source file package-info.java, which allows annotating and documenting packages. All JDT tools (code assist, code select, search, outline, type hierarchies, etc.) can be used in this special compilation unit.

Doc comments inside the package-info.java are processed, and the syntax and references in standard comment tags are verified.

picture of Package Explorer and Java editor on package-info.java


Code formatter for J2SE 5.0 constructs

The code formatter supports all the new J2SE 5.0 language constructs. Control over how the formatter handles them are found on the Java > Code Style > Code Formatter preference page:

Picture of white space formatter preference page


Debugging 5.0 source code

You can run and debug 5.0 source code with a 1.5 JRE. Java debug evaluations support J2SE 5.0 constructs such as generics and enhanced for loops.

Class file naming change for local inner types

In 5.0 compliance mode, the Java compiler generates class files that follow the naming convention specified in JLS 13.1 (3rd edition) for local inner types. As a consequence, in the below example, instead of generating a file named X$1$A.class, it will simply be X$1A.class.

picture of Navigator with local inner type class file


Java Debugger


Watchpoints and
method entry
breakpoints

Double clicking in the Java editor ruler creates watchpoints on fields and method entry breakpoints on method declarations.

Locks and deadlocks

The locks owned by a thread as well as the lock a thread is waiting for can both be displayed inline in the Debug view by toggling the Show Monitors menu item in the Debug view drop-down menu. Threads and locks involved in a deadlock are highlighted in red.

A deadlock displayed in the Debug view


Navigating stack traces

Copy and paste a stack trace into the Java Stack Trace Console and use hyperlinks to navigate the trace. The Java Stack Trace Console can be opened from the Open Console drop-down menu in the Console view. Pasted stack traces can be formatted via the standard Format key binding.

Java Stack Trace Console


'toString()' inline

The toString()-computed value of a variable can be displayed inline in the Variables view tree, as well as in the details area. The Java Detail Formatters... command in the view drop-down menu is used for configuring how this feature works.

Inline toString() example


User-defined logical structures

The Java debugger now lets you control what gets shown in the variables view for different types of objects. For example, collections can be displayed as a simple array of values, instead of the gory details on how that particular collection object is implemented.

This is done from the Java > Debug> Logical Structures preference page, where you associate with a specific class or interface either a single expression (for example, this.toArray()) or a series of named expressions. When the object is to be shown in the variables view, the expressions are evaluated to produce the values to display.

Dialog to edit Java logical structure


Enhanced variable value modification

The Java debugger now lets you change the value of variables by entering an expression into either the Change Value dialog or into the details area of the variables view and pressing Save.

Dialog to edit an expression to replace the current value of a variable


Find variable

The Find Variable action in the Variables view allows you to type in the name of a variable you are looking for. As you type, the Variables view selects the next visible variable matching the entered text. As well, the Find variable dialog shows variables matching the text entered so far.


Javadoc attachments

You can now associate a different Javadoc location with each JAR in a JRE's libraries.

Dialog showing a javadoc location per JRE library


Java Compiler


New Javadoc
compiler settings

When Javadoc checking is enabled, you can configure it to
  • warn when @see and @link tags reference deprecated elements
  • warn when @see and @link tags reference elements that are not visible

The settings are on the Java > Compiler > Javadoc preference page.


Assignment with no effect diagnosis for postfix expression

The optional diagnosis for assignment with no effect detects the case where a postfix expression is assigned to the same variable, e.g. i = i++;

picture of post fix expression assignment


Serial Version UID

There is a new optional compiler diagnosis for serializable classes missing a declaration of a serialVersionUID field.

The preference setting can be found at Java > Compiler > Errors/Warnings > Potential programming problems


Early detection of references to internal classes

You can annotate library (and project) entries on the Java build path (Properties > Java Build Path > Libraries) to identify any internal packages that you want to avoid referencing directly from your code. For example, it's generally a bad idea to depend on any of the vendor-specific packages, like com.ibm.* or com.sun.*, commonly found in the J2SE libraries. Access restrictions are expressed with a combination of inclusion and exclusion rules on build path entries. The pattern syntax follows Ant fileset notation, and matches against the path to the class file. For example, using the pattern com/ibm/** as an exclusion rule would restrict access to all classes in the com.ibm package and its subpackages; using the pattern org/eclipse/**/internal/** as an exclusion rule would catch all classes to internal Eclipse packages. When you provide inclusion rules, everything matched by these rules is ok, and everything else is considered out of bounds.

The Java > Compiler > Errors/Warnings > Deprecated and restricted API preference setting lets you control whether errant references are flagged as errors or warnings (they are errors by default for forbidden reference and warnings for discouraged references).

picture of Java Build Path properties dialog


Access rules on libraries and projects

Access rules can be defined on referenced libraries and projects to explicitly allow/disallow/discourage access to specific types.

picture of Build path wizard with access rules


Java Editor


Improved folding icons and captions

When folding a Java element, the remaining line in the Java editor is the one containing the element's name. The first comment line is displayed for folded Javadoc comments. The new lightweight folding icons shown in the Java editor now differ from the override and implements indicators:

Picture of new folding artwork


Header comment folding

Header comments and copyright statements in Java source files can be folded:

Screenshot showing a a folded header comment


Mark occurrences of inherited methods

The Java editor can highlight all method declarations that implement or override methods inherited from the selected supertype. See the Java > Editor > Mark Occurrences > Method implementing an interface preference setting.

Picture of mark Implement occurrences


New Occurrences Quick Menu

A context menu with occurrences searches can be opened in the Java editor by pressing Ctrl+Shift+U.

Note: Those who prefer the old behavior can reassign the above key sequence to the "Search All Occurrences in File" command.


Highlighting of deprecated class members in the Java editor

Deprecated class members are marked by advanced highlighting:

Highlighting of deprecated members

This is configurable on the Java > Editor > Syntax Coloring preference page.

References in Javadoc

Eclipse now recognizes references to Java elements inside doc comments (i.e., @see, @link, @linkplain, @throws, @exception, @param or @value tags). This enables hover help and linking to the referenced Java element.

picture of Java editor with hover in Javadoc


Improved completion on empty word

Java code completion on an empty word no longer automatically proposes all types visible at the completion location. You have to type the first character of the type to get a completion proposal.

picture of Java editor showing completion on empty word


Tool tip description for Javadoc

The Javadoc which is shown via Edit > Show Tooltip Description (F2) shows up in the SWT Browser widget.


Move Lines adjusts indentation

The Move Lines (Alt+Up/Down) and Copy Lines (Ctrl+Alt+Up/Down) commands automatically adjust the indentation of the selected lines as you move them inside the Java editor.

Improved Java properties file editor

The editors for Java property files have been greatly improved. They offer syntax highlighting, improved double-clicking behavior, and a separate font preference. The syntax highlighting colors are adjusted from the Java > Properties File Editor preference page. Spell checking is also available, and Quick Fix (Ctrl+1) can be used to fix spelling problems.

Picture of Java Properties File editor


Working with externalized strings

When you linger over a key for an externalized string in the Java editor, the associated externalized value is shown in a hover:

Picture of Externalize String hover

Ctrl+Click on it to navigate directly to the entry in the corresponding Java properties file:

Picture of Ctrl+Click in Java editor


Navigate from property key in Properties File editor to its references

Use Navigate > Open (F3) or Ctrl+click to navigate from a property key in the Properties File editor back to places in the code where the key is referenced.

Picture showing property key hyperlinking


Externalize Strings wizard supports new message bundles

The Externalize Strings wizard supports Eclipse's string externalization mechanism which is new with this release:

Picture of Externalize Strings wizard


New API to create code proposals like in the Java editor

Implementing an editor for a Java-like language? Create your own code assist proposals similar to the ones proposed in the Java editor. Instantiate CompletionProposalCollector to get the same proposals as the Java editor, or subclass it to mix in your own proposals. Use CompletionProposalLabelProvider to get the images and labels right, and sort the proposals using CompletionProposalComparator.

Package: org.eclipse.jdt.ui.text.java in the org.eclipse.jdt.ui plug-in.


General Java Tools


New Open Type dialog

The Java Open Type dialog has been improved in a number of ways:
  • There is now only a single list to select from.
  • A history of recently opened types shows up first in the dialog; workspace types matching the pattern appear below the separator line.
  • CamelCase pattern matching takes you to a type with fewer keystrokes. For example TZ matches TimeZone or IOOBE matches IndexOutOfBoundsException.
  • The content of the dialog can further be constrained to a working set. The working set can be selected from the dialog's drop down menu.

Open type dialog

There are major architectural changes under the hood as well. The types shown in the dialog are now found with a Java search engine query. This nets a saving of 4-6MB on a normal Eclipse development workspace over the memory-hungry approach used previously.


Organizing workspace with many projects

Use Show > Working Sets in the Package Explorer's view menu to enable a new mode that shows working sets as top level elements. This mode makes it much easier to manage workspaces containing lots of projects.

Package Explorer in Working Set mode

Use Select Working Sets from the Package Explorer's view menu to configure which working sets get shown. The dialog lets you create new Java working sets, define which working sets are shown and in what order. Working sets can also be rearranged directly in the Package Explorer using drag and drop and copy/paste.


Improved source folder page for new Java project wizard

An improved source folder configuration page in the Java project creation wizard assists you in creating projects from existing source. You can define source folder entries, include/exclude folders directly on the tree, and test the results of your action right away.

New source folder page


Sharing Java project settings

Each Java project can carry custom settings for compiler options and code style. These settings are stored in the project itself, and automatically applied when the project is loaded (or updated) from the repository.

Modifying the settings of a Java project via the UI automatically writes the settings to a file in the .settings directory. (The contents of the setting file are auto-generated, and not intended to be edited directly).

Shareable compiler settings


Navigate to project-specific settings

The preference pages for settings that are also configurable on a per-project basis offer a link to the project specific preference page.

Screenshot showing the per project settings link


Javadoc locations stored in the .classpath file

The Javadoc locations that are attached to JAR files and class folders are stored in the .classpath file so they can be shared with the team. When 3.1 starts up, a background job will migrate all the previously internally stored locations to the .classpath file.

The Javadoc locations are used by 'Open External Javadoc' (CTRL + F2) and by the Javadoc wizard.


Shortcuts for quick assists and quick fixes

Some of the popular quick assists like Rename In File and Assign To Local can be invoked directly with Ctrl+2 R and Ctrl+2 L. Check the keys preference page for more quick fixes that support direct invocation.

Keys preference page with quick assist shortcuts


New Quick Fixes

New Quick Fixes have been added for several Java compiler options, for example:
  • Missing serial version ID: Screenshot showing serial version quick fixes

New Quick Assists

Several Quick Assists (Ctrl+1) have been added to the Java Editor:
  • Invert boolean expressions:
    Picture of invert conditions quick assist
  • Invert a conditional expression:
    Invert condition quick assist
    results in:
    Inverted result
  • Convert conditional expression (? operator) to if-else statement, or vice versa
  • Introduce a new local variable after an instanceof check:
    Assign cast to local before invocation
    results in:
    Result after quick assist invocation
  • Break out single substring literal:
    Pick out string quick assist
    results in:
    Result of 'Pick out string' quick assist

Refactoring Undo/Redo available from Edit menu

Refactoring Undo/Redo is now available from the Edit menu, and the separate Refactor Undo/Redo actions have been removed from the global menu bar. Additionally, refactoring Undo/Redo operations are now integrated with Java editor Undo/Redo, resulting in a more transparent undo story in the editor. For example, a refactoring triggered from within the editor is now undoable in the editor by simply pressing Ctrl+Z.

Undo action in editor context menu


Member visibility adjustment

The refactoring commands Move method, Move Member Type to New File, Move Static member, Pull Up and Push Down automatically change the visibility of referenced fields, methods and types wherever necessary.

Screenshot showing the move member type to new file refactoring


Move method refactoring

The Refactor > Move command has been extended to better support moving instance methods. New features include:
  • The option to create a delegate method for compatibility
  • Unreferenced fields can now also be method targets

Screenshot showing the move refactoring on an instance method


Use Supertype Where Possible refactoring

The Use Supertype Where Possible refactoring has been extended with a preference that specifies whether type occurrences in instanceof expressions should be updated:

Screenshot showing the use supertype where possible wizard


Build path menu in the Package Explorer

The context menu of the Java Package Explorer has a new 'Build Path' menu entry, offering context-sensitive actions to modify the build path of a Java project. You can add/remove new source folders, archives and libraries, and include/exclude folders and files from a source folder:

Build path menu


New Eclipse default built-in formatter profile

Although Eclipse's default 3.0 code formatter profile is named Java Conventions, formatting a file using this profile uses tabs for indentation instead of spaces. A new profile named Eclipse has been added which reflects what the default formatter options have been all along, which uses tabs for indentation. To use true Java Convention settings, simply switch the formatter profile to Java Conventions using Java > Code Style > Formatter preference page.

Changing multiple line-wrap settings at once

The Java code formatter page lets you change multiple line-wrap settings at once by multi-selecting in the tree and then changing settings:

Code Formatter line wrap page

Code formatter settings are on the Java > Code Style > Formatter preference page.


Mixed indentation settings

The Java formatter preferences allows the tab size to be configured independently from the indentation size (see the Indentation tab in your formatter profile):

Java formatter preference page. Set the indentation preferences on the 'Indentation' tab of the formatter profile.

For example, set Tab size to 8 and Indentation size to 4 to indent your source with four spaces. If you set the Tab policy to Mixed, every two indentation units will be replaced by a tab character.

Formatter profiles can be configured on the Java > Code Style > Formatter preference page.


Rerun failed tests first

There's a new action in the JUnit view that allows you to rerun failing tests before any of the ones that were passing.

Rerun last failed tests