Аннотации уровня API Android для Android-библиотек

Question

Я пишу библиотеку Android. Подавляющее большинство интерфейсов в lbirary поддерживает Android API уровня 10 или выше. Однако для некоторых функций требуется более высокий уровень API. Например, часть библиотеки требует API 18 для Bluetooth Low Energy.

Ради конкретности предположим, что библиотека производит три класса: ClassA, ClassB и ClassC. ClassA использует функциональные возможности, доступные в API 10, ClassB использует функциональные возможности, доступные в API 14 и ClassC использует функциональные возможности, доступные в API 18.

Я хочу, чтобы иметь возможность вызвать проблемы ворса (предупреждение/ошибка) всякий раз, когда кто-то использует класс от моего библиотеки, не имея требуемого уровня API в своем проекте (если они не подавляют предупреждение с соответствующей аннотацией), аналогично уже встроенной проблеме NewApi, используемой lint.

После поиска, я нашел следующие возможные решения:

1) Это решение не вдоль линий пуха: Сплит библиотеки в три .jar файлов, скажет lib_10.jar, что включает в себя все классы, используя функциональные возможности в API 10 (ClassA в примере), lib_14.jar, который включает в себя все классы с использованием функциональных возможностей, доступных в API 14 (класс B в примере) и lib_18.jar, который включает в себя все классы с использованием функциональных возможностей, доступных в API 18 (класс C в примере). Это решение обеспечивает переносимость, но усложнит более позднюю ремонтопригодность кодовой базы и потенциально может потребовать некоторого дублирования кода.

2) Создайте свою собственную аннотацию (скажем, @RequireAndroidApi(API_LEVEL), указывающее минимальный уровень API, необходимый для аннотированный класс/метод/и т.д ...) и использовать lint-api.jar (http://tools.android.com/tips/lint-custom-rules) для создания пользовательских пуха правил, которые проверяют использование любые аннотированные классы/методы/etc ... с более низким API, чем требуется. Что-то, что будет позже выглядеть следующим образом:

@RequireAndroidApi(10) 
Class ClassA { 
} 

@RequireAndroidApi(14) 
Class ClassB { 
} 

@RequireAndroidApi(18) 
Class ClassC { 
} 

Проблема заключается в том, что я не мог найти хорошую документацию для пуха API и кажется, что это изобретать колесо для функциональности, которая ворс уже поддерживает (ворс уже проверяет для проблемы «NewApi»).

3) И, наконец, мне удалось изменить <SDK>/platform-tools/api/api-versions.xml, чтобы указать уровень API, необходимые каждым классом следующим образом:

<api version="1"> 
    ... 
    <class name="package/path/ClassA" since="10"> 
     <extends name="java/lang/Object" /> 
     <method name="&lt;init>()V" /> 
    </class> 
    <class name="package/path/ClassB" since="14"> 
     <extends name="java/lang/Object" /> 
     <method name="&lt;init>()V" /> 
    </class> 
    <class name="package/path/ClassC" since="18"> 
     <extends name="java/lang/Object" /> 
     <method name="&lt;init>()V" /> 
    </class> 
</api> 

Что вызвало ворса, чтобы вызвать проблему NewApi таким же образом, как это было бы с API Android. Мне нравится этот тип решения, потому что он не изобретает колесо, и в дальнейшем любые ошибки, возникшие таким образом, будут использовать предлагаемые решения, запрограммированные в Eclipse или Android Studio, для решения проблемы (т. Е. «Быстрые исправления» в Eclipse). Проблема с этим решением заключается в том, что он требует редактирования api-versions.xml, который поставляется с Android SDK, что делает это решение не очень переносимым для выпуска библиотеки по нескольким причинам, включая: а) файл api-versions.xml не является локальным для проекта и изменяет поведение lint для всех проектов Android, включая те, которые не используют библиотеку; и b) api-versions.xml будет перезаписываться каждый раз, когда SDK обновляется из менеджера Android SDK, который перезаписывает сделанные изменения.

Мне было интересно, есть ли более простое решение для достижения «минимальных ошибок/предупреждений API» или существует способ написать отдельный файл, похожий на api-versions.xml, который может быть помещен в каталог проекта, который может быть прочитан когда во время пробега пробегает проект (что-то похожее на lint.xml).

Благодарим вас за внимание при этом длинном описании проблемы, и я ценю любую помощь заранее.

Answer 1

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

Я сделал это с аннотацией @TargetApi.

Если метод доступен только с уровня апи 16:

@TargetApi(16) 
public void someMethod() {} 

Это должно сделать трюк, в том числе ошибки линт.

Answer 2

Нет необходимости создавать собственные аннотации, аннотация андроидной поддержки @RequiresApi - это то, что вы ищете. Например:

@RequiresApi(Build.VERSION_CODES.LOLLIPOP) 
public void someMethod() {} 

Это примечание говорит ворса, чтобы предупредить, если someMethod() используется в контексте, который может иметь более низкий уровень API.

Отметьте, что @TargetApi отличается: он используется для обеспечения того, чтобы аннотированный метод вызывался только с помощью целевого API, в ситуации, когда он иначе предупреждал бы вас об использовании этого метода. Таким образом, @TargetApi можно использовать для отключения предупреждения о помехах, вызванного @RequiresApi.