Null-annotaties gebruiken

NullPointerException is een van de meest voorkomende oorzaken van storingen in Java-programma's. In de eenvoudigste gevallen kan de compiler u rechtstreeks waarschuwen als deze een code zoals de volgende aantreft:

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

Bij gebruik van branching/looping en het genereren van uitzonderingen is er een zeer nauwkeurige stroomanalyse nodig om uit te zoeken of er aan een variabele waarnaar wordt verwezen, door het programma een null-/niet-null-waarde is toegekend op een of meer paden.

Vanwege de inherente complexiteit kan een stroomanalyse het beste in kleine delen worden uitgevoerd. Het analyseren van één methode per keer kan met een redelijke snelheid worden uitgevoerd - terwijl een analyse van het hele systeem buiten het bereik van de Eclipse Java-compiler valt. Het voordeel is dat de analyse snel is en incrementeel kan worden uitgevoerd, zodat de compiler u direct tijdens het typen kan waarschuwen. Het nadeel is dat de analyse niet kan "zien" welke waarden (null of niet-null) tussen de methoden stromen (als parameters en retourwaarden).

Interprocedurele null-analyse

Hierbij komen de null-annotaties om de hoek kijken. Door een methodeparameter als @NonNull op te geven, kunt u de compiler duidelijk maken dat u geen null-waarde op deze positie wilt.

    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
    }

Net als bij Design-by-Contract zijn hier twee kanten aan:

  1. Het is de verantwoordelijkheid van het aanroepende kant om nooit een null-waarde door te geven, bijvoorbeeld door een expliciete null-controle.
  2. De implementor van de methode capitalize heeft de garantie dat het argument in geen null-waarde bevat, en dereferentie zonder null-controle hier in dus orde is.

Voor de retourwaardemethode is de situatie symmetrisch:

    @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. De implementor moet nu zorgen dat er nooit null wordt geretourneerd.
  2. Het aanroepende programma heeft nu de garantie dat dereferentie van het methoderesultaat zonder controle in orde is.

Beschikbare annotaties

De Eclipse Java-compiler kan worden geconfigureerd om drie verschillende annotatietype te gebruiken voor de uitgebreide null-analyse (die standaard is uitgeschakeld):

Annotaties @NonNull en @Nullable worden ondersteund op de volgende locaties:

@NonNullByDefault wordt ondersteund voor

Let erop dat zelfs de werkelijk gekwalificeerde namen van deze annotaties configureerbaar zijn, maar standaard worden de bovengenoemde gebruikt (uit het pakket org.eclipse.jdt.annotation).

Instelling van het buildpad

Er wordt een JAR-bestand met de standaard-null-annotaties geleverd bij Eclipse. Dit is te vinden in eclipse/plugins/org.eclipse.jdt.annotation_*.jar. Het JAR-bestand moet tijdens de compilatietijd aanwezig zijn in het buildpad, maar het is niet nodig tijdens runtime (u hoeft het dus niet naar gebruikers van uw gecompileerde code te sturen).

Er zijn twee snelfixes voor niet-omgezette verwijzingen naar @NonNull, @Nullable of @NonNullByDefault, die het JAR-bestand in het buildpad plaatsen:

Interpretatie van null-annotaties

Het is nu wel duidelijk dat null-annotaties veel informatie aan uw Java-programma toevoegen (die door de compiler gebruikt kan worden om betere waarschuwingen te geven). Maar wat moeten deze annotaties precies zeggen? Vanuit een pragmatisch perspectief zijn er minstens drie niveaus van wat we null-annotaties willen noemen:

  1. Sporadische hints voor de lezer (mens en compiler)
  2. Design-by-Contract: API-specificatie voor sommige of alle methoden
  3. Volledige specificatie met een uitgebreid typesysteem

In geval (1) kunt u de null-annotaties direct en zonder verder te lezen gebruiken, maar u moet niet meer dan af en toe een hint verwachten. De andere niveaus verdienen meer uitleg.

Design-by-Contract: API-specificatie

Op het eerste gezicht betekent het gebruik van null-annotaties voor API-specificaties in de geest van Design-by-Contract alleen dat de handtekeningen van alle API-methoden nauwkeurig geannoteerd moeten worden. Dat wil zeggen: voor primitieve typen zoals int moet elke parameter en elk methoderetourtype worden gemarkeerd als hetzij @NonNull, hetzij @Nullable. Aangezien dit zou betekenen dat er zeer veel null-annotaties zouden moeten worden ingevoegd, is het goed om te weten dat @NonNull in goed ontworpen code (met name API-methoden) véél vaker voorkomt dan @Nullable. Het aantal annotaties kan dus aanzienlijk worden teruggebracht door @NonNull te declareren als standaard, middels een annotatie van het type @NonNullByDefault op pakketniveau.

Let ook op het grote verschilt tussen @Nullable en het weglaten van null-annotaties: De annotatie geeft uitdrukkelijk aan dat null in orde en zelfs te verwachten is. Dit in tegenstelling tot het eenvoudig weglaten van annotaties, want dan is het volstrekt onduidelijk wat de bedoeling is. Dit is de oude situatie, waarin er soms aan beide kanten (aanroeper en aangeroepene) redundant wordt gecontroleerd op null, terwijl beide kanten soms abusievelijk aannemen dat de controle wel aan de andere kant wordt uitgevoerd. Hier komen de beruchte NullPointerExceptions vandaan. Als er geen annotatie aanwezig is, geeft de compiler geen specifiek advies, maar met een @Nullable-annotatie wordt elke niet-gecontroleerde dereferentie gemarkeerd.

Met dit in het achterhoofd kunnen we alle parameterannotaties rechtstreeks toewijzen aan voorwaarden vooraf en kunnen we retourannotaties interpreteren als voorwaarden achteraf van de methode.

Sub-typing en overriding

Bij objectgeoriënteerd programmeren moet het begrip Design-by-Contract rekening houden met nog een extra dimensie: sub-typing en overriding (in het vervolg wordt de term "override" gebruikt in de zin van de annotatie @Override in Java 6: methods overriding of het implementeren van een andere methode van een super-type). Een client die een methode zoals deze aanroept:

    @NonNull String checkedString(@Nullable String in)

mag gevoeglijk aannemen dat alle implementaties van deze methode aan het contract voldoen. Dus als de methodedeclaratie te vinden is in de interface I1, moeten we de mogelijkheid uitsluiten dat een bepaalde klasse Cn die I1 implementeert, een incompatibele implementatie biedt. Meer in het bijzonder: Het is niet toegestaan dat een Cn probeert deze methode te overschrijven (override) met een implementatie waarin de parameter wordt gedeclareerd als @NonNull. Als dat wél toegestaan zou zijn, zou een clientmodule die op basis van I1 is geprogrammeerd, het argument null mogen doorgeven terwijl de implementatie zou aannemen dat de waarde niet-null is. Niet-gecontroleerde dereferentie binnen de methode-implementatie zou toegestaan zijn, maar zou bij runtime problemen opleveren. Een @Nullable parameterspecificatie dwingt alle overrides dus om null toe te staan als een toegestane waarde is verwacht kan worden.

Andersom dwingt een @NonNull retourspecificatie alle overrides te garanderen dat er nooit null wordt teruggezonden.

Dit is de reden dat de compiler moet controleren of er geen overrides zijn die de parameterannotatie @NonNull (of de retourannotatie @Nullable) toevoegen die nog niet aanwezig was in het super-type.

Het interessante is dat de omgekeerde herdefinities wél zijn toegestaan: het toevoegen van een parameterannotatie @Nullable of een retourannotatie @NonNull. U zou het als een "verbetering" van de methode kunnen beschouwen wanneer deze meer waarden accepteert en een meer specifieke retourwaarde produceert.

Legacy super-typen

Het voorgaande levert extra moeilijkheden op wanneer er geannoteerde code wordt geschreven als subcode van een "legacy" type (d.w.z. niet-geannoteerd). Als dergelijke code zich in een bibliotheek van een externe leverancier bevindt, kan die code niet worden gewijzigd. Hebt u het laatste gedeelte zorgvuldig doorgelezen, dan is het u waarschijnlijk opgevallen dat we niet kunnen toestaan dat een "legacy" methode wordt overschreven (overridden) door een methode met een @NonNull-parameter (want clients die het super-type gebruiken, "zien" de @NonNull-verplichting niet).

In deze situatie wordt u gedwongen de null-annotaties weg te laten. Er bestaan wel plannen om het mogelijk te maken om na afloop annotaties aan bibliotheken toe te voegen, maar er kan op dat punt geen enkele toezegging worden gedaan.

Een standaard over de "nullheid" annuleren

De situatie wordt gecompliceerd als er een sub-type van een "legacy" type aanwezig is in een pakket waarvoor @NonNullByDefault is opgegeven. In dat geval moet een type met een niet-geannoteerd super-type alle parameters in overriding methoden markeren als @Nullable. Zelfs het weglaten van parameterannotaties is niet toegestaan, want dat zou worden geïnterpreteerd als een @NonNull-parameter, en die is op die positie niet toegestaan. Daarom is het met de Eclipse Java-compiler mogelijk om een standaard over de "nullheid" te annuleren. Door een methode of type te annoteren met @NonNullByDefault(false) wordt de desbetreffende standaard voor dat element geannuleerd en worden niet-geannoteerde parameters weer geïnterpreteerd als niet-opgegeven. Nu is het gebruik van sub-typen weer toegestaan zonder dat er ongewenste @Nullable-annotaties toegevoegd hoeven te worden:

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

Voordelen van Design-by-Contract

Het gebruik van null-annotaties in de stijl van Design-by-Contract, zoals hierboven beschreven, helpt op verschillende manieren de kwaliteit van de Java-code te verbeteren: In de interface tussen methoden wordt expliciet gemaakt welke parameters / retourwaarden een null-waarde accepteren en welke dat niet doen. Het gaat hier om ontwerpbeslissingen die zeer belangrijk zijn voor ontwikkelaars en die goed kunnen worden gecontroleerd door de compiler.

Daar komt bij dat de intra-procedurele stroomanalyse, op basis van deze interfacespecificatie, belangrijke informatie kan oppikken en veel nauwkeuriger fouten/waarschuwingen kan genereren. Zonder annotaties zou de "nullheid" van elke waarde die een methode binnengaat of verlaat onbekend zijn en daarom zou de null-analyse niets over het gebruik ervan kunnen zeggen. Met null-annotaties op API-niveau is de "nullheid" van de meeste waarden gewoon bekend, zodat er veel minder NullPointerExceptions zijn die niet door de compiler worden opgemerkt. Houd er echter rekening mee dat er nog steeds valkuilen bestaan, waarbij er niet-gespecificeerde waarden worden aangeboden voor analyse. Dit voorkomt dat er met zekerheid kan worden vastgesteld dat er tijdens runtime geen NullPointerExceptions optreden.

Volledige specificatie met een uitgebreid typesysteem

De ondersteuning voor null-annotaties is zodanig ontworpen dat deze compatibel is met toekomstige uitbreidingen waarmee de compiler is staat moet worden gesteld te garanderen dat een gecerticifeerd programma tijdens runtime nooit een NullPointerException oplevert (met het gebruikelijke voorbehoud wat betreft niet-controleerbare onderdelen, zoals reflectie). Hoewel er nog geen enkele toezegging kan worden gedaan ten aanzien van dergelijke toekomstige uitbreidingen, is het basisidee in feite niets anders dan een andere interpretatie van datgene wat we al hebben.

Wanneer null-annotaties worden geïnterpreteerd als onderdeel van het typesysteem, wordt het aantal typen in een bepaald programma verdubbeld: voor een willekeurige klasse Cn wordt die klasse zelf niet meer beschouws als een geldig type; alleen "@NonNull Cn" en "@Nullable Cn" zijn nu nog geldige typen. In het ideale geval weten we dus voor elke waarde in een programma of die waarde al of niet null kan zijn. Dit moet vóór de dereferentie worden gecontroleerd. Sluiten we de derde opties uit (niet-geannoteerde typen), dan kan de compiler elk onveilig gebruik rigoureus markeren.

De huidige implementatie kent in dat opzicht twee grote beperkingen:

Ondanks de bestaande beperkingen is het op dit moment zo dat de visie van volledig gespecificeerde en gecontroleerde programma's al bepaalde gevolgen heeft voor de huidige analyse en de fouten/waarschuwingen die door de compiler worden gemeld. De details daarvan worden gepresenteerd door uitleg te geven over de regels die door de compiler worden gecontroleerd en over de berichten die worden gegenereerd wanneer er een regel wordt overtreden.

Uitleg over berichten van de compiler

Op de desbetreffende voorkeurenpagina zijn de afzonderlijke berichten die door de compiler worden gecontroleerd, gegroepeerd onder de volgende kopjes:

Inbreuk op null-specificatie

Er is sprake van een overtreding van de specificatie wanneer een null-annotatie iets beweert dat door de feitelijke implementatie niet waar wordt gemaakt. De meest voorkomende situatie is het gevolg van het feit dat er een waarde (lokaal, argument, retourwaarde van een methode) is opgegeven als @NonNull terwijl de implementatie in werkelijkheid een nullable waarde aanlevert. Hier wordt een expressie als nullable beschouwd als ervan bekend is dat deze statisch de waarde null oplevert of als deze is gedeclareerd met een @Nullable-annotatie.

Ten tweede bevat deze groep ook de regels voor "method overriding", zoals hierboven beschreven. Hier doet een super-methode een bewering (bijv. dat null een toegestaan argument is) terwijl er een override is die probeert deze bewering te ontwijken (door aan te nemen dat null geen toegestaan argument is). Zoals gezegd, treedt er zelfs een overtreding op wanneer een niet-geannoteerd argument verder wordt gespecialiseerd tot @NonNull. Dat komt doordat er dan een contract in werking treedt dat de client een bepaalde verplichting oplegt (geen null doorgeven), terwijl een client die gebruikmaakt van een super-type dat contract helemaal niet te zien krijgt en dus ook niet weet wat er van hem wordt verwacht.

Een volledige lijst van situaties die worden beschouwd als overtredingen van de specificaties vindt u hier. Het is belangrijk dat u zich realiseert dat fouten in deze groep nooit genegeerd mogen worden, omdat anders de volledige null-analyse wordt uitgevoerd op basis van onjuiste aannames. Meer in het bijzonder: overal waar de compiler een waarde met een @NonNull-annotatie ziet, wordt zonder meer aangenomen dat er tijdens runtime geen null optreedt. Het zijn de regels inzake overtreding van de specificaties die garanderen dat deze redenering vol te houden is. Daarom wordt u ten zeerste aangeraden dit soort problemen geconfigureerd te houden als fouten.

Conflict tussen null-annotaties en null-inferentie

Deze groep waakt ook over de naleving van null-specificaties. Hier hebben we echter te maken met waarden die niet zijn gedeclareerd als @Nullable (noch de waarde null zelf), maar met waarden waarbij de intra-procedurele stroomanalyse concludeert dat er in een bepaald uitvoeringspad wel eens null zou kunnen optreden.

Deze situatie vloeit voort uit het feit dat de compiler, voor niet-geannoteerde lokale variabelen, op basis van zijn eigen stroomanalyse concludeert of null al dan niet mogelijk is. Aangenomen dat deze analyse correct is en dat er een probleem wordt gevonden, dan krijgt dat probleem dezelfde severity als rechtstreekse overtredingen van een null-specificatie. Daarom wordt u ook hier nadrukkelijk geadviseerd om dit soort problemen geconfigureerd te houden als fouten en om deze berichten vooral niet te negeren.

Het maken van een afzonderlijke groep voor deze problemen heeft twee voordelen: er wordt vastgelegd dat er een probleem aan het licht is gebracht met behulp van stroomanalyse, en er wordt rekening gehouden met de mogelijkheid dat deze stroomanalyse er wel eens naast zou kunnen zitten (als gevolg van een bug in de implementatie). Als er daadwerkelijk een bug in de implementatie is vastgesteld, kan het in zeer bijzondere situaties in orde zijn om een foutbericht van dit type te negeren.

Gezien de aard van elke statistische analyse is het mogelijk dat de stroomanalyse over het hoofd ziet dat een bepaalde combinatie van uitvoeringspaden en waarden niet mogelijk is. Neem bijvoorbeeld de correlatie van variabelen:

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

De compiler meldt een potentiële nullpointer-toegang bij de aanroep van sb2.append(..). Het menselijk oog kan zien dat er geen echt gevaar is, want sb1 en sb2 correleren in feite zodanig dat ofwel beide variabelen null zijn, ofwel geen van beide null is. Op de regel in kwestie weten we dat sb1 niet null is, dus ook sb2 is niet null. Zonder in details te treden over de vraag waarom een dergelijke correlatieanalyse buiten de mogelijkheden van de Eclipse Java-compiler valt, kunt u het beste onthouden dat deze analyse gewoon niet de kracht heeft van een volledige "theorem prover" en daarom pessimistisch is ingesteld. Daarom worden er ook problemen gemeld die door een krachtiger analyse zouden worden aangemerkt als "vals alarm".

Als u wilt profiteren van stroomanalyse, wordt u geadviseerd om de compiler een handje te helpen, zodat deze uw conclusies kan "zien". Deze hulp houdt soms niet meer in dan het splitsen van if (sb1 == null) in twee afzonderlijke if's, een voor elke lokale variabele. Op deze kleine investering haalt u een grote winst, namelijk dat de compiler nu precies kan zien wat er gebeurt en dat uw code dienovereenkomstig kan worden gecontroleerd. Een verdere bespreking van dit interessante onderwerp vindt u hier.

Ongecontroleerde conversie van niet-geannoteerd type naar @NonNull-type

Deze groep problemen is gebaseerd op de volgende analogie: in een programma dat gebruikmaakt van generieke items van Java 5, kunnen aanroepen van bibliotheken van vóór Java 5 onbewerkte typen aan het licht brengen. Dat wil zeggen: toepassingen van een generiek type zijn niet in staat om argumenten van een concreet type op te geven. Om dergelijke items in een programma in te passen met behulp van generieke items kan de compiler een impliciete conversie toevoegen door aan te nemen dat de typeargumenten zijn opgegeven op de manier die door het clientgedeelte van de code wordt verwacht. De compiler geeft een waarschuwing over het gebruik van een dergelijke conversie en gaat door met de typecontrole, ervan uitgaande dat de bibliotheek "het juiste" zal doen. Op precies diezelfde manier kan een niet-geannoteerd retourtype van een bibliotheekmethode worden beschouwd als een "onbewerkt" of "legacy" type. Ook hier kan een impliciete conversie op een optimistische manier uitgaan van de verwachte specificatie. En ook hier is er een waarschuwing en wordt de analyse voortgezet, onder het motto dat de bibliotheek "het juiste" zal doen.

In theorie vormt de noodzaak van een dergelijke impliciete conversie een overtreding van de specificaties. In dit geval kan het echter code van een externe leverancier zijn die de door onze code verwachte specificaties overtreedt. Of misschien voldoet de code van een bepaalde externe leverancier wel aan het contract (en hebben we ons daarvan verzekerd), maar is die leverancier vergeten dat duidelijk aan te geven (omdat hij geen gebruik maakt van null-annotaties). In dergelijke situaties zijn we om organisatorische redenen wellicht niet in staat het probleem op te lossen.

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

De bovenstaande codesnippet gaat ervan uit dat Library.getFoo() een Foo retourneert zonder dat er een null-annotatie wordt gespecificeerd. We kunnen de retourwaarde in ons geannoteerde programma integreren door deze toe te wijzen aan een lokale variabele @NonNull. Er wordt dan een waarschuwing gegenereerd met betrekking tot een niet-gecontroleerde conversie. Door een bijbehorende SuppressWarnings("null") aan deze declaratie toe te voegen, erkennen we het inherente gevaar en aanvaarden we de verantwoordelijkheid voor de vraag of de bibliotheek daadwerkelijk op de gewenste manier werkt.

Tips voor het beter analyseerbaar maken van code

Als de stroomanalyse niet kan zien of een waarde inderdaad niet null is, is het altijd de eenvoudigste strategie om een nieuwe "scoped" lokale variabele toe te voegen met de annotatie @NonNull. Als u ervan overtuigd bent dat de waarde die tijdens runtime aan deze lokale variabele wordt toegekend nooit null is, kunt u vervolgens gebruikmaken van een helpermethode zoals deze:

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

Let op: Door gebruik te maken van de bovenstaande methode assertNonNull() accepteert u de verantwoordelijkheid dat deze verzekering altijd standhoudt tijdens runtime. Als dat niet is wat u wilt, kunt u nog steeds geannoteerde lokale variabelen gebruiken om een inperking te maken wat betreft de manier een plaats waarop er null kan voorkomen op een bepaalde locatie, althans volgens de analyse.

Tips voor het overstappen op null-annotaties

Op het moment dat JDT-versie 3.8.0 op de markt komt, worden er nog adviezen verzameld omtrent de overstap op null-annotaties. Daarom wordt deze informatie momenteel bijgehouden in de Eclipse-wiki.