Using null type annotations in practice...Using null type annotations in practice Till Brychcy, Mercateo EclipseCon Europe, 2017 EclipseCon Europe, 2017 • What they are, why and

Using null type annotations in practice

Till Brychcy, Mercateo

EclipseCon Europe, 2017


• What they are, why and when to use them

• @Nullable vs. java.util.Optional

• Configuration choices

• Switching from declaration annotations to type annotations

• How to get warning free code - Code Patterns and Antipatterns

• Free Type variables and extends @Nullable

• Arrays

• Improvements released with Oxygen

• Preview to Photon


Some Statistics• First commit: Sep 18 2002

• First commit with null annotations: Jul 2 2012

• Switched to java 8 and null type annotations: Apr 15 2015

• Sample size: 7866 java files (approx. 20% of total code base)

• 3025 files use @NonNullByDefault (no package annotations)

• 10910 @Nullable annotation in 2175 files

• 1970 @NonNull annotations in 709 files

• 1070 @SuppressWarnings(„null")


Before null annotations /** * * @param catalogID * @param groupID * @param searchSpec * (may be null) * @param minIndex * @param maxIndex * @param sortBy * @param sortAscending * @return String */


Null annotation advantages

• One thing less to worry about

• Code that is easier to understand, change and debug

• No more NullPointerException

• Fewer other bugs


Null annotations disadvantages

• Compiler sometimes needs help: Avoid some code patterns

• Syntax a bit ugly


Newer languages: nice syntax• kotlin

• var x: String? = null;

• swift

• var x: String? = nil;

• c# (announced for version 8)

• string? x = null;


Null Annotations

• Normal use: @NonNullByDefault + @Nullable

• @NonNull: only for type parameters and during migration


Declaration vs. type annotations• Declaration annotation:

@Target({ FIELD, METHOD, PARAMETER, LOCAL_VARIABLE }) public @interface Nullable { }

• Type annotation:@Target({ TYPE_USE }) public @interface Nullable { }

• "Mixed" annotations are allowed by Java, but bad as null annotations:@Target({ TYPE_USE, FIELD, METHOD, PARAMETER, LOCAL_VARIABLE }) public @interface Nullable { }


Declaration annotation usages@NonNullByDefault public class Example { @Nullable String field;

@Nullable String add(@Nullable String arg1, List<String> list, @Nullable String[] array) { // just to show the syntax (local variables usually don't need annotations) @Nullable String local = arg1;

list.add(null); // is this OK? if(array != null) { array[0] = null; // or this? }

return local; } }


Equivalent with type annotations@NonNullByDefault({ FIELD, PARAMETER, RETURN_TYPE }) public class Example { @Nullable String field;

@Nullable String add(@Nullable String arg1, List<String> list, String @Nullable [] array) { // just to show the syntax (local variables usually don't need annotations) @Nullable String local = arg1;

list.add(null); // is this OK? if(array != null) { array[0] = null; // or this? }

return local; } }


Completely annotated@NonNullByDefault({ FIELD, PARAMETER, RETURN_TYPE, ARRAY_CONTENTS, TYPE_ARGUMENT }) public class Example { @Nullable String field;

@Nullable String add(@Nullable String arg1, List<@Nullable String> list, @Nullable String @Nullable [] array) { // just to show the syntax (local variables usually don't need annotations) @Nullable String local = arg1;

list.add(null); // OK! if (array != null) { array[0] = null; // OK! }

return local; } }


@NonNullByDefault defaultspublic enum DefaultLocation { PARAMETER, RETURN_TYPE, FIELD, TYPE_PARAMETER, TYPE_BOUND, TYPE_ARGUMENT, ARRAY_CONTENTS }

@Target({ ElementType.PACKAGE, ElementType.TYPE, ElementType.METHOD, ElementType.CONSTRUCTOR, ElementType.FIELD, ElementType.LOCAL_VARIABLE }) public @interface NonNullByDefault { DefaultLocation[] value() default { DefaultLocation.PARAMETER, DefaultLocation.RETURN_TYPE, DefaultLocation.FIELD, DefaultLocation.TYPE_ARGUMENT, DefaultLocation.TYPE_BOUND };

}


Type bounds: "extends"

• Think in types: Object x = ""; // OK String s = new Object(); // error

@Nullable String s1 = ""; // OK @NonNull String s2 = null; // error

⇒"String extends Object" corresponds to "@NonNull String extends @Nullable String"

• So:"@NonNull String extends @NonNull Object""@NonNull String extends @Nullable Object""@Nullable String extends @Nullable Object"


Free Type variables and extends @NullableWith standard @NonNullByDefault:

• class List<T> {…} T can be @Nullable or @NonNull

• user chooses List<@Nullable Integer> or List<String> (=List<@NonNull String>)

• class NumberList<T extends Number>{…} T must be @NonNull

• same as class NumberList<T extends @NonNull Number>

• same as NumberList<@NonNull T>

• class NumberList<@Nullable Number>: T must be @Nullable

• class NumberList<T extends @Nullable Number>: T can be @Nullable or @NonNull


Principles• Warning free workspace

• @NonNullByDefault in new code

• Add @NonNullByDefault to existing code with other changes

• If necessary, annotate related code

• @SuppressWarnings("null") is OK in certain situations

• Must be easy to use with maven (now: no maven settings at all, IDE-only)


@SuppressWarnings

• Generated code: hashCode & equals

• stream.filter(x->x != null).

• optional.orElse(null)

• Tests (still add @NonNullByDefault)

• Overrides for which we don’t want to add external annotations


Configuration choices

• Enable annotations based analysis in workspace settings (not project)

• File template with @NonNullByDefault

• DefaultLocation as favorites

• External annotations added to the JDK in Workspace

• Hide INFO in problems view




Why custom annotations

• Different defaults for @NonNullByDefault (e.g. exclude FIELD)

• @Retention(RUNTIME) for testing framework

• Easier to accept for users of other IDEs


Workspace-wide EEA for the JDK




Challenges when switching to type annotations

• Syntax for qualified names java.io.@Nullable File file (easy to fix)

• Syntax for Arrays (we used some regular expressions)

• Generics:

• Map.get() (configure external annotations)

• Generics that take a .class literal


Arrays

• @Nullable String @NonNull [] x;

• Problem during migration from declaration annotations

• Problem: new @NonNull String[10] contains nulls

• methods that don't care about nullness about array contents

<T extends @Nullable String> @NonNull String concat(T[] strings)


Observed null parameter handling

1. Don't think about it, let method caller guess

2. if(param==null) return null

3. Objects.requireNonNull(param)

4. try{…}catch(Exception e){…}

5. Assume nonnull, use javadoc for nullable


Some Antipatterns• No correlation analysis

• boolean b=(x != null); if(b) {x.someMethod()}

• int length = array == null ? 0 : array.length; for (int i = 0; i < length; i++)…

• No intraprocedural analysis:

• init(…)-methods in constructor

• if(isValid(x)) { x.something() }

boolean isValid(Some x) {return x != null && …}

• Event callbacks without context: e.g., org.xml.sax.ContentHandler

• Struts form beans

• some builder patterns


Some Good Patterns

• Empty string / collection / NOP-implementation instead of null

• final fields or even completely immutable fields

• Avoid null literals except to define class specific NULL constants


@Nullable vs. java.util.Optional• Two solutions for the same topic.

• "Don't care": Convenient mapping to other Optionals

• Code with Optional gets reliable with @NonNullByDefault, so use both

• Use Optional only for return values

• Optional is not Serializable

• @Nullable better when overriding methods

• Problem Optional#orElse (Guava had: #orNull)


Improvements in Oxygen• 54 bug fixes and enhancements related to null analysis and null annotations

• Quick Fix to move type annotations

• @NonNullByDefault

• DefaultLocation.ARRAY_CONTENTS implemented

• @Target(ElementType.FIELD) implemented

• @Target(ElementType.LOCAL_VARIABLE) implemented

• No warning for "T extends @Nullable String"

• Many quick assists avoid creating redundant @NonNull


• extract local variable

• create local variable for missing symbol

• create field for missing symbol

• create parameter for missing symbol

• override method

• create method (parameters, details of return type)

• change method: (add parameter)

• change method: (change parameter)

• assign expression to new local variable

• create constructor using fields

• generate delegate methods

• create method

• type change and signature change

• introduce parameter object

• extract class


Preview to Photon

• Quick fix to add @NonNullByDefault to package

• Java 9: @NonNullByDefault in module-info.java

• Maybe support 3rd-party NonNullByDefault variations (TypeQualifierDefault)

• More quick assists that avoid creating redundant @NonNull

Using null type annotations in practice...Using null type annotations in practice Till Brychcy, Mercateo EclipseCon Europe, 2017 EclipseCon Europe, 2017 • What they are, why and

Documents