Bruke nullannotasjoner

NullPointerException er en av de vanligste årsakene til feil for Java-programmer. I de enkleste tilfellene kan kompilatoren advare deg direkte når den ser kode som denne:

    Object o = null;
    String s = o.toString();

Med forgrening / sløyfer og kastede unntak blir det nødvendig med ganske sofistikert flytanalyse for å finne ut om en variabel som derefereres, er tildelt en verdi som er eller ikke er null, for noen eller alle baner gjennom programmet.

På grunn av den iboende kompleksiteten utføres flytanalyse helst i små bolker. Analyse av en metode om gangen kan utføres med god ytelse for verktøyet, mens helsystemanalyse er utenfor rekkevidden til Eclipses Java-kompilator. Fordelen er at analysen er rask og kan utføres trinnvis, slik at kompilatoren kan advare deg direkte mens du skriver. Ulempen er av analysen ikke kan "se" hvilke verdier (null eller ikke) som strømmer mellom metodene (som parametere og returverdier).

Nullanalyse mellom prosedyrer

Det er her nullannotasjoner kommer inn. Ved å spesifisere en metodeparameter som @NonNull kan du fortelle kompilatoren at du ikke ønsker en nullverdi i denne posisjonen.

    String capitalize(@NonNull String in) {
        return in.toUpperCase();                // no null check required
    }
    void caller(String s) {
        if (s != null)
            System.out.println(capitalize(s));  // preceding null check is required
    }

I likhet med Design-by-Contract har denne to sider:

  1. Det er kallerens ansvar aldri å sende en nullverdi, noe som kan sikres f.eks. ved en eksplisitt nullkontroll.
  2. Implementoren for metoden capitalize har garanti for at argumentet in ikke vil være null. Dermed er det OK å dereferere uten nullkontroll her.

For metodens returverdier er situasjonen symmetrisk:

    @NonNull String getString(String maybeString) {
        if (maybeString != null)
            return maybeString;                         // the above null check is required
   else
            return "<n/a>";
    }
    void caller(String s) {
        System.out.println(getString(s).toUpperCase()); // no null check required
    }
  1. Nå må implementoren sikre at null aldri returneres.
  2. Motsatt har kalleren nå garanti for at dereferering av metoderesultatet uten kontroll er OK.

Tilgjengelige annotasjoner

Eclipses Java-kompilator kan konfigureres til å bruke tre forskjellige annotasjonstyper for sin forbedrede nullanalyse (som er deaktivert som standard):

Annotasjonene @NonNull og @Nullable støttes på disse stedene:

@NonNullByDefault støttes for

Legg merke til at selve de faktiske kvalifiserte navnene for disse annotasjonene kan konfigureres, men som standard brukes de ovennevnte (fra pakken org.eclipse.jdt.annotation).

Oppsett for byggebane

En JAR-fil med standard nullannotasjoner sendes med Eclipse i eclipse/plugins/org.eclipse.jdt.annotation_*.jar. Denne JAR-filen må være i byggebanen ved kompilering, men det er ikke nødvendig ved kjøring (så du er ikke nødt til å sende den til brukerne av den kompilerte koden).

Det er to hurtigrettelser for uløste referanser til @NonNull, @Nullable eller @NonNullByDefault som legger til JAR-filen i byggebanen:

Tolkning av nullannotasjoner

Det skulle være åpenbart at nullannotasjoner tilfører mer informasjon til Java-programmet (som så kan brukes av kompilatoren til å gi bedre varsler). Men hva vil vi egentlig at disse annotasjonene skal si? Fra et pragmatisk synspunkt er det minst tre nivåer for hva vi vil uttrykke med nullannotasjoner:

  1. Sporadiske hint til leseren (menneske og kompilator)
  2. Design etter avtale: API-spesifikasjon for noen av metodene eller alle
  3. Full spesifikasjon med et utvidet typesystem

For (1) kan du begynne å bruke nullannotasjoner med en gang uten å lese mer, men du bør ikke forvente mer enn et lite hint en gang imellom. De andre nivåene krever mer forklaring.

Design etter avtale: API-spesifikasjon

Ved første øyekast betyr bruk av nullannotasjoner for API-spesifikasjoner som ved design etter avtale bare at signaturer for alle API-metoder må være fullt annotert. Det vil si at med unntak av primitive typer som int skal hver parameter og hver metodereturtype merkes som enten @NonNull eller @Nullable. Siden dette vil bety at man setter inn veldig mange nullannotasjoner, er det greit å vite at @NonNull forekommer betydelig oftere enn @Nullable i velutformet kode (særlig API-metoder). Antallet annotasjoner kan dermed reduseres ved å deklarere @NonNull som standard og bruke @NonNullByDefault-annotasjonen på pakkenivå.

Legg merke til at det er betydelige forskjeller mellom @Nullable og det å utelate en nullannotasjon: Denne annotasjonen kunngjør eksplisitt at null er OK og må forventes. Derimot innebærer fravær av annotasjon bare at vi ikke vet hva hensikten er. Dette er den gamle situasjonen der begge sider (kaller og oppkalt) iblant utfører nullkontroll, og iblant antar begge sider at den andre siden utfører kontrollen. Det er her NullPointerExceptions stammer fra. Men en annotasjon gir ikke kompilatoren noe bestemt råd, men med en @Nullable-annotasjon flagges hver eneste ukontrollerte dereferanse.

På dette grunnlaget kan vi direkte tilordne alle parameterannotasjoner til før-betingelser og tolke returannotasjonene som etter-betingelser for metoden.

Subtyper og overstyring

I objektorientert programmering må begrepet design etter avtale ta seg av en dimensjon til: subtyper og overstyring (i fortsettelsen brukes "overstyre" i betydningen @Override-annotasjon i Java 6: metoder som overstyrer eller implementerer en annen metode fra en supertype. En klient som aktiverer en metode som denne:

    @NonNull String checkedString(@Nullable String in)

bør tillates å anta at alle implementeringer av denne metoden overholder kontrakten. Så når metodedeklarasjonen blir funnet i et grensesnitt I1, må vi utelukke at enhver klasse Cn som implementerer I1, innebærer en inkompatibel implementering. Særlig er det forbudt hvis noen Cn prøver å overstyre denne metoden med en implementering som deklarerer parameteren som @NonNull. Hvis vil vil tillate det, kan en klientmodul som er programmert mot I1, lovlig sende null som argument, men implementeringen vil anta at verdien ikke er null. Ikke-kontrollert dereferanse i metodeimplementeringen er tillatt, men ødelegges ved kjøring. En @Nullable-parameterspesifikasjon forplikter dermed alle overstyringer til å tillate null som forventet, lovlig verdi.

Motsatt: En @NonNull-returspesifikasjon forplikter alle overstyringer til å sikre at null aldri returneres.

Kompilatoren må derfor kontrollere at ingen overstyring legger til en @NonNull-parameterannotasjon (eller en @Nullable-returannotasjon) som ikke fantes i supertypen.

Interessant nok er de motsatte redefinisjonene tillatt: å legge til en @Nullable-parameterannotasjon eller en @NonNull-returannotasjon. (Du kan anse disse som "forbedringer" av metoden. Flere verdier godtas, og en mer spesifikk returverdi produseres.)

Legacy-supertyper

Vurderingene ovenfor byr på vanskeligheter når annotert kode skrives som en subtype av en "legacy"-type (dvs. en ikke-annotert type, eventuelt fra et tredjepartsbibliotek, som ikke kan endres). Hvis du leser siste seksjon svært nøye, har du kanskje merket at vi ikke tillater at en "legacy"-metode overstyres av en metode med en @NonNull-parameter (siden klienter som bruker supertypen, ikke "ser" @NonNull-forpliktelsen).

I denne situasjonen blir du tvunget til å utelate nullannotasjoner. (Det er planer om å støtte tilføyelse av annotasjoner til biblioteker i etterkant, men det kan ennå ikke loves noe om hvorvidt og når dette vil være tilgjengelig.)

Avbryte en nullstandard

Situasjonen kan bli vanskelig hvis en subtype av en "legacy"-type er i en pakke som det er spesifisert @NonNullByDefault for. En type med en ikke-annotert supertype må merke alle parametere i overstyringsmetoder som @Nullable: Selv det å utelate parameterannotasjoner er ikke tillatt, for det ville bli tolket som en @NonNull-parameter, som er forbudt i den posisjonen. Derfor støtter Eclipses Java-kompilator avbrudd for en nullstandard: Ved at en metode eller type annoteres med @NonNullByDefault(false), kan en relevant standard avbrytes for dette elementet, og ikke-annoterte parametere tolkes igjen som uspesifiserte. Subtyper er tillatt uten at uønskede @Nullable-annotasjoner legges til:

class LegacyClass {
    String enhance (String in) { // clients are not forced to pass nonnull.
        return in.toUpperCase();
    }
}
 
@NonNullByDefault
class MyClass extends LegacyClass {
	
    // ... methods with @NonNull default ...
 
    @Override
    @NonNullByDefault(false)
    String enhance(String in) { // would not be valid if @NonNullByDefault were effective here
        return super.enhance(in);
    }
}

Fordeler ved design etter avtale

Bruk av nullannotasjoner i form av design etter avtale som omtalt ovenfor bidrar til å forbedre kvaliteten til Java-koden på flere måter: Ved grensesnittet mellom metodene gjøres det eksplisitt hvilke parametere / returer som tolererer en nullverdi, og hvilke som ikke gjør det. Dette favner om designbeslutninger som er svært relevante for utviklere, på en måte som gjør at kompilatoren kan kontrollere det.

På grunnlag av denne grensesnittspesifikasjonen kan dessuten flytanalyse mellom prosedyrer få tak i tilgjengelig informasjon og sørge for mer presise feilmeldinger/advarsler. Uten annotasjoner har enhver verdi som strømmer inn i eller ut av en metode, ukjent nullstatus. Derfor sier nullanalysen ingenting om bruken. Med nullannotasjoner på API-nivå er nullstatusen til de fleste verdier faktisk kjent, og betydelig færre NPEer går ubemerket gjennom kompilatoren. Du bør imidlertid være klar over at det fortsatt finnes smutthull der uspesifiserte verdier strømmen inn i analysen og hindrer en fullstendig påstand om hvorvidt NPEer kan forekomme ved kjøring.

Full spesifikasjon med et utvidet typesystem

Støtten for nullannotasjoner er utformet slik at den er kompatibel med en fremtidig utvidelse, slik at kompilatoren skal kunne sikre at et sertifisert program aldri kaster et NullPointerException ved kjøring (med forbehold om ukontrollerbare deler som refleksjon). Selv om det ennå ikke kan loves noe med hensyn til fremtidig utvidelse, er ideen en litt annen tolkning av det vi allerede har.

Ved å tolke nullannotasjoner som en del av typesystemet kan vi doble antall typer i et gitt program: For en gitt klasse Cn anses ikke lenger selve klassen som en gyldig type. Bare "@NonNull Cn" og "@Nullable Cn" er nyttige typer. Så ideelt sett vil vi vite for hver verdi i et program om den kan være null (og må kontrolleres før dereferanse). Hvis vi utelukker det tredje alternativet (ikke-annoterte typer), kan kompilatoren strengt flagge hvert tilfelle av utrygg bruk.

Gjeldende implementering har to viktige begrensninger med tanke på dette målet:

Til tross for begrensningene har visjonen om fullt spesifiserte og fullstendig kontrollerte programmer allerede på det nåværende tidspunkt gitt seg utslag i gjeldende analyse og feilmeldinger/varsler som rapporteres av kompilatoren. Reglene som kompilatoren kontrollerer og meldingene den sender ut ved brudd på regler, vil bli forklart.

Forklaring på kompilatormeldinger

På tilsvarende preferanseside finner du de enkelte reglene som kompilatoren kontrollerer, under følgende overskrifter:

Overtredelse av null-spesifikasjon

Som spesifikasjonsbrudd kan vi håndtere enhver situasjon der en nullannotasjon hevder å være overtrådt av den faktiske implementeringen. En typisk situasjon skyldes at det oppgis en verdi (lokal, argument, metoderetur) som as @NonNull, mens implementeringen faktisk gir en verdi som kan ha nullverdi. Her anses et uttrykk å kunne ha nullverdi dersom det enten er statisk kjent for å evaluere til verdien null, eller det er deklarert med en @Nullable-annotasjon.

Denne gruppen inneholder også reglene for metodeoverstyring, som nevnt over. En utmerket metode etablerer i den forbindelse et krav (f.eks. at null er et gyldig argument), mens en overstyring prøver å unnslippe dette kravet (ved å anta at null ikke er et gyldig argument). Som nevnt er det å spesialisere et argument fra ikke-annotert til @NonNull et spesifikasjonsbrudd fordi det introduserer en avtale som kan binde klienten (til ikke å sende null), mens en klient som bruker supertypen, ikke en gang vil se denne avtalen, siden han ikke vet hva som forventes av ham.

Den fullstendige listen over situasjoner som anses som spesifikasjonsbrudd, finner du her. Det er viktig å forstå at feil i denne gruppen aldri må ignoreres. Ellers vil hele nullanalysen bli utført på falske premisser. Når kompilatoren ser en verdi med en @NonNull-annotasjon, tar den for gitt at null ikke vil forekomme ved kjøring. Det er regler om spesifikasjonsbrudd som sikrer at denne antakelsen holder. Derfor anbefales du på det sterkeste å la denne typen problemer konfigureres som feil.

Konflikt mellom null-annotasjoner og null-slutninger

Denne gruppen av regler våker også over overholdelse av nullspesifikasjoner. Her skal vi imidlertid ta for oss verdier som ikke er deklarert som @Nullable (eller som selve verdien null), men verdier der flytanalyse mellom prosedyrer utleder at null muligens kan opptre i noen utføringsbaner.

Denne situasjonen oppstår fordi kompilatoren for ikke-annoterte lokale variabler trekker slutninger om hvorvidt null er mulig, ved hjelp av flytanalyse. Hvis vi antar at dette er riktig, og kompilatoren ser et problem, har dette problemet samme alvorsgrad som direkte brudd på en nullspesifikasjon. Du anbefales derfor igjen på det sterkeste å la disse problemene konfigureres som feil og ikke ignorere disse meldingene.

Det er to grunner til å opprette en separat gruppe for disse problemene: å dokumentere at et gitt problem har oppstått, ved hjelp av flytanalyse, og å forklare at denne flytanalysen kan inneholde feil (på grunn av en feil i implementeringen). I tilfelle en kjent implementeringsfeil kan det i unntakstilfeller være OK å utelate en feilmelding av denne typen.

Ut fra den statiske analysens natur er det mulig at flytanalysen ikke ser at en viss kombinasjon av utføringsbaner og verdier ikke er mulig. Ta for eksempel denne variabelkorrelasjonen:

   String flatten(String[] inputs1, String[] inputs2) { 
        StringBuffer sb1 = null, sb2 = null;
        int len = Math.min(inputs1.length, inputs2.length);
        for (int i=0; i<len; i++) {
            if (sb1 == null) {
                sb1 = new StringBuffer();
                sb2 = new StringBuffer();
            }
            sb1.append(inputs1[i]);
            sb2.append(inputs2[i]); // warning here
        }
        if (sb1 != null) return sb1.append(sb2).toString();
        return "";
    }

Kompilatoren vil rapportere en potensiell nullpekers tilgang ved aktivering av sb2.append(..). En person som leser, kan se at det ikke er noen reell fare, for sb1 og sb2 korrelerer på en måte der begge variabler er null eller ingen er null. I den aktuelle linjen vet vi at sb1 ikke er null. Dermed er heller ikke sb2 null. Uten å gå i detalj om hvorfor slik korrelasjonsanalyse er hinsides funksjonaliteten til Eclipses Java-kompilator, bør du huske at denne analysen ikke er like kraftig som et fullstendig teorembevis, og derfor pessimistisk rapporterer noen problemer som grundigere analyse muligens kunne ha identifisert som falsk alarm.

Hvis du vil dra nytte av flytanalysen, bør du hjelpe kompilatoren litt, så den kan "se" dine konklusjoner. Denne hjelpen av være noe så enkelt som å dele if (sb1 == null) i to separate if, én for hver lokale variabel, som er en liten pris å betale for den fordelen at kompilatoren nå kan se nøyaktig hva som skjer, og kontrollere koden deretter. Dette emnet diskuteres mer i detalj nedenfor.

Umerket konvertering fra ikke-annotert type til @NonNull-type

Denne gruppen av problemer bygger på følgende analogi: I et program som bruker Java 5 generics, kan ethvert kall til biblioteker fra før Java 5 eksponere ubehandlede typer, det vil si applikasjoner av en generisk type som ikke spesifiserer konkrete typeargumenter. For at slike verdier skal passe i et program som bruker generics, kan kompilatoren legge til en implisitt konvertering ved å anta at typeargumentene er spesifisert på den måten som forventes av klientdelen av koden. Kompilatoren vil sende ut en advarsel om bruken av en slik konvertering og fortsette sin typekontroll ut fra antakelsen om at biblioteket "gjør det rette". På nøyaktig samme vis kan en ikke-annotert returtype anses som ubehandlet type eller "legacy"-type. Igjen kan et implisitt konvertering optimistisk anta forventet spesifikasjon. Igjen sendes en advarsel ut og analysen fortsetter ut fra antakelsen om av biblioteket "gjør det rette".

Teoretisk angir også behovet for slike implisitte konverteringer et spesifikasjonsbrudd. I dette tilfellet kan det imidlertid være tredjepartskode som bryter mot spesifikasjonene som vår kode forventer. Eller kanskje (som vi har overbevist oss selv om) en tredjepartskode overholder avtalen, men ikke deklarerer dette (fordi den ikke bruker nullannotasjoner). I slike situasjoner er det ikke sikkert vi kan rette problemet helt av organisatoriske grunner.

    @SuppressWarnings("null")
    @NonNull Foo foo = Library.getFoo(); // implicit conversion
    foo.bar(); 

Kodesnutten over antar at Library.getFoo() returnerer en Foo uten å spesifisere en nullannotasjon. Vi kan integrere returverdien i vårt annoterte program ved tildeling til en lokal @NonNull-variabel, som utløser en advarsel vedrørende en ukontrollert konvertering. Ved å legge til en tilsvarende SuppressWarnings("null") i denne deklarasjonen, tilkjennegir vi den potensielle faren og tar på oss ansvaret for å få kontrollert at biblioteket faktisk oppfører seg som ønsket.

Tips om hvordan du gjør koden mer analyserbar

Hvis flytanalysen ikke kan se at en verdi ikke er null, er enkleste strategi alltid å legge til en ny begrenset lokal variabel annotert med @NonNull. Hvis du er sikker på at verdien som er tildelt til denne lokale, aldri vil være null ved kjøring, kan du bruke en helper-metode som denne:

    static @NonNull <T> T assertNonNull(@Nullable T value, @Nullable String msg) {
        if (value == null) throw new AssertionError(msg);
        return value;
    }
    @NonNull MyType foo() {
        if (isInitialized()) {
            MyType couldBeNull = getObjectOrNull();
            @NonNull MyType theValue = assertNonNull(couldBeNull, 
                    "value should not be null because application " +
                    "is fully initialized at this point.");
            return theValue;
        }
        return new MyTypeImpl();
    }

Legg merke til at du ved å bruke assertNonNull()-metoden over godtar ansvaret for at denne påstanden alltid vil stemme ved kjøring. Hvis det ikke er det du vil, hjelper det fortsatt med annoterte lokale variabler når det gjelder å innsnevre hvor og hvorfor analysen ser et potensial for at null strømmer inn på et bestemt sted.

Tips om bruk av nullannotasjoner

Idet JDT versjon 3.8.0 utgis, arbeides det fortsatt med innsamling av råd for bruk av nullannotasjoner. Av den grunn vedlikeholdes denne informasjonen i Eclipse-wikien.