Null annotációk használata

A NullPointerException a Java programok hibáinak egyik leggyakoribb oka. A legegyszerűbb esetekben a fordító közvetlenül tud erre figyelmeztetni, amikor ilyesmi kódot lát:

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

Az elágazásokkal/ciklusokkal és a kivételek dobásával elég összetett folyamelemzés válik szükségessé annak kiderítéséhez, hogy egy változóhoz, amelynek megszünteti a hivatkozásait, null/nem null érték lett rendelve néhány vagy az összes útvonalon a programban.

Az összetettség miatt a folyamelemzést kis részletekben a legjobb végezni. A metódusok egyenkénti elemzése jó eszközteljesítménnyel végezhető, míg a teljes rendszerre kiterjedő elemzés kívül esik az Eclipse Java fordító hatókörén. Az előny: az elemzés gyors és végezhető növekményesen, így a fordító közvetlenül tudja figyelmeztetni a beíráskor. A hátrány: az elemzés nem "látja", hogy milyen értékek (null vagy nem null) áramlanak a metódusok között (paraméterekként és visszatérési értékekként).

Folyamatközi nullelemzés

Itt lépnek színre az annotációk. Azzal, hogy @NonNull-ként határoz meg egy metódusparamétert, azt mondja a fordítónak, hogy nem akar nullértéket ezen a helyen.

    String capitalize(@NonNull String in) {
        return in.toUpperCase();                // nem szükséges nullellenőrzés
    }
    void caller(String s) {
        if (s != null)
            System.out.println(capitalize(s));  // előzetes nullellenőrzés szükséges
    }

A Szerződés szerinti terv keretében ennek két oldala van:

  1. A hívó felelőssége, hogy soha ne adjon át nullértéket, amelyet biztosítani kell, például kifejezett nullellenőrzéssel.
  2. A capitalize metódus megvalósítója élvezi azt a garanciát, hogy a bemeneti paraméter nem null, ezért a nullellenőrzés kihagyása rendben van itt.

A metódus visszatérési értékek esetén a helyzet szimmetrikus:

    @NonNull String getString(String maybeString) {
        if (maybeString != null)
            return maybeString;                         // a fenti nullellenőrzés szükséges
        else
            return "<n/a>";
    }
    void caller(String s) {
        System.out.println(getString(s).toUpperCase()); // nem szükséges nullellenőrzés
    }
  1. Most a megvalósítónak kell biztosítania, hogy soha nem kerül visszaadásra nullérték.
  2. Most a hívó élvezi azt a garanciát, hogy a metódus eredménye biztosan nem null, ellenőrzés nélkül is rendben van.

Elérhető annotációk

Az Eclipse Java fordító három különböző annotációtípus használatára állítható be a bővített nullelemzéshez (ami alapértelmezésben tiltott):

A @NonNull és a @Nullable annotációk az alábbi helyeken támogatottak:

@NonNullByDefault az alábbiakhoz támogatott:

Habár az annotációk tényleges minősített neve konfigurálható, alapértelmezésben a fent megadottak kerülnek felhasználásra (az org.eclipse.jdt.annotation csomagból).

Összeépítési útvonal beállítása

Az alapértelmezett null annotációkkal rendelkező JAR fájlt szállítunk az Eclipse termékkel az eclipse/plugins/org.eclipse.jdt.annotation_*.jar helyen. Ennek a JAR fájlnak az összeépítési útvonalon kell lennie a fordításkor, de nincs rá szükség a futás során (vagyis nem kell szállítania a lefordított kód felhasználóinak).

Két gyorsjavítás van a @NonNull, @Nullable vagy @NonNullByDefault célú feloldatlan hivatkozásokkal kapcsolatban, melyek felveszik a JAR fájlt az összeépítési útvonalra:

Null annotációk értelmezése

Világos, hogy a null annotációk többletinformációkat adnak a Java programnak (melyek felhasználásával a fordítók jobb figyelmeztetéseket tudnak adni). De pontosan mit is akarunk, hogy mondjanak ezek az annotációk? Pragmatikai szempontból legalább három szintje van annak, amit ki akarunk fejezni a null annotációkkal:

  1. Elszórt tippek az olvasónak (ember és fordító)
  2. Szerződés szerinti terv: API specifikáció bizonyos vagy minden metódushoz
  3. Teljes meghatározás kiterjesztett típusrendszer használatával

Az (1) célra máris megkezdheti a null annotációk használatát, anélkül, hogy tovább olvasna, ám ekkor ne várjon többet, mint hogy itt-ott lesz egy-egy kis tipp. A további szintek több magyarázatot érdemelnek.

Szerződés szerinti terv: API specifikáció

Első ránézésre a null annotációk használata az API specifikációkhoz a Szerződés szerinti terv keretében mindössze azt jelenti, hogy minden API metódust teljes körűen el kell látni annotációkkal, vagyis a primitív típusok (például int) kivételével minden egyes paramétert és minden egyes metódus visszatérési típust meg kell jelölni mint @NonNull vagy @Nullable. Mivel ez nagyon sok null annotáció beillesztését jelentené, célszerű tudni, hogy a jól megtervezett kódban (különösen API metódusokban) a @NonNull sokkal gyakoribb, mint a @Nullable. Így csökkentheti az annotációk számát, ha deklarálja a @NonNull annotációt mint alapértelmezést azáltal, hogy @NonNullByDefault annotációt használ a csomag szintjén.

A @Nullable és a null annotáció kihagyása közötti lényeges eltérés, hogy ez az annotáció kifejezetten jelzi, hogy a nullérték rendben van és várható. Ezzel szemben az annotáció hiánya azt jelenti, hogy nem ismerjük a szándékot. Ez az a helyzet, amikor időnként mindkét oldal (hívó és hívott) végez nullellenőrzést (redundánsan), időnként pedig mindkét oldal hibásan azt feltételezi, hogy a másik oldal végzi az ellenőrzést. Innen ered a NullPointerException. Annotáció nélkül a fordító nem ad specifikus tanácsot, @Nullable annotáció esetén azonban minden ellenőrizetlen hivatkozás feloldás meg lesz jelölve.

Ezekkel az alapokkal közvetlenül leképezhetünk minden paraméterannotációt előzetes feltételekre, és úgy értelmezhetjük a visszatérési annotációkat, mint a metódus utólagos feltételeit.

Altípusokra osztás és újradefiniálás

Az objektumorientált programozásban a Szerződés szerinti terv alapelvnek még egy dimenzióval kell foglalkoznia: altípusok és újradefiniálás (a másik részben az "újradefiniálás" kifejezés a Java 6 @Override annotációja értelemben használatos: a metódusok újradefiniálnak vagy megvalósítanak egy másik metódust az őstípusból). Az ilyesmi metódusokat hívó ügyfélnek:

    @NonNull String checkedString(@Nullable String in)

meg kell engedni, hogy azt feltételezze, hogy a metódus összes megvalósítása teljesíti a szerződést. Így amikor van egy metódusdeklaráció az I1 felületen, akkor ki kell zárnunk, hogy az I1-et megvalósító tetszőleges Cn osztály inkompatibilis megvalósítást biztosít. Konkrétan illegális, ha valamely Cn olyan megvalósítással próbálja újradefiniálni a metódust, ami @NonNull-ként deklarálja a paramétert. Ha megengednénk ezt, akkor az I1-re programozott ügyfélmodul legálisan átadhatna null paramétert, de a megvalósítás nem-null értéket feltételezne - az ellenőrizetlen hivatkozás feloldás a metódusmegvalósításon belül megengedett lenne, de felrobbanna a futás során. Így a @Nullable paraméterspecifikáció kötelezővé teszi minden újradefiniálás számára, hogy várt, legális értékként elfogadja a nullértéket.

Ezzel szemben a @NonNull visszatérési specifikáció kötelezővé teszi minden újradefiniálás számára annak biztosítását, hogy sosem kerül visszaadásra nullérték.

Ezért a fordítónak ellenőriznie kell, hogy egyetlen újradefiniálás sem vesz fel olyan @NonNull paraméterannotációt (vagy @Nullable visszatérési annotációt), ami nem létezett az őstípusban.

Érdekes módon a fordított újradefiniálások legálisak: a @Nullable paraméterannotáció vagy @NonNull visszatérési annotáció hozzáadása (ezek tekinthetők a metódus "továbbfejlesztéseinek": több értéket fogad el és specifikusabb visszatérési értéket ad).

Örökölt őstípusok

Az előző megfontolások nehézséget jelentenek, amikor "örökölt" (nem annotált) típus altípusaként ír annotált kódot (lehet, hogy az örökölt típus egy harmadik féltől származó függvénytár, ami nem módosítható). Ha figyelmesen elolvasta az utolsó szakaszt, akkor feltűnhetett, hogy nem állíthatjuk, hogy egy "örökölt" metódust újradefiniál egy @NonNull paraméterrel rendelkező metódus (mivel az őstípust használó ügyfelek nem látják a @NonNull követelményt).

Ebben a helyzetben ki kell hagynia a null annotációkat (vannak arra vonatkozó tervek, hogy támogatott legyen az annotációk utólagos hozzáadása a függvénytárakhoz, de nincs arra vonatkozó ígéret, hogy lesz-e, s ha igen, mikor lesz ilyen szolgáltatás).

Null alapértelmezés megszüntetése

A helyzet különösen összetett, ha egy "örökölt" típus altípusa olyan csomagban található, amelyhez @NonNullByDefault lett megadva. A nem annotált őstípussal rendelkező típusnak meg kellene jelölnie @Nullable annotációval az újradefiniáló metódusok összes paraméterét: még a paraméterannotációk kihagyása sem megengedett, mert azt @NonNull paraméterként értelmezné a rendszer, ami ebben a helyzetben tiltott. Ezért az Eclipse Java fordítóprogram támogatja a null alapértelmezés megszüntetését: ha @NonNullByDefault(false) annotációval lát el egy metódust vagy típust, akkor az alkalmazható alapértelmezett érték megszüntetésre kerül az elemhez, és az annotáció nélküli paramétereket ismét nem megadottként értelmezi a rendszer. Így az altípusok használata ismét legális, nem kívánatos @Nullable annotációk hozzáadása nélkül:

class LegacyClass {
    String enhance (String in) { // az ügyfelek nincsenek rákényszerítve, hogy nem null értéket adjanak át.
        return in.toUpperCase();
    }
}
 
@NonNullByDefault
class MyClass extends LegacyClass {
	
    // ... @NonNull alapértelmezéssel rendelkező metódusok ...
 
    @Override
    @NonNullByDefault(false)
    String enhance(String in) { // nem lenne érvényes, ha @NonNullByDefault lenne érvényes itt
        return super.enhance(in);
    }
}

A Szerződés szerinti terv előnyei

Ha a Szerződés szerinti terv stílusában használja a null annotációkat a fentebb vázolt módon, azzal számos szempontból jobb minőségű Java kódot állíthat elő. A metódusok közötti felületen kifejezetten jelezve lesz, hogy mely paraméterek / visszatérési értékek tolerálják a nullértéket, és melyek nem. Ez oly módon tükrözi a fejlesztők számára kifejezetten fontos tervezési döntéseket, hogy a fordító is ellenőrizni tudja.

Valamint a felületmeghatározás alapján a folyamaton belüli folyamelemzés további információkhoz jut és pontosabb hiba/figyelmeztetés jelzéseket tud adni. Annotációk nélkül nem ismert, hogy lehetnek-e nullértékek a metódusok bemeneti, illetve kimeneti értékei, ezért a nullelemzés nem tudja vizsgálni a használatukat. Az API szintű null annotációk mellett a legtöbb értékről ismeretes, hogy null-e vagy sem, ezért észrevehetően kevesebb NPE kerüli el a fordító figyelmét. Azzal azonban legyen tisztában, hogy továbbra is vannak lyukak a rendszerben, ahol nem megadott értékek kerülnek az elemzésbe, megakadályozva annak megállapítását, hogy előfordulhatnak-e NPE-k a futás során.

Specifikáció elkészítése kiterjesztett típusrendszer használatával

A null annotációk támogatását úgy tervezték, hogy kompatibilis legyen egy jövőbeli kiterjesztéssel, ahol a fordító képes lesz garantálni, hogy a minősített program sosem fog NullPointerException kivételt dobni a futás során (a szokásos fenntartásokkal a nem ellenőrizhető részekkel, például reflekcióval kapcsolatban). Most még nem tehetünk ígéretet ilyen jövőbeli kiterjesztésre, az alapötlet egyszerűen egy más értelmezése annak, amink már van.

Azzal, hogy a típusrendszer részeként értelmezzük a null annotációkat, megduplázzuk a típusok számát egy adott programban: bármely adott Cn osztály esetén maga az osztály így már nem legális típus, csak a "@NonNull Cn" és a "@Nullable Cn" használható. Így ideális esetben egy programban szereplő minden értékről tudjuk, hogy lehet-e null (és emiatt ellenőrizni kell) vagy sem. Ha kizárjuk a harmadik lehetőséget (annotációval nem rendelkező típusok), akkor a fordító pontosan jelezhet minden nem biztonságos használatot.

A jelenlegi megvalósításnak két fő korlátozása van ezen cél szempontjából:

Mostantól kezdve és a jelenlegi korlátozások ellenére a teljes mértékben megadott és ellenőrzött programok víziójának már vannak olyan vonzatai, amelyek alakították a jelenlegi elemzést és a fordító által jelentett hibákat/figyelmeztetéseket. A részletek bemutatásakor elmagyarázzuk, hogy milyen szabályokat ellenőriz a fordító és milyen üzeneteket ad ki egy-egy szabály megsértésekor.

Fordító üzeneteinek magyarázata

A vonatkozó beállításoldalon az alábbi fejlécek alatt vannak elrendezve a fordító által ellenőrzött egyedi szabályok:

Null specifikáció megsértése

Specifikációsértés minden olyan helyzet, ahol egy null annotáció olyat köt ki, amelyet sért a tényleges megvalósítás. A jellemző helyzet az, amikor egy érték (helyi, argumentum vagy metódus) mint @NonNull van megadva, ám a megvalósítás valójában nullképes értéket biztosít. Itt egy kifejezés akkor tekinthető nullképesnek, ha vagy statikusan ismeretes, hogy kiértékelése null, vagy pedig @Nullable annotációval van deklarálva.

Másodsorban, ez a csoport tartalmazza a metódusok újradefiniálásának szabályait is, a fentiek szerint. Itt egy felső szintű metódus kiköt valamit (például hogy a null legális argumentum), míg egy újradefiniálás megpróbálja kikerülni ezt (azt feltételezve, hogy a null nem legális argumentum). Mint említettük, még az is a specifikáció megsértése, ha egy annotációval nem rendelkező argumentumot mint @NonNull ad meg, mivel ez bevezet egy szerződést, ami köti az ügyfelet (hogy nem adhat át nullértéket), de az őstípust használó ügyfél nem látja ezt a szerződést, így nem is tud a vele szemben támasztott elvárásról.

A specifikáció megsértésének tekintett helyzetek teljes listáját itt találja. Fontos, hogy az ebbe a csoportba tartozó hibákat soha ne hagyja figyelmen kívül, mivel máskülönben a teljes nullelemzés téves feltételezések alapján kerül végrehajtásra. Konkrétan amikor a fordító egy @NonNull annotációval rendelkező értéket lát, akkor garantáltnak veszi, hogy nem fog előfordulni nullérték a futás során. A specifikációsértések szabályai biztosítják az okfejtés helytállóságát. Ezért erősen ajánlott meghagyni a beállítást, miszerint ez a problémafajta hiba.

Null annotációk és null következtetés közötti ütközés

Ez a szabálycsoport is a null specifikációk betartását figyeli. Itt azonban olyan értékekkel foglalkozunk, amelyek nincsenek deklarálva mint @Nullable (sem maga a nullérték), de a folyamaton belüli folyamelemzés kikövetkezteti, hogy lehetséges a nullérték előfordulása valamely végrehajtási útvonalon.

A helyzet abból adódik, hogy az annotációval nem rendelkező helyi változóknál a fordító folyamelemzéssel kikövetkezteti, hogy lehetséges-e a nullérték. Feltételezve, hogy az elemzés pontos, ha problémát talál, az ugyanolyan súlyos, mint a null specifikáció közvetlen megsértése. Ezért itt is erősen ajánlott a problémák beállításának meghagyása, miszerint azok hibák és az üzenetek figyelembe vétele.

Amiért külön csoport van ezeknek a problémáknak, az az, hogy így dokumentálva van, hogy egy adott problémát a folyamelemzés hozott felszínre, valamint annak a ténynek a figyelembe vétele, hogy a folyamelemzés esetleg téved (mert hiba van a megvalósításban). Nyugtázott megvalósítási hiba esetén, kivételes esetben elképzelhető, hogy helyénvaló az ilyen fajta hibaüzenet kikapcsolása.

A statikus elemzés jellegéből kifolyólag elképzelhető, hogy a folyamelemzés nem látja, hogy a végrehajtási útvonalak és értékek bizonyos kombinációja nem lehetséges. Például vegyük a változók korrelációját:

   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]); // figyelmeztetés
        }
        if (sb1 != null) return sb1.append(sb2).toString();
        return "";
    }

A fordító lehetséges null mutató hozzáférést jelent az sb2.append(..) hívásánál. Az emberi olvasó látja, hogy nincs tényleges veszély, mert az sb1 és az sb2 valójában úgy korrelál, hogy vagy mindkét változó null, vagy mindkét változó nem-null. A szóban forgó sorban tudjuk, hogy az sb1 nem-null, ezért az sb2 szintén nem-null. Anélkül, hogy belemennénk annak részletezésébe, hogy az ilyen korrelációelemzés miért haladja meg az Eclipse Java fordító képességeit, egyszerűen csak vegye figyelembe, hogy ez az elemzés nem teljes bizonyító erejű, ezért pesszimistán jelent néhány olyan problémát is, amelyekről egy pontosabb elemzés esetleg megállapítaná, hogy téves riasztások.

Ha élvezni akarja a folyamelemzés előnyeit, akkor célszerű némi segítséget adnia az elemzőnek, hogy az "láthassa" a következtetéseit. A segítség lehet egyszerűen csak annyi, hogy két külön if utasításra bontja az if (sb1 == null) utasítást (minden helyi változóhoz egy), ami kis ár ahhoz a haszonhoz képest, hogy a fordító most már pontosan látja, hogy mi történik és ennek megfelelően ellenőrzi a kódot. A témakör további fejtegetését alább olvashatja.

Ellenőrizetlen átalakítás annotáció nélküli típusról @NonNull típusra

A problémacsoport alapja a következő analógia: a Java 5 általános típusokat használó programban elképzelhető, hogy a Java 5 előtti függvénytárak hívásai nyers típusokat exponálnak, vagyis lehetnek olyan általános típusba tartozó alkalmazások, amelyek nem adnak meg konkrét típusattribútumokat. Annak érdekében, hogy beillessze az ilyen értékeket az általános típusokat használó programba, a fordító felvehet implicit átalakítást, feltételezve, hogy a típusargumentumok úgy lettek megadva, ahogyan azt a kód ügyfél része elvárja. A fordító figyelmeztetést ad ki az ilyen átalakítás használatáról, és úgy folytatja a típusellenőrzést, hogy feltételezi, hogy a függvénytár "a megfelelő dolgot teszi". Pontosan ugyanígy, egy függvénytár metódus annotációval nem rendelkező visszatérési típusa "nyers" vagy "örökölt" típusnak tekinthető. Az implicit átalakítás optimistán feltételezheti a várt meghatározást. A fordító itt is figyelmeztetést ad, és a továbbiakban feltételezi, hogy a függvénytár "a megfelelő dolgot teszi".

Elméletileg az ilyen implicit átalakítás szükségessége is a specifikáció megsértését jelzi. Ebben az esetben azonban elképzelhető, hogy a harmadik féltől származó kód sérti a mi kódunk által elvárt specifikációt. Vagy az is lehet, hogy a harmadik féltől származó kód megfelel a szerződésnek (meggyőződtünk róla), de ezt nem deklarálja (mert nem használ null annotációkat). Ilyen esetekben lehet, hogy szervezeti okokból nem tudjuk teljes mértékben javítani a problémát.

    @SuppressWarnings("null")
    @NonNull Foo foo = Library.getFoo(); // implicit átalakítás
    foo.bar(); 

A fenti kódrészlet feltételezi, hogy a Library.getFoo() visszatérési értéke Foo, anélkül, hogy megadna null annotációt. Integrálhatjuk a visszatérési értéket az annotációkkal ellátott programunkba úgy, hogy @NonNull helyi változóhoz rendeljük, ami ellenőrizetlen átalakításra vonatkozó figyelmeztetést aktivál. Azzal, hogy hozzáadjuk a SuppressWarnings("null") beállítást a deklarációhoz, tudomásul vesszük a benne rejlő veszélyt és elfogadjuk annak felelősségét, hogy ellenőrizni kell, hogy a függvénytár tényleg a kívánt módon viselkedik.

Tippek a kód jobban elemezhetővé tételéhez

Ha a folyamelemzés nem látja, hogy egy érték tényleg nem null, akkor a legegyszerűbb stratégia mindig az, hogy felvesz egy új, helyi hatókörű változót @NonNull annotációval. Ezután ha meggyőződött róla, hogy a helyi változóhoz hozzárendelt érték soha nem lesz null a futás során, akkor használjon az alábbihoz hasonló segéd metódusokat:

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

Vegye figyelembe, hogy a fenti assertNonNull() metódus használatával vállalja a felelősséget azért, hogy ez a kijelentés mindig teljesülni fog a futás során. Ha ezt nem akarja, az annotációval ellátott helyi változók akkor is segítenek szűkíteni, hogy az elemzés hol és miért lát lehetőséget arra, hogy nullérték kerül egy bizonyos helyre.

Tippek a null annotációk befogadásához

A 3.8.0 változatának kiadásakor a null annotációk befogadására vonatkozó tanácsok összegyűjtése még folyamatban van. Ezért az Eclipse wiki tartalmazza ezeket az információkat.