Använda null-annoteringar

NullPointerException är en av de vanligaste felorsakerna i Java-program. I de enklaste fallen kan kompilatorn varna direkt när den träffar på kod som denna:

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

Med förgrening/slingor och returnering av undantag blir avancerad flödesanalys nödvändig för att få reda på om en variabel som derefereras har tilldelats null-/icke-nullvärde på vissa eller alla sökvägar i programmet.

På grund av sin komplexitet utförs flödesanalys bäst i små delar. Att analysera en metod i taget kan ge goda prestanda - men att analysera hela systemet ligger utanför Eclipses Java-kompilatorns förmåga. Fördelen är denna: analysen är snabb och kan utföras inkrementellt så att kompilatorn varnar direkt när du skriver. Nackdelen är denna: analysen kan inte "se" vilka värden (null eller icke-null) som flödar mellan metoderna (t.ex. parametrar och returvärden).

Interprocedurell nullanalys

Det är här som null-annotering kommer till användning. Genom att ange en metodparameter som @NonNull kan du visa kompilatorn att du inte vill ha ett nullvärde i denna position.

    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 linje med Design-by-Contract har detta två sidor:

  1. Det är anroparens ansvar att aldrig skicka ett nullvärde som inte är säkrat, t.ex. av en explicit nullkontroll.
  2. Implementeringsfunktionen för metoden capitalize garanterar att argumentet in inte är null, alltså är det OK att dereferera utan nullkontroll här.

För metodens returvärden är situationen 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. Nu måste implementeringsfunktionen säkerställa att null aldrig returneras.
  2. Omvänt garanteras anroparen att dereferering av metodresultatet utan kontroll är OK.

Tillgängliga annoteringar

Eclipse Java-kompilatorn kan konfigureras att använda tre skilda annoteringstyper för sin förbättrade nullanalys (som inte är aktiverad som standard):

Annoteringarna @NonNull och @Nullable kan användas på följande platser:

@NonNullByDefault kan användas för

Observera att de faktiska fullständiga namnen på dessa annoteringar är konfigurerbara, men som standard är de som anges ovan de som används (från paketet org.eclipse.jdt.annotation).

Ange byggsökvägen

En JAR-fil med standardvarianterna av nullannoteringarna finns i eclipse/plugins/org.eclipse.jdt.annotation_*.jar. Denna JAR-fil ska ligga i byggsökvägen vid kompileringen men den behövs inte vid körningen (så du behöver inte skicka den till dem som använder din kompilerade kod).

Det finns två snabbfixar för olösta referenser för @NonNull, @Nullable och @NonNullByDefault som lägger in JAR-filen i byggsökvägen.

Tolkning av nullannoteringar

Du måste veta att nullannoteringar lägger in mer information i Java-programmet (som sedan kan användas av kompilatorn för att ge bättre varningar). Men vad ska annoteringarna säga? Pragmatiskt sett finns det minst tre nivåer av vad vi kan vilka uttrycka med nullannoteringar:

  1. Sporadiska tips till läsaren (människa eller kompilator)
  2. Design by Contract: API-specifikation för vissa eller samtliga metoder
  3. Fullständiga specifikationer genom ett utökat typsystem

Vad (1) beträffar kan du börja använda nullannoteringar direkt utan att läsa vidare, men du kan inte förvänta dig mer än en liten fingervisning då och då. De övriga nivåerna kan behöva ytterligare förklaringar.

Design by Contrakt: API-specifikation

I förstone kan användande av nullannoteringar för API-specifikation i Design by Contracts anda bara betyda att signaturerna för alla API-metoder bör vara fullt annoterade utom för primitiva typer som int där varje parameter och varje metods returtyp bör markeras som antingen @NonNull eller @Nullable. Eftersom detta skulle innebära inläggning av oerhört många nullannoteringar kan det vara bra att veta att det i välformad kod (särskilt API-metoder) finns avsevärt fler @NonNull än @Nullable. Alltså kan antalet annoteringar minskas genom att du deklarerar @NonNull som standard genom en @NonNullByDefault-annotering på paketnivå.

Observera den avsevärda skillnaden mellan @Nullable och att utelämna en nullannotering: annoteringen anger explicit att null är OK och ska förväntas. Ingen annotering betyder helt enkelt att vi inte vet vilken avsikten är. Detta är den gamla situation då bägge sidor (anropade och anropad) ibland helt överflödigt kontrollerar null och ibland helt felaktigt antar att den andra sidan utför kontrollen. Detta är ursprunget till NullPointerExceptions. Utan en annotering ger kompilatorn inga specifika råd men med annoteringen @Nullable flaggas samtliga dereferenser som inte kontrollerats.

Härigenom kan vi direkt avbilda alla parameterannoteringar till för-villkor och tolka returannoteringar som metodens efter-villkor.

Undertyper och åsidosättning

I objektorienterad programmering måste konceptet Design by Contract omfatta ytterligare en dimension: undertyper och åsidosättning (här har termen "åsidosättning" betydelsen @Override-annotering i Java 6: metoder som åsidosätter eller implementerar en annan metod från en överordnad typ). En klient som anropar en metod som följande:

    @NonNull String checkedString(@Nullable String in)

ska tillåtas anta att alla implementationer av denna metod uppfyller kontraktet Så när metoddeklarationen finns i ett gränssnitt I1 måste vi utesluta att någonCn-klass som implementerar I1 tillhandahåller en inkompatibel implementation. Mer exakt uttryckt är det ogiltigt om någon Cn försöker åsidosätta denna metod med en implementation som deklarerar parametern som @NonNull. Om vi faktiskt skulle tillåta detta kunde en klientmodul som programmerats mot I1 helt giltigt skicka null som argument men implementationen skull anta ett icke-nullvärde - en ej kontrollerad dereferens i metodimplementationen skulle tillåtas men spricka vid körningen. Därför godkänneren @Nullable-pararameterspecifikation alla åsidosättningar null som ett förväntat giltigt värde.

Tvärtom tillåter en @NonNull-returspecifikation alla åsidosättningar för att säkerställa att null aldrig returneras.

Därför måste kompilatorn kontrollera att ingen åsidosättning lägger till en @NonNull-parameterannotering (eller en @Nullablereturannotering) som inte fanns i den överordnade typen.

Intressant nog är de motsatta omdefinitionerna giltiga: att lägga in en @Nullable-parameterannotering eller en @NonNullreturannotering (du kan betrakta dem som "förbättringar" i metoden, den godtar fler värden och ger ett mer specifikt returvärde).

Äldre överordnade typer

De föregående betraktandena kan innebära svårigheter när man skriver annoterad kod som underordnad typ till en "äldre kodtyp" (dvs. icke-annoterad) som kanske kommer från ett tredjepartsbibliotek och därför inte går att ändra. Om du läst föregående stycken noggrant kanske du lagt märke till att vi inte kan godkänna att en "äldre" metod åsidosätts av en metod med en parameter av typen @NonNull (eftersom klienter som använder den överordnade typen inte "inser" @NonNull-plikten).

I detta läge tvingas du att avstå från null-annoteringar (man planerar att tillåta tillägg av annoteringar i bibliotek i efterhand, men detta är ännu osäkert).

Annullera nullbarhet som standard

Det kan bli knepigt om en underordnad typ till en "äldre" typ finns i ett paket där man angett@NonNullByDefault. En typ med en icke-annoterad överordnad typ skulle då behöva markera samtliga parametrar i åsidosättande metoder som @Nullable: inte ens att utelämna parameterannoteringar är tillåtet eftersom detta skulle tolkas som en @NonNull-parameter, något som inte är tillåtet i den positionen. Det är därför Eclipse Java-kompilatorn har annullering av nullbarhet som standard: genom att annotera en metod eller typ med @NonNullByDefault(false) kommer ett tillämpligt standardvärde att annulleras för detta element, och icke-annoterade parametrar att tolkas som ospecificerade. Då blir underordnade typer åter giltiga utan oönskade @Nullable-annoteringar:

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);
    }
}

Fördelarna med Design-by-Contract

Att använda nullannoteringar enligt Design-by-Contract som demonstrerats ovan kan förbättra kvaliteten i Java-koden på många sätt: i gränssnittet mellan metoderna framgår det explicit vilka parametrar/returer som tolererar ett nullvärde och vilka som inte gör det. Detta fångar upp designbeslut som är ytterst relevanta för utvecklare på ett sätt som kompilatorn också kan kontrollera.

Dessutom kan den intraprocedurella flödesanalysen i denna gränssnittsspecifikation plocka fram information och ge exaktare felmeddelanden och varningar. Utan annoteringar har alla värden som flödar in i och ut ur en metod okänd nullbarhet och därför kan nullanalysen inte säga någonting om deras användning. Med nullannoteringar på API-nivå är nullbarheten för de flesta värden faktiskt känd och avsevärt färre NPEer noteras av kompilatorn. Observera dock att det ändå finns en del kryphål där ospecificerade värden flyter in i analysen och förhindrar en komplett utsaga huruvida NPEer kan inträffa vid körningen eller ej.

Komplett specifikation med ett utökat typsystem

Hanteringen av nullannoteringar har utformats så att den är kompatibel med framtida utbyggnad, varigenom kompilatorn kan garantera att ett certifierat program aldrig kommer att ge felet NullPointerException vid körningen (med förbehåll för delar som inte går att kontrollera, som reflektion). Visserligen kan inga löften ännu ges angående en sådan framtida utbyggnad, men grundtanken är bara en annorlunda tolkning av det vi redan har.

Genom att tolka nullannoteringar som en del av typsystemet fördubblar vi antalet typer i ett givet program: för varje given klass Cn, betraktas inte själva klassen som en giltig typ utan endast som"@NonNull Cn" och "@Nullable Cn" är användbara typer. Idealiskt sett vet vi för varje värde i ett program om det kan vara null (och måste kontrolleras före dereferens) eller inte. Om vi exkluderar det tredje alternativet (icke-annoterade typer) kan då kompilatorn med stor noggrannhet flagga all osäker användning.

Den nuvarande implementationen har två stora begränsningar med tanke på detta mål:

Idag, och trots de nuvarande begränsningarna, har visionen om fullt specificerade och fullständigt kontrollerade program redan gett vissa konsekvenser som format nuvarande analys och de felmeddelanden och varningar som kompilatorn rapporterar. Detaljerna kommer att presenteras genom en förklaring av de regler kompilatorn kontrollerar och de meddelanden den ger vid brott mot en regel.

Förklaringar på kompileringsmeddelanden

På motsvarande inställningssida finns de respektive regler som kompilatorn kontrollerar under följande rubriker:

Regelbrott mot null-specifikation

Som brott mot specifikationen hanterar vi varje situation där en nullannotering hävdar att den kränkts av den aktuella implementationen. Den typiska situationen uppstår om man specificerat ett värde (local, argument, method return) som @NonNull medan implementationen faktiskt har ett nullbart värde. Här betraktas ett uttryck som nullbart om det antingen är statiskt känt för att utvärdera värdet null eller om det deklarerats med en @Nullable-annotering.

För det andra innehåller denna grupp också reglerna för metodåsidosättande som diskuteras i ovan. Här gör en överordnad metod ett anspråk (t.ex. att null är ett giltigt argument) medan åsidosättandet försöker undgå detta anspråk (genom att anta att null inte är ett giltigt argument). Som nämnts är till och med att specialisera ett argument från icke-annoterat till @NonNull ett specifikationsbrott eftersom det inför ett kontrakt som binder klienten (att inte skicka null), medan en klient som använder den överordnade typen inte ens kommer att se detta kontrakt och inte ens vet vad som förväntas av den.

Den fullständiga listan över situationer som ses som specifikationsbrott finns här. Det är viktigt att förstå att fel i denna grupp aldrig får ignoreras eftersom hela nullanalysen då kommer att utföras med felaktiga förutsättningar. Observera att när kompilatorn stöter på ett värde med @NonNull-annotering tar den för givet att null inte kommer att inträffa under körningen. Det är reglerna om specifikationsbrott som säkerställer att detta är ett klokt resonemang. Därför rekommenderar vi starkt att detta slags problem konfigureras som fel.

Konflikt mellan null-annoteringar och null-slutsats

Denna regelgrupp avser efterlevnaden av nullspecifikationerna. Men här handlar det om värden som inte är deklarerade som @Nullable (och inte heller själva nullvärdet) utan värden därintraprocedurell flödesanalys härleder att null omöjligen kan förekomma i någon körsökväg.

Denna situation uppstår ur det faktum att kompilatorn för icke-annoterade lokala variabler med sin flödesanalys härleder huruvida null är möjligt. Om den hittar ett problem får detta samma allvarlighetsgrad som ett direkt brott mot en nullspecifikation - förutsatt att denna analys är riktig. Därför måste vi åter starkt rekommendera att du konfigurerar dessa problem som fel och att du inte ignorerar dessa meddelanden.

Att skapa en separat grupp för dessa problem tjänar två syften: dels att dokumentera att ett givet problem hittades med hjälp av flödesanalys, dels att redovisas att denna flödesanlys kunde ha fel (på grund av ett programfel i implementationen). I fallet med ett identifierat implementeringsfel kan det i exceptionella fall vara OK att undertrycka felmeddelanden av detta slag.

Med tanke på den statiska analysens natur kan flödesanalysen missa att upptäcka att en viss kombination av körsökvägar inte är möjlig. Se följande exempel på variabelkorrelation:

   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 "";
    }

Kompilatorn kommer att rapportera en potentiell nullpekaråtkomst närsb2.append(..) anropas.. En människa kan se att det inte är någon faktisk fara eftersom sb1 och sb2 faktiskt korrelerar på ett sätt så att bägge variablerna antingen är null eller inte är null. På raden i fråga vet vi att koden sb1 inte är null och därför är inte heller sb2 null. Utan att gå närmare in på varför en sådan korrelationsanalys ligger utanför Eclipse Java- kompilatorns kapacitet vill vi påminna om att analysen inte har samma kraft som en komplett teorembevisare och därför på ett pessimistiskt sätt rapporterar vissa problem som en kompetentare analys antagligen skulle identifiera som falsklarm.

Om du vill utnyttja flödesanalys bör du ge kompilatorn lite hjälp så att den kan "se" dina slutsatser. Det kan vara något så enkelt som att dela upp if (sb1 == null) i två separata if, ett för respektive lokal variabel, ett mycket lågt pris för den vinst som består i att kompilatorn nu exakt kan se vad som händer och kontrollera koden i enlighet med detta. Se även nedan.

Okontrollerad konvertering från icke-annoterad typ till @NonNull-typ

Denna grupp av problem bygger på följande analogi: i ett program som använder generiska Java 5-typer kanske anrop till pre-Java-5-bibliotek exponerar råtyper, dvs. tillämpningar som inte kan specificera konkreta typargument. För att passa in sådana typer i ett program med generiska typer kan kompilatorn lägga till en implicit konvertering genom att anta att typargumenten specificerats på det sätt som förväntats av klientdelen i koden. Kompilatorn ger en varning om denna konvertering och fortsätter sin typkontroll och förutsätter att biblioteket "gör det rätta". På exakt samma sätt kan en icke-annoterad returtyp för en biblioteksmetod anses som en "rå" eller "äldre" typ. Och som sagt kan en implicit konvertering optimistiskt förutsätta den förväntade specifikationen. En varning ges även denna gång och analysen fortsätter att anta att biblioteket "gör rätt".

Teoretiskt sett indikerar också behovet av sådana implicita konverteringar ett brott mot specifikationen. Men i detta fall kan det vara tredjepartskod som bryter mot den specifikation som vår kod förväntar sig. Eller (som vi intalat oss) uppfyller tredjepartskoden kontraktet, men klarar inte av att deklarera detta (eftersom den inte använder nullannoteringar). I sådana situationer kanske vi inte direkt kan åtgärda problemet av organisatoriska skäl.

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

Ovanstående kodstycke förutsätter att Library.getFoo() returnerar Foo utan att specificera en nullannotering. Vi kan integrera returvärdet i vårt annoterade program genom att tilldela en lokal @NonNull-variabel, vilket utlöser en varning för en konvertering som inte har kontrollerats. Genom att lägga till motsvarande SuppressWarnings("null") till denna deklaration medger vi den latenta faran och tar ansvar för att ha verifierat detta.

Tips för att göra kod lättare att analysera

Om flödesanalysen inte kan se att ett värde faktiskt inte är null är den enklaste strategin alltid att lägga in en ny variabel med lokalt omfång som annoterats med @NonNull. Om du då är övertygad om att det värde som tilldelats denna lokala variabel aldrig blir null vid körningen kan du använda en hjälpfunktionsmetod enligt följande:

    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();
    }

Observera att du genom att använda ovanstående assertNonNull()-metod tar ansvar för att denna kontroll alltid håller streck vid körningen. Om detta inte är det du önskar kan annoterade lokala variabler ändå hjälpa till att begränsa var och varför analysen ser en möjlighet för null att flöda till en viss plats.

Tips för att anpassa nullannoteringar

Vid tidpunkten för release av JDT version 3.8.0 pågår insamling av material rörande nullannoteringar alltjämt. Av detta skäl uppdateras denna information för närvarande i Eclipse wiki.