Использование аннотаций null

NullPointerException - одна из наиболее распространенных причин сбоев в программах Java. В самых простых случаях компилятор может непосредственно выдать предупреждение, обнаружив код, подобный приведенному ниже:

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

При ветвлении / образовании циклов и выбросе исключительных ситуаций необходимым становится достаточно сложный анализ потоков, позволяющий определить, присвоено ли переменной, значение которой будет получено по указателю, нулевое / ненулевое значение в одном или нескольких путях в программе.

Из-за присущей ему сложности, анализ потоков лучше всего проводить в небольших фрагментах. Анализируя по одному методу за раз, можно добиться высокой производительности инструмента, тогда как анализ системы в целом не предусмотрен функциональными возможностями компилятора Eclipse Java. Преимуществом является то, что анализ выполняется быстро и может проводиться по принципу приращения, то есть, компилятор может выдавать предупреждения непосредственно по мере ввода текста разработчиком. Недостаток заключается в том, что такой анализ не может "увидеть", какие значения (нулевые или ненулевые) перемещаются между методами (в качестве параметров и значений возврата).

Межпроцедурный анализ null

На этом этапе необходимо рассмотреть аннотации null. Указав параметр метода как @NonNull, можно сообщить компилятору о том, что в данной позиции нулевое значение является нежелательным.

    String capitalize(@NonNull String in) {
        return in.toUpperCase();                // проверка null не требуется
    }
    void caller(String s) {
        if (s != null)
            System.out.println(capitalize(s));  // требуется предварительная проверка null
    }

С точки зрения Контрактного программирования существует два аспекта:

  1. За то, чтобы исключить передачу нулевых значений, отвечает именно инициатор вызова, что необходимо гарантировать, например, с помощью явной проверки null.
  2. Реализующий класс метода capitalize использует гарантию того, что аргумент in не может быть нулевым и, таким образом, разыменование без проверки null в данном случае не вызывает неполадок.

Для значений возврата метода ситуация симметрична:

    @NonNull String getString(String maybeString) {
        if (maybeString != null)
            return maybeString;                         // выше требуется проверка null
        else
            return "<n/a>";
    }
    void caller(String s) {
        System.out.println(getString(s).toUpperCase()); // проверка null не требуется
    }
  1. Таким образом, реализующий класс должен гарантировать, что значение null возвращаться не будет.
  2. И наоборот, инициатор вызова теперь пользуется гарантией того, что разыменование результата метода без проверки не вызывает неполадок.

Доступные аннотации

Компилятор Eclipse Java можно настроить для использования трех отдельных типов аннотаций для проведения расширенного анализа null (который по умолчанию отключен):

Аннотации @NonNull и @Nullable поддерживаются в следующих позициях:

@NonNullByDefault поддерживается для

Обратите внимание на то, что даже фактические полные имена этих аннотаций являются настраиваемыми, но по умолчанию используются имена, приведенные выше (из пакета org.eclipse.jdt.annotation).

Настройка пути компоновки

Файл JAR с аннотациями null по умолчанию входит в состав Eclipse: eclipse/plugins/org.eclipse.jdt.annotation_*.jar. Этот файл JAR должен быть указан в пути компоновки во время компиляции, однако это не требуется во время выполнения (его можно не предоставлять пользователям скомпилированного кода).

Для непреобразованные ссылки @NonNull, @Nullable и @NonNullByDefault доступны быстрые исправления, добавляющие файл JAR в путь компоновки:

Интерпретация аннотаций null

Теперь необходимо уяснить, что аннотации null привносят дополнительную информацию в программу Java (которая потом может использоваться компилятором для формулировки более точных предупреждений). Но какую именно информацию нам нужно получить из аннотаций? С практической точки зрения, существует по меньшей мере три уровня, на которых могут потребоваться пояснения с помощью аннотаций null:

  1. Отдельные рекомендации для читателя (для человека и для компилятора)
  2. Контрактное программирование: Спецификация API для всех или нескольких методов
  3. Полная спецификация с использованием системы расширенного типа

Для случая (1) можно начать применять аннотации null немедленно, не знакомясь с приведенными ниже инструкциями, но не рассчитывайте ни на что большее, чем краткие рекомендации, появляющиеся периодически. В отношении других уровней требуются более подробные пояснения.

Контрактное программирование: Спецификация API

На первый взгляд, использование аннотаций null для спецификаций API в области Контрактного программирования означает только, что сигнатуры всех методов API должны быть полностью аннотированными, то есть, за исключением простых типов, таких как int, каждый параметр и каждый тип возврата метода должен быть помечен как @NonNull или @Nullable. Поскольку такой подход означал бы необходимость вставки множества аннотаций null, необходимо знать, что в правильно спроектированном коде (особенно в методах API) @NonNull встречается значительно чаше, чем @Nullable. Таким образом, число аннотаций можно сократить, объявляя @NonNull аннотацией по умолчанию, использующей аннотацию @NonNullByDefault на уровне пакета.

Обратите внимание на существенную разницу между аннотацией @Nullable и отсутствием аннотации null: Такая аннотация явным образом указывает на то, что значение null является допустимым и ожидаемым. Наоборот, отсутствие аннотации просто говорит о том, что это неизвестно. Давно известна ситуация, в которой иногда обе стороны (вызывающая и вызываемая) проводят избыточную проверку null, а иногда обе стороны ошибочно полагают, что данную проверку проведет другая сторона. Именно отсюда и возникают исключительные ситуации NullPointerException. Без аннотации компилятор не будет выдавать специальных извещений, а с аннотацией @Nullable любое непроверенное разыменование будет помечено.

Основываясь на этом, можно непосредственно соотнести все аннотации параметров с входными условиями и интерпретировать аннотации возврата как выходные условия данного метода.

Создание подтипов и переопределение

В объектно-ориентированном программировании концепция Контрактного программирования должна рассматривать еще один аспект: создание подтипов и переопределение (в дальнейшем термин "переопределение" будет использоваться в значении аннотации @Override в Java 6: методы, переопределяющие или реализующие другой метод на основе супертипа). Клиент, вызывающий метод, например,

    @NonNull String checkedString(@Nullable String in)

должен иметь возможность предположить, что все реализации данного метода соответствуют условиям контракта. Поэтому, при обнаружении объявления метода в интерфейсе I1, необходимо исключить возможность того, что какой бы то ни было класс Cn, реализующий I1, предоставляет несовместимую реализацию. В частности, недопустимыми являются попытки переопределения этого метода каким бы то ни было классом Cn с помощью реализации, объявляющей данный параметр как @NonNull. Если бы это было допустимо, клиентский модуль, запрограммированный под I1, мог бы обоснованно передавать null в качестве аргумента, тогда как реализация предполагала бы ненулевое значение - разыменование без проверки внутри реализации метода было бы допустимым, но в среде выполнения вызвало бы сбой. Следовательно, согласно спецификации параметра @Nullable все переопределения обязательно должны признавать null как ожидаемое, допустимое значение.

И наоборот, согласно спецификации возврата @NonNull все переопределения обязательно должны гарантировать, что значение null никогда не будет возвращено.

Таким образом, компилятор должен проверить, не добавлена ли переопределением аннотация параметра @NonNull (или аннотация возврата @Nullable), не существовавшая в супертипе.

Интересен тот факт, что допускаются и обратные переопределения: добавление аннотации параметра @Nullable или аннотации возврата @NonNull (это можно считать "усовершенствованием" метода, которые принимает больше значений и передает более точное значение возврата).

Устаревшие супертипы

Приведенные выше замечания усложняют процесс, если код с аннотациями написан как подтип типа "legacy" (т.е. неаннотированный) (например, полученный из библиотеки другой фирмы и потому не подлежащий изменению). Если вы внимательно прочли последний раздел, то, возможно, заметили, что нельзя допустить переопределение метода "legacy" методом с параметром @NonNull (поскольку клиенты, использующие супертип, не "видят" аннотацию @NonNull).

В такой ситуации вы будете принудительно пропускать аннотации null (планируется внедрить поддержку добавления аннотаций в библиотеке постфактум, но пока неясно, будет ли данная функция реализована и когда).

Отмена значения по умолчанию, допускающего значения null

Ситуация становится еще более сложной, если подтип типа "legacy" находится в пакете, для которого указана аннотация @NonNullByDefault. Теперь тип с неаннотированным супертипом должен пометить все параметры в переопределяющих методах как @Nullable: даже отсутствие аннотаций параметров не допускается, поскольку это интерпретируется как параметр @NonNull, запрещенный в данной позиции. Вот почему компилятор Eclipse Java поддерживает отмену значения обнуления по умолчанию: при указании для метода или типа аннотации @NonNullByDefault(false), применимое значение по умолчанию будет отменено для этого элемента, а параметры без аннотаций вновь будут интерпретированы как незаданные. Итак, создание подтипа вновь является допустимым, без добавления нежелательных аннотаций @Nullable:

class LegacyClass {
    String enhance (String in) { // clients are not forced to pass nonnull.
        return in.toUpperCase();
    }
}
 
@NonNullByDefault
class MyClass extends LegacyClass {
	
    // ... методы с @NonNull по умолчанию ...
 
    @Override
    @NonNullByDefault(false)
    String enhance(String in) { // недействительно, если здесь имели силу аннотации @NonNullByDefault
        return super.enhance(in);
    }
}

Преимущества Контрактного программирования

Использование аннотаций null в стиле Контрактного программирования, как описано выше, способствует повышению качества кода Java по нескольким причинам. На уровне интерфейса между методами становится ясно, какие параметры / возвраты принимают значения null, а какие нет. Таким образом программные решения, имеющие большое значение для разработчиков, фиксируются в форме, пригодной для проверки компилятором.

Кроме того, исходя из данной спецификации интерфейса, межпроцедурный анализ потоков может выявить доступную информацию и способствовать формулировке более точных сообщений об ошибках/предупреждений. Без аннотаций любое значение, поступающее в метод или выходящее из него, не имеет известной информации о возможности нулевых значений, и потому анализ null не выдает сообщений об их использовании. С аннотациями null уровня API информация об обнулении большинства значений фактически является известной, и значительно меньше NPE останутся незамеченными компилятором. Тем не менее, следует помнить о наличии определенного количества лазеек, когда в анализ попадают неопределенные значения, что снижает точность заключения о том, могут ли происходить NPE в среде выполнения.

Полная спецификация с использованием системы расширенного типа

Поддержка аннотаций null была разработана таким образом, чтобы обеспечить совместимость с последующим расширением, чтобы компилятор мог гарантировать, что сертифицированная программа никогда не выдаст исключительную ситуацию NullPointerException в среде выполнения (с общепринятыми оговорками в отношении непроверяемых частей, например, отражения). Хотя пока ничего нельзя сказать в отношении расширения в будущем, основная идея заключается просто в новой интерпретации того, что уже существует.

Интерпретируя аннотации null как часть системы типов, мы удваиваем число типов в данной программе: для любого отдельного класса Cn сам класс уже не рассматривается как допустимый тип, и полезными типами являются только "@NonNull Cn" и "@Nullable Cn". Поэтому, в идеале, для каждого значения в программе будет известно, может оно быть нулевым (и подлежать проверке перед разыменованием) или нет. Если исключить третий вариант (неаннотированные типы), то компилятор может точно помечать каждый случай небезопасного использования.

Для существующей реализации характерны два основные ограничения в отношении этой цели:

На сегодняшний день, несмотря на существующие ограничения, видение полностью специфицированных и полностью проверенных программ уже характеризуется определенными условиями, определяющими существующий анализ и сообщения об ошибках/предупреждения компилятора. Подробнее об этом будет рассказано в разделе, посвященном описанию правил, проверяемых компилятором, и сообщений, которые он выдает в случае нарушения правила.

Пояснения к сообщениям компилятора

На соответствующей странице параметров перечислены отдельные правила, проверяемые компилятором, под следующими заголовками:

Нарушение спецификации null

Нарушением спецификации считается любая ситуация, в которой аннотация null указывает на то, что фактическая реализация ее нарушает. Такая типичная ситуация является результатом указания значения (локального, аргумента, возврата метода) как @NonNull, в то время как реализация фактически предоставляет значение, допускающее null. Тогда выражение считается допускающим значение null, если оно статически определено как получающее значение null при вычислении, либо если оно объявлено с аннотацией @Nullable.

Во-вторых, эта группа также содержит в себе правила переопределения метода, что было описано выше. В таком случае суперметод устанавливает утверждение (например, что null является допустимым аргументом), тогда как переопределение стремится обойти это утверждение (предполагая, что null не является допустимым аргументом). Как уже отмечалось, даже специализация аргумента из неаннотированного в @NonNull является нарушением спецификации, поскольку вводит контракт, согласно которому клиент имеет обязательства (не передавать значения null), но клиенту, использующему супертип, этот контракт не виден, поэтому он даже не узнает, что от него ожидается.

Полный список ситуаций, считающихся нарушениями спецификации, приведен здесь. Очень важно понимать, что ошибки в данной группе нельзя игнорировать, так как иначе весь анализ null будет выполняться на основе ложных предположений. В частности, каждый раз, когда компилятор встречает значение с аннотацией @NonNull, он принимает за данность то, что значение null в среде выполнения появляться не будет. Правила, определяющие нарушения спецификаций, гарантируют, что такое обоснование является разумным. Поэтому в настройках настоятельно рекомендуется определить неполадки данного вида как ошибки.

Конфликт аннотаций null и выводимых значений null

Эта же группа правил касается соблюдения спецификаций null. Тем не менее, здесь речь идет о значениях, которые не объявлены как @Nullable (ни само значение null), а значения, для которых межпроцедурный анализ потоков определяет, что значение null, возможно, встретится в каком-либо пути выполнения.

Такая ситуация вытекает из того факта, что для неаннотированных локальных переменных компилятор будет определять, возможно ли значение null, с помощью анализа потоков. Если предположить, что такой анализ является точным, то при обнаружении неполадки она является настолько же серьезной, как и непосредственное нарушение спецификации null. Следовательно, снова настоятельно рекомендуется определить в настройках неполадки данного вида как ошибки и не игнорировать сообщения о них.

Создание отдельной группы для таких неполадок преследует две цели: 1) документировать возникновение данной неполадки с помощью анализа потоков и 2) принять во внимание тот факт, что анализ потоков может быть неточным (из-за ошибки в реализации). В случае подтверждения наличия ошибки в реализации, в исключительных ситуациях может быть допустимым отключение сообщений об ошибке данного вида.

Принимая во внимание особенности любого статического анализа, анализ потоков не всегда может определить, что какое-либо сочетание путей выполнения и значений является невозможным. В качестве примера рассмотрим корреляцию переменных:

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

Компилятор выдаст сообщение об обращении к потенциальному значению null при вызове sb2.append(..). Человек может определить, что реальной опасности здесь нет, поскольку sb1 и sb2 действительно взаимосвязаны таким образом, что обе переменные имеют значение либо null, либо отличное от null. В рассматриваемой строке нам известно, что значением sb1 не является null, а следовательно, значение sb2 также отлично от null. Не рассматривая подробно причины того, почему такой корреляционный анализ не входит в спектр функциональных возможностей компилятора Eclipse Java, просим вас просто запомнить, что такой анализ не основывается на полноценных теоретических доказательствах и потому пессимистически сообщает о некоторых неполадках, которые другой, более усовершенствованный, анализ, возможно, идентифицирует как ложную тревогу.

Если вы хотите воспользоваться анализом потоков, рекомендуется в определенной степени "помочь" компилятору, чтобы он "увидел" ваши выводы. Такая помощь может состоять просто в том, чтобы разбить код if (sb1 == null) на два отдельных "if", по одному для каждой локальной переменной. Благодаря этому, казалось бы, незначительному уточнению компилятор сможет точно определить, что происходить, и соответствующим образом выполнить проверку кода. Более подробную информацию по этой теме см. ниже.

Непроверяемое преобразование типа без аннотации в тип @NonNull

Эта группа неполадок основана на следующей аналогии: в программе, использующей шаблоны Java 5, все вызовы библиотек версий, предшествующих Java 5, могут выдать необработанные типы, т.е. приложения общего типа, которые не способны указывать аргументы конкретного типа. Для вставки таких значений в программу с помощью шаблонов, компилятор может добавить неявное преобразование, предположив, что аргументы типа были указаны так, как это ожидается клиентской частью кода. Компилятор выдаст предупреждение об использовании такого преобразования и продолжит проверку типов, исходя из предположения о том, что библиотека "делает всё правильно". Точно так же, неаннотированный тип возврата метода библиотеки может рассматриваться как тип "raw" или "legacy". И снова неявное преобразование может оптимистично предположить ожидаемую спецификацию. И снова будет выдано предупреждение, и анализ продолжится на основе предположения о том, что библиотека "делает всё правильно".

Теоретически, необходимость в таких неявных преобразованиях также указывает на нарушение спецификации. Тем не менее, в этом случае, возможно, спецификацию, ожидаемую нашим кодом, нарушает код, написанный другой фирмой. Или, возможно (как мы себя в этом сами убедили), код, написанный другой фирмой, выполняет контракт, но но только не объявляет об этом (потому что не использует аннотации null). В таких ситуациях у нас, возможно, не получится четко исправить неполадку по организационным причинам.

    @SuppressWarnings("null")
    @NonNull Foo foo = Library.getFoo(); // неявное преобразование
    foo.bar(); 

Приведенный выше фрагмент кода основан на предположении о том, что Library.getFoo() возвращает Foo без указания аннотации null. Значение возврата можно интегрировать в нашу программу с аннотациями путем присвоения аннотации @NonNull локальной переменной, которая инициирует предупреждение о непроверяемом преобразовании. Добавляя соответствующий элемент SuppressWarnings("null") к этому объявлению, мы признаем существующую опасность и принимаем ответственность за проверку того, действительно ли библиотека работает так, как необходимо.

Советы по усовершенствованию анализа кода

Если анализ потоков не может определить, что на самом деле значение отличается от null, самым простым способом всегда является добавление новой локальной переменной области действия с аннотацией @NonNull. Затем, убедившись в том, что значение, присвоенное этой локальной переменной, никогда не будет нулевым в среде выполнения, можно использовать вспомогательные методы, например:

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

Обратите внимание на то, что используя метод assertNonNull(), вы принимаете ответственность за то, что данное утверждение всегда будет сохраняться в среде выполнения. Если это нежелательно, аннотированные локальные переменные все же помогут сузить область, в которой анализом будет определен потенциал перехода значений null в определенное расположение.

Советы по принятию аннотаций null

На момент выпуска JDT версии 3.8.0 сбор рекомендаций относительно принятия аннотаций null все еще продолжается. По этой причине данная информация сейчас хранится в Вики Eclipse.