Записки мобильного разраба

Почему исключения в Kotlin Coroutines это сложно и как с этим жить?

2022-09-19T12:02:00+00:00

Перевод статьи Why exception handling with Kotlin Coroutines is so hard and how to successfully master it!

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

Информация: вы можете посмотреть более полное видео об обработке исключений здесь.

Обработка исключений в “чистом” Kotlin

В Kotlin без корутин обрабатывать исключения достаточно просто. Для этого используются блоки обработки try-catch:

try {
    // some code
    throw RuntimeException("RuntimeException in 'some code'")
} catch (exception: Exception) {
    println("Handle $exception")
}

// Output:
// Handle java.lang.RuntimeException: RuntimeException in 'some code'

В обычной функции исключение пробрасывается (re-thrown). Это значит, что мы можем перехватить исключения блоком try-catch для их обработки в месте вызова такой функции:

fun main() {
    try {
        functionThatThrows()
    } catch (exception: Exception) {
        println("Handle $exception")
    }
}

fun functionThatThrows() {
    // some code
    throw RuntimeException("RuntimeException in regular function")
}

// Output
// Handle java.lang.RuntimeException: RuntimeException in regular function

try-catch в корутинах

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

fun main() {
    val topLevelScope = CoroutineScope(Job())
    topLevelScope.launch {
        try {
            throw RuntimeException("RuntimeException in coroutine")
        } catch (exception: Exception) {
            println("Handle $exception")
        }
    }
    Thread.sleep(100)
}

// Output
// Handle java.lang.RuntimeException: RuntimeException in coroutine

Но если запустить другую корутину внутри блока try-catch…

fun main() {
    val topLevelScope = CoroutineScope(Job())
    topLevelScope.launch {
        try {
            launch {
                throw RuntimeException("RuntimeException in nested coroutine")
            }
        } catch (exception: Exception) {
            println("Handle $exception")
        }
    }
    Thread.sleep(100)
}

// Output
// Exception in thread "main" java.lang.RuntimeException: RuntimeException in nested coroutine

… видно, что исключение больше не обрабатывается и приложение падает. Это весьма неожиданно и сбивает с толку. Если основываться на наших знаниях и опыте работы с try-catch, мы ожидаем, что каждое исключение обернутое блоком try-catch перехватывается и передается в ветку catch. Почему здесь это не срабатывает?

Хорошо, если корутина не перехватывает исключение самостоятельно через блок try-catch, она “завершается по необработанному исключению” или, простыми словами, она падает. В примере выше, внутренняя корутина запущенная через launch не перехватывает RuntimeException сама и поэтому падает.

Как мы увидели в начале, не перехваченное исключение “пробрасывается” выше в обычной функции. В случае корутины это не работает. Иначае, мы бы могли обработать исключение во внешнем try-catch блоке и приложение с примером выше не падало.

Тогда, что происходит с не перехваченным исключением в корутине? Вероятно вы знаете, одна из самых крутых штук в корутинах это Структурная Конкурентность (Structured Concurrency). Для работы всех возможностей Structured Concurrency, объект Job в CoroutineScope и объекты Job в корутинах и дочерние корутины образуют иерархию вида “родитель-ребенок”. Любое не перехваченное исключение, вместо того, чтобы быть проброшенным, распространяется вверх по иерарахии Job объектов. Такое распространение приводит к падению родительской Job и ведет к отказу всех дочерних Job.

Для примера выше иерархия Job выглядит так:

Исключение из дочерней корутины распространяется выше до объекта Job корутины верхнего уровня (1) и затем дальше до объекта Job в topLevelScope (2).

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

По-моему мнению, у нас фактически два разных механизма для обработки исключений – try-catch и CoroutineExceptionHandlers, это один из главных факторов, почему обработка исключений в корутинах такая сложная.

Ключевая особенность #1

Если корутина не обрабатывает исключения сама блоком try-catch, исключение не пробрасывается и таким образом не сможет быть обработана внешним try-catch. Вместо этого, исключение “распространяется по иерархии корутин (Job)” и может быть обработана специально установленным CoroutineExceptionHandler. Если таковых нет, необработанное исключение попадает в обработчик не перехваченных исключений потока.

Обработчик CoroutineExceptionHandler

Ладно, сейчас мы знаем, что try-catch блок бесполезен если мы стартуем корутину с исключением в try ветке. Давайте вместо этого установим CoroutineExceptionHandler! Мы можем передать контекст в функцию-билдер корутин launch. Так как CoroutineExceptionHandler это ContextElement, его можно установить как единственный аргумент в launch, при запуске нашей дочерней корутины:

fun main() {
  
    val coroutineExceptionHandler = CoroutineExceptionHandler { coroutineContext, exception ->
        println("Handle $exception in CoroutineExceptionHandler")
    }
    
    val topLevelScope = CoroutineScope(Job())

    topLevelScope.launch {
        launch(coroutineExceptionHandler) {
            throw RuntimeException("RuntimeException in nested coroutine")
        }
    }

    Thread.sleep(100)
}

// Output
// Exception in thread "DefaultDispatcher-worker-2" java.lang.RuntimeException: RuntimeException in nested coroutine

Хм, тем не менее, наше исключение не обрабатывается в coroutineExceptionHandler и приложение падает! Это потому что установка CoroutineExceptionHandler в дочерние корутины не имеет никакого эффекта. Мы должны установить обработчик в scope или в корутину верхнего уровня, таким образом:

// ...
val topLevelScope = CoroutineScope(Job() + coroutineExceptionHandler)
// ...

или что-то похожее на:

// ...
topLevelScope.launch(coroutineExceptionHandler) {
// ...

И только тогда, наш обработчик ошибок сработает:

// ..
// Output: 
// Handle java.lang.RuntimeException: RuntimeException in nested coroutine in CoroutineExceptionHandler

Ключевая особенность #2

Чтобы CoroutineExceptionHandler сработал, надо его устанавливать или в CoroutineScope или в корутинах верхнего уровня.

try-catch VS CoroutineExceptionHandler

Как вы уже поняли, у нас два варианта для обработки исключений:

оборачиваем код внутри корутины блоком try-catch,
установка обработчика CoroutineExceptionHandler.

Какой вариант следует выбирать?

У официальной документации CoroutineExceptionHandler) есть хорошие ответы на это:

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

Если вам надо обрабатывать исключение в отдельной части кода, рекомендуется использовать try-catch блок вокруг вашего кода внутри корутины. Таким образом, вы можете предотвратить завершение корутины через ошибку (теперь исключение обрабатывается), повторить операцию, и/или предпринять любые другие действия.

Здесь есть еще один аспект - если обрабатывать исключения напрямую в корутине с try-catch, то это ломает концепцию отмены корутин в Structured Concurrency. К примеру, давайте представим, что мы запустили две корутины параллельно. Они обе как-то зависят друг от друга таким образом, что завершение одной не имеет смысла, если другая падает. При использовании try-catch для обработки исключений в каждой корутине, сами исключения не будут распространяться выше к родителю и поэтому другая корутина не будет отменяться. Это тратит ресурсы впустую. В таких ситуациях необходимо использовать CoroutineExceptionHandler.

Ключевая особенность #3

Используйте try-catch если вы хотите как-то восстановиться (повтор или другие операции), до того как корутина закончится. Помните, что перехваченное исключение не распространяется выше по иерархии корутин и функционал отмены для Structured Concurrency не работает в этом случае. CoroutineExceptionHandler применяйте для логики работающей после того, как корутина завершена.

launch{} vs async{}

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

fun main() {

    val topLevelScope = CoroutineScope(SupervisorJob())

    topLevelScope.async {
        throw RuntimeException("RuntimeException in async coroutine")
    }

    Thread.sleep(100)
}

// No output

В этом примере воообще ничего не выводится. Что здесь происходит с RuntimeException? Исключение игнорируется? Нет. В корутинах запущенных через async , необработанные исключения также немедленно распространяются вверх по иерархии корутин. Но в отличие от launch, исключения не обрабатываются установленным CoroutineExceptionHandler и не передаются в обработчик потока для необработанных исключений.

Функция launch для запуска корутин возвращает экземпляр Job, это простое представление корутины которая не возвращает значение. В случае если мы хотим чтобы корутина что-то возвращала, мы должны использовать функцию async, которая возвращает объект Deferred, специальный подтип Job с результатом. Если async корутина падает, то исключение оборачивается в возвращаемое значение Deferred и пробрасывается, когда мы вызываем await у корутины для получения результата.

Поэтому, мы можем обернуть .await() в блок try-catch. Так как .await() это suspend функция, мы должны запустить новую корутину, чтобы можно было ее вызвать:

fun main() {

    val topLevelScope = CoroutineScope(SupervisorJob())

    val deferredResult = topLevelScope.async {
        throw RuntimeException("RuntimeException in async coroutine")
    }

    topLevelScope.launch {
        try {
            deferredResult.await()
        } catch (exception: Exception) {
            println("Handle $exception in try/catch")
        }
    }

    Thread.sleep(100)
}

// Output: 
// Handle java.lang.RuntimeException: RuntimeException in async coroutine in try/catch

Внимание: исключение оборачивается в Deferred, только для async корутин верхнего уровня. В противном случае оно немедленно распространяется вверх по иерархии Job и перехватывается или CoroutineExceptionHandler или передается в обработчик необработанных ошибок в потоке, это происходит даже без вызова метода .await(), как в примере ниже:

fun main() {
  
    val coroutineExceptionHandler = CoroutineExceptionHandler { coroutineContext, exception ->
        println("Handle $exception in CoroutineExceptionHandler")
    }
    
    val topLevelScope = CoroutineScope(SupervisorJob() + coroutineExceptionHandler)
    topLevelScope.launch {
        async {
            throw RuntimeException("RuntimeException in async coroutine")
        }
    }
    Thread.sleep(100)
}

// Output
// Handle java.lang.RuntimeException: RuntimeException in async coroutine in CoroutineExceptionHandler

Ключевая особенность #4

Необработанные исключения для launch и async мгновенно распростаняются по иерархии Job. Однако, если верхнеуровневая корутина была запущена через launch, то исключение обрабатывается CoroutineExceptionHandler или передается в обработчик необработанных исключений в потоке. С другой стороны, при запуске верхнеуровневой корутины через async, исключение оборачивается в возвращаемый объект Deferred и пробрасывается, когда вызывается его метод .await()

Особенности обработки исключений в coroutineScope{}

Когда в начале статьи мы разговаривали об использовании try-catch в корутинах, я сказал вам, что падающая корутина распространяет свое исключение по иерархии Job вместо проброса и таким образом, блок try-catch не работает.

Однако, когда мы оборачиваем падающую корутину в scope функцию coroutineScope{}, происходит нечто интересное:

fun main() {
    
  val topLevelScope = CoroutineScope(Job())
    
  topLevelScope.launch {
        try {
            coroutineScope {
                launch {
                    throw RuntimeException("RuntimeException in nested coroutine")
                }
            }
        } catch (exception: Exception) {
            println("Handle $exception in try/catch")
        }
    }

    Thread.sleep(100)
}

// Output 
// Handle java.lang.RuntimeException: RuntimeException in nested coroutine in try/catch

Теперь мы можем обрабатывать исключения в try-catch. Scope функция coroutineScope{} пробрасывается исключения из своих дочерних корутин вместо распространения по иерарахии Job.

coroutineScope{} используется в основном в suspend функциях для “параллельной декомпозиции”. Эти suspend функции будут пробрасывать исключения из своих корутин и таким образом можно будет организовать обработку исключений.

Ключевая особенность #5

scope функция coroutineScope{} пробрасывает исключения от дочерних корутин, вместо распространия по иерархии Job. Это дает нам обработку ошибок через try-catch.

Обработка исключений в supervisorScope{}

Когда мы используем scope функцию supervisorScope{}, устанавливается новый, отдельный, вложенный scope с типом SupervisorJob в нашей Job иерархии. Что-то вроде этого…

fun main() {

    val topLevelScope = CoroutineScope(Job())

    topLevelScope.launch {
        val job1 = launch {
            println("starting Coroutine 1")
        }

        supervisorScope {
            val job2 = launch {
                println("starting Coroutine 2")
            }

            val job3 = launch {
                println("starting Coroutine 3")
            }
        }
    }

    Thread.sleep(100)
}

… создает иерархию корутин:

Здесь важно понимать, что supervisorScope это новый, отдельный вложенный scope, который должен обрабатывать исключения сам. supervisorScope не пробрасывает исключения своих внутренних корутин (как это делает coroutineScope), и не передает исключения родительской Job (в примере это topLevelScope).

Еще одна важная вещь - исключения распространяются вверх по иерархии, пока не дойдут до scope верхнего уровня или SupervisorJob. Это значит, что в примере выше: “Coroutine 2” и “Coroutine 3”, это корутины верхнего уровня.

Также мы можем установить CoroutineExceptionHandler отдельно для “Coroutine 2” (или “Coroutine 3”):

fun main() {

    val coroutineExceptionHandler = CoroutineExceptionHandler { coroutineContext, exception ->
        println("Handle $exception in CoroutineExceptionHandler")
    }

    val topLevelScope = CoroutineScope(Job())

    topLevelScope.launch {
        val job1 = launch {
            println("starting Coroutine 1")
        }

        supervisorScope {
            val job2 = launch(coroutineExceptionHandler) {
                println("starting Coroutine 2")
                throw RuntimeException("Exception in Coroutine 2")
            }

            val job3 = launch {
                println("starting Coroutine 3")
            }
        }
    }

    Thread.sleep(100)
}

// Output
// starting Coroutine 1
// starting Coroutine 2
// Handle java.lang.RuntimeException: Exception in Coroutine 2 in CoroutineExceptionHandler
// starting Coroutine 3

Так как корутины в supervisorScope это корутины верхнего уровня, это значит, что async корутины теперь оборачивают свои исключения в Deferred объекты…

// ... other code is identical to example above
supervisorScope {
    val job2 = async {
        println("starting Coroutine 2")
        throw RuntimeException("Exception in Coroutine 2")
    }

// ...

// Output: 
// starting Coroutine 1
// starting Coroutine 2
// starting Coroutine 3

… и будут проброшены при вызове .await()

Ключевая особенность #6

scope функция supervisorScope{} создает новый независимый scope с типом SupervisorJob в иерархии Job. Этот новый scope не распространяет свои исключения “вверх по иерархии”, обработку ошибок он должен выполнять самостоятельно. Корутины запускаемые из supervisorScope являются корутинами верхнего уровня. Корутины верхнего уровня ведут себя иначе, чем дочерние корутины, при запуске через launch() или async(). Кроме того, в корутины верхнего уровня можно установить обработчики исключений CoroutineExceptionHandlers.

Все!

Я вывел эти ключевые моменты, пытаясь понять обработку исключений в корутинах.

Kotlin, обрабатываем исключения в корутинах правильно.

2022-05-05T08:02:00+00:00

Перевод статьи Are You Handling Exceptions in Kotlin Coroutines Properly?

Как Kotlin разработчик, вы скорее всего знаете, что корутины в случае ошибки, выкидывают исключения.

Возможно вы думаете обработка таких исключений происходит как обычно в Kotlin/Java коде. К сожалению, при использовании вложенных корутин, все может работать не так как ожидается.

В этой статье я попробую показать ситуации, в которых требуется осторожность и расскажу про лучшие практики в обработке ошибок.

Работа вложенных корутин

Давайте начнем с примера, где все вроде бы выглядит нормально. Пример показывает сценарий, когда нужно обновить View, данные для которого комбинируются из двух разных источников и один из источников падает с ошибкой. Функция-билдер для корутин async будет использоваться в слое Repository для выполнения двух запросов паралелльно. Билдер требует CoroutineScope, обычно он берется из ViewModel в которой запускается выполнение корутины.

Метод в Repository будет выглядеть так:

suspend fun getNecessaryData(scope: CoroutineScope): List<DisplayModel> {
    val failingDataDeferred = scope.async { apiService.getFailingData() }
    val successDataDeferred = scope.async { apiService.getData() }
    return failingDataDeferred.await().plus(successDataDeferred.await())
        .map(DisplayModel::fromResponse)
}

Запрос с ошибкой просто пробрасывает исключение в своем теле через небольшой таймаут:

suspend fun getFailingData(): List<ResponseModel> {
    delay(100)
    throw RuntimeException("Request Failed")
}

Во ViewModel данные запрашиваются:

viewModelScope.launch {
    kotlin.runCatching { repository.getNecessaryData(this) }
        .onSuccess { liveData.postValue(ViewState.Success(it)) }
        .onFailure { liveData.postValue(ViewState.Error(it)) }
}

Я использую удобный kotlin.Result функционал здесь, runCatching оборачивает try-catch блок, a ViewState – класс-обертка для состояний UI. При запуске этого кода, приложение падает с нашим созданным RuntimeException. Это кажется странными, ведь мы используем try-catch блок для перехвата любых исключений. Чтобы понять, что здесь происходит, давайте повторим, как исключения обрабатываются в Kotlin и Java.

Повторный проброс исключений

Простой пример:

fun someMethod() {
   try {
      val failingData = failingMethod()
   } catch (e: Exception) {
      // handle exception
   }
}

fun failingMethod() {
   throw RuntimeException()
}

Исключение возникает в failingMethod. И в Kotlin и в Java, функции по умолчанию пробрасывают все исключения, которые не были обработаны внутри них. Благодаря этому механизму, исключения из функции failingMethod можно поймать в родительском коде через блок try-catch.

Распространение исключений

Давайте перенесем логику предыдущего примера во ViewModel:

viewModelScope.launch {
     try {
        val failingData = async { throw RuntimeException("Request Failed") }
        val data = async { apiService.getData() }
        val result = failingData.await().plus(data.await()).map(DisplayModel::fromResponse)
        liveData.postValue(ViewState.Success(result))
     } catch (e: Exception) {
        liveData.postValue(ViewState.Error(e))
     }
}

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

Это первый ключевой момент в этой истории:

И launch и async функции не пробрасывают исключения, которые возникают внутри. Вместо этого, они РАСПРОСТРАНЯЮТ их вверх по иерархии корутины. Поведение верхнего уровня async объясняется ниже.

Иерархия корутины и CoroutineExceptionHandler

Наша иерархия корутин выглядит таким образом:

На самом верху у нас находится область видимости (scope) от ViewModel, где мы создаем корутину верхнего уровня при помощи функции launch. Внутри этой корутины мы добавляем 2 дочерние корутины через async. Когда исключение возникает в любой дочерней корутине, исключение не пробрасывается, а немедленно передается вверх по иерархии пока не достигнет объекта области видимости (scope).

Далее scope передает исключение в обработчик CoroutineExceptionHandler. Он может быть установлен или в самом scope через конструктор или в корутине верхнего уровня, как параметр в функциях async и launch.

Имейте в виду, установка обработчика в любой дочерней корутине не будет работать.

Такой механизм распространиения исключений это часть Структурной Конкурентности (Structured Concurrency), принцип проектирования корутин, введеный авторами для правильного выполнения и отмены иерархии корутин без утечек памяти.

Больше деталей здесь.

Ок, но почему наше приложение падает, когда есть такой механизм? Потому что мы не установили никакого обработчика CoroutineExceptionHandler!

Давайте передадим обработчик в функцию launch (сделать это через scope здесь невозможно, так как viewModelScope создается не нами):

private val exceptionHandler = CoroutineExceptionHandler { coroutineContext, throwable ->
    liveData.postValue(ViewState.Error(throwable))
}

viewModelScope.launch(exceptionHandler) {
    // content unchanged
}

Теперь мы будем правильно получать ошибку в наше view.

Дополнительные возможности

После наших правок, блок try-catch больше не нужен, исключения больше не будут перехватываться там. Мы можем удалить его и полностью полагаться на установленный обработчик ошибок. Однако, это может быть не самым лучшим решением, если нам нужен больший контроль над выполнением корутин, так как этот обработчик собирает все исключения и не дает механизмов повтора или альтернативного исполнения.

Вторая возможность – удалить обработчик исключений, оставить логику блока try-catch, но изменить слой репозитория данных (Repository) с использованием специальных билдеров корутин для вложенного исполнения: coroutineScope и supervisorScope. Таким образом у нас будет больше контроля над потоком исполнения и, к примеру, можно использовать метод recoverCatching из kotlin.Result если требуется операция восстановления после ошибки.

Давайте взглянем, что эти билдеры предлагают.

coroutineScope билдер

Этот билдер создает дочерний scope в иерархии корутины. Ключевые особенности:

наследует контекст из вызывающей корутины и поддерживает структурную конкурентность
не распространяет исключения из дочерних корутин, вместо этого пробрасывает (re-throw) исключения
отменяет все дочерние корутины, если хотя бы одна из них падает с ошибкой

Теперь больше не надо передавать viewModelScope в метод:

suspend fun getNecessaryData(): List<DisplayModel> = coroutineScope {
     val failingDataDeferred = async { apiService.getFailingData() }
     val successDataDeferred = async { apiService.getData() }
     
     failingDataDeferred.await().plus(successDataDeferred.await())
        .map(DisplayModel::fromResponse)
}

После этих правок, исключение из первой функции async попадет в try-catch блок во ViewModel, потому что исключение повторно пробрасывается из функции билдера.

supervisorScope билдер

Билдер создает новый scope с SupervisorJob.

Ключевые особенности:

если одна из дочерних корутин падает с исключением, другие корутины не отменяются
дочерние корутины становятся верхнеуровневыми (можно настроить CoroutineExceptionHandler)
наследует контекст из вызывающей корутины и поддерживает структурную конкурентность (также как coroutineScope)
не распространяет исключения из дочерних корутин, вместо этого пробрасывает (re-throw) исключения (также как coroutineScope)

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

Эта особенность требует обработчика CoroutineExceptionHandler в верхнеуровневой корутине, иначе supervisorScope все равно упадет. Причина этого в механизме, который обсуждали выше - scope всегда проверяет установлен ли обработчик ошибок. Если обработчика нет - будет падение.

suspend fun getNecessaryData(): List<DisplayModel> = supervisorScope {
     val failingDataDeferred = async(exceptionHandler) { apiService.getFailingData() }
     val successDataDeferred = async(exceptionHandler) { apiService.getData() }
     
     failingDataDeferred.await().plus(successDataDeferred.await())
        .map(DisplayModel::fromResponse)
}

К сожалению, если запустить этот код, ViewModel все еще перехватывает исключение. Почему так?

Верхнеуровневый async

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

async верхнего уровня скрывает обработку исключения в объекте Deffered, который возвращает билдер. Объект выбрасывает нормальное исключение только при вызове метода await()

Обычные исключения в supervisorScope

В документации есть следующее: “Сбой в scope (исключение выбрасывается в блоке или на этапе отмены) приводит к сбою всего scope со всеми дочерними корутинами”.

В нашем сценарии, исключение выбрасывается при вызове ailingDataDeffered.await(). Это происходит вне билдера async, таким образом это не распространяется в supervisorScope, а выбрасывается как обычное исключение. Весь supervisorScope немедленно падает и пробрасывает это исключение.

Чтобы избежать этой проблемы, мы можем использовать launch решение, которое будет правильно распространять исключение в supervisorScope и вторая кортуна будет оставаться живой.

suspend fun getNecessaryData(): List<DisplayModel> = supervisorScope {
   buildList {
        launch(exceptionHandler) { apiService.getFailingData() }.join()
        launch(exceptionHandler) { apiService.getData() }.join()
    }.map(DisplayModel::fromResponse)
}

Короткая заметка: вызов join() тут нужен, потому что он приостанавливает корутину в которой работает. Благодаря этому метод getNecessaryData не вернет управление пока обе Job не будут завершены. В противном случае метод вернет управление сразу без всяких данных.

CancellationException

В последней части статьи, я бы хотел рассказать об исключении CancellationException, которое используется в механизме Structured Concurrency как сигнал отмены в корутинах. Это исключение передается всем корутинам внутри scope при его отмене (к примеру, если пользователь ушел с экрана) или если другая корутина падает.

Очень часто мы ненароком ломаем этот механизм, используя такой подход, чтобы обернуть корутины:

private suspend fun fetchData(action: suspend () -> T) =
    try {
       liveData.postValue(ViewState.Success(action()))
    } catch (e: Exception) {
       liveData.postValue(ViewState.Error(e))
    }

Это работает ок, если есть такой вызов для каждой корутины (Я также использовал подобный подход выше).

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

Например, мы вызываем для загрузки данных следующее:

viewModelScope.launch {
    fetchData { someApi.request1() }
    fetchData { someApi.request2() }
}

launch запускает задачи последовательно по своей природе, это значит, что второй вызов fetchData ждет, пока не выполнится первый вызов.

Если пользователь уходит с экрана до того момента, когда request1 заканчивается, viewModelScope будет отменен и первый вызов fetchData перехватит и обработает CancellationException.

После этого, корутина продолжит свою работу и запустит request2 как ни в чем не бывало, потому что мы скрыли CancellationException от нее.

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

Чтобы это предотвратить, мы можем улучшить метод fetchData, чтобы повторно пробрасывать CancellationException. Таким образом вся родительская корутина будет отменена правильно:

private suspend fun fetchData(action: suspend () -> T) =
    try {
        liveData.postValue(ViewState.Success(action()))
    } catch (e: Exception) {
        liveData.postValue(ViewState.Error(e))
        if (e is CancellationException) {
            throw e
        }
    }

Также помним об удобном операторе kotlin.Result:

private suspend fun runDataFetch(action: suspend () -> T) =
    kotlin.runCatching { action() }
        .onSuccess { liveData.postValue(ViewState.Success(it) }
        .onFailure {
            liveData.postValue(ViewState.Error(it))
            if (it is CancellationException) {
                throw it
            }
        }

Это безопасный проброс конкретного исключения - мы можем быть уверены, корутина обработает его правильно.

Kotlin, как работает SUSPEND под капотом.

2022-04-06T12:02:00+00:00

Перевод статьи The suspend modifier — under the hood.

Как компилятор преобразует suspend код, чтобы корутины можно было приостанавливать и возобновлять?

Корутины в Kotlin представлены ключевым словом suspend. Интересно, что там происходит внутри? Как компилятор преобразует suspend блоки в код, поддерживающий приостановку и возобновление работы корутины?

Знание этого поможет понимать, почему suspend функция не возвращает управление, пока не завершится вся запущенная работа и как код может приостановить выполнение без блокировки потоков.

TL;DR; Компилятор Kotlin создает специальную машину состояний для каждой suspend функции, эта машина берет управление корутиной на себя!

Новенький в Android? Взгляни на эти полезные ресурсы по корутинам:

Для тех, кто предпочитает видео:

Корутины, краткое введение

Говоря по-простому, корутины это асинхронные операции в Android. Как описано в документации, мы можем использовать корутины для управления асинхронными задачами, которые иначе могут блокировать основной поток и приводить к зависанию UI приложения.

Также корутины удобно использовать для замены callback-кода на императивный код. Например, посмотрите на этот код с использованием колбеков:

// Simplified code that only considers the happy path
fun loginUser(userId: String, password: String, userResult: Callback<User>) {
  // Async callbacks
  userRemoteDataSource.logUserIn { user ->
    // Successful network request
    userLocalDataSource.logUserIn(user) { userDb ->
      // Result saved in DB
      userResult.success(userDb)
    }
  }
}

Заменяем эти колбеки на последовательные вызовы функций с использованием корутин:

suspend fun loginUser(userId: String, password: String): UserDb {
  val user = userRemoteDataSource.logUserIn(userId, password)
  val userDb = userLocalDataSource.logUserIn(user)
  return userDb
}

Для функций, которые вызываются в корутинах, мы добавили ключевое слово suspend. Так компилятор знает, что эти функции для корутин. С точки зрения разработчика, рассматривайте suspend функцию как обычную, выполнение которой может быть приостановлено и возобновлено в определенный момент.

В отличие от колбеков, корутины предлагают простой способ переключения между потоками и обработки исключений.

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

Suspend под капотом

Давайте вернемся к suspend функции loginUser, посмотрите, другие функции которые она вызывает это тоже suspend функции:

suspend fun loginUser(userId: String, password: String): UserDb {
  val user = userRemoteDataSource.logUserIn(userId, password)
  val userDb = userLocalDataSource.logUserIn(user)
  return userDb
}

// UserRemoteDataSource.kt
suspend fun logUserIn(userId: String, password: String): User

// UserLocalDataSource.kt
suspend fun logUserIn(userId: String): UserDb

Кратко говоря, компилятор Kotlin берет suspend функции и преобразовывает их в оптимизированную версию колбеков с использованием конечной машины состояний (о которой мы поговорим позже).

Интерфейс Continuation

Suspend функции взаимодействуют друг с другом с помощью Continuation объектов. Continuation объект - это простой generic интерфейс с дополнительными данными. Позже мы увидим, что сгенерированная машина состояний для suspend функции будет реализовать этот интерфейс.

Сам интерфейс выглядит так:

interface Continuation<in T> {
  public val context: CoroutineContext
  public fun resumeWith(value: Result<T>)
}

context это экземпляр CoroutineContext, который будет использоваться при возобновлении.
resumeWith возобновляет выполнение корутины с Result, он может либо содержать результат вычисления, либо исключение.

С Kotlin 1.3 и далее, вы можете использовать extensions функции resume(value: T) и resumeWithException(exception: Throwable), это специализированные версии метода resumeWith.

Компилятор заменяет ключевое слово suspend на дополнительный аргумент completion (тип Continuation) в функции, аргумент используется для передачи результата suspend функции в вызывающую корутину:

fun loginUser(userId: String, password: String, completion: Continuation<Any?>) {
  val user = userRemoteDataSource.logUserIn(userId, password)
  val userDb = userLocalDataSource.logUserIn(user)
  completion.resume(userDb)
}

Для упрощения, наш пример возвращает Unit вместо объекта User.

Байткод suspend функций фактически возвращает Any? так как это объединение (union) типов T | COROUTINE_SUSPENDED. Что позволяет функции возвращать результат синхронно, когда это возможно.

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

Кроме того, интерфейс Continuation можно увидеть в:

При конвертации колбек-API в корутины с использованием suspendCoroutine или suspendCancellableCoroutine (предпочтительнее использовать в большинстве случаев). Вы напрямую взаимодействуете с экземпляром Continuation, чтобы возобновить корутину, приостановленную после выполнения блока кода из аргументов suspend функции.
Вы можете запустить корутину при помощи startCoroutine extension функции в suspend методе. Она принимает Continuation как аргумент, который будет вызван, когда новая корутина завершится либо с результатом, либо с исключением.

Используем Dispatchers

Вы можете переключаться между разными диспетчерами для запуска вычислений на разных потоках. Как Kotlin знает, где возобновить suspend вычисления?

Есть подтип Continuation, он называется DispatchedContinuation, где его метод resume делает вызов Dispatcher доступного в контексте корутины CoroutineContext. Все диспетчеры (Dispatchers) будут вызывать метод dispatch, кроме типа Dispatchers.Unconfined, он переопределяет метод isDispatchNeeded (он вызывается перед вызовом dispatch), который возвращает false в этом случае.

Сгенерированная машина состояний

Уточнение: Приведенный код не полностью соответствует байткоду сгенерированному компилятором. Это будет код на Kotlin, достаточно точный, для понимания того, что в действительности происходит внутри. Это представление сгенерировано корутинами версии 1.3.3 и может поменяться в следующих версиях библиотеки.

Компилятор Kotlin определяет, когда функция может остановится внутри. Каждая точка останова представляется как отдельное состояние в конечной машине состояний. Такие состояния компилятор помечает метками:

fun loginUser(userId: String, password: String, completion: Continuation<Any?>) {
  
  // Label 0 -> first execution
  val user = userRemoteDataSource.logUserIn(userId, password)
  
  // Label 1 -> resumes from userRemoteDataSource
  val userDb = userLocalDataSource.logUserIn(user)
  
  // Label 2 -> resumes from userLocalDataSource
  completion.resume(userDb)
}

Компилятор использует when для состояний:

fun loginUser(userId: String, password: String, completion: Continuation<Any?>) {
  when(label) {
    0 -> { // Label 0 -> first execution
        userRemoteDataSource.logUserIn(userId, password)
    }
    1 -> { // Label 1 -> resumes from userRemoteDataSource
        userLocalDataSource.logUserIn(user)
    }
    2 -> { // Label 2 -> resumes from userLocalDataSource
        completion.resume(userDb)
    }
    else -> throw IllegalStateException(/* ... */)
  }
}

Этот код неполный, так как различные состояния не могут обмениваться информацией. Компилятор использует для обмена тот же самый объект Continuation. Вот почему родительски тип в Continuation это Any? вместо ожидаемого возвращаемого типа User.

При этом компилятор создает приватный класс, который:

хранит нужные данные
вызывает функцию loginUser рекурсивно для возобновления вычисления

Ниже представлен примерный вид такого сгенерированного класса:

Комментарии в коде были добавлены вручную для объяснения действий

fun loginUser(userId: String?, password: String?, completion: Continuation<Any?>) {
  
  class LoginUserStateMachine(
    // completion parameter is the callback to the function 
    // that called loginUser
    completion: Continuation<Any?>
  ): CoroutineImpl(completion) {
  
    // Local variables of the suspend function
    var user: User? = null
    var userDb: UserDb? = null
  
    // Common objects for all CoroutineImpls
    var result: Any? = null
    var label: Int = 0
  
    // this function calls the loginUser again to trigger the
    // state machine (label will be already in the next state) and
    // result will be the result of the previous state's computation
    override fun invokeSuspend(result: Any?) {
      this.result = result
      loginUser(null, null, this)
    }
  }
  /* ... */
}

Поскольку invokeSuspend вызывает loginUser только с аргументом Continuation, остальные аргументы в функции loginUser будут нулевыми. На этом этапе компилятору нужно только добавить информацию как переходить из одного состояния в другое.

Компилятору нужно знать:

Функция вызывается первый раз или
Функция была возобновлена из предыдущего состояния Для этого проверяется тип аргумента Continuation в функции:

fun loginUser(userId: String?, password: String?, completion: Continuation<Any?>) {
  /* ... */
  val continuation = completion as? LoginUserStateMachine ?: LoginUserStateMachine(completion)
  /* ... */
}

Если функция вызывается первый раз, то создается новый экземпляр LoginUserStateMachine и аргумент completion передается в этот экземпляр, чтобы возобновить вычисление. Иначе продолжится выполнение машины состояний.

Давайте взглянем на код, который генерирует компилятор для смены состояний и обмена информацией между ними:

fun loginUser(userId: String?, password: String?, completion: Continuation<Any?>) {
    /* ... */

    val continuation = completion as? LoginUserStateMachine ?: LoginUserStateMachine(completion)

    when(continuation.label) {
        0 -> {
            // Checks for failures
            throwOnFailure(continuation.result)
            // Next time this continuation is called, it should go to state 1
            continuation.label = 1
            // The continuation object is passed to logUserIn to resume 
            // this state machine's execution when it finishes
            userRemoteDataSource.logUserIn(userId!!, password!!, continuation)
        }
        1 -> {
            // Checks for failures
            throwOnFailure(continuation.result)
            // Gets the result of the previous state
            continuation.user = continuation.result as User
            // Next time this continuation is called, it should go to state 2
            continuation.label = 2
            // The continuation object is passed to logUserIn to resume 
            // this state machine's execution when it finishes
            userLocalDataSource.logUserIn(continuation.user, continuation)
        }
          /* ... leaving out the last state on purpose */
    }
}

Обратите внимание на различия между этим и предыдущим примером кода:

Появилась переменная label из LoginUserStateMachine, которая передается в when.
Каждый раз при обработке нового состояния проверяется есть ли ошибка.
Перед вызовом следующей suspend функции (logUserIn), LoginUserStateMachine обновляет переменную label.
Когда внутри машины состояний вызывается другая suspend функция, экземпляр Continuation (с типом LoginUserStateMachine) передается как аргумент. Вложенная suspend функция также была преобразована компилятором со своей машиной состояний. Когда эта внутренняя машина состояний завершит свою работу, она возобновит выполнение “родительской” машины состояний.

Последнее состояние должно возобновить выполнение completion через вызов continuation.cont.resume (очевидно что входной аргумент completion, сохраняется в переменной continuation.cont экземпляра LoginUserStateMachine):

fun loginUser(userId: String?, password: String?, completion: Continuation<Any?>) {
    /* ... */

    val continuation = completion as? LoginUserStateMachine ?: LoginUserStateMachine(completion)

    when(continuation.label) {
        /* ... */
        2 -> {
            // Checks for failures
            throwOnFailure(continuation.result)
            // Gets the result of the previous state
            continuation.userDb = continuation.result as UserDb
            // Resumes the execution of the function that called this one
            continuation.cont.resume(continuation.userDb)
        }
        else -> throw IllegalStateException(/* ... */)
    }
}

Компилятор Kotlin делает много работы “под капотом”. Из suspend функции:

suspend fun loginUser(userId: String, password: String): User {
  val user = userRemoteDataSource.logUserIn(userId, password)
  val userDb = userLocalDataSource.logUserIn(user)
  return userDb
}

Генерируется большой кусок кода:

fun loginUser(userId: String?, password: String?, completion: Continuation<Any?>) {

    class LoginUserStateMachine(
        // completion parameter is the callback to the function that called loginUser
        completion: Continuation<Any?>
    ): CoroutineImpl(completion) {
        // objects to store across the suspend function
        var user: User? = null
        var userDb: UserDb? = null

        // Common objects for all CoroutineImpl
        var result: Any? = null
        var label: Int = 0

        // this function calls the loginUser again to trigger the 
        // state machine (label will be already in the next state) and 
        // result will be the result of the previous state's computation
        override fun invokeSuspend(result: Any?) {
            this.result = result
            loginUser(null, null, this)
        }
    }

    val continuation = completion as? LoginUserStateMachine ?: LoginUserStateMachine(completion)

    when(continuation.label) {
        0 -> {
            // Checks for failures
            throwOnFailure(continuation.result)
            // Next time this continuation is called, it should go to state 1
            continuation.label = 1
            // The continuation object is passed to logUserIn to resume 
            // this state machine's execution when it finishes
            userRemoteDataSource.logUserIn(userId!!, password!!, continuation)
        }
        1 -> {
            // Checks for failures
            throwOnFailure(continuation.result)
            // Gets the result of the previous state
            continuation.user = continuation.result as User
            // Next time this continuation is called, it should go to state 2
            continuation.label = 2
            // The continuation object is passed to logUserIn to resume 
            // this state machine's execution when it finishes
            userLocalDataSource.logUserIn(continuation.user, continuation)
        }
        2 -> {
            // Checks for failures
            throwOnFailure(continuation.result)
            // Gets the result of the previous state
            continuation.userDb = continuation.result as UserDb
            // Resumes the execution of the function that called this one
            continuation.cont.resume(continuation.userDb)
        }
        else -> throw IllegalStateException(/* ... */)
    }
}

Компилятор Kotlin преобразовывает каждую suspend функцию в машину состояний, с использованием обратных вызовов.

Зная как компилятор работает “под капотом”, вы лучше понимаете:

почему suspend функция возвращает результат только, когда завершится вся работа, которую она начала;
каким образом код приостанавливается не блокируя потоки (вся информация, о том что нужно выполнить при возобновлении работы, хранится в объекте Continuation).

Android, Kotlin Flow во ViewModel - все сложно.

2021-09-12T12:02:00+00:00

Перевод статьи Kotlin’s Flow in ViewModels: it’s complicated.

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

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

Изменения конфигурации происходят в случаях:

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

Повышаем эффективность

Для улучшения пользовательского опыта, эффективная загрузка данных во Fragment и Activity должна учитывать следующие правила:

Кеширование: актуальные загруженные данные, должны быть доставлены немедленно и не загружаться повторно. В частности, когда существующий Fragment или Activity становятся видимыми снова или Activity пересоздается после изменения конфигурации.
Избегать фоновую работу: когда Activity или Fragment скрываются (состояние изменяется со STARTED на STOPPED), любая работа по загрузке внешних данных должна вставать на паузу или отменяться для экономии ресурсов. Это особенно важно для бесконeчных потоков данных, как например геолокация или периодическое обновление каких-либо данных.
Работа не прерывается при изменении конфигурации: это исключение из правила #2, Во время смены конфигурации, текущая Activity заменяется новым экземпляром с сохранением состояния, поэтому отменять текущую работу в старом экземпляре Activity и перезапускать работу при создании нового экземпляра Activiti было бы контр продуктивно.

Современный подход: ViewModel и LiveData

В 2017 Google зарелизила первый набор библиотек Architecture Components, там появились ViewModel и LiveData компоненты, которые помогают разработчикам эффективно работать с данными, поддерживая все 3 правила выше.

ViewModel, сохраняет данные при изменении конфигурации, используется для достижения правил #1 и #3: операции загрузки выполняются непрерывно во время изменения конфигурации, полученные данные могут кешироваться и совместно использоваться одним, или несколькими Fragment или Activity.

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

Опытный разработчик, как правило уже знаком со всем этим. Но важно вспомнить все возможности, чтобы сравнить их с Flow.

LiveData + Coroutines

LiveData довольна ограничена по сравнению с реактивными решениями (например RxJava):

передает и берет данные только на главном потоке (main thread). Интересно, что оператор map выполняет трансформацию объектов на главном потоке и не может использоваться на I/O потоках или для тяжелых вычислений на CPU. Для этого используется оператор switchMap совместно с ручным запуском асинхронной операции в нужном потоке, даже если в основной поток надо отправить единственное значение.
есть только 3 оператора преобразования для LiveData: map(), switchMap() и distinctUntilChanged(). Если вам нужно больше, вы должны сами это сделать, используя MediatorLiveData.

Чтобы преодолеть эти ограничения, библиотеки Jetpack дают специальные “мосты” из LiveData для других технологий, таких как RxJava или Kotlin корутины.

Самый простой и наиболее элегантный из них, по мнению автора, это LiveData coroutine builder, подключается через androidx.lifecycle:lifecycle-livedata-ktx Gradle зависимость. Этот функционал похож на flow {} builder function из библиотеки Kotlin Coroutines и позволяет грамотно обернуть корутину в экземпляр LiveData:

val result: LiveData<Result> = liveData {
    val data = someSuspendingFunction()
    emit(data)
}

Вы можете использовать все силу корутин, их контекстов для написания асинхронного кода в синхронной манере без колбеков, автоматически переключаясь между нужными потоками;
Новые значения отправляются наблюдателям LiveData в главном потоке через suspending методы emit() или emitSource() из корутины;
Корутина использует специальную область видимости (scope) и жизненный цикл привязанный к экземпляру LiveData. Когда LiveData становится неактивной (это значит, что больше нет наблюдателей в состоянии STARTED), то корутина будет автоматически отменена, работает правило #2;
В реальности отмена корутины будет задержана на 5 секунд после того как LiveData станет неактивной для правильной обработки смены конфигурации: если новая Activity немедленно заменит старую и LiveData станет активной до срабатывания задержки, то отмена корутины не будет и цена перезапуска будет нулевой (правило #3);
если пользователь вернется назад на экран и LiveData станет активной, то корутина автоматически перезапустится, но только если она была отменена до завершения. Как только корутина завершится, она больше не будет перезапускаться, те же данные не будут загружаться дважды, если входные параметры не изменились (правило #1).

Вывод: используйте LiveData coroutines builder, это дает простой код и лучшее поведение по умолчанию.

А что если, репозиторий возвращает поток значений в форме Flow (вместо suspend функций с единственным значением)? В этом случае также возможно сконвертировать поток в LiveData и использовать все преимущества перечисленные выше, используя asLiveData() функцию-расширение.

val result: LiveData<Result> = someFunctionReturningFlow().asLiveData()

Внутри asLiveData() также использует LiveData coroutines builder для создания простой корутины обрабатывающий Flow пока LiveData активна:

fun <T> Flow<T>.asLiveData(): LiveData<T> = liveData {
    collect {
        emit(it)
    }
}

Но давайте остановимся ненадолго – что такое Flow и можно ли им полностью заменить LiveData?

Введение в Kotlin Flow

Flow это класс из библиотеки Kotlin Coroutines представленной в 2019 году, класс является потоком значений, вычисляемый асинхронно. Концептуально похож на RxJava Observable, но основан на корутинах и имеет более простой API.

Изначально были доступны только холодные потоки (cold flows): потоки без состояний, которые создаются по требованию каждый раз, когда наблюдатель начинает собирать значения в области видимости (scope) корутины. Каждый наблюдатель получает собственную последовательность значений, они не общие.

Позже были добавлены новые горячие потоки подтипы Flow: SharedFlow и StateFlow. Они были выпущены со стабильной реализацией API в версии библиотеки корутин #1.4.0.

SharedFlow публикует данные, которые распространяются всем слушателям. Класс может управлять дополнительным кешем и/или буфером и фактически заменяет все варианты устаревшего BroadcastChannel API.

StateFlow специально оптимизированный подкласс SharedFlow, который хранит и воспроизводит только последнее значение. Что-то знакомое, да?

StateFlow и LiveData много общего:

Эти классы наблюдаемые (observable)
Они хранят и распространяют последнее значение любому количеству наблюдателей
Они заставляют перехватывать ошибки на ранней стадии: необработанное исключение (Exception) в колбеке LiveData останавливает приложение. Не пойманное исключение в горячем Flow потоке завершает поток без возможности перезапустить его, даже если использовать оператор .catch().

Но есть и важные отличия:

MutableStateFlow требует начального значения, в отличие от MutableLiveData. Замечание: MutableSharedFlow(replay = 1) может эмулировать MutableStateFlow без начального значения, но данная реализация менее эффективна.
StateFlow всегда фильтрует повторяющиеся значения с помощью сравнения Any.equals(), LiveData так не делает, для этого следует подключить оператор distinctUntilChanged() (замечание: SharedFlow не имеет такого поведения).
StateFlow не учитывает жизненный цикл (not lifecycle-aware). Однако, Flow может быть использовано в корутине с учетом жизненного цикла, это требует некоторого кода для настройки без использования LiveData (детали ниже).
LiveData использует “версионность”, чтобы управлять отправкой значений наблюдателям. При помощи этого наблюдатель не получит дважды одного и того же значения при переходе обратно в состояние STARTED. StateFlow не использует “версионность”. Каждый раз, когда корутина собирает данные Flow, она рассматривается как новый наблюдатель и всегда будет получать сначала последнее значение. Из-за этого может быть дублирование работы, как мы увидим на следующем примере.

Наблюдение за LiveData против сбора данных в Flow

Организовать наблюдение за экземпляром LiveData довольно просто:

viewModel.results.observe(viewLifecycleOwner) { data ->
    displayResult(data)
}

Эта операция однократная и дальше LiveData берет на себя синхронизацию потока данных с жизненным циклом наблюдателей.

Аналогичная операция для Flow называется сбором (collecting) и сбор должен выполняться в корутине. Из-за того, что Flow не знает ничего о жизненном цикле, ответственность за жизненный цикл возлагают на корутину, работающую с Flow.

Чтобы создать корутину для работы с Flow, учитывающую жизненный цикл Activity/Fragment (запускать работу с данными при состоянии STARTED и автоматически отменять эту работу при уничтожении):

viewLifecycleOwner.lifecycleScope.launchWhenStarted {
    viewModel.result.collect { data ->
        displayResult(data)
    }
}

Но здесь есть серьезное ограничение: код будет работать правильно только с “холодными” потоками, без поддержки каналом или буфером. Такой Flow управляется только собирающей его корутиной: когда Activity/Fragment перейдет в состояние STOPPPED, корутина приостановится, производитель Flow также приостановится с ней, и больше ничего не произойдет пока корутина не возобновится.

Однако, есть и другие виды Flow:

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

В этих случаях, основной производитель Flow будет оставаться активным даже когда корутина будет приостановлена, сохраняя (в буфер) новые результаты в фоновом режиме. Ресурсы расходуются впустую, правило #2 нарушается.

Нужно создать более безопасный способ сборка Flow любого типа. Корутина работающая с потоком данных, должна быть отменена когда Activity/Fragment становится невидимой и перезапущена снова, так же как это делает LiveData-Coroutine-Builder. Для этого был представлен новый API в lifecycle:lifecycle-runtime-ktx:2.4.0 (остается в статусе alpha на момент написания статьи, на момент перевода - перешел в beta).

viewLifecycleOwner.lifecycleScope.launch {
    viewLifecycleOwner.repeatOnLifecycle(Lifecycle.State.STARTED) {
        viewModel.result.collect { data ->
            displayResult(data)
        }
    }
}

Или аналогично:

viewLifecycleOwner.lifecycleScope.launch {
    viewModel.result
        .flowWithLifecycle(viewLifecycleOwner.lifecycle, Lifecycle.State.STARTED)
        .collect { data ->
            displayResult(data)
        }
}

Как видно, эффективно и безопасно работать с данными в Actvivity или Fragment проще с помощью LiveData.

Можно посмотреть дополнительную информацию о новом API в статье “A safer way to collect flows from Android UIs. from Manuel Vivo.

Заменяем LiveData на StateFlow во ViewModel

Давайте-ка вернемся к ViewModel. Мы убедились, что это простой и эффективный способ работы с данными в асинхронном режиме:

val result: LiveData<Result> = liveData {
    val data = someSuspendingFunction()
    emit(data)
}

Как мы можем добиться того же самого, используя StateFlow вместо LiveData? Jose Alcérreca написал внушительное руководство для ответа на этот вопрос. Вкратце, для случая выше, код будет выглядеть так:

val result: Flow<Result> = flow {
    val data = someSuspendingFunction()
    emit(data)
}.stateIn(
    scope = viewModelScope,
    started = SharingStarted.WhileSubscribed(5000L),
    initialValue = Result.Loading
)

Оператор stateIn() трансформирует наш холодный Flow в горячий, способный делиться одним и тем же результатом между разными наблюдателями. Благодаря SharingStarted.WhileSubscribed(5000L), горячий поток запускается лениво при подписке первого наблюдателя и отменяется через 5 секунд, когда последний наблюдатель отпишется, что позволяет избегать лишней работы в фоновом режиме и при этом сохраняется работа при смене конфигурации. Кроме того, как только исходящий поток данных достигнет конца, он не будет перезапущен автоматически, этим мы избегаем двойной работы.

Похоже, что мы сумели выполнить 3 наших правила и воспроизвести почти такое же поведение как у LiveData с использованием более сложного кода.

Все же еще остается небольшая, но важная разница: каждый раз когда Activity/Fragment становится видимым снова, начинается новый сбор потока и StateFlow всегда будет отправлять последний результат наблюдателю немедленно. Даже если этот же результат был уже доставлен в тот же самый Activity/Fragment во время последнего сбора данных. Потому что StateFlow не поддерживает версионность (в отличие от LiveData) и каждый новый сбор потока данных - это новый подписчик.

Это проблематично? Для простых случаев нет, Activity или Fragment могут сделать дополнительную проверку, чтобы не делать лишнее обновление UI, если данные не изменились.

viewLifecycleOwner.lifecycleScope.launch {
    viewModel.result
        .flowWithLifecycle(viewLifecycleOwner.lifecycle, Lifecycle.State.STARTED)
        .distinctUntilChanged()
        .collect { data ->
            displayResult(data)
        }
}

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

Использование StateFlow как триггер во ViewModel

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

MutableLiveData для этого работает очень хорошо:

class MyViewModel(repository: MyRepository) : ViewModel() {
    private val trigger = MutableLiveData<String>()

    fun setQuery(query: String) {
        trigger.value = query
    }

    val results: LiveData<SearchResult>
            = trigger.switchMap { query ->
        liveData {
            emit(repository.search(query))
        }
    }
}

При обновлении, оператор switchMap() подключает наблюдателей к новому источнику LiveData, заменяя старый. И так как в примере выше, используется LiveData coroutine builder, старая LiveData автоматически отменит связанную с ним корутину через 5 секунд после отключения от своих наблюдателей. Работа с устаревшими данными прекращается с небольшой задержкой.
Так как в LiveData есть версионность, MutableLiveData триггер отправит новое значение только один раз оператору switchMap(), как только появится хотя бы один активный наблюдатель. Позже, если наблюдатели становятся неактивными и активными снова, работа источника данных LiveData просто возобновится с последними данными, где она остановилась.

Этот код достаточно прост и соблюдает все правила по эффективности выше.

Давайте посмотрим, можно ли реализовать ту же самую логику с классом MutableStateFlow вместо MutableLiveData.

Наивный подход

class MyViewModel(repository: MyRepository) : ViewModel() {
    private val trigger = MutableStateFlow("")

    fun setQuery(query: String) {
        trigger.value = query
    }

    val results: Flow<SearchResult> = trigger.mapLatest { query ->
        repository.search(query)
    }.stateIn(
        scope = viewModelScope,
        started = SharingStarted.WhileSubscribed(5000L),
        initialValue = SearchResult.EMPTY
    )
}

API MutableLiveData и MutableLiveData выглядят очень похоже, код триггера выглядит почти одинаково. Самое большое различие это использование mapLatest, это эквивалент функции switchMap() в LiveData для возвращения единственного значения (для возвращения нескольких значений, надо использовать flatMapLatest).

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

Вроде выглядит неплохо. Однако здесь всплывает основная проблема: так как StateFlow не поддерживает версионность, триггер отправит повторно последнее значение, когда Flow перезапустится. Это случается каждый раз, когда Activity/Frgament становится видимым опять, после того, как был невидимым более 5 секунд.

Триггер выдает значение повторно, mapLatest() снова запускается, еще раз дергается метод в репозитории с теми же аргументами, хотя результат уже был получен и обработан. Правило #1 не работает: актуальные данные не должны загружаться повторно.

Чиним повторную отправку последнего сообщения

Вопросы приходящие на ум: должны ли мы предотвращать повторную отправку и как это сделать? StateFlow уже позаботился об этом внутри коллекции flow и оператор distinctUntilChanged() делает то же самое для других типов flow. При этом нет стандартного оператора для отмены повторной отправки среди множества коллекций одного и того же flow, потому что flow коллекции должны быть самодостаточные. Это главная разница с LiveData.

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

// Don't do this at home (or at work)
fun <T> Flow<T>.rememberLatest(): Flow<T> {
    var latest: Any? = NULL
    return flow {
        collectIndexed { index, value ->
            if (index != 0 || value !== latest) {
                emit(value)
                latest = value
            }
        }
    }
}

Примечание: внимательный читатель может заметить, что такое же поведение достигается за счет замены MutableStateFlow с Channel(capacity = CONFLATED) и затем превратиь его в Flow с использованием receiveAsFlow(). Сhannel никогда не передают значение повторно.

К сожалению, логика в коде выше несовершенна и перестанет работать, как задумано, когда трансформация flow будет отменена до завершения.

Код предполагает, что после возврата emit(value), значение было обработано и не должно быть выдано снова, если сбор flow перезапустится, но это так, только при использовании не буферизированных Flow операторов. Операторы, подобные mapLatest(), буферизированные и в этом случае emit(value) вернется немедленно, при этом преобразование выполняется асинхронно. Это значит, что нет способа узнать, когда значение было обработано flow. Если сбор flow отменяется в середине асинхронного преобразования, нам все равно придется повторно сделать emit последнего значения, когда сбор flow возобновится, чтобы возобновить преобразование, иначе значение будет потеряно.

TL;DR Использование StateFlow в качестве триггера в ViewModel приводит к дублирующейся работе каждый раз когда Activity/Fragment становится видимой повторно и здесь нет простого пути избежать такого поведения.

Вот почему LiveData предпочтительнее StateFlow при использовании как триггер во ViewModel. Эти различия не упоминаются в Codelab от Google - Advanced coroutines with Kotlin Flow, там подразумевается, что реализация на Flow ведет себя так же как на LiveData. Но это не так.

Выводы

Мои рекомендации на основании примеров выше:

Продолжайте использовать LiveData в вашем Android-UI слое и ViewModels, особенно в качестве триггера. Используйте это везде, для передачи данных в Activity/Fragment: код будет простым и эффективным;
LiveData coroutine builder ваш друг и может заменить Flows во ViewModels в большинстве случаев;
Вы можете использовать мощь Flow операторов при необходимости, конвертируя Flows в LiveData;
Flow лучше подходит, чем LiveData, для других слоев приложения, таких как - репозитории, источники данных и т.д., они не завязаны на платформенные особенности Android и их будет легче тестировать.

Теперь вы знаете все компромиcсы при переходе от LiveData к подходу “полностью на Flow” в вашем Android-UI слое.

Android, жизненый цикл Jetpack компонентов.

2021-09-10T12:02:00+00:00

Перевод статьи Lifecycle-Aware Components Using Android Jetpack.

используется: Kotlin 1.4, Android 10.0, Android Studio 4.2

Android Jetpack - коллекция библиотек для разработчиков, которая улучшает код, уменьшает повторяющийся код и работает единообразно в различных версиях Android. Архитектурные компоненты Android Jetpack дают инструменты для создания компонентов в приложении с учетом жизненного цикла Activity или Fragment.

В этой статье, вы создадите компонент, учитывающий жизненный цикл (lifecycle-aware компонент), в приложении AwarenessFood. Компонент будет обрабатывать изменения сетевого подключения. Вы также создадите lifecycle owner для обновления состояние сети в Activity.

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

В статье вы изучите:

Жизненные циклы в Android компонентах
Компоненты учитывающие жизненный цикл (Lifecycle-aware components)
Наблюдателей жизненного цикла (Lifecycle observers)
События и состояния
Владельцев жизненного цикла (Lifecycle owners)
Как тестировать Lifecycle-aware компоненты
Компонент LiveData

Статья предполагает, что вы знакомы с основами разработки под Android. Если это не так, посмотрите руководство для начинающих в Android.

Начало

Загрузите материал с оригинальной статьи (кнопка Download вверху страницы здесь). Откройте Android Studio версии 4.2.1 или выше и импортируйте проект.

Ниже общая информация, что делает каждый пакет в проекте:

analytics классы для трекинга событий в приложении
data классы модели
di поддержка зависимостей
monitor содержит единственный класс, который смотрит за состоянием подключения к сети
network классы для доступа к внешним API
repositories классы для доступа к постоянному хранилищу
viewmodels бизнес логика
view экраны

Регистрация в spoonacular API

AwarenessFood приложение получает рецепты через spoonacular API. Вам нужно зарегистрироваться там, чтобы приложение работало правильно.

Заходим на сайт spoonacular.com и создаем новый аккаунт. После подтверждения аккаунта, входим в личный кабинет и ищем там API ключ. Копируем его, открываем файл RecipesModule.kt внутри пакета di и заменяем ключ в следующей строке:

private const val API_KEY = "YOUR_API_KEY_HERE"

Компилируем и запускаем. Должен появиться экран со случайным рецептом, похожий на такой:

Жмем на кнопку Reload, чтобы загрузить другой случайный рецепт. Если отключить интернет на устройстве и попробовать получить новый рецепт, то появится SnackBar с ошибкой и кнопкой повторить, как на изображении ниже:

Чтобы перейти на экран деталей, жмем в меню More пункт Food Trivia. Вы добавите этот функционал позже. Сейчас это просто экран с кнопкой:

На этом настройка проекта закончена. Сейчас вы готовы познакомиться с компонентами, учитывающие жизненный цикл (lifecycle-aware).

Жизненные циклы в Android

Важная базовая вещь для Android разработчика - это понимание, как работает жизненный цикл Activity и Fragment. Жизненный цикл представляет собой серию вызовов в определенном порядке при изменении состояния Activity или Fragment.

Жизненный цикл – необходимая концепция, потому что нужно понимать, что делать в определенных состояниях Activity и Fragment. Например, настройка layout (макета) происходит в Activity.onCreate(). Во Fragment за настройку layout отвечает метод Fragment.onCreateView(). Другой пример - включение чтения геолокации в методе onStart().

Для освобождения ресурсов, чтение геолокации должно быть отключено в onStop(), здесь же освобождаются и другие ресуры и компоненты. Важный момент: не все lifecycle вызовы обязательно выполняются каждый раз. К примеру, операционная система может вызывать, а может и нет метод onDestory().

Жизненный цикл Activity:

Для тех, кто хочет узнать побольше о жизненном цикле Activity, взгляните на статью Introduction to Android Activities With Kotlin.

Жизненный цикл Fragment:

Подробная статья о жизненном цикле Frament - Android Fragments Tutorial: An Introduction With Kotlin.

Реагируем на изменения жизненного цикла

В большинстве приложений есть несколько компонентов, которым надо реагировать на события жизненного цикла Activity или Fragment. Вам нужно инициализировать или регистрировать их в методе onStart() и освобождать ресурсы в методе onStop().

При таком подходе, ваш код может стать запутанным и подверженным ошибкам. Код внутри методов onStart() и onStop() будет нарастать бесконечно. При этом, легко забыть отписаться от компонента или вызвать метод компонента в неподходящем событии жизненного цикла, что может привести к багам, утечкам памяти и падениям приложения.

Некоторые из этих проблем есть прямо сейчас в приложении. Откройте файл NetworkMonitor.kt в проекте. Этот класс слушает состояние сети и уведомляет Activity об этом.

Примечание: Подробная информация о мониторинге сетевого соединения находится здесь - Read Network State.

Экземпляр NetworkMonitor должен быть доступен с момента инициализации Activity. Откройте MainActivity.kt и метод onCreate(), где монитор сети инициализируется вызовом networkMonitor.init().

Затем NetworkMonitor регистрирует колбек в методе onStart() через вызов networkMonitor.registerNetworkCallback(). Наконец, экземпляр Activity отписывается от колбека в методе onStop, вызывая networkMonitor.unregisterNetworkCallback().

Инициализация компонента, подписка на события через колбек и отписка от событий добавляет большое количество шаблонного кода в Activity. Кроме того, необходимо использовать только onStart и onStop для вызова методов NetworkMonitor.

В MainActivity используется только один компонент, который зависит от жизненного цикла Activity. В более крупных и сложных проектах таких компонентов гораздо больше и это может привести к полному беспорядку.

Используем компоненты жизненного цикла (Lifecycle-Aware)

NetworkMonitor выполняет различные действия, зависящие от состояния жизненного цикла Activity. Другими словами, NetworkMonitor должен быть компонентом учитывающим жизненный цикл (lifecycle-aware компонент) и реагировать на изменения в жизненном цикле своего родителя – в нашем случае это MainActivity.

Android Jetpack предоставляет классы и интерфейсы для создания lifecycle-aware компонентов. Используя их, вы можете улучшить работу NetworkMonitor. Он будет работать автоматически с учетом текущего состояния жизненного цикла родительской Activity.

Владелец жизненного цикла (lifecycle owner) – это компонент имеющий жизненный цикл, такой как Activity или Fragment. Владелец жизненного цикла должен знать все компоненты, которые будут слушать события жизненного цикла. Паттерн “Наблюдатель” считается лучшим подходом для решения такой задачи.

Создание наблюдателя жизненного цикла (lifecycle observer)

Наблюдатель жизненного цикла компонент, который способен слушать и реагировать на состояния жизненного цикла своего родителя. У Jetpack есть специальный интерфейс для этого – LifecycleObserver.

Ну что, настало время улучшить наш NetworkMonitor. Откройте NetworkMonitor.kt и добавьте к классу поддержку интерфейса LifecycleObserver:

class NetworkMonitor 
@Inject constructor(private val context: Context) : LifecycleObserver {
 // Code to observe changes in the network connection.
}

Вот и все, теперь это lifecycle наблюдатель. Вы только что сделали первый шаг по превращению NetworkMonitor в lifecycle-aware компонент.

События и состояния жизненного цикла

Класс Lifecycle знает состояние (state) жизненного цикла родителя и передает его любому прослушивающему LifecycleObserver.

Lifecycle использует два перечисления для обмена данными о жизненном цикле: Event и State.

Events

Event представляет события жизненного цикла, которые отправляет операционная система:

ON_CREATE
ON_START
ON_RESUME
ON_PAUSE
ON_STOP
ON_DESTROY
ON_ANY

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

Реакция на события жизненного цикла

Сейчас NetworkMonitor – это LifecycleObserver, но он пока не реагирует на жизненный цикл. Нужно добавить аннотацию @OnLifecycleEvent к методу, чтобы он начал реагировать на конкретное событие.

Добавьте @OnLifecycleEvent к нужным методам, как указано ниже:

@OnLifecycleEvent(Lifecycle.Event.ON_CREATE)
fun init() {
// ...
}

@OnLifecycleEvent(Lifecycle.Event.ON_START)
fun registerNetworkCallback() {
// ...
}

@OnLifecycleEvent(Lifecycle.Event.ON_STOP)
fun unregisterNetworkCallback() {
// ...
}

В этом случае, метод init() реагирует на ON_CREATE событие, registerNetworkCallback() на ON_START и на событие ON_STOP вызывается unregisterNetworkCallback().

Итак, NetworkMonitor теперь получает изменения жизненного цикла, сейчас нужно немного подчистить код. Следующий код больше не нужен в MainActivity.kt, потому что эти действия NetworkMonitor выполняет сам:

override fun onCreate(savedInstanceState: Bundle?) {
  // ...
  // 1.Network Monitor initialization.
  networkMonitor.init()
  // ...
}

// 2. Register network callback.
override fun onStart() {
  super.onStart()
  networkMonitor.registerNetworkCallback()
}

// 3. Unregister network callback.
override fun onStop() {
  super.onStop()
  networkMonitor.unregisterNetworkCallback()
}

Полностью удаляйте onStart() и onStop(). Кроме того надо удалить networkMonitor.init() из метода onCreate().

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

Состояния (States)

State хранит текущее состояние владельца жизненного цикла. Возможные значения:

INITIALIZED
CREATED
STARTED
RESUMED
DESTROYED

Состояния жизненного цикла сигнализируют, что конкретное событие случилось.

В качестве примера, представим, что мы запускаем длительную инициализацию компонента в событии ON_START и Activity (или Fragment) уничтожаются до того, как инициализация закончится. В этом случае компонент не должен выполнять никаких действий по событию ON_STOP, так как он не был инициализирован.

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

Эти состояния возникают при:

INITIALIZED: Когда Activity или Fragment уже созданы, но onCreate() еще не вызван. Это первоначальное состояние жизненного цикла.
CREATED: После ON_CREATE и после ON_STOP.
STARTED: После ON_START and После ON_PAUSE.
RESUMED: только после ON_RESUME.
DESTROYED: после ON_DESTROY, но прямо перед вызовом onDestroy(). Как только состояние становится DESTROYED, Activity или Fragment больше не будут посылать события.

Используем состояния (State) жизненного цикла

Иногда компоненты должны выполнять код, если их родитель находится, по крайней мере, в определенном состоянии. Нужно быть уверенным, что NetworkMonitor выполняет registerNetworkCallback() в нужный момент жизненного цикла.

Добавьте Lifecycle аргумент в конструктор NetworkMonitor:

private val lifecycle: Lifecycle

С ним у NetworkMonitor будет доступ к состоянию жизненного цикла родителя.

После этого добавьте в код registerNetworkCallback() условие:

fun registerNetworkCallback() {
  if (lifecycle.currentState.isAtLeast(Lifecycle.State.STARTED)) {
    // ...
  }
}

С этим условием NetworkMonitor будет запускать мониторинг состояния сети только, если состояние жизненного цикла не менее, чем STARTED. Это достаточно удобно, потому что жизненный цикл может измениться до завершения кода в компоненте. Зная состояние родителя можно избежать крешей, утечек памяти и гонок состояния в компоненте.

Итак, откройте MainActivity.kt и сделайте изменения для NetworkMonitor:

networkMonitor = NetworkMonitor(this, lifecycle)

У NetworkMonitor сейчас есть доступ к родительскому жизненному циклу и прослушивание сети запускается только когда Activity находится в нужном состоянии.

Подписка на события жизненного цикла

Чтобы NetworkMonitor действительно начал реагировать на изменения, его родитель должен зарегистрировать NetworkMonitor как слушателя событий. В MainActivity.kt добавьте следующую линию в методе onCreate() после инициализации компонента:

 lifecycle.addObserver(networkMonitor)

Теперь владелец жизненного цикла будет уведомлять NetworkMonitor об изменениях. Таким же образом можно добавить другие компоненты на прослушивание событий жизненного цикла.

Это отличное улучшение. С помощью одной строчки кода компонент будет получать события жизненного цикла от родителя. Больше не надо писать шаблонный код в Activity или Fragment. Кроме того, компонент содержит весь код инициализации и конфигурации, что делает его самодостаточном и тестируемым.

Соберите и запустите приложение снова. После загрузки рецептов включите “Самолетный режим”. Вы увидите ошибку сети в SnackBar, так же как и раньше:

Однако внутреннняя реализация была значительно улучшена.

Кто владеет жизненным циклом?

Все выглядит хорошо, но… кто владеет жизненным циклом? Почему Activity сама владеет жизненным циклом в этом примере? Существуют ли другие владельцы?

Владелец жизненного цикла (lifecycle owner) – компонент реализующий интерфейс LifecycleOwner. В нем есть единственный метод, который необходимо реализовать: Lifecycle.getLifecycle(). Выходит, что любой класс поддерживающий этот интерфейс может быть владельцем жизненного цикла.

Android имеет встроенные компоненты с поддержкой жизненного цикла. Для Activity это ComponentActivity (является базовым классом для AppCompatActivity и реализует интерфейс LifecycleOwner).

Однако, есть и другие классы с поддержкой LifecycleOwner. Например, Fragment это LifecycleOwner. Это значит, что можно переместить код в любой Fragment, если это надо и это будет работать точно так же, как и в MainActivity.

Жизненный цикл Fragment может быть значительно длиннее, чем цикл визуальных компонентов (UI), которых он содержит. Если наблюдатель взаимодействует с UI во Fragment, это может привести к проблемам, поскольку наблюдатель может изменить UI до инициализации или после уничтожения.

Это причина почему есть viewLifecycleOwner в Fragment. Вы можете использовать viewLifecycleOwner после вызова onCreateView() и перед onDestroyView(). Как только жизненный цикл будет уничтожен, он больше не будет отправлять события.

Распространенный случай использования viewLifecycleOwner это работа с LiveData в Fragment. Откройте FoodTriviaFragment.kt и добавьте в методе onViewCreated(), до viewModel.getRandomFoodTrivia(), следующий код:

viewModel.foodTriviaState.observe(viewLifecycleOwner, Observer { 
  handleFoodTriviaApiState(it)
})

Также надо будет добавить импорт класса import androidx.lifecycle.Observer.

Используя этот код, FoodTriviaFragment будет реагировать на события от foodTriviaState (является LiveData). Так как Fragment является владельцем жизненного цикла (viewLifecycleOwner), наблюдатель будет получать обновления данных только, когда Fragment находится в активном состоянии.

Время сделать сборку и запустить приложение. Нажмите More в меню и выберите Food Trivia. Теперь можно получить несколько забавных и интересных Food Trivia в вашем приложении.

Использование ProcessLifecycleOwner

В некоторых случаях компоненту надо реагировать на изменения жизненного цикла самого приложения. К примеру, отследить когда приложение уходит в фоновый режим и возвращается на передний план. Для таких ситуаций в Jetpack есть ProcessLifecycleOwner, который естественно реализует интерфейс LifecycleOwner.

Этот класс представляет жизненный цикл всего процесса приложения. Событие ON_CREATE посылается только один раз, когда приложение стартует. При этом событие ON_DESTROY не будет посылаться вообще.

ProcessLifecycleOwner отправляет события ON_START и ON_RESUME, когда первая Activity проходит через эти состояния. Наконец, ProcessLifecycleOwner отправляет события ON_PAUSE и ON_STOP после того, последняя видимая Activity приложения проходит через соответствующие состояния.

Важно знать, что эти два последних события произойдут после определенной задержки. ProcessLifecycleOwner должен быть уверен в причине этих изменений. Он отправляет события ON_PAUSE и ON_STOP только если приложение перешло в фоновый режим, а не из-за изменения конфигурации.

При использовании такого владельца жизненного цикла, компонент должен также поддерживать интерфейс LifecycleObserver. Откройте AppGlobalEvents.kt в пакете analytics. Видно, что это LifecycleObserver.

Класс отслеживает, когда приложение выходит на передний план или переходит в фоновый режим. Это происходит когда владелец жизненного цикла посылает события ON_START и ON_STOP.

Регистрация такого LifecycleObserver происходит немного по-другому. Откройте RecipesApplication.kt и добавьте следующий код в метод onCreate():

  ProcessLifecycleOwner.get().lifecycle.addObserver(appGlobalEvents)

Здесь мы получаем экземпляр ProcessLifecycleOwner и добавляем appGlobalEvents как слушателя событий.

Соберите и запустите приложение. После старта приложения, сверните его в фон. Если открыть LogCat и отфильтровать вывод по тегу APP_LOGGER, то вы должны увидеть сообщения:

Итак, вы увидели как Fragment, Activity и Application компоненты реализуют интерфейс LifecycleOwner. Но это еще не все. Сейчас вы узнаете, как создавать собственные классы, которые делают то же самое.

Создаем собственного владельца жизненного цикла

Как вы помните, любой класс может поддерживать интерфейс LifecycleOwner. Это значит, что можно создать кастомного владельца жизненного цикла.

Давайте создадим такого владельца, жизненный цикл которого начинается, когда смартфон теряет сетевое соединение и заканчивается при восстановлении соединения.

Откройте UnavailableConnectionLifecycleOwner.kt в пакете monitor и сделайте изменения, чтобы класс поддерживал интерфейс LifecycleOwner:

@Singleton
class UnavailableConnectionLifecycleOwner @Inject constructor() : LifecycleOwner {
// ...
}

После этого, добавьте LifecycleRegistry в UnavailableConnectionLifecycleOwner:

private val lifecycleRegistry: LifecycleRegistry = LifecycleRegistry(this)

override fun getLifecycle() = lifecycleRegistry

Класс LifecycleRegistry это реализация Lifecycle, который может работать с несколькими наблюдателями и уведомлять их о любых изменениях в жизненном цикле.

Добавляем события

Для уведомления о событиях жизненного цикла можно использовать метод handleLifecycleEvent(). Давайте добавим пару методов в наш класс:

fun onConnectionLost() {
  lifecycleRegistry.handleLifecycleEvent(Lifecycle.Event.ON_START)
}

fun onConnectionAvailable() {
  lifecycleRegistry.handleLifecycleEvent(Lifecycle.Event.ON_STOP)
}

В случае, когда смартфон потеряет сетевое соединение, lifecycleRegistry пошлет событие ON_START всем наблюдателям. Когда соединение снова появится, lifecycleRegistry отправит ON_STOP.

Наконец, добавьте следующий код:

fun addObserver(lifecycleObserver: LifecycleObserver) {
  lifecycleRegistry.addObserver(lifecycleObserver)
}

addObserver() регистрирует слушателя жизненного цикла UnavailableConnectionLifecycleOwner.

Реакция на события

Теперь откройте MainActivity.kt и добавьте такую строчку кода:

unavailableConnectionLifecycleOwner.addObserver(networkObserver)

После этого networkObserver будет реагировать на события unavailableConnectionLifecycleOwner. NetworkObserver покажет SnackBar, когда устройство потеряет сеть и скроет SnackBar при восстановлении сети.

И наконец, замените handleNetworkState():

private fun handleNetworkState(networkState: NetworkState?) {
  when (networkState) {
    NetworkState.Unavailable -> unavailableConnectionLifecycleOwner.onConnectionLost()
    NetworkState.Available -> unavailableConnectionLifecycleOwner.onConnectionAvailable()
  }
}

Этот код запускает события unavailableConnectionLifecycleOwner.

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

В следующей секции, вы узнаете как тестировать компоненты жизненного цикла.

Тестирование компонентов жизненного цикла

Использование компонента жизненного цикла в нашем NetworkMonitor дает еще одно преимущество - мы можем тестировать код со всеми связанными событиями жизненного цикла.

Эти тесты будут проверять, что вызывается нужный метод в NetworkMonitor в соответствии с состоянием владельца жизненного цикла. Чтобы создать тест, нужно пройти те же шаги, что и при создании кастомного владельца жизненного цикла.

Настройка тестов

Откройте NetworkMonitorTest.kt. Для запуска теста необходимо сделать заглушки (mock) для владельца жизненного цикла и NetworkMonitor. Добавьте две заглушки в тестовый класс:

private val lifecycleOwner = mockk<LifecycleOwner>(relaxed = true)
private val networkMonitor = mockk<NetworkMonitor>(relaxed = true)

Здесь используется функционал библиотеки MockK, она позволяет имитировать реализацию класса. Аргумент relaxed говорит, что заглушки могут работать без указания их поведения.

После этого создайте переменную:

private lateinit var lifecycle: LifecycleRegistry

Этот код добавляет объект LifecycleRegistry в тест, для управления наблюдателями и рассылки им событий жизненного цикла.

И наконец, добавьте следующую строчку кода в метод setup():

lifecycle = LifecycleRegistry(lifecycleOwner)
lifecycle.addObserver(networkMonitor)

Здесь инициализируется реестр LifecycleRegistry, в него передается заглушка владельца жизненного цикла и добавляется наблюдатель NetworkMonitor, чтобы слушать события.

Добавляем тесты

Чтобы убедиться, что нужный метод вызывается в NetworkMonitor, реестр жизненного цикла должен установить правильное состояние и уведомить своих слушателей. Для этого будет использоваться метод handleLifecycleEvent().

Первый тест будет проверять, что при событии ON_CREATE вызывается метод init().

Давайте напишем тест:

@Test
fun `When dispatching On Create lifecycle event, call init()`() {
  // 1. Notify observers and set the lifecycle state.
  lifecycle.handleLifecycleEvent(Lifecycle.Event.ON_CREATE)

  // 2. Verify the execution of the correct method.
  verify { networkMonitor.init() }
}

В коде выше вы:

Сначала устанавливаете состояние ON_CREATE
После этого, проверяете, что был вызван метод init() в NetworkMonitor.

Не забудьте импортировать зависимости:

import androidx.lifecycle.Lifecycle
import io.mockk.verify
import org.junit.Test

Запускайте тест, он проходит успешно.

Теперь давайте проверим событие ON_START, оно должно вызывать метод registerNetworkCallback():

@Test
fun `When dispatching On Start lifecycle event, call registerNetworkCallback()`() {
  lifecycle.handleLifecycleEvent(Lifecycle.Event.ON_START)

  verify { networkMonitor.registerNetworkCallback() }
}

Этот код проверяет ON_START событие.

Тест должен пройти успешно.

В конце концов, создадим тест для проверки события ON_STOP и вызова метода unregisterNetworkCallback():

@Test
fun `When dispatching On Stop lifecycle event, call unregisterNetworkCallback()`() {
  // 1. Notify observers and set the lifecycle state.
  lifecycle.handleLifecycleEvent(Lifecycle.Event.ON_STOP)

  // 2. Verify the execution of the correct method.
  verify { networkMonitor.unregisterNetworkCallback() }
}

Этот код проверяет ON_STOP событие.

Запустите тест и … он падает с ошибкой Verification failed: call 1 of 1: NetworkMonitor(#2).unregisterNetworkCallback()) was not called. Это значит, что unregisterNetworkCallback() не выполнился при событии ON_STOP? Тестовый код посылает событие ON_STOP, но перед ним обязательно должно быть событие ON_START.

Добавляем событие ON_START в тест:

lifecycle.handleLifecycleEvent(Lifecycle.Event.ON_START)
lifecycle.handleLifecycleEvent(Lifecycle.Event.ON_STOP)

Теперь тест проходит успешно.

Таким образом, мы проверили все события жизненного цикла и они вызывают нужные методы в NetworkMonitor.

LiveData: компонент жизненного цикла

К этому моменту вы узнали, как создавать собственный компонент жизненного цикла. Но существуют ли такие же готовые компоненты в Android? Конечно, возможно самый известный из них это LiveData.

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

Наблюдатель в активном состоянии если его жизненный цикл в состоянии STARTED или RESUMED. Если жизненный цикл в другом состоянии, LiveData не будет уведомлять слушателей об изменениях.

Создание и присваивание переменных LiveData

Откройте MainViewModel.kt из пакета viewmodels. Добавьте там следующие переменные:

private val _loadingState = MutableLiveData<UiLoadingState>()
val loadingState: LiveData<UiLoadingState>
  get() {
    return _loadingState
  }

_loadingState это LiveData с двумя возможными значениями: Loading и NotLoading. Эти значения будут говорить UI показывать или скрывать загрузку (ProgressBar).

Каждый раз, когда LiveData переменная получает новое значение, она уведомляет своих слушателей об изменении. Для установки нового значения используйте поле value.

Давайте изменим метод getRandomRecipe():

fun getRandomRecipe() {
  _loadingState.value = UiLoadingState.Loading
  viewModelScope.launch {
    recipeRepository.getRandomRecipe().collect { result ->
      _loadingState.value = UiLoadingState.NotLoading
      _recipeState.value = result
    }
  }
}

Теперь обновление value будет отправлено всем слушателям _loadingState.

Наблюдения за изменениями LiveData

Откройте MainActivity.kt и добавьте код в метод onCreate():

viewModel.loadingState.observe(this, Observer { uiLoadingState ->
  handleLoadingState(uiLoadingState)
})

Здесь, MainActivity начнет наблюдать за обновлениями от viewModel.loadingState. Как вы видите, первый аргумент observe() это this, то есть текущий экземпляр MainActivity. Взгляните на сигнатуру метода observe(), там видно, что первый аргумент имеет тип LifecycleOwner. Это значит, что наблюдатели LiveData будут реагировать на изменения в зависимости от состояния жизненного цикла Activity. Для того чтобы открыть сигнатуру метода, нажмите Control- или Command-click.

В методе observe() есть такой код:

if (owner.getLifecycle().getCurrentState() == DESTROYED) {
  // ignore
  return;
}

Видно, если LifecycleOwner в состоянии DESTROYED и новое значение было установлено для переменной, то наблюдатель не получит обновление.

Однако, если LifecycleOwner становится активным опять, то наблюдатели получат последнее значение автоматически.

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

Поздравляю! Вы отрефакторили проект с использованием компонентов жизненного цикла.

Что посмотреть?

Официальная документация по архитектурным компонентам: Architecture Components: Official Documentation.

Изучаем Jetpack компоненты: Android Jetpack Architecture Components: Getting Started.

Дополнительные материалы по тестированию Jetpack компонентов: Testing Android Architecture Components.

Глубокое погружение в LiveData: Testing Android Architecture Components.

Android, работа с BLE - часть 4.

2020-01-25T10:03:00+00:00

Перевод статьи Making Android BLE work — part 4.

внимание: в цикле статей используется минимальная версия - Android 6

В предыдущей статье мы разобрались с операциями чтения/записи, включения/выключения нотификаций и организации очереди команд. В этой статье мы поговорим о спряжении устройств (Прим. переводчика – далее я буду использовать термин «bonding»).

Bonding

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

Тема bonding плохо описана в документации Google, полностью непонятно, как приложение должно работать с bonding. Первое на что вы обратите внимание это метод createBond(). Что интересно, в iOS такого метода нет вообще и фреймворк CoreBluetooth делает все за вас! Тогда зачем вызывать createBond()? Кажется немного странным, вам заранее надо знать, какие устройства требуют bonding, а какие нет. Протокол Bluetooth был спроектирован так, что обычно устройства явно говорят – им требуется или нет bonding. Я копнул немного глубже и поэкспериментировал. Чтобы разобраться с этим, ушло некоторое время, но в конце концов, все оказалось просто.

Принципы работы с bonding:

Пусть Android сам работает с bonding. Android сделает bonding за вас, когда устройство скажет, что нужен bonding, или во время операции чтения/записи зашифрованной характеристики. В большинстве случаев не надо вызывать createBond() самостоятельно (Прим. переводчика: мне пришлось это делать самостоятельно, из-за особенностей прошивки устройства. Кроме того, Samsung работает по-другому, чем другие вендоры);
Нельзя запускать другие операции, в процессе работы bonding. Если вы будете запускать обнаружение сервисов или читать/писать характеристики, это приведет к ошибками и сбросу соединения. Просто дождитесь пока Android выполнит bonding;
Продолжайте очередь операций после завершения bonding. Как только операция bonding завершилась, продолжайте выполнение операций из очереди;
Если вы знаете, что делаете, и это необходимо вы можете вызвать createBond() для запуска bonding с устройством самостоятельно. Но это должно быть исключением.

Что вызывает bonding?

Есть три причины, по которым запускается процесс bonding:

При соединении с устройством, оно сигнализирует, что требуется bonding, до любых других операций;
Характеристика может быть «зашифрована» для чтения или записи. При попытке прочитать или записать такую характеристику, запустится bonding. Если он пройдет удачно чтение/запись также выполнится, в случае ошибки bonding – чтение/запись выполнится с ошибкой INSUFFICIENT_AUTHENTICATION. Такая же ошибка есть в iOS.
Вы запускаете процесс bonding самостоятельно через вызов createBond(). Если этого требует ваше устройство, оно вероятно не будет совместимо с iOS, так как там нет аналогичного метода. Но формально в протоколе Bluetooth такое возможно.

Давайте обсудим каждый случай.

Bonding во время подключения

Если устройство требует bonding сразу после подключения, то при вызове колбека onConnectionStateChange состояние bonding будет BOND_BONDING. Это означает что идет процесс bonding и вы не должны ничего делать в этот момент, например вызывать discoverServices(), до тех пор пока процесс bonding не закончится! Иначе возможны неожиданные дисконнекты или ошибки обнаружения сервисов. Поэтому следует специально обрабатывать эту ситуацию в onConnectionStateChanged:

// Take action depending on the bond state
if(bondstate == BOND_NONE || bondstate == BOND_BONDED) {
    // Connected to device, now proceed to discover it's services
    ... 
} else if (bondstate == BOND_BONDING) {
    // Bonding process has already started let it complete
    Log.i(TAG, "waiting for bonding to complete");
}

Чтобы следить, как идет процесс bonding, необходимо зарегистрировать колбек BroadcastReceiver для интента ACTION_BOND_STATE_CHANGED до вызова connectGatt. Этот колбек будет вызываться несколько раз в процессе bonding.

context.registerReceiver(bondStateReceiver, 
                        new IntentFilter(ACTION_BOND_STATE_CHANGED));
private final BroadcastReceiver bondStateReceiver = new BroadcastReceiver() {
    @Override
    public void onReceive(Context context, Intent intent) {
        final String action = intent.getAction();
        final BluetoothDevice device = intent.getParcelableExtra(BluetoothDevice.EXTRA_DEVICE);

        // Ignore updates for other devices
        if (bluetoothGatt == null || !device.getAddress().equals(bluetoothGatt.getDevice().getAddress()))
            return;

        // Check if action is valid
        if(action == null) return;

        // Take action depending on new bond state
        if (action.equals(ACTION_BOND_STATE_CHANGED)) {
            final int bondState = intent.getIntExtra(EXTRA_BOND_STATE, ERROR);
            final int previousBondState = intent.getIntExtra(BluetoothDevice.EXTRA_PREVIOUS_BOND_STATE, -1);

            switch (bondState) {
                case BOND_BONDING:
                    // Bonding started
                    ...
                    break;
                case BOND_BONDED:
                    // Bonding succeeded
                    ...
                    break;
                case BOND_NONE:
                    // Oh oh
                    ...
                    break;
            }
        }
    }
};

После завершения bonding, мы запускаем обнаружение сервисов (service discovery), если они еще не обнаружены, это можно проверить:

case BOND_BONDED:
    // Bonding succeeded
    Log.d(TAG, "bonded");

    // Check if there are services
    if(bluetoothGatt.getServices().isEmpty()) {
        // No services discovered yet
        bleHandler.post(new Runnable() {
            @Override
            public void run() {
                Log.d(TAG, String.format("discovering services of '%s'", getName()));
                boolean result = bluetoothGatt.discoverServices();
                if (!result) {
                    Log.e(TAG, "discoverServices failed to start");
                }
            }
        });
    }

Вот и все, что касается особенностей bonding при подключении.

Bonding при чтении/записи зашифрованных характеристик

Если bonding стартует при чтении/записи зашифрованной характеристики, то самая первая операция чтения/записи окончится с ошибкой GATT_INSUFFICIENT_AUTHENTICATION. На версиях Android-6, 7 вы получите эту ошибку в onCharacteristicRead/onCharacteristicWrite, при этом процесс bonding уже будет запущен внутри Android. С версии Android-8 ошибки не будет и Android самостоятельно повторит операцию после завершения bonding. Получается на Android-6, 7 надо повторить операцию чтения/записи самостоятельно. Итак, вам надо поймать ошибку и сделать повтор операции после bonding.

При получении такой ошибки, не продолжайте запуск операций:

public void onCharacteristicRead(BluetoothGatt gatt, final BluetoothGattCharacteristic characteristic, int status) {
    // Perform some checks on the status field
    if (status != GATT_SUCCESS) {
        if (status == GATT_INSUFFICIENT_AUTHENTICATION ) {
            // Characteristic encrypted and needs bonding,
            // So retry operation after bonding completes
            // This only happens on Android 5/6/7
            Log.w(TAG, "read needs bonding, bonding in progress");
            return;
        } else {
            Log.e(TAG, String.format(Locale.ENGLISH,"ERROR: Read failed for characteristic: %s, status %d", characteristic.getUuid(), status));
            completedCommand();
            return;
        }
    }
...

После bonding проверяем, есть ли операция в процессе выполнения и повторяем ее:

case BOND_BONDED:
    // Bonding succeeded
    Log.d(TAG, "bonded");

    // Check if there are services
    ...
    // If bonding was triggered by a read/write, we must retry it
    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) {
        if (commandQueueBusy && !manuallyBonding) {
            bleHandler.postDelayed(new Runnable() {
                @Override
                public void run() {
                    Log.d(TAG, "retrying command after bonding");
                    retryCommand();
                }
            }, 50);
        }
    }

Запуск bonding самостоятельно

Как я говорил выше, лучше не вызывать createBond самостоятельно, хотя сделать это, конечно можно. Спросите себя, это действительно необходимо? На iOS нет эквивалента метода createBond(), если этот метод – единственный способ сделать bonding для вашего устройства, то скорее всего оно несовместимо с iOS. Это прямо указывается в документации iOS. Я перепробовал несколько десятков BLE устройств, и только в единственном случае я вызывал createBond() самостоятельно из-за исключительных обстоятельств.

При вызове createBond самостоятельно, также нельзя ничего делать, пока bonding не завершится и требуется регистрировать колбек BroadcastReceiver для отслеживания процесса. Если устройство уже сопряжено (bonding завершился), то createBond() вызовет ошибку, надо проверить состояние bonding перед вызовом.

Еще одна причина запускать createBond() самостоятельно – упростить повторное подключение. Объект BluetoothDevice можно получить при помощи MAC-адреса, если устройство закешировано или сопряжено (bonding). Таким образом вам не придется снова сканировать устройство… Может пригодиться! (Прим. переводчика: я как раз работал с таким вариантом подключения, его требовалось сделатьполностью детерминированным, разбитым на подфазы, для точного понимания что происходит.)

Удаление bonding

Как пользователь Android, я могу увидеть список сопряженных устройств в Bluetooth настройках. Там можно удалить устройство, bonding также будет удален.

Требуется некоторое время на удаление устройства.

Достаточно странно, что нет официального способа удалить bonding устройства программно. Это можно сделать, используя скрытый метод removeBond(), доступный через механизм рефлексии в Java:

try {
    Method method = device.getClass().getMethod("removeBond", (Class[]) null);
    result = (boolean) method.invoke(device, (Object[]) null);
    if (result) {
        Log.i(TAG, "Successfully removed bond");
    }
    return result;
} catch (Exception e) {
    Log.e(TAG, "ERROR: could not remove bond");
    e.printStackTrace();
    return false;
}

Потеря bonding

Большинство BLE устройств поддерживают bonding только с одним смартфоном. Типичный сценарий, когда мы теряем bonding такой:

Смартфон А делает bonding с устройством Х
Смартфон B делает bonding с устройством Х
Смартфон А переподключается к устройству Х, и теперь bonding потерян.

При реконнекте смартфон А получит состояние bonding BOND_NONE в колбеке BroadcastReceiver. Сравнивайте предыдущее состояние bonding, чтобы понять была потеря или нет:

case BOND_NONE:
    if(previousBondState == BOND_BONDING) {
       // Bonding failed
       ...
    } else {
       // Bond lost
       ...
    }
    disconnect();
    break;

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

Существует мелкий баг, о котором следует знать. При потере bonding, кажется нужна одна секунда для того, чтобы Bluetooth стек обновил свое внутреннее состояние. Если сделать реконнект сразу после потери bonding, Android может сказать, что устройство все еще сопряжено, но на самом деле это будет не так. Сделайте задержку в одну секунду перед переподключением.

Pairing попап

Прим. переводчика: не нашел толковой замены слова «pairing», «спаривание» - звучит неблагозвучно здесь.

Когда Android запускает процесс bonding, может появится всплывающее окно. Я говорю «может», потому что некоторые вендоры используют свою логику показа этого попапа (Прим. переводчика: на моем Samsung-S9, после обновления до Android-10, это попап стал появляться всегда, при коннекте любого нового устройства, до этого обновления, такого не было). На смартфонах Google (или других вендоров, где код Android в этой части не изменялся), всплывающий попап появляется только при определенный условиях.

Pairing попап появляется на переднем фоне если:

Устройство недавно было в режиме обнаружения;
Устройство было обнаружено недавно;
Устройство недавно было выбрано в «сборщике устройств»;
Экран настроек Bluetooth виден.

Значение «недавно» означает в течение последних 60 секунд. Условия выглядят непонятными, поэтому лучше посмотреть на исходный код. Если все эти условия не выполняются, то вместо попапа появится уведомление, которое большинство пользователей не замечает. Но если они заметят и нажмут на него, всплывающее окно сбивает с толку своей опцией доступа к контактам. Ужасный UI по-моему! Некоторые производители (справедливо) решили исправить такое поведение! На устройствах Samsung всплывающее окно-подтверждение (для подключений в режиме JustWorks) вообще не отображается, а всплывающие окна всегда появляются на переднем плане. При этом всплывающее окно открывается только при вводе PIN-кода или кодовой фразы. Никаких доступов к контактам и всегда передний план. Так намного лучше!

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

public void startPairingPopupHack() {
    String manufacturer = Build.MANUFACTURER;
    if(!manufacturer.equals("samsung")) {
        bluetoothAdapter.startDiscovery();

        callBackHandler.postDelayed(new Runnable() {
            @Override
            public void run() {
                Log.d(TAG, "popup hack completed");
                bluetoothAdapter.cancelDiscovery();
            }
        }, 1000);
    }
}

Важный момент здесь – вы не должны запускать никакие BLE операции пока попап на экране. Подождите ответа от пользователя.

Если учтете все эти моменты, bonding будет работать как часики!

Подведение итогов…

На этом мы завершаем цикл статей о BLE в Android (Прим. переводчика: я готовлю отдельную статью-заключение, где опишу свои подходы к работе с BLE устройствами на Android, небольшие ньюансы и решения для стабильной продолжительной работы с устройствами). Надеюсь эта информация будет полезной вам и сделает работу с BLE комфортнее. Чем больше знаешь про BLE, тем лучше работает ваше приложение. Успехов!

Не терпится поработать с BLE? Попробуйте мою библиотеку Blessed for Android. Она использует все подходы из этой серии статей и упрощает работу с BLE в вашем приложении.

Android, работа с BLE - часть 3.

2020-01-18T12:30:00+00:00

Перевод статьи Making Android BLE work — part 3.

внимание: в цикле статей используется минимальная версия - Android 6

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

Чтение и запись характеристик

Многие разработчики, которые начинают работать с BLE на Android, сталкиваются с проблемами чтения/записи BLE характеристик. На Stackoverflow полно людей, предлагающих просто использовать задержки… Большинство таких советов неверные.

Есть две основные причины проблем:

Операции чтения/записи асинхронные. Это значит, что вызов метода вернется немедленно, но результат вызова вы получите немного позже – в соответствующих колбеках. Например onCharacteristicRead() или onCharacteristicWrite().
Одновременно может быть запущена только одна операция. Нужно дождаться выполнения текущей операции, и затем, запускать следующую. В исходном коде BluetoothGatt есть блокирующая переменная, которая при запуске операции устанавливается и при вызове колбека сбрасывается. Google забыла про это упомянуть в документации… (Прим. переводчика: речь идет о mDeviceBusy и mDeviceBusyLock здесь).

Первая причина, на самом деле, не является проблемой, такова природа BLE. Асинхронное программирование это распространенная штука, используется, например, при сетевых вызовах. Однако вторая причина раздражает и требует специального подхода.

Ниже кусок кода BluetoothGatt.java с блокировкой переменной mDeviceBusy, перед чтением характеристики:

public boolean readCharacteristic(BluetoothGattCharacteristic characteristic) {
    if ((characteristic.getProperties() 
            & BluetoothGattCharacteristic.PROPERTY_READ) == 0) {
        return false;
    }

    if (VDBG) Log.d(TAG, "readCharacteristic() - uuid: " + characteristic.getUuid());
    if (mService == null || mClientIf == 0) return false;

    BluetoothGattService service = characteristic.getService();
    if (service == null) return false;

    BluetoothDevice device = service.getDevice();
    if (device == null) return false;

    synchronized (mDeviceBusy) {
        if (mDeviceBusy) return false;
        mDeviceBusy = true;
    }

    try {
        mService.readCharacteristic(mClientIf, device.getAddress(),
                characteristic.getInstanceId(), AUTHENTICATION_NONE);
    } catch (RemoteException e) {
        Log.e(TAG, "", e);
        mDeviceBusy = false;
        return false;
    }

    return true;
}

Когда приходит результат чтения/записи, переменная mDeviceBusy сбрасывается в false снова:

public void onCharacteristicRead(String address, 
                                int status, 
                                int handle, 
                                byte[] value) {
    if (VDBG) {
        Log.d(TAG, "onCharacteristicRead() - Device=" + address
                + " handle=" + handle + " Status=" + status);
    }

    if (!address.equals(mDevice.getAddress())) {
        return;
    }

    synchronized (mDeviceBusy) {
        mDeviceBusy = false;
    }
....

Используем очередь

Выполнять чтение/запись по одной операции за раз неудобно, но любое сложное приложение должно это учитывать. Решение этой проблемы - использование очереди команд. Все BLE библиотеки, которые я ранее упоминал, так или иначе реализуют очередь. Это одна из лучших практик! Идея простая – каждая команда сначала добавляется в очередь. Затем команда забирается из очереди на исполнение, после результата, команда помечается как «завершенная» и, удаляется из очереди. Запускать команды можно в любое время, но они выполняются точно в том порядке, в котором поступают в очередь. Это очень упрощает разработку под BLE. В iOS аналогично работает фреймворк CoreBluetooth (Прим. переводчика: который намного удобнее, чем реализация Bluetooth стека в Android).

Очередь создается для каждого объекта BluetoothGatt. К счастью, Android сможет обрабатывать очереди от нескольких объектов BluetoothGatt, вам не нужно об этом беспокоиться (Прим. переводчика: у меня это не сработало, я использовал глобальную очередь команд для всех устройств). Есть много способов создать очередь, мы будем использовать простую очередь Queue с Runnable для каждой команды и переменной commandQueueBusy для отслеживания работы команды:

private Queue<Runnable> commandQueue;
private boolean commandQueueBusy;

Мы добавляем новый экземпляр Runnable в очередь при выполнении команды. Ниже пример чтения характеристики (readCharacteristic):

public boolean readCharacteristic(final BluetoothGattCharacteristic characteristic) {
    if(bluetoothGatt == null) {
        Log.e(TAG, "ERROR: Gatt is 'null', ignoring read request");
        return false;
    }

    // Check if characteristic is valid
    if(characteristic == null) {
        Log.e(TAG, "ERROR: Characteristic is 'null', ignoring read request");
        return false;
    }

    // Check if this characteristic actually has READ property
    if((characteristic.getProperties() & PROPERTY_READ) == 0 ) {
        Log.e(TAG, "ERROR: Characteristic cannot be read");
        return false;
    }

    // Enqueue the read command now that all checks have been passed
    boolean result = commandQueue.add(new Runnable() {
        @Override
        public void run() {
            if(!bluetoothGatt.readCharacteristic(characteristic)) {
                Log.e(TAG, String.format("ERROR: readCharacteristic failed for characteristic: %s", characteristic.getUuid()));
                completedCommand();
            } else {
                Log.d(TAG, String.format("reading characteristic <%s>", characteristic.getUuid()));
                nrTries++;
            }
        }
    });

    if(result) {
        nextCommand();
    } else {
        Log.e(TAG, "ERROR: Could not enqueue read characteristic command");
    }
    return result;
}

В этом методе, сначала проверяем все ли готово для выполнения (наличие и тип характеристики) и логгируем ошибки, если они есть. Внутри Runnable, фактически вызывается метод readCharacteristic(), который выдает команду на устройство. Мы также отслеживаем сколько было попыток, чтобы сделать повтор в случае ошибки (Прим. переводчика: это лучшая тактика, чтобы добиться стабильной работы с устройством). Если чтение характеристики возвращает false, мы логгируем ошибку, «завершаем» команду, чтобы можно было запустить следующую. Наконец вызывается nextCommand(), чтобы запустить следующую команду из очереди:

private void nextCommand() {
    // If there is still a command being executed then bail out
    if(commandQueueBusy) {
        return;
    }

    // Check if we still have a valid gatt object
    if (bluetoothGatt == null) {
        Log.e(TAG, String.format("ERROR: GATT is 'null' for peripheral '%s', clearing command queue", getAddress()));
        commandQueue.clear();
        commandQueueBusy = false;
        return;
    }

    // Execute the next command in the queue
    if (commandQueue.size() > 0) {
        final Runnable bluetoothCommand = commandQueue.peek();
        commandQueueBusy = true;
        nrTries = 0;

        bleHandler.post(new Runnable() {
            @Override
            public void run() {
                    try {
                        bluetoothCommand.run();
                    } catch (Exception ex) {
                        Log.e(TAG, String.format("ERROR: Command exception for device '%s'", getName()), ex);
                    }
            }
        });
    }
}

Обратите внимание, мы используем метод peek() для получения объекта Runnable из очереди, чтобы можно было повторить запуск позже. Этот метод не удаляет объект из очереди.

Результат чтения будет отправлен в ваш колбек:

@Override
public void onCharacteristicRead(BluetoothGatt gatt, 
                                final BluetoothGattCharacteristic characteristic, 
                                int status) {
    // Perform some checks on the status field
    if (status != GATT_SUCCESS) {
        Log.e(TAG, String.format(Locale.ENGLISH,"ERROR: Read failed for characteristic: %s, status %d", characteristic.getUuid(), status));
        completedCommand();
        return;
    }

    // Characteristic has been read so processes it   
    ...
    // We done, complete the command
    completedCommand();
}

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

Теперь мы готовы завершить команду, убираем Runnable из очереди через вызов poll() и запускаем следующую из очереди:

private void completedCommand() {
    commandQueueBusy = false;
    isRetrying = false;
    commandQueue.poll();
    nextCommand();
}

В некоторых случаях (ошибка, неожиданное значение), вам нужно будет повторить команду. Сделать это просто, так как объект Runnable остается в очереди до вызова completedCommand(). Чтобы не уйти в бесконечное повторение – проверяем лимит на повторы:

private void retryCommand() {
    commandQueueBusy = false;
    Runnable currentCommand = commandQueue.peek();
    if(currentCommand != null) {
        if (nrTries >= MAX_TRIES) {
            // Max retries reached, give up on this one and proceed
            Log.v(TAG, "Max number of tries reached");
            commandQueue.poll();
        } else {
            isRetrying = true;
        }
    }
    nextCommand();
}

Запись характеристик

Чтение характеристики достаточно простая операция, а запись требует дополнительных пояснений. Для выполнения записи нужно предоставить характеристику, массив байтов и тип записи. Существует несколько типов записи, важные для нас это:

WRITE_TYPE_DEFAULT (вы получите ответ от устройства, например, код завершения);
WRITE_TYPE_NO_RESPONSE (никакого ответа от устройства не будет).

Использовать тот или иной тип зависит от вашего устройства и характеристики (иногда она поддерживает оба типа записи, иногда только один конкретный тип).

В Android каждая характеристика имеет дефолтный тип записи, который определяется при ее создании. Ниже фрагмент кода из исходников Android, где определяется тип:

...
if ((mProperties & PROPERTY_WRITE_NO_RESPONSE) != 0) {
    mWriteType = WRITE_TYPE_NO_RESPONSE;
} else {
    mWriteType = WRITE_TYPE_DEFAULT;
}
...

Как вы видите, это работает нормально, если характеристика поддерживает только один их двух типов записи. Если характеристика поддерживает оба типа, то значение по умолчанию будет WRITE_TYPE_NO_RESPONSE. Имейте это ввиду!

Перед записью можно проверить характеристику, поддерживает ли она нужный тип записи:

// Check if this characteristic actually supports this writeType
int writeProperty;
switch (writeType) {
    case WRITE_TYPE_DEFAULT: writeProperty = PROPERTY_WRITE; break;
    case WRITE_TYPE_NO_RESPONSE : writeProperty = PROPERTY_WRITE_NO_RESPONSE; break;
    case WRITE_TYPE_SIGNED : writeProperty = PROPERTY_SIGNED_WRITE; break;
    default: writeProperty = 0; break;
}
if((characteristic.getProperties() & writeProperty) == 0 ) {
    Log.e(TAG, String.format(Locale.ENGLISH,"ERROR: Characteristic <%s> does not support writeType '%s'", characteristic.getUuid(), writeTypeToString(writeType)));
    return false;
}

Я рекомендую всегда явно указывать тип записи и не полагаться на дефолтные настройки выбранные Android!

Итак, запись массива байтов bytesToWrite в характеристику выглядит так:

characteristic.setValue(bytesToWrite);
characteristic.setWriteType(writeType);
if (!bluetoothGatt.writeCharacteristic(characteristic)) {
    Log.e(TAG, String.format("ERROR: writeCharacteristic failed for characteristic: %s", characteristic.getUuid()));
    completedCommand();
} else {
    Log.d(TAG, String.format("writing <%s> to characteristic <%s>", bytes2String(bytesToWrite), characteristic.getUuid()));
    nrTries++;
}

Включение/выключение уведомлений

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

Для включения уведомлений нужно сделать две вещи в Android:

вызвать setCharacteristicNotification. Bluetooth стек будет ожидать уведомления для этой характеристики.
записать 1 или 2 как unsigned int16 в дескриптор конфигурации характеристик (Client Characteristic Configuration, сокращенно - ССС). Дескриптор CCC имеет короткий UUID 2902.

Почему 1 или 2? Потому что «под капотом» Bluetooth стека есть Уведомление и Индикация. Полученное Уведомление не подтверждаются стеком Bluetooth, а Индикация наоборот – подтверждается стеком. При использовании Индикации, устройство будет точно знать, что данные получены и может их, например, удалить из локального хранилища. С точки зрения Android приложения нет разницы: в обоих случаях вы просто получите массив байтов и Bluetooth стек уведомит устройство об этом, если вы используете Индикацию. Итак, 1 включает уведомления, 2 – индикацию. Чтобы выключить их, записываем 0. Вы должны самостоятельно определить, что записать в дескриптор CCC.

В iOS метод setNotify() делает всю работу за вас. Ниже пример, как сделать тоже самое на Android, там сначала идут проверки входных параметров, определяется что записать в дескриптор и, наконец команда отправляется в очередь:

private final String CCC_DESCRIPTOR_UUID = "00002902-0000-1000-8000-00805f9b34fb";
public boolean setNotify(BluetoothGattCharacteristic characteristic, 
                        final boolean enable) {
    // Check if characteristic is valid
    if(characteristic == null) {
        Log.e(TAG, "ERROR: Characteristic is 'null', ignoring setNotify request");
        return false;
    }

    // Get the CCC Descriptor for the characteristic
    final BluetoothGattDescriptor descriptor = characteristic.getDescriptor(UUID.fromString(CCC_DESCRIPTOR_UUID));
    if(descriptor == null) {
        Log.e(TAG, String.format("ERROR: Could not get CCC descriptor for characteristic %s", characteristic.getUuid()));
        return false;
    }

    // Check if characteristic has NOTIFY or INDICATE properties and set the correct byte value to be written
    byte[] value;
    int properties = characteristic.getProperties();
    if ((properties & PROPERTY_NOTIFY) > 0) {
        value = BluetoothGattDescriptor.ENABLE_NOTIFICATION_VALUE;
    } else if ((properties & PROPERTY_INDICATE) > 0) {
        value = BluetoothGattDescriptor.ENABLE_INDICATION_VALUE;
    } else {
        Log.e(TAG, String.format("ERROR: Characteristic %s does not have notify or indicate property", characteristic.getUuid()));
        return false;
    }
    final byte[] finalValue = enable ? value : BluetoothGattDescriptor.DISABLE_NOTIFICATION_VALUE;

    // Queue Runnable to turn on/off the notification now that all checks have been passed
    boolean result = commandQueue.add(new Runnable() {
        @Override
        public void run() {
            // First set notification for Gatt object  if(!bluetoothGatt.setCharacteristicNotification(descriptor.getCharacteristic(), enable)) {
                Log.e(TAG, String.format("ERROR: setCharacteristicNotification failed for descriptor: %s", descriptor.getUuid()));
            }

            // Then write to descriptor
            descriptor.setValue(finalValue);
            boolean result;
            result = bluetoothGatt.writeDescriptor(descriptor);
            if(!result) {
                Log.e(TAG, String.format("ERROR: writeDescriptor failed for descriptor: %s", descriptor.getUuid()));
                completedCommand();
            } else {
                nrTries++;
            }
        }
    });

    if(result) {
        nextCommand();
    } else {
        Log.e(TAG, "ERROR: Could not enqueue write command");
    }

    return result;
}

Результат записи в CCC дескриптор обрабатывается в колбеке onDescriptorWrite. Здесь вы должны отличить запись в CCC от записей в другие дескрипторы. Во время обработки колбека, мы также должны хранить, какие в данный момент характеристики уведомляются.

@Override
public void onDescriptorWrite(BluetoothGatt gatt, 
                                final BluetoothGattDescriptor descriptor, 
                                final int status) {
    // Do some checks first
    final BluetoothGattCharacteristic parentCharacteristic = descriptor.getCharacteristic();
    if(status!= GATT_SUCCESS) {
        Log.e(TAG, String.format("ERROR: Write descriptor failed value <%s>, device: %s, characteristic: %s", bytes2String(currentWriteBytes), getAddress(), parentCharacteristic.getUuid()));
    }

    // Check if this was the Client Configuration Descriptor  if(descriptor.getUuid().equals(UUID.fromString(CCC_DESCRIPTOR_UUID))) {
        if(status==GATT_SUCCESS) {
            // Check if we were turning notify on or off
            byte[] value = descriptor.getValue();
            if (value != null) {
                if (value[0] != 0) {
                    // Notify set to on, add it to the set of notifying characteristics          notifyingCharacteristics.add(parentCharacteristic.getUuid());
                    }
                } else {
                    // Notify was turned off, so remove it from the set of notifying characteristics               notifyingCharacteristics.remove(parentCharacteristic.getUuid());
                }
            }
        }
        // This was a setNotify operation
        ....
    } else {
        // This was a normal descriptor write....
        ...
        });
    }
    completedCommand();
}

Чтобы узнать из какой характеристики пришло уведомление – используйте метод isNotifying():

public boolean isNotifying(BluetoothGattCharacteristic characteristic) {
    return notifyingCharacteristics.contains(characteristic.getUuid());
}

Лимиты на установку уведомлений

К сожалению, нельзя включить столько уведомлений, сколько хочешь. Начиная с Android-5 лимит равен 15. В более старых версиях он был равен 7 или даже 4. Большинство смартфонов поддерживают 15 уведомлений. Не забывайте отключать их, если они вам больше не нужны, чтобы не исчерпать лимит.

Проблемы с потоками

Итак, мы научились читать/писать характеристики, включать/выключать уведомления, а значит готовы использовать это в реальном проекте. Я думаю, что устройства BLE можно разделить на две категории:

Простые устройства. Например, термометр, который использует официальный Bluetooth Health Thermometer сервис. Такие устройства легко использовать, вы просто включаете уведомления и данные начинают поступать. Здесь мы используем только операции чтения характеристики, запись не нужна;
Сложные устройства. Это может быть любое устройство, но обычно все они используют свой внутренний протокол обмена данными. Часто эти протоколы не спроектированы под BLE, а просто транслируют внутренний последовательный протокол в BLE, где одна характеристика используется для отправки данных, а другая для приема. Сложность в том, что вам требуется знать большое количество команд для работы с устройством: авторизация, обновление пользовательских параметров, параметров самого устройства, получение сохраненных данных и т.д.

Простые устройства обычно не создают проблем с потоками, для сложных – следует работать внимательно. Чтение, запись и уведомления в этом случае будут чередоваться и могут мешать друг другу, особенно если у вас устройство с высокой частотой передачи данных (30Hz или около).

Типичная проблема с потоками выглядит так:

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

Причины такого поведения:

как только сообщение доставлено, Android будет отправлять следующее (если оно есть). Посколько обработка данных отправляется в другой поток, текущий освобождается и Android продолжит доставку уведомлений;
Android переиспользует BluetoothGattCharacteristic объекты внутри. Они создаются в время обнаружения сервисов (services discovering) и после этого переспользуются многократно. Таким образом, когда приходит уведомления Android сохраняет значение в объект BluetoothGattCharacteristic. Если характеристика в этот момент обрабатывается в другом потоке мы получим гонку состояний (race condition) и результат будет непредсказуемым.

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

Ниже пример, который использует такую тактику:

@Override
public void onCharacteristicChanged(BluetoothGatt gatt, 
                                    final BluetoothGattCharacteristic characteristic) {
    // Copy the byte array so we have a threadsafe copy
    final byte[] value = new byte[characteristic.getValue().length];
    System.arraycopy(
        characteristic.getValue(), 
        0, value, 0, 
        characteristic.getValue().length);

    // Characteristic has new value so pass it on for processing
    bleHandler.post(new Runnable() {
        @Override
        public void run() {         
            myProcessor.onCharacteristicUpdate(BluetoothPeripheral.this, value, characteristic);
        }
    });
}

Другие рекомендации по работе с потоками

Есть несколько дополнительных рекомендаций по работе с BLE на Android. Поскольку стек BLE в основном асинхронный, у нас есть мульти-поточная обработка задач.

Android использует потоки:

При сканировании (результаты приходят в main поток);
Вызове колбеков BluetoothGattCallback (выполняются в потоках Binder);

Обработка результатов сканирования на main потоке не будет проблемой. Но с потоками Binder все немного сложнее. При вызове колбека на потоке Binder, Android не будет отправлять новые данные пока не закончится обработка текущих, то есть поток Binder блокируется пока ваш код не завершится. Следует избегать тяжелых операций в колбеках, никаких sleep() или что-то подобное. Кроме того, никаких новых вызовов в объекте BluetoothGatt, пока вы находитесь в потоке Binder, хотя большинство методов асинхронные.

Я рекомендую следующее:

Всегда выполняйте вызовы BluetoothGattCallback в отдельном потоке, возможно даже из потока пользовательского интерфейса (Прим. переводчика: работать на main потоке - плохая идея, если у вас есть активный обмен с устройством, обязательно будут залипания UI, не делайте так);
Освобождайте потоки Binder как можно быстрее и никогда не блокируйте их;

Самый простой способ выполнить рекомендации выше – создать выделенный Handler и использовать его для обработки данных и выдачи новых команд. Обратите внимание, я уже использовал Handler на примере кода для колбека onCharacteristicUpdate.

Объявление объекта:

Handler bleHandler = new Handler();

Если хотите запустить Handler на main потоке:

Handler bleHandler = new Handler(Looper.getMainLooper());

Прокрутите назад и взгляните на наш метод nextCommand(), каждый Runnable выполняется в нашем собственном Handler, следовательно, мы гарантируем, что все команды выполняются вне потока Binder.

Следующая статья: сопряжение (bonding)

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

Не терпится поработать с BLE? Попробуйте мою библиотеку Blessed for Android. Она использует все подходы из этой серии статей и упрощает работу с BLE в вашем приложении.

Android, работа с BLE - часть 2.

2020-01-10T09:00:00+00:00

Перевод статьи Making Android BLE work — part 2.

внимание: в цикле статей используется минимальная версия - Android 6

В предыдущей статье мы подробно рассмотрели сканирование устройств. Эта статья - о подключении, отключении и обнаружении сервисов (discovering services).

Подключение к устройству

После удачного сканирования, вы должны подключиться к устройству, вызывая метод connectGatt(). В результате мы получаем объект – BluetoothGatt, который будет использоваться для всех GATT операций, такие как чтение и запись характеристик. Однако будьте внимательны, есть две версии метода connectGatt(). Поздние версии Android имеют еще несколько вариантов, но нам нужна совместимость с Android-6 и мы рассматриваем только эти две:

BluetoothGatt connectGatt(Context context, boolean autoConnect,
        BluetoothGattCallback callback)
BluetoothGatt connectGatt(Context context, boolean autoConnect,
        BluetoothGattCallback callback, int transport)

Внутренняя реализация первой версии – это фактически вызов второй версии с аргументом transport = TRANSPORT_AUTO. Для подключения BLE устройств такой вариант не подходит. TRANSPORT_AUTO используется для устройств с поддержкой и BLE и классического Bluetooth протоколов. Это значит, что Android будет сам выбирать протокол подключения. Этот момент практически нигде не описан и может привести к непредсказуемым результатам, много людей сталкивались с такой проблемой. Вот почему вы должны использовать вторую версию connectGatt() с transport = TRANSPORT_LE:

BluetoothGatt gatt = device.connectGatt(context, false, 
    bluetoothGattCallback, TRANSPORT_LE);

Первый аргумент – context приложения. Второй аргумент – флаг autoconnect, говорит подключаться немедленно (false) или нет (true). При немедленном подключении (false) Android будет пытаться соединиться в течение 30 секунд (на большинстве смартфонов), по истечении этого времени придет статус соединения status_code = 133. Это не официальная ошибка для таймаута соединения. В исходниках Android код фигурирует как GATT_ERROR. К сожалению, эта ошибка появляется и в других случаях. Имейте ввиду, с autoconnect = false Android делает соединение только с одним устройством в одно и то же время (это значит если у вас несколько устройств - подключайте их последовательно, а не паралелльно). Третий аргумент – функция обратного вызова BluetoothGattCallback (callback) для конкретного устройства. Этот колбек используется для всех связанных с устройством операциях, такие как чтение и запись. Мы рассмотрим это более детально в следующей статье.

Autoconnect = true

Если вы установите autoconnect = true, Android будет подключаться самостоятельно к устройству всякий раз, когда оно будет обнаружено. Внутри это работает так: Bluetooth стек сканирует сохраненные устройства и когда увидит одно из них – подключается к нему. Это довольно удобно, если вы хотите подключиться к конкретному устройству, когда оно становится доступным. Фактически, это предпочтительный способ для переподключения. Вы просто создаете BluetoothDevice объект и вызываете connectGattwith с autoconnect = true.

BluetoothDevice device = 
bluetoothAdapter.getRemoteDevice("12:34:56:AA:BB:CC");

BluetoothGatt gatt = 
device.connectGatt(context, true, bluetoothGattCallback, TRANSPORT_LE);

Обратите внимание, этот подход работает только, если устройство есть в Bluetooth кеше или устройство было уже сопряжено (bonding). Посмотрите мою предыдущую статью, где подробно объясняется работа с Bluetooth кешем. При перезагрузке смартфона или выключении/включении Bluetooth (а также Airplane режима) – кеш очистится, это надо проверять перед подключением с autoconnect = true, что действительно раздражает.

Autoconnect работает только с закешированными и сопряженными (bonded) устройствами!

Для того, чтобы узнать, закешировано устройство или нет, можно использовать небольшой трюк. После создания объекта BluetoothDevice, вызовите у него getType, если результат – TYPE_UNKNOWN, значит устройство не закешировано. В этом случае, необходимо просканировать устройство с этим мак-адресом (используя не агрессивный метод сканирования) и после этого можно использовать автоподключение снова.

Android-6 и ниже имеет известный баг, в котором возникает гонка состояний и автоматическое подключение становится обычным (autoconnect = false). К счастью, умные ребята из Polidea нашли решение для этого. Настоятельно рекомендуется использовать его, если думаете использовать автоподключение.

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

работает достаточно хорошо на современных версиях Android (прим. переводчика - от Android-8 и выше);
возможность подключаться к нескольким устройствам одновременно;

Недостатки:

работает медленнее (Android в этом случае сканирует в режиме SCAN_MODE_LOW_POWER, экономя энергию), если сравнивать сканирование в агрессивном режиме + подключение с autoconnect = false;

Изменения статуса подключения

После вызова connectGatt(), Bluetooth стек присылает результат в колбек onConnectionStateChange, он вызывается при любом изменении соединения.

Работа с этим колбеком – достаточно нетривиальная вещь. Большинство простых примеров из сети выглядит так (не обольщайтесь):

public void onConnectionStateChange(final BluetoothGatt gatt, 
                                    final int status, 
                                    final int newState) {
    if (newState == BluetoothProfile.STATE_CONNECTED) {
        gatt.discoverServices();
    } else {
        gatt.close();
    }
}

Этот код обрабатывает только аргумент newState и полностью игнорирует status. В многих случаях это работает и кажется безошибочным. Действительно, после подключения, следующее что нужно сделать – это вызвать discoverServices(). А в случае отключения - необходимо сделать вызов close(), чтобы Android освободил все связанные ресурсы в стеке Bluetooth. Эти два момента очень важные для стабильной работы BLE под Android, давайте их обсудим прямо сейчас!

При вызове connectGatt(), Bluetooth стек регистрирует внутри себя интерфейс для нового клиента (client interface: clientIf).

Возможно вы заметили такие логи в LogCat:

D/BluetoothGatt: connect() - device: B0:49:5F:01:20:XX, auto: false
D/BluetoothGatt: registerApp()
D/BluetoothGatt: registerApp() — UUID=0e47c0cf-ef13–4afb-9f54–8cf3e9e808d5
D/BluetoothGatt: onClientRegistered() — status=0 clientIf=6

Здесь видно, что клиент 6 был зарегистрирован после вызова connectGatt(). Максимальное количество клиентов (подключения) у Android равно 30 (константа GATT_MAX_APPS в исходниках), при достижении которого – Android не будет подключаться к устройствам вообще и вы будете получать постоянно ошибку подключения. Достаточно странно, но сразу после загрузки Android уже имеет 5 или 6 таких подключенных клиентов, предполагаю, что Android использует их для внутренних нужд. Таким образом, если вы не вызываете метод close(), то счетчик клиентов увеличивается каждый раз при вызове connectGatt(). Когда вы вызываете close(), Bluetooth стек удаляет ваш колбек, счетчик клиентов уменьшается на единицу и освобождает ресурсы клиента.

D/BluetoothGatt: close()
D/BluetoothGatt: unregisterApp() — mClientIf=6

Важно всегда вызывать close() после отключения! А сейчас обсудим основные случаи дисконнекта устройств.

Состояние подключения (newState)

Переменная newState содержит новое состояние подключения и может иметь 4 значения:

STATE_CONNECTED
STATE_DISCONNECTED
STATE_CONNECTING
STATE_DISCONNECTING

Значения говорят сами за себя. Хотя состояния STATE_CONNECTING, STATE_DISCONNECTING на практике я их не встречал. Так что, в принципе, можно не обрабатывать их, но для уверенности, я предлагаю их явно учитывать (прим. переводчика - и это лучше, чем не обрабатывать их.), вызывая close() только в том случае если устройство действительно отключено.

Статус подключения (status)

В примере выше, переменная статуса status полностью игнорировалась, но в действительности обрабатывать ее важно. Эта переменная, по сути, является кодом ошибки. Вы можете получить GATT_SUCCESS в результате как подключения, так и контролируемого отключения. Таким образом, мы можем по-разному обрабатывать контролируемое или внезапное отключение устройства. Если вы получили значение отличное от GATT_SUCCESS, значит «что-то пошло не так» и в status будет указана причина. К сожалению, объект BluetoothGatt дает очень мало кодов ошибок, все они описаны здесь. Чаще всего вы будете встречаться с кодом 133 (GATT_ERROR). Который не имеет точного описания, и просто говорит – “произошла какая-то ошибка”. Не очень информативно, подробнее об GATT_ERROR позже.

Теперь мы знаем, что обозначают переменные newState и status, давайте улучшим наш колбек onConnectionStateChange:

public void onConnectionStateChange(final BluetoothGatt gatt, 
                                    final int status, 
                                    final int newState) {
if(status == GATT_SUCCESS) {
    if (newState == BluetoothProfile.STATE_CONNECTED) {
        // Мы подключились, можно запускать обнаружение сервисов
        gatt.discoverServices();
    } else if (newState == BluetoothProfile.STATE_DISCONNECTED) {
        // Мы успешно отключились (контролируемое отключение)
        gatt.close();
    } else {
        // мы или подключаемся или отключаемся, просто игнорируем эти статусы
    }
} else {
   // Произошла ошибка... разбираемся, что случилось!
   ...
   gatt.close();
}

Это не последний вариант, мы еще улучшим колбек в этой статье. В любом случае, теперь у нас есть обработка ошибок и успешных операций.

Состояние bonding (bondState)

Последний параметр, который необходимо учитывать в колбеке onConnectionStateChange – это bondState, состояние сопряжения (bonding) с устройством. Мы получаем этот параметр так:

int bondstate = device.getBondState();

Состояние bonding может иметь одно из трех значений BOND_NONE, BOND_BONDING or BOND_BONDED. Каждое из них влияет на то, как обрабатывать подключение.

BOND_NONE, нет проблем, можно вызывать discoverServices();
BOND_BONDING, устройство в процессе сопряжения, нельзя вызывать discoverServices(), так как Bluetooth стек в работе и запуск discoverServices() может прервать сопряжение и вызвать ошибку соединения. discoverServices() вызываем только после того, как пройдет сопряжение (bonding);
BOND_BONDED, для Android-8 и выше, можно запускать discoverServices() без задержки. Для версий 7 и ниже может потребоваться задержка перед вызовом. Если ваше устройство имеет Service Changed Characteristic, то Bluetooth стек в этот момент еще обрабатывает их и запуск discoverServices() без задержки может вызвать ошибку соединения. Добавьте 1000-1500мс задержки, конкретное значение зависит от количества характеристик на устройстве. Используйте задержку всегда, если вы не знаете сколько Service Changed Characteristic имеет устройство.

Теперь мы можем учитывать состояние bondState вместе с status и newState:

if (status == GATT_SUCCESS) {
    if (newState == BluetoothProfile.STATE_CONNECTED) {
        int bondstate = device.getBondState();
        // Обрабатываем bondState
        if(bondstate == BOND_NONE || bondstate == BOND_BONDED) {
            // Подключились к устройству, вызываем discoverServices с задержкой
            int delayWhenBonded = 0;
            if (Build.VERSION.SDK_INT <= Build.VERSION_CODES.N) {
                delayWhenBonded = 1000;
            }
            final int delay = bondstate == BOND_BONDED ? delayWhenBonded : 0;
            discoverServicesRunnable = new Runnable() {
                @Override
                public void run() {
                    Log.d(TAG, String.format(Locale.ENGLISH, "discovering services of '%s' with delay of %d ms", getName(), delay));
                    boolean result = gatt.discoverServices();
                    if (!result) {
                        Log.e(TAG, "discoverServices failed to start");
                    }
                    discoverServicesRunnable = null;
                }
            };
            bleHandler.postDelayed(discoverServicesRunnable, delay);
        } else if (bondstate == BOND_BONDING) {
            // Bonding в процессе, ждем когда закончится
            Log.i(TAG, "waiting for bonding to complete");
        }
....

Обработка ошибок

После того как мы разобрались с успешными операциями, давайте взглянем на ошибки. Есть ряд ситуаций, которые на самом деле “нормальные”, но выдают себя за ошибки.

Устройство отключилось намеренно. Например, все данные были переданы и больше ему нечего делать. Вы получите статус - 19 (GATT_CONN_TERMINATE_PEER_USER);
Истекло время ожидания соединения и устройство отключилось само. В этом случае придет статус - 8 (GATT_CONN_TIMEOUT);
Низкоуровневая ошибка соединения, которая привела к отключению. Обычно это статус - 133 (GATT_ERROR) или более конкретный код, если повезет;
Bluetooth стек не смог подключится ни разу. Здесь также получим статус - 133 (GATT_ERROR);
Соединение было потеряно в процессе bonding или discoverServices. Необходимо выяснить причину и возможно повторить попытку подключения.

Первые два случая абсолютно нормальные явления и все что нужно сделать - это вызывать close() и подчистить ссылки на объект BluetoothGatt, если необходимо. В остальных случаях, либо ваш код, либо устройство, что-то делает не так. Вы возможно захотите уведомить UI или другие части приложения о проблеме, повторить подключение или еще каким-то образом отреагировать на ситуацию. Взгляните как я сделал это в моей библиотеке.

Статус 133 при подключении (connecting)

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

Убедитесь, что вы всегда вызываете close() при отключении. Если этого не сделать, в следующий раз при подключении вы точно получите status=133;
Всегда используйте TRANSPORT_LE в вызове connectGatt();
Перезагрузите смартфон. Возможно Bluetooth стек выбрал лимит по клиентским подключениям или есть внутренняя проблема. (Прим. переводчика: я сначала выключал/включал Bluetooth, потом Airplane режим и если не помогало - перезагружал);
Проверьте что устройство посылает advertising пакеты. Вызов connectGatt() с autoconnect = false имеет таймаут 30 секунд, после чего присылает ошибку status=133;
Замените/зарядите батарею на устройстве. Обычно устройства работают нестабильно при низком заряде;

Если вы попробовали все способы выше и все еще получаете статус 133, необходимо просто повторить подключение! Это одна из Android ошибок, которую мне так и не удалось понять или решить. Иногда вы получаете 133 при подключении к устройству, но если вызывать close() и переподключиться, то все работает без проблем! Есть подозрение, что проблема в кеше Android и вызов close() сбрасывает его состояние для конкретного устройства. Если кто-нибудь поймет, как решить эту проблему – дайте мне знать!

Отключение по запросу (disconnect)

Для отключения устройства вам необходимо сделать шаги:

вызвать disconnect();
подождать обновления статуса в onConnectionStateChange;
вызвать close();
освободить связанные с объектом gatt ресурсы;

Команда disconnect() фактически разрывает соединение с устройством и обновляет внутреннее состояние Bluetooth стека. Затем вызывается колбек onConnectionStateChange с новым состоянием «disconnected».

Вызов close() удаляет ваш BluetoothGattCallback и освобождает клиента в Bluetooth стеке.

Наконец, удаление BluetoothGatt освободит все связанные с подключением ресурсы.

Отключение «неправильно»

В примерах из сети можно увидеть, разные примеры отключения, например:

вызвать disconnect()
сразу вызвать close()

Это будет работать более-менее. Да устройство отключится, но вы никогда не получите вызов колбека с состоянием «disconnected». Дело в том, что disconnect() операция асинхронная (не блокирует поток и имеет свое время выполнения), а close() немедленно удаляет коллбек! Получается, когда Android будет готов вызвать колбек, его уже не будет.

Иногда в примерах не вызывают disconnect(), а только close(). Это приведет к отключению устройства, но это неправильный способ, поскольку disconnect() отключает активное соединение и отменяет ожидающее автоматическое подключение (вызов с autoconnect = true). Поэтому, если вы вызываете только close(), любое ожидающее автоподключение может привести к новому подключению.

Отмена попытки подключения

Если вы хотите отменить подключение после connectGatt(), вам нужно вызвать disconnect(). Так как в этому моменту вы еще не подключены, колбек onConnectionStateChange не сработает! Просто подождите некоторое время после disconnect() и после этого вызывайте close() (прим. переводчика: обычно это 50-100мс).

При удачной отмене вы увидите примерно такое в логах:

D/BluetoothGatt: cancelOpen() — device: CF:A9:BA:D9:62:9E

Скорее всего, вы никогда не отмените соединение, для параметра autoconnect = false. Часто это делается для подключений с autoconnect = true. Например, когда приложение на переднем плане – вы подключаетесь к вашим устройствам и отключаетесь от них, если приложение переходит в фон.

Прим. переводчика: но это не значит что для autoconnect = false не надо проводить такую отмену! Скорее всего вы не увидите этого в логах.

Обнаружение сервисов (discovering services)

Как только вы подключились к устройству, необходимо запустить обнаружение его сервисов вызовом discoverServices(). Bluetooth стек запустит серию низкоуровневых команд для получения сервисов, характеристик и дескрипторов. Это занимает обычно около одной секунды в зависимости от того сколько таких служб, характеристик, дескрипторов имеет ваше устройство. В результате будет вызыван колбек onServicesDiscovered.

Первым делом проверим, есть ли какие ошибки после обнаружения сервисов:

// Проверяем есть ли ошибки? Если да - отключаемся
if (status == GATT_INTERNAL_ERROR) {
    Log.e(TAG, "Service discovery failed");
    disconnect();
    return;
}

Если есть ошибки (обычно это GATT_INTERNAL_ERROR со значением 129), делаем отключение устройства, что-то исправить здесь невозможно (нет специальных технических способов для этого). Вы просто отключаете устройство и повторно пробуете подключиться.

Если все прошло удачно, вы получите список сервисов:

final List<BluetoothGattService> services = gatt.getServices();
Log.i(TAG, String.format(Locale.ENGLISH,"discovered %d services for '%s'", services.size(), getName()));
// Работа со списком сервисов (если требуется)
...

Кеширование сервисов.

Bluetooth стек кеширует найденные на устройстве сервисы, характеристики и дескрипторы. Первое подключение вызывает реальное обнаружение сервисов, все последующие – возвращаются кешированные версии. Это соответствует стандарту Bluetooth. Обычно это нормально и сокращает время соединения с устройством. Однако в некоторых случаях, может потребоваться очистить кеш, чтобы снова обнаружить их с устройства при следующем соединении. Типичный сценарий: обновление прошивки, в которой изменяется набор сервисов, характеристик, дескрипторов. Есть скрытый метод очистки кеша и добраться до него нам поможет рефлексия:

private boolean clearServicesCache() {
    boolean result = false;
    try {
        Method refreshMethod = bluetoothGatt.getClass().getMethod("refresh");
        if(refreshMethod != null) {
            result = (boolean) refreshMethod.invoke(bluetoothGatt);
        }
    } catch (Exception e) {
        Log.e(TAG, "ERROR: Could not invoke refresh method");
    }
    return result;
}

Этот метод асинхронный, дайте ему некоторое время для завершения!

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

Хотя операции подключения и отключения выглядят просто, есть некоторые особенности, которые нужно знать.

Случайная ошибка 133 при подключении, выше мы разобрались как с ней работать;
Периодическое зависание подключения, не срабатывает таймаут и не вызывается колбек onConnectionStateChange. Это случается не часто, но я видел такие случае при низком уровне батареи или когда устройство находится на границе доступности по расстоянию Bluetooth. Скорее всего общение с устройством происходит, но затем прерывается и зависает. Мой обходной путь – использовать свой таймер подключения и в случае таймаута – закрывать соединение и отключаться;
Некоторые смартфоны имеют проблему с подключением во время сканирования. Например, Huawei P8 Lite один из таких. Останавливаем сканнер перед любым подключением (Прим. переводчика: это правило соблюдаем строго!);
Все вызовы подключения/отключения асинхронные. То есть неблокирующие, но при этом им нужно время, чтобы выполнится до конца. Избегайте быстрый запуск их друг за другом (Прим. переводчика: я обычно использую задержку 50-100мс между вызовами).

Следующая статья: чтение и запись характеристик.

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

Не терпится поработать с BLE? Попробуйте мою библиотеку Blessed for Android. Она использует все подходы из этой серии статей и упрощает работу с BLE в вашем приложении.

Android, работа с BLE - часть 1.

2019-11-12T09:00:00+00:00

Перевод статьи Making Android BLE work — part 1.

внимание: в цикле статей используется минимальная версия - Android 6

В последний год я разрабатывал Bluetooth Low Energy (BLE) приложения под iOS и это оказалось довольно простым. Далее было портирование их на Android… насколько это могло быть сложным?

Могу точно сказать это было сложней, чем я представлял, пришлось приложить немало усилий для стабильной работы под Android. Я изучил много статей в свободном доступе, некоторые оказались ошибочными, многие были очень полезными и помогли в деле. В этой серии статей я хочу описать свои выводы, чтобы вы не тратили уйму времени на поиски, как я.

Особенности работы BLE под Android:

Google документация по BLE очень общая, в некоторых случаях нет важной информации или она устарела, примеры приложений не показывают как правильно использовать BLE. Я обнаружил лишь несколько источников, как правильно сделать BLE. Презентация Stuart Kent дает замечательный материал для старта. Для некоторых продвинутых тем есть хорошая статья Nordic.
Android BLE API это низкоуровневые операции, в реальных приложениях нужно использовать несколько слоев абстракции (как например сделано “из коробки” в iOS-CoreBluetooth). Обычно нужно самостоятельно сделать: очередь команд, bonding, обслуживание соединений, обработка ошибок и багов, мультипоточный доступ . Самые известные библиотеки: SweetBlue, RxAndroidBle и Nordic. На мой взгляд самая легкая для изучения - Nordic, см. детали тут.
Производители делают изменения в Android BLE стеке или полностью заменяют на свою реализацию. И надо учитывать разницу поведения для разных устройств в приложении. То что прекрасно работает на одном телефоне, может не работать на других! В целом не все так плохо, например реализация Samsung сделана лучше собственной реализации от Google!
В Android есть несколько известных (и неизвестных) багов которые должны быть обработаны, особенно в версиях 4,5 и 6. Более поздние версии работают намного лучше, но тоже имеют определенные проблемы, такие как случайные сбои соединения с ошибкой 133. Подробнее об этом ниже.

Не претендую на то, что я решил все проблемы, но мне удалось выйти на “приемлемый” уровень. Начнем со сканирования.

Сканирование устройств

Перед подключением к устройству вам нужно его просканировать. Это делается при помощи класса BluetoothLeScanner:

BluetoothAdapter adapter = BluetoothAdapter.getDefaultAdapter();
BluetoothLeScanner scanner = adapter.getBluetoothLeScanner();

if (scanner != null) {
    scanner.startScan(filters, scanSettings, scanCallback);
    Log.d(TAG, "scan started");
}  else {
    Log.e(TAG, "could not get scanner object");
}

Сканер пытается обнаружить устройства в соответствии с filters и scanSettings и при нахождении устройства вызывается scanCallback:

private final ScanCallback scanCallback = new ScanCallback() {
    @Override
    public void onScanResult(int callbackType, ScanResult result) {
        BluetoothDevice device = result.getDevice();
        // ...do whatever you want with this found device
    }

    @Override
    public void onBatchScanResults(List<ScanResult> results) {
        // Ignore for now
    }

    @Override
    public void onScanFailed(int errorCode) {
        // Ignore for now
    }
};

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

Advertisement data - массив байтов с информацией об устройстве, для большинства устройств это имя и UUIDы сервисов, можно задать в filters имя устройства и UUID сервисов для поиска конкретных устройств.
RSSI уровень - уровень сигнала (насколько близко устройство).
… дополнительные данные, см. документацию по ScanResult здесь.

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

Настраиваем фильтр для сканирования

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

Сканирование устройств по UUID сервиса

Используется если вам необходимо найти устройства определенной категории, например мониторы артериального давления со стандартным сервисным UUID: 1810. При сканировании устройство может содержать в Advertisement data UUID сервис, который характеризует это устройство. На самом деле эти данные ненадежные, фактически сервисы могут не поддерживаться, или подделываеться Advertisement data данные, в общем тут есть творческий момент.

Прим. перевочика: одно из моих устройств со специфичной прошивкой, вообще не содержало список UUID сервисов в Advertisement data, хотя все остальные прошивки работали ок.

Пример сканирования службы с артериальным давлением:

UUID BLP_SERVICE_UUID = UUID.fromString("00001810-0000-1000-8000-00805f9b34fb");
UUID[] serviceUUIDs = new UUID[]{BLP_SERVICE_UUID};
List<ScanFilter> filters = null;
if(serviceUUIDs != null) {
    filters = new ArrayList<>();
    for (UUID serviceUUID : serviceUUIDs) {
        ScanFilter filter = new ScanFilter.Builder()
                .setServiceUuid(new ParcelUuid(serviceUUID))
                .build();
        filters.add(filter);
    }
}
scanner.startScan(filters, scanSettings, scanCallback);

Обратите внимание, короткий UUID (например 1810), называется 16-bit UUID является частью длинного 128-bit UUID (в данном случае 00001810-000000-1000-8000-000-00805f9b34fb). Короткий UUID это BASE_PART длинного UUID, см. спецификацию здесь

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

Поиск устройств использует точное совпадение имени устройства, обычно это применяется в двух случаях:

поиск конкретного устройства
поиск конкретной модели устройста Например мой нагрудный напульсник Polar H7 определяется как “Polar H7 391BBB014”, первая часть - “Polar H7” общая для всех таких устройств этой модели, а последняя часть “391BBB014” - уникальный серийный номер. Это очень распространненая практика. Если вы хотите найти все устройства “Polar H7”, то фильтр по имени вам не поможет, придется искать подстроку у всех отсканированных устройств в ScanResult. Пример с поиском точно по имени:

String[] names = new String[]{"Polar H7 391BB014"};
List<ScanFilter> filters = null;
if(names != null) {
    filters = new ArrayList<>();
    for (String name : names) {
        ScanFilter filter = new ScanFilter.Builder()
                .setDeviceName(name)
                .build();
        filters.add(filter);
    }
}
scanner.startScan(filters, scanSettings, scanCallback);

Сканирование устройств по MAC-адресам.

Обычно применяется для переподключения к уже известным устройствам. Обычно мы не знаем MAC-адрес девайса, если не сканировали его раньше, иногда адрес печатается на коробке или на корпусе самого устройства, особенно это касается медицинских приборов. Существует другой способ повторного подключения, но в некоторых случаях придется еще раз сканировать устройство, например при очистке кеша Bluetooth.

String[] peripheralAddresses = new String[]{"01:0A:5C:7D:D0:1A"};
// Build filters list
List<ScanFilter> filters = null;
if (peripheralAddresses != null) {
    filters = new ArrayList<>();
    for (String address : peripheralAddresses) {
        ScanFilter filter = new ScanFilter.Builder()
                .setDeviceAddress(address)
                .build();
        filters.add(filter);
    }
}
scanner.startScan(filters, scanSettings, scanByServiceUUIDCallback);

Вероятно вы уже поняли, что можно комбинировать в фильтре UUID, имя и MAC-адрес устройства. Выглядит неплохо, но на практике я не применял такое. Хотя может быть вам это пригодится?

Настройка ScanSettings

ScanSettings объясняют Android как он должен сканировать устройства. Там несколько настроек, которые можно задать, ниже полный пример:

ScanSettings scanSettings = new ScanSettings.Builder()
        .setScanMode(ScanSettings.SCAN_MODE_LOW_POWER)
        .setCallbackType(ScanSettings.CALLBACK_TYPE_ALL_MATCHES)
        .setMatchMode(ScanSettings.MATCH_MODE_AGGRESSIVE)
        .setNumOfMatches(ScanSettings.MATCH_NUM_ONE_ADVERTISEMENT)
        .setReportDelay(0L)
        .build();

ScanMode

Безусловно, это самый важный параметр. Определяет метод и время сканирования в Bluetooth стеке. Такая операция требует много энергии и необходим контроль над этим процессом, чтобы не разрядить батарею телефона быстро. Есть 4 режима работы, в соответствии с руководством Nordics:

SCAN_MODE_LOW_POWER. В этом режиме Android сканирует 0.5с, потом делает паузу на 4.5с. Поиск может занять относительно длительное время, зависит от того насколько часто устройство посылает пакет advertisement данных.
SCAN_MODE_BALANCED. Время сканирования: 2с, время паузы: 3с, “компромисный” режим работы.
SCAN_MODE_LOW_LATENCY. В этом случае, Android сканирует непрерывно, что очевидно требует больше энергозатрат, при этом получаются лучшие результаты сканирования. Режим подходит если вы хотите найти свое устройство как можно быстрее. Не стоит использовать для длительного сканирования.
SCAN_MODE_OPPORTUNISTIC. Результаты будут получены, если сканирование выполняется другими приложениями! Строго говоря, это вообще не гарантирует, что обнаружится ваше устройство. Стек Android использует этот режим в случае долгого сканирования, для понижения качества результатов (см. ниже “Непрерывное сканирование”).

Callback Type

Настройка контролирует как будет вызываться callback со ScanResult в соответствии с заданными фильтрами, есть 3 варианта:

CALLBACK_TYPE_ALL_MATCHES. Callback будет вызывать каждый раз, при получении advertisement пакета от устройств. На практике - каждые 200-500мс будет срабатывать сallback, в зависимости от частоты отправки advertisement пакетов устройствами.
CALLBACK_TYPE_FIRST_MATCH. Callback сработает один раз для устройства, даже если оно далее будет снова посылать advertisement пакеты.
CALLBACK_TYPE_MATCH_LOST. Callback будет вызыван если получен первый advertisement пакет от устройства и дальнейшие advertisement пакеты не обнаружены. Немного странное поведение.

В практике обычно используются настройка CALLBACK_TYPE_ALL_MATCHES или CALLBACK_TYPE_FIRST_MATCH. Правильный тип зависит от конкретного случая. Если не знаете - используйте CALLBACK_TYPE_ALL_MATCHES, это дает больше контроля при получении callback, если вы останавливаете сканирование после получения нужных результатов - фактически это CALLBACK_TYPE_FIRST_MATCH.

Match mode

Настройка того, как Android определяет “совпадения”.

MATCH_MODE_AGGRESSIVE. Агрессивность обуславливается поиском минимального количества advertisement пакетов и устройств даже со слабым сигналом.
MATCH_MODE_STICKY. В противоположность, этот режим требует большего количества advertisement пакетов и хорошего уровня сигнала от устройств.

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

Number of matches

Параметр определяет сколько advertisement данных необходимо для совпадения.

MATCH_NUM_ONE_ADVERTISEMENT. Одного пакета достаточно.
MATCH_NUM_FEW_ADVERTISEMENT. Несколько пакетов нужно для соответствия.
MATCH_NUM_MAX_ADVERTISEMENT. Максимальное количество advertisement данных, которые устройство может обработать за один временной кадр.

Нет большой необходимости в таком низкоуровнем контроле. Все что вам надо - быстро найти свое устройство, используйте первые 2 варианта.

Report delay

Задержка для вызова сallback в милисекундах. Если она больше нуля, Android будет собирать результаты в течение этого времени и вышлет их сразу все в обработчике onBatchScanResults. Важно понимать что onScanResult не будет вызываться. Обычно применяется, когда есть несколько устройств одного типа и мы хотим дать пользователю выбрать одно из них. Единственная проблема здесь - предоставить информацию пользователю для выбора, это должно быть больше чем MAC-адрес.

Важно: есть известный баг для Samsung S6 / Samsung S6 Edge, когда все результаты сканирования имеют один и тот же RSSI (уровень сигнала) при задержке больше нуля.

Прим. переводчика: в моему случае требовалось обнаружить 2 однотипных устройства, при этом каждое из них имело свое имя, которое отображалось в UI.

Кеширование Android Bluetooth стека

Процесс сканирования дает вам список BLE устройств и при этом данные устройств “кешируются” в Bluetooth стеке. Там хранится основная информация: имя, MAC-адрес, тип адреса (публичный, случайный), тип устройства (Classic, Dual, BLE) и т.д. Android нужны эти данные, чтобы подключится к устройству быстрее. Он кеширует все устройства, которые видит при сканировании. Для каждого из них записывается небольшой файл с данными. Когда вы пытаетесь подключиться к устройству, стек Android ищет соответствующий файл, чтобы прочитать данные для подключения. Важный момент - одного MAC-адреса недостаточно для успешного подключения к устройству!

Очистка кеша

Bluetooth cache, как и любой другой, не существует вечно и есть 3 ситуации когда он очищается:

Выключение и включение системного переключателя Bluetooth,
Перезагрузка телефона,
Очистка в ручном режиме в настройках телефона.

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

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

// Get device object for a mac address
BluetoothDevice device = bluetoothAdapter.getRemoteDevice(peripheralAddress)
// Check if the peripheral is cached or not
int deviceType = device.getType();
if(deviceType == BluetoothDevice.DEVICE_TYPE_UNKNOWN) {
    // The peripheral is not cached
} else {
    // The peripheral is cached
}

Это важно, если нужно подключиться к устройству позже, не сканируя его. Подробнее об этом позже.

Непрерывное сканирование?

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

В последнее время Google ограничивает (недокументированно) непрерывное сканирование:

c Android 8.1 сканирование без фильтров блокируется при выключенном экране. Если у вас нет никаких ScanFilters, Android приостановит сканирование, когда экран выключен и продолжит, когда экран снова будет включен. Комментарии от Google. Это очевидно очередной способ энергосбережения от Google.
c Android 7 вы можете сканировать только в течение 30 минут, после чего Android меняет параметры на SCAN_MODE_OPPORTUNISTIC. Очевидное решение, перезапускать сканирование с периодом менее, чем 30 мин. Посмотрите commit в исходном коде.
с Android 7 запуск и останов сканирования более 5 раз за 30 секунд временно отключает сканирование.

Непрерывное сканирование в фоне

Google значительно усложнил сканирование на переднем плане. Для фонового режима вы столкнетесь с еще большими трудностями! Новые версии Android имеют лимиты на работу служб в фоновом режиме, обычно после 10 минут работы, фоновый сервис прекращает свою работу принудительно. Посмотрите возможные решения этой проблемы:

Обсуждение на StackOverflow
Статья David Young

Прим. переводчика: я использовал Foreground Service, потому что после сканирования, будет длительный обмен данными с устройствами в процессе использованя аппы. Один из плюсов этого решения - работает в Doze Mode.

Проверка разрешений (permissions)

Есть еще несколько важных моментов, прежде чем мы закончим статью. Для начала сканирования нужны системные разрешения (permissions):

<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

Убедитесь что все разрешения одобрены, или запросите их у пользователя. Разрешение ACCESS_COARSE_LOCATION Google считает “опасным” и для него требуется обязательное согласие пользователя.

private boolean hasPermissions() {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
        if (getApplicationContext().checkSelfPermission(Manifest.permission.ACCESS_COARSE_LOCATION) != PackageManager.PERMISSION_GRANTED) {
            requestPermissions(new String[] { Manifest.permission.ACCESS_COARSE_LOCATION }, ACCESS_COARSE_LOCATION_REQUEST);
            return false;
        }
    }
    return true;
}

Прим. переводчика, в моем проекте для корректной работы с BLE потребовалось еще 2 разрешения: ACCESS_FINE_LOCATION (для API<23) и ACCESS_BACKGROUND_LOCATION обсуждение на Stackoverflow.

В итоге полный список разрешений включая версию Android10:

<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

После получения всех нужный разрешений, нужно проверить включен Bluetooth, если нет - используйте Intent для запуска запроса на включение:

BluetoothAdapter bluetoothAdapter = BluetoothAdapter.getDefaultAdapter();
if (!bluetoothAdapter.isEnabled()) {
    Intent enableBtIntent = new Intent(BluetoothAdapter.ACTION_REQUEST_ENABLE);
    startActivityForResult(enableBtIntent, REQUEST_ENABLE_BT);
}

Следующая статья: подключени и отключение

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

Спасибо!

Provisioning ios часть-2.

2017-08-30T10:00:00+00:00

Перевод статьи DEMYSTIFYING IOS PROVISIONING PART 2: CREATING AND ASSIGNING CERTIFICATES AND PROFILES

Перевод первой части здесь

Разрушая мифы iOS Provisioning, часть 2: управление сертификатами и профилями.

В первой части этой статьи мы узнали что такое сертификаты и профили, как они используются в разработке под платформу Apple. Во второй части статьи мы обсудим как создать все нужное для подписи приложения в личном кабинете разработчика на сайте Apple и как это подключить в Xcode.

Наши задачи:

создать App ID
сгенерировать development and App Store сертификаты
создать development и distribution provisioning профили
создать схему (назовем ее App Store) в Xcode проекте
настроить сертификаты и профили в схеме

Многие задачи выполняются в разделе Provisioning в личном кабинете разработчика на сайте Apple Developer.

Если у вас уже есть оплаченный аккаунт, откройте Apple Developer website, выберете “Account” -> “Certificates, Identifiers & Profiles.”

Создание App IDs

App ID это уникальный идентификатор для регистрации вашего приложения. Первым делом, давайте создадим его.

Шаги для регистрации на сайте apple разрабочика:

Выберите “App IDs” под вкладкой “Identifiers”
Нажмите “+” вверху списка
Введите имя для App ID (используйте название приложения или название + дополнительное имя)
Выберите “Explicit App ID” и введите ваш Bundle ID в текстовое поле
Под “App Services” раздела, выберите сервисы нужные для вашего приложения (их можно будет отредактировать позже)
Нажимаем “Continue”
Если все хорошо - выбираем “Register”

Это все. Bundle ID зарегистрирован и можно генерировать профили на основе этого ID. Если в будущем вы измените Bundle ID, придется также удалить App ID (если он не будет использоваться) и пересоздать новый App ID.

Так, а в чем тогда разница между App ID и Bundle ID? В общем App ID это уникальный идентификатор приложения в экосистеме App Store, не может быть двух приложений там с одинаковыми App ID. Bunlde ID это идентификатор учетной записи разработчика (используется обратная доменная запись - com.mysite.appname).

Создание сертификатов

Я расскажу вам как создавать сертификат для App Store (другие сертификаты созадаются аналогично). Сертификат можно использовать для разработки и распространения всех ваших приложений.

Первое - нужно создать Certificate Signing Request (CSR) в личном кабинете разработчика, для этого:

на вашем Mac откройте Keychain Access (находится тут - /Applications/Utilities).
далее в Keychain Access > Certificate Assistant > Request a Certificate From a Certificate Authority.
в окне введите ваш email и имя, затем выберите “Save to disk” в опции “Request is”.
жмите Contunue и сохраните файл на компьютере Mac.

Теперь у на есть CSR, и мы готовы сгенерировать рабочий сертификат, для этого заходим в личный кабинет и:

идем в раздел Certificates, Identifiers & Profiles > Certificates > All
нажимаем “+” чтобы создать новый сертификат
выбираем “iOS App Development” для создания development сертификата для отладки на зарегистрированных устройствах
Continue
дальше будут инструкции как сгенерировать CSR (мы уже это сделали!)
загрузите запрос CSR (инструкции прилагаются)
жмем на Download для загрузки сгенерированного сертификата, после этого двойным кликом мышки добавляем его в Keychain Access

Для проверки что сертификат установлен в системе, зайдите в Keychain Access > Login Keychain > Certificate, вы должны увидеть публичный и приватные ключи с префиксом “iPhone Developer” (это значит что сертификат для подписки ios приложений, у сертификатов для Mac приложений будет - “Mac development”).

“App Store and Ad Hoc” сертификаты создаются аналогично (разница в п.3 только), сертификат действителен один год, по окончании срока его нужно удалить и создать новый, при этом все связанные provisioning профили аннулируются и их также придется повторно сгенерировать.

Регистрация устройств

Тестовые устройства для отладки приложений регистрируются в помощью UDID - уникального идентификатора. Он включается в provisioning профили (создадим на следующем шаге), при добавлении/удалении нового устройства нужно повторно сгенерировать provisioning профиль. Поэтому мы сделаем этот шаг первым.

UDID устройства можно найти в iTunes или в Xcode (подключите устройство к Mac запустите Xcode, найдите в Window > Devices > ваше устройство и скопируйте UDID строку в разделе “Identifier”), это уникальный идентификатор вашего физического устройства.

Для регистрации UDID:

идем в Certificates, Identifiers & Profiles > Devices > All (личный кабинет разработчика)
жмем “+” для добавления нового устройства
вводим имя, мы рекомендуем формат для этого “Имя/Тип устройства/Добавлен или Изменен/Дата”, удобно для больший команд
вводим UDID
нажимаем “Contunue”

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

Создание профилей

Provisionig профиль это ключевой момент для подписи приложения. Он определяет какие устройства имеют право запускать подписанное приложение, указывает на сертификат для подписи приложения, а также какие сервисы будут доступны для приложения на этом устройстве (iCloud, APNs и т.д).

Создать provision профиль довольно просто в личном кабинете разработчика, для этого:

идем в Certificates, Identifiers & Profiles > Provisioning Profiles > All и видим список созданных профилей
жмем “+” для добавления нового профиля
выбираем из списка “iOS App Development” и жмем на Continue
далее выберите App ID (созданный ранее) и опять Continue
на этом экране вам предлагают выбрать сертификат для подписи профиля, указываем только что созданный сертификат, и жмем Contunue (можно выбрать несколько сертфикатов для профиля, каждый из них может подписать приложение)
на экране “Select Devices” укажите устройства, на которых вы будете запускать приложение
экран “Generate” предлагает дать профилю читаемое имя, в MartianCraft мы обычно используем формат: [App Name]: [Profile Type] Profile (например “MartianApp: Development Profile”), жмем по привычке Continue
итак на последнем экране (вы тоже не любите неуместное употребление “крайний”?) можно загрузить созданный профиль. После загрузки перетащите его на иконку Xcode в доке (быстрый способ добавить файл в ~/Library/MobileDevice/Provisioning Profiles, это директория для всех профилей, можно сделать это вручную).

Для создания App Store профиля повторяем весь процесс, но на шаге 3 выбираем “App Store”, это профиль для распространия приложений в AppStore, и поэтому в него нельзя добавить устройства.

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

Процесс обновления профиля простой: идем в Certificates, Identifiers & Profiles in the provisioning portal > Provisioning Profiles > All, находим нужный профиль и жмем Edit для изменений App ID, настроек сертификата или списка устройств.

Работа с схемами и сертификатами в Xcode

Наконец-то у нас есть все для подписи iOS приложения, мы соберем все вместе внутри Xcode и свяжем сертификат и provisioning профиль в особую схему.

По умолчанию, XCode автоматически создает две схемы: Debug и Release. Воспользуемся ими, для Debug схемы мы будем использовать Development профиль и сертификат, для Release - AppStore профиль и сертификат. Открываем “General” вкладку и ищем там “targets” (помним что для этого используем сертификаты добавленные в Keychain и Provisioning profiles это папка в XCode см. выше).

Снимаем галочку “Automatically manage signing”, так как мы будем подписывать “самостоятельно”. После этого появятся две секции: “Signing (Debug)” и “Signing (Release).”

В Signing (Debug) > Provisioning Profile выставляем Development профиль, а в Signing (Release) - AppStore профиль.

Это все что нужно сделать для работы с профилями в “ручном” режиме. Мне кажется не так уж и сложно :) Теперь можно и поработать.

Частые ошибки и как их исправить

Provisioning Profile doesn’t match bundle ID Это значит что provisioning профиль был сгенерирован с неправильным App ID/Bundle ID и профиль содержит Bundle ID от другого проекта.
Code Signing Entitlements file do not match those specified in your provisioning profile Локальные права не соответствуют профилю (посмотрите Capabilites вкладку). При добавлении сервисов типа iCloud, Keychain они должны быть зарегистрированы в профиле.
No Matching Provisioning Profiles Found случается когда сертификату не имеет связанных профилей для подписи приложений. Проверьте что профиль импортирован в Xcode (можно вручную открыть папку: ~/Library/MobileDevice/Provisioning Profiles), посл этого в личном кабинете убедитесь, что профиль использует необходимый сертификат, в случае необходимости обновите профиль.

Более подробно ошибки описаны на сайте для разработчиков Apple Developer.

Сборка и подпись приложения

С нашими настройками удобно создавать сборки приложения и запускать на зарегистрированных устройствах. Для выпуска приложения под AppStore следует выбрать “Generic iOS Device”, затем Product > Archive, будет создан архив, подписанный профилем-сертификатом “AppStore Provisioning”.

Отправка приложения происходит в Xcode Organizer (Window > Organizer), выбирайте архив для отправки в AppStore и следуйте инструкциям в окне. Не забываем выбрать “Use local signing assets” при выборе команды разработчиков.

Выводы

В этих двух статьях мы рассмотрели все этапы provisioning процесса, для новичков это может показаться непростым делом, к счастью это нужно делать только раз в год и для старта нового проекта. Все коснулись всех базовых моментов provisioning и сборки приложения, если еще остались вопросы, у Apple есть несколько видео с прошлых WWDCC для более глубокого понимания процесса, ссылки ниже.

Ссылки на видео

Спасибо!