Motivation

Find Usages in Project Dependencies and JDK is a highly requested feature, especially from users working with J2EE projects or using maven. Issue 55291

The user expectation is that you will find all usages - there is no indication that non-project classes will be excluded, and it is quite a surprise when you are unable to use this basic feature to understand the way the JDK and libraries work. (At least the Go to Class dialog offers you the choice - F.U. does not.) There has been repeated feedback from users on this point.

Description

Java's Find Usages support will be enhanced with searching in a project's dependencies. When the user invokes Find Usages on an element and selects a newly added scope in the dialog:

Current Project & Dependencies
Open Projects & Dependencies

the index will be queried for all resources that reference the element. Usages from these resources, binary or source, will be shown in the results window. In this window the user can filter the results with the already available filters and the newly added filters binary, dependency and platform.

Enablement

In NetBeans 8.1 this enhancement will be enabled by default.

Command line option

Can be disabled by setting the cmdline option "org.netbeans.modules.refactoring.java.plugins.JavaWhereUsedQueryPlugin.dependencies=false".

Open Problems

Missing type references in the byte code

Missing Annotations with RetentionPolicy.SOURCE

Missing unused imports

Missing field access on constants.

According to JLS the constant is defined as
static final primitive type or string which value is constant in compile time.
For example: public static final String PROP_ENTRIES = "entries";
In the JDK 9 there should be an unused CONSTANT_Fieldref in constant pool emitted
by compiler which will fix the problem.

Missing references from if (compile time false) bloks.

private static final boolean DEBUG = false;
...
if (DEBUG) {
....
}

Missing references on types which are just referred in the method bodies (no method call

or field access is done on them) unless you compile with -g:vars. These references are not present due to missing Local Variable Table.

Possible solution

identifier index created from attached sources (no attribution) created when user first time does find usages on the jar with attached sources.
Benefits: Fixes missing source patterns
Problems: Lots of work on the level of index and refactoring.

If we decide to implement it with binary full index we should notify user about missing features. When the user invokes find usages on a constant or source level annotation, the new scope should not be available and this should be documented in the accompanied help files.
As only the method references and field access on non constant fields are reliable we should consider to do the find usages only on them. This will also remove the performance problem as neither method signatures nor code method attributes are parsed. No command line options will be needed.

UI

Find Usages dialog

Scopes for Type

Find Usages results

Results from dependency

Results from JDK

Filters for Dependencies and Binary results

Read

Write

ReadWrite

Import

Commment

SourceFile

BinaryFile*

TestFile

Dependency*

Platform*

Effort estimation

2 engineers/2 weeks

Dependencies

Impacts

Architecture

API

ClassIndex to get Binary Resources from the index.

Probably not needed. The ClassIndex already returns resources for binaries which have attached sources for super class, super interfaces. So it can do the same for method calls, field or type references. For binaries with no sources the usage cannot be displayed in method which uses the type, so it does not make much sense.

Documentation

Testing

Performance

Indexing binary attached sources by JavaCustomIndexer is no option due to performance impact.

Using binary full index.

Benefits: Already implemented in BinaryAnalyzer, needs to be just enabled.

The performance impact of enabling full binary index on JDK 7 rt.jar:

partial index

full index

Optimized

Index size:

6,546KB

7,605KB

(~+1MB)

6,663KB

creation time

2751ms

5225ms

(~100% regression)

5000ms

impact on query time

44ms

48ms

(~10% regression)

n/a

Performance evaluation

Collecting method calls and field access causes no performance degradation.