Použití anotací hodnot null

NullPointerException je jednou z nejběžnějších příčin selhání programů v jazyce Java. V nejjednodušších případech vás může kompilátor přímo varovat, jestliže zachytí takovýto kód:

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

Při větvení/vytváření smyček a aktivaci výjimek je nezbytná poměrně sofistikovaná analýza toku pro zjištění, zda je proměnné s vyhodnoceným odkazem přiřazena hodnota Null/non-null v některých nebo ve všech cestách programu.

Kvůli složitosti se analýza toku nejlépe provádí po malých částech. Analýza pouze jedné metody v daný moment může dobře využít výkon nástroje, ale analýza celého systému je mimo možnosti kompilátoru jazyka Java platformy Eclipse. Výhody: analýza je rychlá a může být prováděna přírůstkově, takže vás kompilátor může varovat přímo při psaní. Nevýhody: analýza nezachytí, které hodnoty (nulové nebo nenulové) proudí mezi metodami (jako parametry a návratová hodnota).

Analýza hodnot Null mezi procedurami

Zde se uplatní anotace Null. Určením parametru metody jako @NonNull můžete kompilátoru sdělit, že nechcete v této pozici hodnotu Null.

    String capitalize(@NonNull String in) {
        return in.toUpperCase();                // Není nutná kontrola hodnoty Null.
    }
    void caller(String s) {
        if (s != null)
            System.out.println(capitalize(s));  // Je nutná předchozí kontrola hodnoty Null.
    }

Ve stylu Design-by-Contract to má dvě stránky:

  1. Volající zodpovídá za to, že nikdy nepředá hodnotu Null, což má být zaručeno například explicitní kontrolou hodnoty Null.
  2. Implementátor metody capitalize využije záruku, že argument in nebude nulový, a proto je v tomto případě vyhodnocení bez kontroly nulové hodnoty v pořádku.

Pro návratové hodnoty metody je situace symetrická:

    @NonNull String getString(String maybeString) {
        if (maybeString != null)
            return maybeString;                         // Je nutná výše uvedená kontrola hodnoty Null.
        else
            return "<n/a>";
    }
    void caller(String s) {
        System.out.println(getString(s).toUpperCase()); // Není nutná kontrola hodnoty Null.
    }
  1. Nyní musí implementátor zaručit, že nebude nikdy vrácena hodnota Null.
  2. Naopak, volající nyní využívá záruku, že vyhodnocení odkazu výsledku metody bez kontroly je v pořádku.

Dostupné anotace

Kompilátor jazyka Java platformy Eclipse může být nakonfigurován pro použití tří různých typů anotace pro svoji rozšířenou analýzu hodnoty Null (která je ve výchozím nastavení zakázána):

Anotace @NonNull a @Nullable jsou podporovány v těchto umístěních:

@NonNullByDefault je podporována pr.:

Pamatujte, že i skutečné úplné názvy těchto anotací jsou konfigurovatelné, ale ve výchozím nastavení jsou použity ty, které jsou uvedeny výše (z balíku org.eclipse.jdt.annotation).

Nastavení cesty sestavení

Soubor JAR s výchozími anotacemi s hodnotou null se dodává s platformou Eclipse v souboru eclipse/plugins/org.eclipse.jdt.annotation_*.jar. V době kompilace musí být tento soubor JAR v cestě sestavení, za běhu to však není nutné (takže jej nemusíte dodávat uživatelům zkompilovaného kódu).

Existují dvě rychlé opravy na nevyřešených odkazech na @NonNull, @Nullable nebo @NonNullByDefault, které přidají soubor JAR do cesty sestavení:

Interpretace anotací hodnot Null

Nyní by mělo být zřejmé, že nulové anotace přidávají více informací vašemu programu v jazyce Java (které potom mohou být použity kompilátorem pro lepší varování). Avšak jaké sdělení od těchto anotací chceme? Z pragmatického hlediska existují alespoň tři úrovně toho, co chceme vyjádřit pomocí nulových anotací:

  1. Občasné rady čtenáři nebo kompilátoru.
  2. Návrh podle smlouvy: specifikace rozhraní API pro některé nebo všechny metody.
  3. Úplná specifikace pomocí rozšířeného systému typů.

Pro (1) můžete začít nulové anotace používat ihned a bez dalšího čtení, ale neměli byste očekávat více než malou radu jednou za čas. Další úrovně si zaslouží podrobnější vysvětlení.

Návrh podle smlouvy: Specifikace API

Na první pohled použití nulových anotací pro specifikace rozhraní API ve stylu Design by Contract pouze znamená, že podpisy všech metod rozhraní API by měly být plně anotované, to znamená, že s výjimkou primitivních typů, jako int, by každý parametr a každý návratový typ metody měl být označen jako @NonNull nebo @Nullable. Protože by to znamenalo vložení velkého počtu nulových anotací, je dobré vědět, že v dobře navrženém kódu (především metody rozhraní API) je @NonNull podstatně četnější než @Nullable. Takto může být počet anotací snížen deklarací @NonNull jako výchozího nastavení pomocí anotace @NonNullByDefault na úrovni balíku.

Všimněte si podstatného rozdílu mezi @Nullable a vynecháním nulové anotace: Tato anotace explicitně uvádí, že hodnota Null je v pořádku a je nutné ji očekávat. Naopak, chybějící anotace znamenají, že neznáme záměr. Toto je známá situace, kdy obě strany (volající a volaný) někdy nadbytečně kontrolují hodnotu Null a v některých případech obě strany chybně předpokládají, že kontrolu provede druhá strana. Zde mají původ NullPointerExceptions. Bez anotace kompilátor neposkytne specifickou radu, ale s anotací @Nullable bude každé nekontrolované vyhodnocení odkazu označeno příznakem.

S těmito základy můžeme přímo mapovat všechny anotace parametrů na předběžné podmínky a interpretovat návratové anotace jako následné podmínky metody.

Vytváření podtypů a potlačení

V objektově orientovaném programování vyžaduje koncept Návrh podle smlouvy řešení dalšího rozměru: vytváření podtypů a potlačení (v následujícím textu bude termín "potlačit" používán ve smyslu anotace @Override v jazyku Java 6: metody potlačující nebo implementující další metody ze supertypu). Klient vyvolávající metodu, jako je tato:

    @NonNull String checkedString(@Nullable String in)

by měl mít možnost předpokládat, že všechny implementace této metody dodržují tuto smlouvu. Takže, pokud se deklarace metody nachází v rozhraní I1, musíme vyloučit, aby jakákoli třída Cn implementující I1 poskytovala nekompatibilní implementaci. Je výslovně zakázáno, aby se jakýkoli Cn pokusil potlačit tuto metodu pomocí implementace, která deklaruje parametr jako @NonNull. Pokud bychom to povolili, klientský modul naprogramovaný vzhledem k I1 by mohl mít povoleno předat hodnotu Null jako argument, ale implementace by předpokládala nenulovou hodnotu - nekontrolované vyhodnocení odkazu v implementaci metody by bylo povoleno, ale při běhu by selhalo. Proto specifikace parametru @Nullable vyžaduje, aby všechna potlačení připouštěla hodnotu Null jako očekávanou povolenou hodnotu.

Naopak, návratová specifikace @NonNull vyžaduje, aby všechna potlačení zaručovala, že nikdy nebude vrácena hodnota Null.

Proto musí kompilátor kontrolovat, aby žádné potlačení nepřidalo anotaci parametru @NonNull (ani návratovou anotaci @Nullable), která neexistovala v supertypu.

Je zajímavé, že zpětné opakované definování je povoleno: přidání anotace parametru @Nullable nebo návratové anotace @NonNull (můžete je považovat za "vylepšení" metody, přijímá více hodnot a vytváří specifičtější návratovou hodnotu).

Starší supertypy

Předchozí pohledy přidávají obtížnost, je-li anotovaný kód zapsán jako podtyp "staršího" (to znamená neanotovaného) typu (který může pocházet z knihovny třetí strany, a proto jej nelze měnit). Jestliže jste velmi pečlivě přečetli poslední oddíl, možná jste zaznamenali, že nelze připustit, aby "starší" metoda byla potlačena metodou s parametrem @NonNull (protože klienti využívající supertyp "nezjistí" povinnost @NonNull).

V této situaci budete nuceni vynechat nulové anotace (existují plány na podporu přidávání anotací do knihoven následně (after-the-fact), ale není možné zatím slíbit, zda a kdy bude tato funkce k dispozici).

Rušení předvolby nulovosti

Situace bude velmi složitá, jestliže je podtyp "staršího" typu umístěn v balíku, pro který byl určen @NonNullByDefault. Nyní by typ s neanotovaným supertypem vyžadoval označení všech parametrů v potlačujících metodách jako @Nullable: není povoleno ani vynechání anotací parametrů, protože by to bylo interpretováno jako parametr @NonNull, který je v této pozici zakázán. Proto kompilátor jazyka Java platformy Eclipse podporuje zrušení předvolby nulovosti: anotací metody nebo typu pomocí @NonNullByDefault(false) bude platná výchozí hodnota pro tento prvek zrušena a neanotované parametry jsou opět interpretovány jako nespecifikované. Nyní je znovu povoleno vytváření podtypů bez přidávání nechtěných anotací @Nullable:

class LegacyClass {
    String enhance (String in) { // Klienti nejsou nuceni předat nenulový.
        return in.toUpperCase();
    }
}
 
@NonNullByDefault
class MyClass extends LegacyClass {
	
    // ... Metody s výchozím @NonNull ...
 
    @Override
    @NonNullByDefault(false)
    String enhance(String in) { // Byl by neplatný, pokud by byl účinný @NonNullByDefault.
        return super.enhance(in);
    }
}

Výhody Design-by-Contract

Použití nulových anotací ve stylu Design-by-Contract popsaném výše pomáhá zlepšovat kvalitu vašeho kódu jazyka Java několika způsoby: v rozhraní mezi metodami je zřejmé, které parametry/vrácené hodnoty tolerují hodnotu Null a které ne. To zachycuje rozhodnutí o návrzích, která jsou velmi relevantní pro vývojáře, a to způsobem, který může být také kontrolován kompilátorem.

Kromě toho může analýza toku mezi procedurami na základě této specifikace rozhraní sbírat dostupné informace, a značně tak zpřesňovat chyby/varování. Bez anotací má jakákoli hodnota proudící do nebo z metody neznámou nulovost, a proto analýza nulové hodnoty neinformuje o jejich použití. Při nulových anotacích na úrovni rozhraní API je nulovost většiny hodnot ve skutečnosti známá a podstatně méně NPE zůstane nezachycených kompilátorem. Avšak měli byste si být vědomi, že i tak existují určité mezery, kdy neurčené hodnoty proudí do analýzy a brání kompletnímu příkazu, zda může dojít k NPR při běhu.

Úplná specifikace pomocí rozšířeného systému typů

Podpora nulových anotací byla navržena způsobem, který je kompatibilní s budoucím rozšířením, díky kterému bude kompilátor schopen zaručit, že certifikovaný program nikdy nevyvolá vznik výjimky NullPointerException v běhovém prostředí (s typickými výstrahami o nekontrolovatelných částech jako odrazem). I když ještě nelze nic slíbit v souvislosti s takovým budoucím rozšířením, základní myšlenka je pouze jinou interpretací toho, co již máme.

Interpretací nulových anotací jako součásti systému typů zdvojnásobíme počet typů v daném programu: pro jakoukoli třídu Cn již není samotná třída považována za povolený typ, ale užitečné jsou pouze typy "@NonNull Cn" a "@Nullable Cn". Takže ideálně u každé hodnoty v programu budeme vědět, zda může být Null (a musí být zkontrolována před vyhodnocením odkazu) nebo ne. Pokud vynecháme třetí volbu (neanotované typy), kompilátor může přísně označit příznakem každé nebezpečné použití.

Aktuální implementace má dvě hlavní omezení související s tímto cílem:

Ode dneška a navzdory aktuálním omezením má vize plně určených a kompletně kontrolovaných programů již nějaké důsledky, které daly podobu aktuální analýze a chybám/varováním hlášeným kompilátorem. Podrobnosti budou prezentovány vysvětlením pravidel, která kompilátor kontroluje, a zpráv, které při porušení pravidla zobrazuje.

Vysvětlené zprávy kompilátoru

Na příslušné stránce předvoleb jsou jednotlivá pravidla kontrolovaná kompilátorem umístěna pod těmito záhlavími:

Porušení specifikace hodnoty Null

Jako porušení specifikace řešíme situaci, kdy nulová anotace vytvoří požadavek, který je porušen skutečnou implementací. Obvyklá situace je výsledkem určení hodnoty (lokální, argument, návratu metody) jako @NonNull, přičemž implementace skutečně poskytne hodnotu s povolenou hodnotou Null. Výraz je v tomto případě považován za výraz s povolenou hodnotou Null, pokud je statisticky zjištěno, že se vyhodnocuje s hodnotou Null, nebo pokud je deklarován pomocí anotace @Nullable.

Dále tato skupina obsahuje pravidla pro potlačení metody, jak je popsáno výše. Supermetoda v tomto případě vytváří požadavek (například, že null je povolený argument), zatímco potlačení se pokusí tomuto požadavku vyhnout (pomocí předpokladu, že null není povolený argument). Jak bylo zmíněno, i změna argumentu z neanotovaného na @NonNull je porušením specifikace, protože zavádí smlouvu, která by měla klienta zavazovat (nezadávat hodnotu null), ale klient používající supertyp tuto smlouvu ani neuvidí, takže ani neví, co se od něj očekává.

Úplný seznam situací považovaných za porušení specifikace je uveden zde. Je důležité pochopit, že chyby v této skupině by neměly být nikdy ignorovány, protože jinak bude celá analýza hodnoty Null provedena na základě nesprávných předpokladů. Přesněji řečeno, kdykoli kompilátor zjistí hodnotu s anotací @NonNull, předpokládá, že se v běhovém prostředí nevyskytne hodnota Null. Správnost této úvahy zajišťují pravidla o porušení specifikace. Proto se doporučuje ponechat tento druh problému nakonfigurován jako chyby.

Konflikt mezi anotacemi hodnoty Null a odvozením hodnoty Null

Tato skupina pravidel také sleduje dodržování specifikací hodnoty Null. Avšak zde se jedná o hodnoty, které nejsou deklarovány jako @Nullable (ani samotná hodnota Null), ale hodnoty, kde analýza toku mezi procedurami odvozuje, že v některé cestě provedení se může vyskytnout hodnota Null.

K této situaci dojde, když u neanotovaných lokálních proměnných kompilátor pomocí analýzy toku odvodí, zda je možná hodnota Null. Za předpokladu, že je tato analýza přesná platí, že pokud zjistí problém, má tento problém stejnou závažnost jako přímé porušení specifikace hodnoty Null. Proto se opět velmi doporučuje ponechat tyto problémy nakonfigurované jako chyby, nikoli tyto zprávy ignorovat.

Vytvoření samostatné skupiny pro tyto problémy má dva účely: dokumentovat vznesení daného problému pomocí analýzy toku a objasnit skutečnost, že tato analýza toku by mohla být chybná (kvůli chybě v implementaci). Pro případ potvrzené chyby implementace by mohlo být ve výjimečných případech v pořádku tento druh chybové zprávy potlačit.

Vzhledem k povaze jakékoli statické analýzy nemusí analýza toku zjistit, že určitá kombinace cest provedení a hodnot není možná. Jako příklad uvádíme korelaci proměnných:

   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]); // varování zde
        }
        if (sb1 != null) return sb1.append(sb2).toString();
        return "";
    }

Kompilátor bude hlásit potenciální přístup ukazatele Null při vyvolání sb2.append(..). Čtenář vidí, že neexistuje žádné skutečné nebezpečí, protože sb1 a sb2 jsou ve skutečnosti v korelaci způsobem, kdy mají obě proměnné nebo ani jedna z nich hodnotu Null. Na příslušném řádku vidíme, že sb1 nemá hodnotu Null, a proto také sb2 nemá hodnotu Null. Bez zacházení do detailů, proč taková analýza korelací překračuje možnosti kompilátoru jazyka Java platformy Eclipse, si pouze pamatujte, že tato analýza nemá dostatečnou schopnost úplného prověření pravidel, a proto pesimisticky hlásí některé problémy, které schopnější analýza může identifikovat jako falešný poplach.

Chcete-li využít výhod analýzy toku, měli byste kompilátoru pomoci, aby "viděl" vaše závěry. Tato pomoc může spočívat pouze v rozdělení výrazu if (sb1 == null) na dvě samostatné části if, pro každou lokální proměnnou jednu, kdy za velmi malou cenu získáte kompilátor, který přesně zjistí, co se děje, a může odpovídajícím způsobem kontrolovat váš kód. Níže jsou uvedeny další informace o tomto tématu.

Nekontrolovaný převod z neanotovaného typu na typ @NonNull

Tato skupina problémů je založena na následující analogii: v programu využívajícím generické typy jazyka Java 5 mohou jakákoli volání do knihoven starších verzí Javy odhalit základní typy, to znamená aplikace generického typu, které neurčují konkrétní argumenty typu. Pro přizpůsobení těchto hodnot programu pomocí generických typů může kompilátor přidat implicitní převod s předpokladem, že argumenty typu byly určeny způsobem očekávaným kódu v části klienta. Kompilátor generuje varování o použití takového převodu a pokračuje v kontrole typu s předpokladem, že knihovna "funguje správně." Přesně stejným způsobem může být neanotovaný návratový typ metody knihovny považován za "základní" nebo "starší" typ. A opět, implicitní převod může optimisticky předpokládat očekávanou specifikaci. Opět je generováno varování a analýza nadále předpokládá, že knihovna "funguje správně."

Teoreticky vzato, také potřeba takových implicitních převodů indikuje porušení specifikace. Avšak v tomto případě může porušení specifikace očekávané naším kódem zapříčinit kód třetí strany. Nebo může (jak jsme se přesvědčili) nějaký kód třetí strany splnit smlouvu a pouze to nedeklaruje (protože nepoužívá nulové anotace). V takových situacích nemusí být problém přesně řešitelný z organizačních důvodů.

    @SuppressWarnings("null")
    @NonNull Foo foo = Library.getFoo(); // implicitní převod
    foo.bar(); 

Výše uvedený úsek kódu předpokládá, že Library.getFoo() vrátí Foo bez určení nulové anotace. Můžeme integrovat návratovou hodnotu do našeho anotovaného programu přiřazením k lokální proměnné @NonNull, která spouští varování týkající se nekontrolovaného převodu. Přidáním odpovídajícího SuppressWarnings("null") do této deklarace potvrzujeme související nebezpečí a přijímáme odpovědnost za to, že bylo ověřeno skutečné chování knihovny.

Tipy pro umožnění lepší analýzy kódu

Jestliže analýza toku není schopna zjistit, že hodnota opravdu není Null, nejjednodušší strategie vždy spočívá v přidání nové lokální proměnné s vymezeným rozsahem platnosti anotované pomocí @NonNull. Jste-li přesvědčeni, že hodnota přiřazená této lokální proměnné nikdy v běhovém prostředí nebude Null, můžete poté použít metody pomocníka, jako je tato:

    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, 
                    "Hodnota by neměla být Null, protože aplikace " +
                    "je v tomto bodě plně inicializována.");
            return theValue;
        }
        return new MyTypeImpl();
    }

Pamatujte, že použitím výše uvedené metody assertNonNull() přijímáte odpovědnost za to, že se tato deklarace při běhu vždy zachová. Pokud to nechcete, anotované lokální proměnné vám přesto pomohou zúžit nastavení kde a kdy analýza zjistí možnost hodnoty Null proudící do určitého umístění.

Tipy pro převzetí anotací hodnot Null

V době vydání JDT verze 3.8.0 stále probíhá shromažďování rad pro přijímání anotací Null. Z toho důvodu jsou tyto informace momentálně umístěny na wikiwebu platformy Eclipse.