Android annotation android studio

Improving Code Inspection with Annotations

In this document

See also

Using code inspections tools such as lint can help you find problems and improve your code, but inspection tools can only infer so much. Android resource ids, for example, use an int to identify strings, graphics, colors and other resource types, so inspection tools cannot tell when you have specified a string resource where you should have specified a color. This situation means that your app may render incorrectly or fail to run at all, even if you use code inspection.

Annotations allow you to provide hints to code inspections tools like lint , to help detect these, more subtle code problems. They are added as metadata tags that you attach to variables, parameters, and return values to inspect method return values, passed parameters, and local variables and fields. When used with code inspections tools, annotations can help you detect problems, such as null pointer exceptions and resource type conflicts.

For more information on enabling lint inspections and running lint, see Improving Your Code with lint.

Android supports a variety of annotations for insertion in the methods, parameters, and return values in your code, for example:

@Nullable Can be null. @NonNull Cannot be null. @StringRes References a R.string resource. @DrawableRes References a Drawable resource. @ColorRes References a Color resource. @InterpolatorRes References a Interpolator resource. @AnyRes References any type of R. resource.

For a complete list of the supported annotations, either examine the contents of the Support-Annotations library or use the auto-complete feature to display the available options for the import android.support.annotation. statement. The SDK Manager packages the Support-Annotations library in the Android Support Repository for use with Android Studio and in the Android Support Library for use with other Android development tools.

To add annotations to your code, first add a dependency to the Support-Annotations library. In Android Studio, add the dependency to your build.gradle file.

The Support-Annotations library is decorated with the supported annotations so using this library’s methods and resources automatically checks the code for potential problems.

If you include annotations in a library and use the Android Plugin for Gradle to build an Android ARchive (AAR) artifact of that library, the annotations are included as part of the artifact in XML format in the annotations.zip file.

To start a code inspection from Android Studio, which includes validating annotations and automatic lint checking, select Analyze > Inspect Code from the menu options. Android Studio displays conflict messages throughout the code to indication annotation conflicts and suggest possible resolutions.

Adding Nullness Annotations

Add @Nullable and @NonNull annotations to check the nullness of a given variable, parameter, or return value. For example, if a local variable that contains a null value is passed as a parameter to a method with the @NonNull annotation attached to that parameter, building the code generates a warning indicating a non-null conflict.

This example attaches the @NonNull annotation to the context and attrs parameters to check that the passed parameter values are not null.

Note: Android Studio supports running a nullability analysis to automatically infer and insert nullness annotations in your code. For more information about inferring nullability in Android Studio, see Annotations in Android Studio.

Adding Resource Annotations

Add @StringRes annotations to check that a resource parameter contains a R.string reference. During code inspection, the annotation generates a warning if a R.string reference is not passed in the parameter.

This example attaches the @StringRes annotation to the resId parameter to validate that it is really a string resource.

Annotations for the other resource types, such as @DrawableRes , @ColorRes , and @InterpolatorRes can be added using the same annotation format and run during the code inspection.

Creating Enumerated Annotations

Use the @IntDef and @StringDef annotations so you can create enumerated annotations of integer and string sets to validate other types of code references, such as passing references to a set of constants.

The following example illustrates the steps to create an enumerated annotation that ensures a value passed as a method parameter references one of the defined constants.

When you build this code, a warning is generated if the mode parameter does not reference one of the defined constants ( NAVIGATION_MODE_STANDARD , NAVIGATION_MODE_LIST , or NAVIGATION_MODE_TABS ).

You can also define an annotation with a flag to check if a parameter or return value references a valid pattern. This example creates the DisplayOptions annotation with a list of valid DISPLAY_ constants.

When you build code with an annotation flag, a warning is generated if the decorated parameter or return value does not reference a valid pattern.

Источник

Support Annotations — аннотации для кода

Начиная с версии 19.1 библиотека Android support library включает себя аннотации, которые помогают улучшить код, уменьшая количество ошибок. Кстати, сама библиотека и многие другие классы системы уже используют новые аннотации в своём коде и вы их можете иногда видеть при наборе своего текста. Количество аннотаций увеличивается, поэтому сверяйтесь с документацией.

По умолчанию аннотации не включены, они идут как отдельная библиотека. Но она входит в состав библиотеки appcompat. Если вы не используете appcompat, то подключите библиотеку аннотаций самостоятельно.

Так как на сегодняшний день проекты по умолчанию используют appcompat, то будем считать, что аннотации всегда готовы к употреблению.

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

Аннотации для ресурсов

Для первого знакомства приведу пример с использованием ресурсов. В коде мы часто используем ресурсы строк, изображений, идентификаторов и т.п. По сути ресурс в данном случае является числом типа int. Подготовим ресурсы для имён котов в res/strings.xml

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

Студия не замечает ошибок, метод написан правильно и даже работает.

Но никто вам не помешает написать и такие варианты:

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

Как избежать этих ошибок, перепишем метод с добавлением аннотации:

Теперь студия будет подчёркивать неправильные параметры 451 или R.mipmap.ic_launcher и выводить предупреждение, что она ожидает строковые ресурсы, а не любые выдуманные вами числа.

Вы можете использовать аннотации @AnimatorRes, @AnimRes, @AnyRes, @ArrayRes, @AttrRes, @BoolRes, @ColorRes, @DimenRes, @DrawableRes, @FractionRes, @IdRes, @IntegerRes, @InterpolatorRes, @LayoutRes, @MenuRes, @PluralsRes, @RawRes, @StringRes, @StyleableRes, @StyleRes, @XmlRes и т.д. Если у вас есть свой тип ресурсов «foo», то можете использовать аннотацию FooRes.

@NONNULL/@NULLABLE

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

Студия выводит предупреждение, но позволит запустить программу. Нажатие на кнопку и опять ваш труд коту под хвост — крах приложения.

@CheckResult — ожидание результата

Метод может возвращать какое-то значение, которое нужно применить. А можно просто вызвать метод, только какой в этом смысл, если возвращаемое значение нигде не используется? Для тех, кто страдает склерозом — встречайте аннотацию @CheckResult.

Студия укажет на ошибку и откажется запускать ваше приложение. Умница.

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

Аннотации для потоков

Существуют специальные аннотации для указания потоков.

Например, мы знаем, что методы класса AsyncTask могут работать только в определённых потоках.

Если в методе doInBackground() обратиться к какому-нибудь компоненту, то студия предупредит, что так делать нельзя.

@UiThread и @MainThread практически совпадают, но в редких случаях могут различаться. Подробности в документации.

Аннотация для цвета

Вы можете задать цвет через ресурс, используя аннотацию @ColorRes. А если перед вами стоит противоположная задача — указать значение цвета через RGB/ARGB, то используйте аннотацию @ColorInt. В этом случае при использовании цветового ресурса студия покажет ошибку.

Диапазон значений

Можно указать диапазон значений для типов float/double через аннотацию @FloatRange:

В этом случае можно использовать значения от 0.0 до 1.0. Любая попытка ввести другое значение приведёт к предупреждению.

Аналогично работает для типов int/long через аннотацию @IntRange:

Для массивов, коллекций и строк можно использовать аннотацию @Size для установки ограничений в размерах или длине строк.

• Если коллекция не должна быть пустой — @Size(min=1)
• Максимальная длина строки 15 символов — @Size(max=15)
• Массив точно состоит из двух элементов — @Size(2)
• Длина массива должна быть кратна двум (например, координаты точек X и Y) — @Size(multiple=2)

Аннотации для разрешений

Если ваш метод использует функциональность, которая доступна через разрешения, то можете указать через аннотацию @RequiresPermission:

Если имеются несколько подходящих разрешений, то можно использовать атрибут anyOf, чтобы выбрать один из них:

А если нужно выбрать несколько разрешений, то используйте атрибут allOf:

Разрешения для намерений

Если есть разрешения на чтение или запись, то можно указать нужный режим через аннотации @Read или @Write:

Суперкласс

Если метод должен использовать вызов суперкласса, то используем аннотацию @CallSuper:

Остальные аннотации

В документации вы можете узнать о других аннотациях: IntDef/StringDef, @VisibleForTesting и т.д.

Источник

AndroidAnnotations — упрощаем и укорачиваем код без вреда для здоровья проекта (I часть)

Преимущества

Первое — это сокращение кода, вам больше не нужно искать по id вьюшки и отдельно определять для них слушателей.
Второе — это реализованная, как в самых эротических снах разработчиков под Android, работа с потоками.
Третье — удобное и лаконичное храние состояния активити/фрагмента
Четвертое — простое обращение с адаптерами ListView.
И еще много разных вкусностей.

Что внутри и как работает

Работает это великолепно! Вам не нужно наследоваться от RoboGreendroidOrmliteActionBarFragmentActivity и добавлять в проект тяжеловесные библиотеки. Аннотации обрабатываются на одном из шагов во время компиляции, в собранный проект добавляется лишь 50кб jar, остальное лежит и не лезет в собранный apk.
После аннотации Activity, во время компиляции AndroidAnnotations создаст наследника от него, в котором будут реализованы стандартные методы Android. А остальной код, который мы написали будет вызываться из предка. Из-за этого нам нужно в манифесе декларировать, a MyActivity_ — класс наследник MyActivity, автоматически генерируемый AndroidAnnotations.
Звучит страшно, но самом деле благодаря такому подходу мы как разработчики только выигрываем.
Производительность не падает — используются стандартные методы. А удобство написания растет во много раз.
И еще одна важная особенность: нам не нужно переписывать весь проект — достаточно аннотировать наши Activity/Fragment/View и использовать внутри только, те аннотации, которые нам нужны. А остальное писать, как мы привыкли это делать ранее, и как нам говорит официальная документация. К примеру, нужны в проекте только аннотации для потоков — их и аннотацию Activity/Fragment добавляем, а остальное пишем через стандартные методы.

Имлементация в проект

Здесь и далее всё описано для версии 2.6. Об изменениях в следующих версиях читайте чейнжлог

Настройки проекта

• Скачиваем архив с библиотекой
• androidannotations-2.6-api.jar — помещаем в папку «libs» нашего проекта.
• androidannotations-2.6.jar — поместим в новую папку внутри проекта с названием «ext-libs».
• Затем зайдем в «Project/Properties/Java compiler/Annotation Processing».
• Ставим галочки «Enable project specific settings», «Enable annotations processing», «Enable processing in editor».
• Заходим в подвкладку «Factory path»: ставим галочку «Enable project specific settings» и жмем «Add jar». Добавляем из папки «ext-libs» «androidannotations-2.6.jar». Жмем «apply» и «yes».
• Во вкладке «Java Compiler» убеждаемся, что у нас «1.6» версия компилятора.
• Во вкладке «Java Build Path/Source» жмем «Add Folder» и добавляем новую папку «.apt_generated».
• Жмем ОК

Самое нудное закончилось, дальше начинается песня.

Простая Activity

Для начала аннотируем MainActivity — в манифесте:

заменим .MainActivity на .MainActivity_
Аннотируем класс:

Теперь перегрузку onCreate можно смело удалить и попробовать скомпилировать.

Запуск последующих Activity

В обычном Activity всегда выполняется метод инициализации элементов интерфейса, и только после его выполнения мы можем вызывать свои методы, обращающиеся к различным View. Для аннотированных Activity метод, который обращается к элементам интерфейса мы аннотируем вот так: @AfterViews
Далее попробуем запустить следующую аннотированную Activity, над которой и будем производить различные эксперименты:

Вот таким простым способом запускаются аннотированные Activity
Для запуска с передачей экстры: TestActivity_.intent(context).myDateExtra(someDate).start();
где myDateExtra — аннотированное @ Extra сериализуемое protected-поле в TestActivity
Для запуска с флагами: TestActivity_.intent(context).flags(FLAG_ACTIVITY_CLEAR_TOP).start();

Аннотируем Activity по полной

Для сохранения состояния не нужно вынимать сохраненные объекты instance state вручную, достаточно:

И при измененнии состояния, например при повороте экрана — это поле не будет пересоздано, а сохранит свое значение.

Получение ресурсов, например строк:

Слушаем изменения текста:

Наиудобнейшая работа с потоками

В основном эту библиотеку в своих проектах я использую для работы с потоками.
Для этого используются две аннотации:
@ Background — аннотированный так метод выполнится в фоне
@ UiThread — так должен аннотироваться метод, вызываемый в фоновом потоке, но выполняющийся в потоке UI
Вот код примера:

На клик кнопки запускается фоновый поток, который во время своего выполнения публикует прогресс и в итоге передает результат выполнения.

Источник