2018/12/23

Android: 擬似的に日本に夏時間を導入してテストする

はじめに

i18n対応で考えないといけないことの1つに夏時間(Daylight Saving Time)があります.
夏時間のテストはいくつかの理由で難しい場合が多いです.

  • サーバAPI開発中で, 海外へのサービス提供が蓋閉めされている
  • 夏時間がくるまで待てない

そこで, 日本でも夏時間が導入されていることにして, 好きなタイミングでJST(Japan Standard Time)↔️JDT(Japan Daylight Saving Time)を切り替えられればテストが捗りそうです.

本稿は, そのような環境を構築するためにTZDB(Time Zone Database)をテスト用に編集して, それをシステムに認識させる方法を紹介します.

本稿執筆時点でのTZDB Versionは2018gが最新です. 以降は最新が 2018g の前提で話を進めます.

ThreeTenBp と ThreeTenABP

ThreeTenBpはTime Zone情報のロード周りでメモリ効率が悪いため, Android向けにThreeTenABPが提供されています.

ThreeTenBpを使用するためにはTime Zone情報を提供する必要があります.
ThreeTenABPはその手続きを肩代わりしてくれるライブラリです.

ThreeTenABPは, ThreeTenBp(/IANA)が提供する TZDB.dat を Assetsに内包し, AndroidThreeTen.init でこれを ZoneRulesProviderに登録する AssetsZoneRulesInitializerを実行します.

ThreeTenABPがやっていることはこれだけです.
自前でAssetsZoneRulesInitializerTZDB.datを用意して, ZoneRulesProvider に登録すれば同じことが実現できるので, 次のようなクラスを用意しておけば, 好きなTZDB.datを登録できるようになります.

class AssetsZoneRulesInitializer(private val context: Context) : ZoneRulesInitializer() {
  override fun initializeProviders() {
    context.assets.open("TZDB.dat").use {
      ZoneRulesProvider.registerProvider(TzdbZoneRulesProvider(it))
    }
  }
}

// Application.onCreateで下記を実行する
ZoneRulesInitializer.setInitializer(AssetsZoneRulesInitializer(this))

今回は, テスト用に定義した TZDB.data を作成・登録することで, 擬似的に日本にも夏時間があることにします.

カスタム TZDB.dat 生成手順

  1. ThreeTenBP GitHubをクローン
  2. IANAから最新のTZDBをダウンロード
  3. クローンしたソースの src/tzdb/{tzdb-version} に, 展開したTZDBファイルを移動
  4. TZDBを編集
  5. mvn clean package -Dtzdb-jar を実行
  6. target/threeten-TZDB-{version}.jar から TZDB.dat を抽出

1. ThreeTenBP GitHubをクローン

ThreeTenBP GitHub にはTZDBを読み込んでビルドし, TZDB.datを生成するコンパイラ TzdbZoneRulesCompiler があります.
TzdbZoneRulesProviderに読み込ませるTZDB.datを生成するためにこのレポジトリをクローンします.

2. IANAから最新のTZDBをダウンロード

TZDBを管理するInternet Assigned Numbers Authority(IANA)から最新のTZDBをダウンロードすることができます.

ダウンロードできる種類がいくつかありますが, 今回はタイムゾーン情報があればよいので “tzdata2018g.tar.gz - Data Only Distribution” を選びます.

3. クローンしたソースの src/tzdb/{tzdb-version} に, 展開したTZDBファイルを移動

手順2でダウンロードした tar.gz を展開するとTZDBファイルが入っています.
このTZDBファイルを, 手順1でクローンしたThreeTenBpsrc/tzdb/{tzdb-version}ディレクトリに移動します.

クローン直後は srcディレクトリ直下に tzdb ディレクトリはないので作成しておきます.
また, 注意点として {tzdb-version} の名前は下記の正規表現にマッチする必要があります

[12][0-9][0-9][0-9][A-Za-z0-9._-]+

OK: 2018g
NG: tzdb-2018g

tar.gzを展開してできるディレクトリ名には余計なプレフィックス tzdb- が入っているので注意が必要です.

最終的に, asia ファイルの場所は下記になります.

{threetenbp-root}/src/tzdb/2018g/asia

4. TZDBを編集

手順3で移動したTZDB情報を編集します.
今回は日本に夏時間があった場合をシミュレーションするため “Asia/Tokyo” リージョンの情報が定義されている {threetenbp-root}/src/tzdb/2018g/asia ファイルを編集します.

日本(Asia/Tokyo)のタイムゾーン情報は 2018g では次のように定義されています.

# Rule  NAME    FROM    TO  TYPE    IN  ON  AT  SAVE    LETTER/S
Rule    Japan   1948    only    -   May Sat>=1  24:00   1:00    D
Rule    Japan   1948    1951    -   Sep Sat>=8  25:00   0   S
Rule    Japan   1949    only    -   Apr Sat>=1  24:00   1:00    D
Rule    Japan   1950    1951    -   May Sat>=1  24:00   1:00    D

日本でも過去に夏時間(夏時刻法)があったことがわかります.

TZDBのフォーマットは人間にも読めるようになっています.
フォーマットルールはzic man pageに載っています.
これに則り, 日本に夏時間を導入するため次の1行を追加してみましょう.

Rule  Japan  2018  only  -  Dec  23  00:00  1:00  D

これで, TZDB的には 2018/12/23 00:00:00(JST) から日本では夏時間(JDT)が適用されるようになります.

5. mvn clean package -Dtzdb-jar を実行

TzdbZoneRulesCompilerを使って編集したTZDBをもとに TZDB.dat を生成します.
ThreeTenBpのルートで下記のコマンドを実行するとTzdbZoneRulesCompilerがビルドを始めます.

mvn clean package -Dtzdb-jar

実行するとビルドログが出力されます.
下記のように Source directory contains no valid source folders のログが出力される場合はTZDBのディレクトリ名かパスが間違っており, TzdbZoneRulesCompilerがTZDBをうまく認識できていない可能性があります. その場合は手順2をやり直しましょう.

Source filenames not specified, using default set
(africa antarctica asia australasia backward etcetera europe northamerica southamerica)

は, 今回特にファイル名を指定していないので出力されても問題ありません.

...
[INFO] --- exec-maven-plugin:1.2.1:java (default) @ threetenbp ---
Source filenames not specified, using default set
(africa antarctica asia australasia backward etcetera europe northamerica southamerica)
Source directory contains no valid source folders: xxx
...

編集したTZDBがうまく読み込まれなかった場合も BUILD SUCCESS となるので注意してください. その場合, 後述の threeten-TZDB-2018g.jar が出力されません.

6. target/threeten-TZDB-{version}.jar から TZDB.dat を抽出

TzdbZoneRulesCompiler のビルド結果はThreeTenBpプロジェクトルート直下の target ディレクトリに出力されます.
ビルドが成功すると target/threeten-TZDB-2018g.jar が出力されます.

このJarファイルに目的のTZDB.datが含まれているので, それを抽出します.
下記のJarコマンドで内包されているファイルパスの一覧を取得します.

jar tf {threeten-TZDB-2018g.jar のパス} 

今回のケースでは org/threeten/bp/TZDB.datTZDB.datがありました.
同じくJar コマンドでこれを抽出します.

jar -xvf {threeten-TZDB-2018g.jar のパス} org/threeten/bp/TZDB.dat

コマンドを実行したディレクトリに org/threeten/bp/TZDB.dat が抽出されます.

テスト

日本にも夏時間が定義されたTZDB.dat が作成できたので, これをZoneRulesProviderに登録します.

class AssetsZoneRulesInitializer(private val context: Context) : ZoneRulesInitializer() {
  override fun initializeProviders() {
    context.assets.open("TZDB.dat").use {
      ZoneRulesProvider.registerProvider(TzdbZoneRulesProvider(it))
    }
  }
}

// Application.onCreateで下記を実行する.
// AndroidThreeTen.initは実行しない(ThreeTenABPは使わない)
ZoneRulesInitializer.setInitializer(AssetsZoneRulesInitializer(this))

この状態で, ZonedDateTimeを使って日本時間表示してみると夏時間が適用されていることがわかります.

ZonedDateTime
  .now(ZoneId.of("Asia/Tokyo"))
  .format(DateTimeFormatter.ISO_DATE_TIME)

// 出力: 2018-12-23T15:26:19.295+10:00[Asia/Tokyo]

ZoneId.of("Asia/Tokyo").rules.isDaylightSavings(Instant.now())

// 出力:true

以上です.

参考:

2018/12/14

不変条件とか, Nullabilityとか, Kotlin化とか

備忘録. 走り書き.
Kotlin化するときに苦しんだお話.

Java → Kotlin化する時によく困るのがNullabilityの判断.
ある日, こんな感じのコードに出会った.

class Hoge {
  public final String id;
  protected String foo;

  public static Hoge from(proto HogeProto) {
    if (proto == null) throw new IllegalArgumentException(...);

    Hoge hoge = Hoge(proto.id)
    hoge.foo = Wire.get(proto.foo, HogeProto.DEFAULT_FOO)
    return hoge;
  }

  private Hoge(String id) { 
    this.id = id;
  }
  ...
}

APIコールの応答として HogeProto を受け取り, それをモデル Hoge に変換させるコード. (Protocol Buffers と Wireライブラリを使ってる)

直したい部分がいくつかある.

まず, proto.id がJavaのString型なので null の可能性を捨てきれない.
もし, とってもラッキーなことに, 全く正しく疑う余地のない最新のドキュメントが存在していて「idは絶対にnullにならない」って明記されていたり, サーバサイドのコードが assert id != null の不変条件を表明していたりする場合は, requireNotNull(...) の一文を事前条件として追加できるかもしれない.

  public static Hoge from(proto HogeProto) {
    requireNotNull(proto, "...");
    String id = requireNotNull(proto.id, "...");

    Hoge hoge = Hoge(id);
    ....

でも, 残念なことに今回はそんな状況じゃなかった.

ビジネス上, proto.idnull である可能性が限りなく乏しい状況だけれど, 数千万のユーザを抱えるサービスのエンジニアとしての責任を考えると「大丈夫でしょ♪」と根拠のない自信だけで例外を投げるチェックコードを追加する訳にもいかないし, そんなコードをリリースした夜はきっと眠れない(私は少し心配性).

サービスやコードの規模が大きくなった後で, こうしたチェックを追加するのはかなり苦労する. この問題は, Hogeクラスのコードを書いたプログラマがちょっと気を利かせて, Hogeクラスの不変条件をコードで表明しておいてくれれば助かるケースだった.

不変条件が追加できると判断できれば, Kotlin化もスムーズに滞りなくできる.

class Hoge (
  val id: String
) {
  companion object {
    fun from(HogeProto proto): Hoge {
      requireNonNull(proto) {...}
      val id = requireNotNull(proto.id) {...}

      Hoge(id)
      ...
}

IDの不変条件の話はこれぐらいにして, Hogeクラスにはもう一つ問題があった.
でもそれはIDの問題と比べればとっても小さい問題. 相手はフィールド foo.

class Hoge {
  ...
  protected String foo;

  public static Hoge from(proto HogeProto) {
    ...
    Hoge hoge = Hoge(proto.id)
    hoge.foo = Wire.get(proto.foo, HogeProto.DEFAULT_FOO)
    return hoge;
  }
  ...
}

foo のアクセス修飾子は protected. たぶん書いた当時はユニットテストからアクセスさせるためにスコープを広くとったんだと思う.
だったら @VisibleForTesting をつけてほしいけど, まぁ本題じゃないのでそれは横に置いといて…(よくないけど)

実はHogeクラスはモデルというより POJO なクラス. ビジネスロジックを持っている訳でもないし, DTO 的な使われ方をする. Kotlin化で data class になるようなヤツ.
なので, 実際に foo は一度初期化されれば, その後変更されない.

だけれども foo はコンストラクタで初期化されていない.
なので, この状態で フィールドfoo の宣言文に @NonNull アノテーションをつけるとIDEが @Not-null fields must be initialized ってWarningを表示する(そりゃそうだ).
何も考えずKotlin化すると lateinit になっちゃうとこだけど, それはこのクラスの実態にあっていないから, そんなことはしたくない.

Kotlin化するときは引数やフィールドのNullabilityをはっきりとさせるためのチェックとして Javaコードに @NonNull, @Nullable を付けてからKotlin化するようにしているけれど, こういう foo のようなコードを書かれると, 問題解消のための一手間が必要になる.

でもこれはIDの問題と比べればとっても小さい問題. foofinal にすれば解消できる(もちろん, そうできるなら… だけど)

class Hoge {
  @NonNull public final String id;
  @NonNull public final String foo;

  public static Hoge from(proto HogeProto) {
    requireNotNull(proto, "...");
    String id = requireNotNull(proto.id, "...");

    return Hoge(
      id,
      Wire.get(proto.foo, HogeProto.DEFAULT_FOO)
    );
  }

  private Hoge(String id, String foo) { 
    this.id = id;
    this.foo = foo;
  }
  ...
}

ここまでくれば, すぐにでもkotlin化に着手できる.

ちょっと id の話に戻るけど,,,
HogeProto 側にある “デフォルト値” の意味を考えると idWire.get(proto.id, HogeProto.DEFAULT_ID) って形で取得した方がいいのかな〜って思ったりする.
でも, 大抵 DEFAULT_ID って空文字だろうし, モデル Hoge としてはIDに空文字を許したくないので, 結局次のようなコードが必要になる.

String id = Wire.get(proto.id, HogeProto.DEFAULT_ID);
if (StringUtil.isNullOrEmpty(id)) throw new IllegalArgumentException(...);

“空文字を許さない” って部分をちゃんと事前条件として表明できているのはいいことだし, もし DEFAULT_ID が “空文字ではない何か” に置き換わるアップデートが proto にあったとしてもうまく対応できそうだ.

大切にしたいのは, proto はあくまで “APIレスポンスの仕様” ってだけで, クラス Hoge はアプリ内で使われるモデルやデータとして正しい形で存在してなきゃいけないってところ.
Hoge クラスに「こうあってほしい」って考えをコードに落とし込むってところ.

“理解なんてものは概ね願望に基づくものだ” ってセリフがある.
自分の理解をコードを通して他人にも理解させるってとこは, 願望のコード化でもあるなと思った.

閑話休題. 本題のkotlin化に戻る.

Nullabilityもハッキリして, 不変条件まで付いてくればKotlin化はかなり楽になる.
ただ, Hoge のコードには現れていないけれど, Javaの頃によくやった NullObject Pattern が意外とKotlin化する上で厄介だったりする.

例えば, もし次のようなコードがあった場合にちょっと困る.

final Hoge EMPTY = Hoge(null);

だいたい, UNKNOWN とか EMPTY みたいな名前と一緒に NullObject Pattern が使われている.
↑のケースだと, Hoge.idnullable (String?) にしなきゃいけなくなるし, わざわざ HogeEMPTY かどうかを各所でチェックする必要が出てくる.
nullを許容して Hoge? なプロパティや引数をとる方が isEmpty チェック漏れを心配する必要もない.

Javaの頃はこういうオブジェクトがあればnull-safeなコードが書けたので重宝したけど, Kotlinだと言語レベルでnull-safeをサポートしているので, NullObject Patternの必要性がかなり下がると思った.
むしろ, あると邪魔なケースが多くて, ??: で解決できるようなところをわざわざif (obj !== UNKNOWN) みたいにしなきゃいけないし, null であってくれたほうが, 型チェック(nullable or not-nullable)の機構が働くので嬉しいことが多い.

特に何もしないデフォルトリスナーとかを NullObject にしているケースなんかは nullable にしてもさほど困らなさそう.
ただ, nullNullObjectを明確に区別する使い方をしているケースだと簡単に nullable にはできないので厄介だったりする.

以上, 走り書きでした.

2018/10/23

Android: DownloadManagerのタスク管理と競合

タスクの状態

開発者はダウンローダへの要求をアクションとして表現します. アクションには ダウンロード削除 の2種類があり, ダウンローダはこれらをタスクとして処理していきます.
ExoPlayer downloaderはタスクの状態を2種類定義しています.
1つはTaskStateとして外部に公開される状態で下記の状態と遷移を持ちます.

状態リスト:

State Description
queued 開始待機状態
started 開始済み状態
completed 完了状態
canceled キャンセル状態
failed 失敗状態

状態遷移:

もう1つは外部に公開されない, DownloadManagerの内部管理用の状態です.
主に, “キャンセル中”や”停止中”といった状態遷移中の状態が定義されています.

内部状態リスト:

State Description
queued 開始待機状態
started 開始済み状態
completed 完了状態
canceled キャンセル状態
failed 失敗状態
queued_canceling 開始待機キャンセル中状態
started_canceling 実行キャンセル中状態
started_stopping 実行停止中状態

内部状態遷移:

ExoPlayer downloaderを使う上では前者の公開用状態を把握しておけば十分なのですが、ダウンローダの振る舞いを把握するには後者の内部状態を把握しておいた方が理解が進みます。

DownloadManagerのタスク管理と競合

DownloadManagerはタスクの状態変更を DownloadManager.onTaskStateChange 検知します.
ここでタスクの状態がアクティブではない場合, タスクの開始が試みられます.
タスクが下記の条件を満たす場合にはアクティブであると判断されます.

    /** Returns whether the task is started. */
    public boolean isActive() {
      return currentState == STATE_QUEUED_CANCELING
          || currentState == STATE_STARTED
          || currentState == STATE_STARTED_STOPPING
          || currentState == STATE_STARTED_CANCELING;
    }

要するにタスクが何かしらのアクション中であればアクティブと判断されます.

DownloadManagerは次の条件が全て満たされていることを確認してタスクを開始します.

  1. タスクがまだ開始されていないこと(taskstate == queued)
  2. 既にあるタスクと競合しないこと
  3. ダウンロードタスクの場合, 先行するダウンロードタスクが保留中ではない. かつ, アクティブダウンロード数の上限に達していないこと

1はわかりやすいですね. 既に開始済みのタスクを再び開始することはできないということです.
DownloadManagerは, タスクの状態に関わらずタスクリストの先頭から順番に開始を試みます. 既に開始済みのタスクはここで除外されます.

3の”アクティブダウンロード数の上限”はDownloadManagerのコンストラクタ引数 maxSimultaneousDownloads が参照されます.
また, これはダウンロードタスクに課せられる条件で, 削除タスクはこの条件に該当しません.

2は少し複雑です. DownloadManagerは次の2点をチェックしてタスク(アクション)の競合を検知します.

  1. 同じコンテンツに対するアクションか
  2. いずれかのアクションが削除アクションであるか

DownloadManagerはタスクリストの先頭から順番に開始を試みる過程で, 同タスクリスト内の他タスクと競合していないかを検知するためにタスク同士を比較します.
タスクが扱うコンテンツの同一性は DownloadAction.isSameMedia を使って判定され, タスクに紐づくアクションが持つ uri が同じかどうかで判断されます.

  /** Returns whether this is an action for the same media as the {@code other}. */
  public boolean isSameMedia(DownloadAction other) {
    return uri.equals(other.uri);
  }

同じコンテンツに対するアクションがタスクリスト内に複数見つかった場合, 比較元あるいは比較先のタスクのいずれかが削除アクションである場合は “競合した” と判定されます.
例えば, とあるコンテンツAをダウンロード中に, 同コンテンツに対して削除アクションを投げるとこの状態になります.

タスクが競合すると, 比較元が削除アクションであれば比較対象のタスクがキャンセルされ, 比較元の削除タスクもスキップされます(キャンセルはされません).
比較対象のタスクが削除アクションであれば比較元のタスクはスキップされます(キャンセルはされません).

タスクがキャンセルされるとタスクの状態が変化するので DownloadManager.onTaskStateChange が呼ばれます. DownloadManager.onTaskStateChange ではタスクの状態がアクティブではない場合にタスクの開始を試みるので, ここで再びタスクの開始が試みられます. スキップされた削除タスクはアクティブにはなっておらず, また競合していたタスクはキャンセルされているので競合は発生しなくなります.

これによって, とあるコンテンツAをダウンロード中に, 同コンテンツに対して削除アクションを投げるとダウンロード処理はキャンセルされて, ダウンロードのキャンセル処理が終了した後に削除処理が行われることになります.

ダウンローダの開始と停止

DownloadServiceが起動されるとRequirementsHelperを登録してデバイス状態の監視を始めます.
デバイスの状態がダウンロード開始条件を満たした場合, いよいよダウンロード処理が開始されます.

DownloadManagerはダウンローダ停止状態を示す downloadsStopped フィールドを内部に持っています.
このフィールドが false の時, ダウンロードアクション/タスクが追加されたとしても新しくダウンロードが開始されることはありません.
ダウンローダを開始するには DownloadManager.startDownloads を呼び出して, このフィールドを true にする必要があります.

ダウンローダの状態はダウンローダ停止状態がデフォルトですが, 開発者が明示的に DownloadManager.startDownloads を呼び出してダウンローダを開始する必要はありません.
その理由として, まずDownloadServiceにダウンロードアクションを登録すると, タスクの開始を試みる処理が実行されます.
しかし, このタイミングではダウンローダが停止状態なので, ダウンロードタスクは一旦スキップされます.
スキップされたタスクがどのようにして実行されるのかというと, DownloadServiceがアクション/タスクを追加した後, RequirementsHelperを登録してデバイス状態の監視を始めます.
デバイス状態がダウンロード開始の条件を満たした時, DownloadServiceはDownloadManager.startDownloadsでダウンローダを開始状態にします.
ダウンローダの開始時にはタスクの実行を試みるようになっているので, ここでスキップされたタスクが実行されることになります.

“ダウンロードの開始/停止条件はRequirementsで表現される”と過去の投稿で言いましたが, 厳密には Requirementsはダウンローダの開始条件 になります.
ExoPlayerのダウンローダは開始済みであれば全てのタスクを処理しようとします.
このダウンローダは全てのタスクが消化されたとしても, Requirementsの条件が満たされている限り停止しません.
開発者が手動でDownloadManager.startDownload/stopDownloadを呼び出すときは, Requirementsとの整合性が崩れる可能性がある点に注意しなければいけません.

ちなみに, downloadsStopped はダウンロードアクションに対するものであり, 削除アクションはダウンローダの開始状態に依存しないため, このフィールドが false であっても削除アクションは実行されます.
つまり, Requirementsを満たしていない状態でもコンテンツの削除は可能です.

2018/10/19

Android: ExoPlayer DownloadManager, DownloadService

ExoPlyerのDownloadManager, DownloadServiceを調べた時のメモ.

中断されたアクションを読み込むタイミング

保存されたActionFileの読み込みタイミングはDownloadManagerを初期化したタイミングとなります.

プロセスの強制終了などでActionを完遂できなかった場合, 保存されたActionFileをプロセス再開後に読み込んでダウンロード処理を再開する必要があります.
保存されたActionFileは DownloadManager.loadActions によってバックグラウンドスレッド上で読み込まれ, これはDownloadManagerのコンストラクタで実行されます.

コンテンツの削除はバックグラウンド?

コンテンツを削除するにはremove flagをtrueにしたアクションを発行します.
アクションはDownloadServiceで実行されるので, フォアグラウンドサービスとして実行することが可能です.
削除中の通知も DownloadService.getForegroundNotification で返すNotification objectをカスタマイズすることができます.
また, 通知の雛形として DownloadNotificationUtil.buildProgressNotification が用意されています.
buildProgressNotification は引数のタスクステートに応じて通知の表示内容を変えるため, ダウンロード中通知や削除中通知もこのメソッドで生成できます.

ダウンロード進捗率を取得する

DownloadManager.Listenerの onTaskStateChanged コールバック引数のTaskStateから間近のダウンロード進捗率が取得できます.
TaskState.downloadPercentage がダウンロード進捗率を格納したフィールドです.
ダウンロード進捗率が未定/不明 あるいは 削除タスクである場合は com.google.android.exoplayer2.C#PERCENTAGE_UNSET がセットされます.
DownloadServiceでは, このコールバックを受けて通知の進捗率を更新するようになっています.

タスクの実行順序とダウンロードのキャンセル

タスクはDownloadManagerによってArrayListで管理されており, 新しいタスクはタスクキュー(タスクリスト)の最後尾に追加され, 先頭から順に実行されます.
DownloadManager.handleAction は新しいダウンロード/削除アクションアクションからタスクを生成してタスクキューの最後尾に追加します.
新しく削除アクションがリクエストされた場合, 既に同じメディアファイルのダウンロードタスクがタスクキューに存在するなら, そのダウンロードを即座にキャンセルします.
つまり, ダウンロード中やダウンロードリクエストをキューイングした後にこれをキャンセルしたい場合は削除アクションを投げるとキャンセルできます.

ダウンロードの開始条件

サービスによっては”従量制ネットワーク接続時にはダウンロードしたくない”といった要件があるかもしれません.
あるいは, “NWが瞬断されてダウンロード中断されたけれど, NW接続が回復したら自動再開したい” 要件があるかもしれません.
ExoPlayer Downloaderではデバイスの状態を監視して, こうした要件に応える機能があります.

RequirementsHelper はデバイスの状態を監視し, 特定の条件を満たした場合にダウンロードを開始/再開するヘルパークラスです. ここで指定できる”特定の条件” は Requirements クラスで表現され, Requirementsに指定できる条件は次の通りです.

  1. ネットワーク種別 ( NW接続済み, 従量制NWに接続済み, ローミング中, etc. )
  2. 充電中かどうか
  3. アイドル状態かどうか

また, JobSchedulerによる監視もサポートされています.
JobSchedulerを使用する場合は, Requirementsの情報がJobInfoに変換されてスケジューリングされます.

API Lv.によっては判定できるNW種別の種類や, アイドル状態と判定する条件に差異があるので, JobSchedulerRequirementsのコードを確認した方がよいです.

ダウンロードの開始プロセス

ダウンロードを開始するにはDownloadManagerを初期化して, DownloadServiceを起動し, タスク(アクション)を追加する必要があります.
DownloadServiceは起動されるとRequirementsHelperを起動してデバイス状態を監視し始めます.
デバイスの状態がダウンロード開始条件を満たした場合, いよいよダウンロード処理が開始されます.

RequirementsHelperとスケジューラの生存区間

アプリのプロセスが生きている間はRequirementsHelperが動的ブロードキャストレシーバーを使ってデバイス状態を監視し, ダウンロードを開始/再開させます.
デバイスの監視はDownloadServiceによって開始されますが, ダウンロードが中断されてDownloadServiceが停止してもこの監視は続きます.
これは, デバイスの状態を監視するRequirementsHelperをDownloadServiceのstaticフィールドで保持しているためです.

DownloadServiceがgetSchedulerでスケジューラを指定している場合は, スケジューラでもデバイス状態が監視されます.
スケジューラはAndroid標準のJobSchedulerを使用することができ, これによってアプリのプロセスが停止している場合にもダウンロードを開始/再開させることが可能になります.
スケジューラはダウンロード開始条件が満たされていないと判断された場合にスケジューリングされます.

ダウンロード開始条件が満たされた場合, RequirementsHelperによる監視が続いている(アプリのプロセスが生きている)状態であればRequirementsHelperがダウンロードを開始/再開させて, スケジューラのスケジューリングをキャンセルします.
RequiermentsHelperによる監視がされていない(アプリのプロセスが停止している)状態であればスケジューラによる開始/再開が行われます.

スケジューラだけでデバイス監視しないのは, RequirementsHelper(staticフィールドと動的ブロードキャストレシーバー)を使った方がデバイス状態の検知からダウンロードの開始/再開までを素早く行えるというメリットがあります.

RequirementsとSchedulerとDownloadService

RequirementsとSchedulerは, DownloadServiceのgetSchedulergetRequirementsをオーバーライドして指定します.

  @Override
  protected Requirements getRequirements() {
    return new Requirements(Requirements.NETWORK_TYPE_ANY, false, false);
  }

  @Override
  protected PlatformScheduler getScheduler() {
    return Util.SDK_INT >= 21 ? new PlatformScheduler(this, JOB_ID) : null;
  }

JobScheduler を使ったデバイスの監視を実現するため PlatformScheduler クラスが用意されています. PlatformSchedulerを使うにはAndroidManifest.xmlに次の定義を追加します.

<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>

<service android:name="com.google.android.exoplayer2.util.scheduler.PlatformScheduler$PlatformSchedulerService"
    android:permission="android.permission.BIND_JOB_SERVICE"
    android:exported="true"/>

あるいはFirebaseJobDispatcherを使ったスケジューラ JobDispatcherScheduler も用意されています. JobDispatcherSchedulerを使うにはAndroidManifest.xmlに次の定義を追加します.

  <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>

  <service
      android:name="com.google.android.exoplayer2.ext.jobdispatcher.JobDispatcherScheduler$JobDispatcherSchedulerService"
      android:exported="false">
    <intent-filter>
      <action android:name="com.firebase.jobdispatcher.ACTION_EXECUTE"/>
    </intent-filter>
  </service>
2018/09/19

Android: Exoplayer DownloadManager

Exoplayer r2.8.4のダウンローダ機能関連APIのメモ.

r2.6.0の頃はコンテンツをダウンロードするAPIだけが提供されていましたが, r2.8.0からはダウンロードタスクの管理やダウンロード処理の再開、サービスや通知といった部分までサポートされるようになっています.

関連記事:Android: ExoPlayer - Downloader

DownloadManager

DownloadManager
マルチダウンロードストリームの管理とダウンロードリクエストの削除をするクラスです.
このクラスのメソッドはメインスレッド上から呼び出す必要があり, 複数スレッドからの呼び出しは想定されていません.

ダウンロードマネージャは内部ハンドラを持ちます. もしLooperを持たないスレッドからの呼び出しがあった場合, Looper.getMainLooper()によってメインスレッドが取得されます.

次のコードはダウンロードマネージャーを生成します.

// ダウンロードアクションファイルのデシリアライズに必要なクラスを定義
private val DOWNLOAD_DESERIALIZERS = arrayOf(
  DashDownloadAction.DESERIALIZER,
  HlsDownloadAction.DESERIALIZER)

fun initDownloadManager() {
  // ダウンローダの生成に必要なコンストラクタヘルパー
  val constructorHelper = DownloaderConstructorHelper(...)

  // ダウンロードマネージャを生成
  DownloadManager(
    constructorHelper,
    DownloadManager.DEFAULT_MAX_SIMULTANEOUS_DOWNLOADS,
    DownloadManager.DEFAULT_MIN_RETRY_COUNT,
    File( /* アクションファイルを保存するファイルパス */ ),
    DOWNLOAD_DESERIALIZERS)
}

ダウンロードマネージャのコンストラクタパラメータは下記.

public DownloadManager(
    DownloaderConstructorHelper constructorHelper,
    int maxSimultaneousDownloads,
    int minRetryCount,
    String actionSaveFile,
    Deserializer... deserializers) {

constructorHelper
ダウンローダを生成するためのコンストラクタヘルパー.

maxSimultaneousDownloads
最大同時ダウンロード本数. デフォルト値は1 (DownloadManager.DEFAULT_MAX_SIMULTANEOUS_DOWNLOADS) です.

minRetryCount
ダウンロードの最小再試行回数. デフォルト値は5 (DownloadManager.DEFAULT_MIN_RETRY_COUNT) です.

actionSaveFile
DownloadActionのシリアライズを保存するファイルパス. アクションを永続化することでプロセスを跨いでアクションを再開することができる. ただし, このファイルをSimpleCacheで使用したフォルダに保存しないこと. (ダウンローダは知らないファイルを削除するため)

deserializers
actionSaveFileに保存されているDownloadActionのデシリアライザ. HlsDownloadAction.DESERIALIZER etc.

DownloadManager.Listener

DownloadManager.Listenerを使ってダウンロードイベントのリスナーを登録することができます.
次のコールバックメソッドを定義してイベントを受け取ることができるようになります.

onInitialized
全てのアクションがリストアされたときに呼び出される.

onTaskStateChanged
タスクの状態が変わったときに呼び出される.

onIdle
アクティブなタスクがなくなったときに呼び出される.

DownloadAction

DownloadAction
コンテンツのダウンロードリクエストやコンテンツの削除リクエストを表現するクラス.
ダウンロードやコンテンツ削除のために必要なパラメータ情報を保持している.
このクラスは自前のシリアライザ/デシリアライザを持っており, 自身のアクションをシリアライズすることで, プロセスを跨いでも同アクションをでシリアライズして再開できるようになっている.

アクションが持つパラメータは下記.

type
アクションのタイプ.
このタイプ値はシリアライズ情報に含まれ, アクションをデシリアライズする際に最適なデシリアライザーを選択するために使用される.

version
アクションのバージョン.
アクションはシリアライザによって永続化される際にバージョン情報を記録する.
これによって保存されたアクションのバージョンを判別でき, バリデーションやマイグレーション処理に使うことができる.

uri
ダウンロードまたは削除するURI.
SegmentDownloaderを継承したクラスであれば, URIフィールドもシリアライズの対象になる.

isRemoveAction
削除アクションであればtrue, ダウンロードアクションであればfalse.
SegmentDownloaderを継承したクラスであれば, URIフィールドもシリアライズの対象になる.

data
アクションのカスタムデータ.
アクションファイルには任意の情報をカスタムデータとしてバイト配列形式で保存することができる.
SegmentDownloaderを継承したクラスであれば, URIフィールドもシリアライズの対象になる.

アクションファイルのフォーマットは次の通り.

// type, version は共通フォーマット
output.writeUTF(action.type);
output.writeInt(action.version);

// 以下はSegmentDownloadAction系のフォーマット. keysについては後述
output.writeUTF(uri.toString());
output.writeBoolean(isRemoveAction);
output.writeInt(data.length);
output.write(data);
output.writeInt(keys.size());
for (int i = 0; i < keys.size(); i++) 
  writeKey(output, keys.get(i));
}

SegmentDownloader - HlsDownloaderの関係と同じく, HlsDownloadActionSegmentDownloadActionを継承しています.
SegmentDownloadActionの生成方法は下記です.

protected SegmentDownloadAction(
    Uri manifestUri, 
    boolean isRemoveAction, 
    @Nullable String data, 
    K[] keys)

manifestUri
ダウンロードしたいコンテンツのURL(Master/MediaPlaylist etc.).

isRemoveAction
ダウンロードするアクションの場合はfalse, ダウンロードコンテンツの削除アクションの場合はfalse.

data
カスタムデータを指定したい場合はここに指定する.
DownloadServiceでも参照することができる.

keys
ダウンロードするトラックのキー(HLSであればレンディション. DASHであればレプリゼンテーション)を指定します. keysが空配列の場合はすべてのトラックがダウンロードされる.
この引数をnullにすることはできず, またremoveActionがtrueの場合は空配列である必要がある.

DownloadHelper

ダウンロードアクションを生成する際には, ダウンロード対象のプレイリスト/マニフェストURLと, トラックキー(レンディション / レプリゼンテーション)を指定する必要がある.
トラックキーを取得するにはプレイリスト/マニフェストファイルをダウンロード・パースする必要がある.
DownloadHelperはそうした前準備処理とトラックキー取得、ダウンロードアクションの生成を助けてくれる.

DownloadHelperが提供するヘルパーメソッドは次の通り.

prepare
ヘルパーを初期化する.
この操作にはプレイリストやマニフェストのダウンロードを伴う.
引数callbackDownloadHelper.Callbackを指定することで初期化の成功・失敗を受け取ることができる.
初期化処理は別スレッドで実行され, コールバックはメインスレッド上で実行される.

getPeriodCount
有効なピリオドの数を取得します.
HLSコンテンツの場合は固定で1が返され, DASHコンテンツの場合はピリオド数が返されます.
このメソッドはヘルパーを初期化した後で呼び出す必要があります.

getTrackGroups
指定ピリオドに含まれるトラックグループを取得します.
HLSコンテンツの場合, Media playlistであれば空が返され, Master playlistであればvariants, audio, subtitleを含むグループを返します.
DASHコンテンツの場合は, 引数periodIndexで指定されたピリオドに含まれるアダプションセットに含まれるレプリゼンテーションのフォーマット配列を返します.
このメソッドはヘルパーを初期化した後で呼び出す必要があります.

getDownloadAction
指定のトラック(レンディション / レプリゼンテーション)をダウンロードするダウンロードアクションを構築します.
引数dataにはダウンロードアクションのコンストラクタ引数dataを指定します.
このメソッドはヘルパーを初期化した後で呼び出す必要があります.

getRemoveAction
コンテンツを削除するダウンロードアクションを構築します.
このメソッドはヘルパーを初期化していない状態でも呼び出すことができます.

次のコードはヘルパーを使ってダウンロードアクションを生成するものです.

val mediaPlaylistUri = ...
val helper = HlsDownloadHelper(mediaPlaylistUri, dataSourceFactory)
helper.prepare(object : DownloadHelper.Callback {
    override fun onPrepared(helper: DownloadHelper) {
      helper.getDownloadAction( ... )

      // TrackKeyのリストは下記の要領で構築できる
      // val trackKeys = mutableListOf<TrackKey>()
      // for (i in 0 until helper.periodCount) {
      //   val trackGroups = helper.getTrackGroups(i)
      //   for (j in 0 until trackGroups.length) {
      //     val trackGroup = trackGroups.get(j)
      //     for (k in 0 until trackGroup.length) {
      //       // 必要ならtrackGroup.getFormat(k)でパラメータを確認してフィルタアウトできる
      //       trackKeys += TrackKey(i, j, k)
      //     }
      //   }
      // }
    }

    override fun onPrepareError(helper: DownloadHelper, e: IOException) {
      ...
    }
  })

単純にHLSコンテンツのMedia playlistに含まれる全てのレンディションをダウンロードするのであれば, 事前にプレイリストをダウンロードして解析する必要もないので, ヘルパーを使わずに次のように生成します.

HlsDownloadAction(uri, false, data, emptyList())

DonwloadService

DownloadService
バックグラウンドでダウンロード処理を継続維持するためのServiceを継承した抽象クラス.
アプリはこのクラスを継承して必要なメソッドをオーバーライドすることでサービスの管理をExoPlayerに任せることができる.

コンストラクタ引数には次のものがある.

foregroundNotificationId
フォアグラウンドサービス用のNotification ID.

foregroundNotificationUpdateInterval
フォアグラウンドノーティフィケーションをアップデートする間隔(ミリ秒).

channelId
フォアグラウンドノーティフィケーションで使用されるチャネルID.
チャネルは低優先度のチャネルとして作成される. 自身でチャネルを作成する場合はnullを指定する.

channelName
フォアグラウンドノティフィケーションで使用するチャネル名.
自身でチャネルを作成する場合は特に使用されない.

定義されている抽象メソッドは下記.

getDownloadManager()
コンテンツのダウンロードで使用されるDownloadManagerインスタンスを返す.
このメソッドはサービスのライフサイクルの中で1度しか呼ばれない.

getScheduler()
特定の条件を満たした時にDownloadServiceを初期化するジョブを持ったSchedulerを返す.
これによって, アプリが実行されていなくてもダウンロードを開始するスケジューリングが可能になる.
スケジューリングが不要な場合はnullを返す.

getForegroundNotification
フォアグラウンドサービスに必要なNotificationを生成する. 引数taskState[]を使ってNotification情報を構築することができる.
このメソッドは, タスクの状態が変化するか, アクティブなタスクがあれば定期的に呼び出される.
呼び出し間隔はDownloadServiceのコンストラクタで調整可能.
API Lv.26以降, このメソッドはサービスが停止する前に空のTaskState[]を引数に呼び出される.

抽象メソッドではないが, サブクラスが意識するべきメソッドは下記.

getRequirements
ダウンロード開始条件をカスタマイズすることができる. デフォルトではネットワーク接続の有無がダウンロード条件として設定される.

onTaskStateChanged
タスクの状態が変わった時に呼び出される.

ダウンロードサービスの開始

アプリがバックグラウンドにいる状態でもダウンロード処理を継続したい場合は, ダウンロードサービスをフォアグラウンドサービスとして振る舞わせる必要がある.
DownloadServiceDownloadService.startForeground(Notification) を使って起動することができる.

// DownloadService
public static void startWithAction(
    Context context, 
    Class<? extends DownloadService> clazz, 
    DownloadAction downloadAction.
    boolean foreground)

clazz
作成したDownloadServiceのサブクラスを指定します.

downloadAction
DownloadActionはダウンロードストリーム/コンテンツに対するアクション.
対象のストリーム種別によってProgressiveDownloadAction, HlsDownloadAction, DashDownloadActionなどが用意されている.

foreground
フォアグラウンドサービスとして起動する場合はtrue.

ダウンロードサービスを開始するIntentだけが欲しい場合は次のメソッドを使用する.

DownloadService.buildAddActionIntent

生成されるIntentにはダウンロードアクションを格納する download_action と, フォアグラウンドサービスとして移動するかどうかのフラグ foreground が格納される.

ダウンロードサービスは次のメソッドを使うことでダウンロードアクションを指定せずに起動することもできる.

DownloadService.start
DownloadService.startForeground

未完了のダウンロードアクションがある場合や, ダウンロード開始条件が満了された場合, サービスはそれらのダウンロードアクションを再開する.
実行するアクションがなければサービスは即終了する.

ダウンロードタスクの状態

ダウンロードタスクの状態は DownloadManager.TaskState で表現される.

定義:

STATE_QUEUED:開始待ち
STATE_STARTED:開始済み
STATE_COMPLETED:完了済み
STATE_CANCELED:キャンセル済み
STATE_FAILED:失敗

状態遷移図:

queued <-> started -> (canceled | completed | failed)
2018/08/27

ボトムシートダイアログの背景を角丸にする

ボトムシートダイアログの上辺だけを角丸にしたい.

ボトムシートの背景画像を定義する.

<shape
  xmlns:android="http://schemas.android.com/apk/res/android"
  android:shape="rectangle"
  >
  <corners
    android:bottomLeftRadius="0dp"
    android:bottomRightRadius="0dp"
    android:radius="1dp"
    android:topLeftRadius="12dp"
    android:topRightRadius="12dp"
    />
  <solid android:color="#fff"/>
</shape>

ボトムシートダイアログのレイアウト背景に上記画像を設定する.

  <XxxLayout
    ...
    android:background="@drawable/bg_bottomsheet"
    >

このままだと、ウィンドウ背景色が塗りつぶされてしまうので, これを透過するスタイルを用意する.

<style name="AppTheme.ShareDialog" parent="Theme.Design.Light.BottomSheetDialog">
  <item name="android:windowCloseOnTouchOutside">true</item>
  <item name="android:windowIsTranslucent">true</item>
  <item name="android:windowContentOverlay">@null</item>
  <item name="android:colorBackground">@android:color/transparent</item>
  <item name="android:backgroundDimEnabled">true</item>
  <item name="android:backgroundDimAmount">0.3</item>
  <item name="android:windowFrame">@null</item>
  <item name="android:windowIsFloating">true</item>
</style>

スタイルを適用するダイアログを定義する.

private class HogeBottomSheetDialog(
  context: Context
) : BottomSheetDialog(
  context,
  R.style.AppTheme_ShareDialog
) {

done.

ダイアログのスタイルには parent="Theme.Design.Xxx.BottomSheetDialog" を継承したものを定義しないと,
Robolectricのテストで attr/bottomSheetStyle が解決できずtest failする.
Github robolectric/robolectric issue 2941

以上.

2018/03/29

DataBinding v2: NullPointerException

DataBinding v2にすると

     Caused by: java.lang.NullPointerException: Attempt to invoke interface method 'void android.databinding.Observable.addOnPropertyChangedCallback(android.databinding.Observable$OnPropertyChangedCallback)' on a null object reference
        at android.databinding.BaseObservableField.<init>(BaseObservableField.java:16)
        at android.databinding.ObservableField.<init>(ObservableField.java:73)
        at ...

問題のコードが下記.

private val hoge = ObservableField<Foo?>(null)

これを, 次のように修正することで解決した.

private val hoge= ObservableField<Foo?>()
2018/03/28

Kotlin & StringFormatMatches lint

val foo = 1
context.getString(R.string.string_format, foo)

↑こういうコードだと, ↓こんなLintエラーが出る.

Errors found:
/xxx/src/xxx/Hoge.kt:100: Error: Wrong argument type for formatting argument '#1' in string_format: conversion is 'd', received <ErrorType> (argument #2 in method call) [StringFormatMatches]
    setText(context.getString(R.string.string_format, foo))

/xxx/src/main/res/values/strings.xml:100: Conflicting argument declaration here
val foo: Int = 1
context.getString(R.string.string_format, foo)

これだとOK.
静的解析で型推論できずにハマっているのかな?