English

SINETStream for Android ユーザガイド

目次

1. 概要
2. モジュール構成
3. 作業準備
    3.1 開発環境の導入
    3.2 実行環境の用意
4. 作業手順
    4.1 ビルド環境設定
        4.1.1 ライブラリファイルの取得
        4.1.2 開発ソースへの組み込み
        4.1.3 リポジトリ追加
        4.1.4 依存関係追加
            4.1.4.1 SINETStreamライブラリ
            4.1.4.2 Paho MQTT Androidライブラリ
    4.2 マニフェストファイルの記述
        4.2.1 利用者権限追加
        4.2.2 サービスコンポーネント追加
    4.3 SINETStreamライブラリの動作設定
        4.3.1 SINETStream設定ファイルの配置
        4.3.2 基本設定
        4.3.3 接続先URIの決定方法
        4.3.4 接続先ホスト・ポートが複数ある場合の振る舞い
    4.4 SSL/TLSの利用設定
        4.4.1 設定ファイルを用いる運用の場合
        4.4.2 コンフィグサーバを利用する運用の場合
    4.5 開発成果物のAndroid端末への導入
        4.5.1 Androidエミュレータに導入する場合
        4.5.2 Android実機に導入する場合
5. まとめ

1. 概要

国立情報学研究所(NII)開発によるAndroid版のSINETStreamライブラリを提供するにあたり、 これを利用するユーザアプリケーションの開発者が考慮すべきことを概説する。

2. モジュール構成

SINETStreamライブラリ、およびそれを利用するユーザアプリケーションの依存関係を簡略的に図示すると以下のように表現される。

      #---------------------------------------------+
      | User Application using MQTT              (1)|
      +---------------------------------------------+
    =================================================== SINETStream API
      +---------------------------------------------+
      | SINETStream Android Library              (2)|
      |                                             |
      +---------------------------------------------+
      +------------------+  +-----------------------+
      | Paho MQTT    (3a)|  | Paho MQTT         (3b)|
      | client library   |  | client library        |
      | (Paho ORIGINAL)  |  | (BUGFIX: Android 12+) |
      +------------------+  +-----------------------+
    =================================================== System API
      +---------------------------------------------+
      | Android System                           (4)|
      |       ........... ............ ............ |
      |       : Network : : File I/O : : KeyChain : |
      |       :.........: :..........: :..........: |
      +------------A--------------------------------+
                   |
                   | IP network
                   V
            [ MQTT Broker ]

<凡例>

(1) ユーザが開発するアプリケーション

(2) SINETStreamライブラリ本体

(3) Eclipse Pahoプロジェクトが提供するAndroid版のMQTTクライアントライブラリ

注意: Pahoプロジェクト活動停止(?)による不具合放置への暫定対応

(3a) Android 12未満はオリジナル版をそのまま使用可能

(3b) Android 12以降は動作不具合があるため、NIIによる暫定改修版を使用する

(4) Androidシステム

MQTTを扱うネットワーク処理、設定情報を扱うファイルI/O、秘匿情報を扱うKeyChainなどの機能モジュールを利用する。

3. 作業準備

3.1 開発環境の導入

Google社が提供する統合開発環境 Android Studio を入手して、手元の作業機材に導入する。

Android Studio自体は、Windows, MacOS, Linux, ChromeOS の各プラットフォームに対応しているが、その動作環境として高性能な開発機材が必要となる。 特に実装メモリ量やCPU/GPUの性能が効いてくる。 少なくとも上記プラットフォーム毎の システム要件 を満足するものを選定すること。

また、開発機材上で エミュレータ を動作させる場合は、その システム要件 にも留意すること。

注意: Android Studioの版数

Android開発環境は継続的に更新されており、時としてビルド環境と設定ファイルの不整合によりビルドに失敗することがある。 その場合、 Android Studio のダウンロード アーカイブより、 Android Studio Dolphin | 2021.3.1 ベータ版 3を取得されたい。

3.2 実行環境の用意

Android端末の実機、またはAndroidStudioと連携する エミュレータ 環境にて所用の Android仮想デバイス(AVD) を用意する。

注意: Android動作環境の制約

ユーザアプリケーションのビルド設定、および対象Android端末のいずれも、Android 8.0(APIレベル26)以上であること。 Android版のSINETStreamライブラリは、メッセージのシリアライザ/デシリアライザ機能でApache Avroライブラリを利用しており、後者の実装内容が動作上の制約条件となっている。

4. 作業手順

4.1 ビルド環境設定

ユーザアプリケーションにとって、SINETStreamライブラリPaho MQTT Androidも外部ライブラリとして参照するものである。 すなわち「どこに何があるか」というリポジトリ参照先と、「どの版のものを参照するか」という二種類の情報を開発環境に設定する必要がある。

Android Studioでは、Gradle Build Toolによるビルド管理を行なっている。 よって、ユーザアプリケーションが参照する外部ライブラリなどの設定情報はGradle制御ファイルの一つである モジュールレベルのbuild.gradleにて設定する。 ビルド依存関係の追加の記述を参照されたい。

以降では、ユーザのAndroid開発ソースからSINETStreamライブラリを利用するための具体的な手順について記述する。

注意: ライブラリ参照方法の違い

SINETStreamライブラリ自身、およびその依存ライブラリである Paho MQTT Androidとでは参照方法が異なる。 前者は Android ARchive (AAR)ファイルを手元にダウンロードして、それを直接参照する。 後者はネット上のmavenリポジトリに配置されるのでそれを参照する。

4.1.1 ライブラリファイルの取得

SINETStreamライブラリは、ソースおよびバイナリの形式でGitHub上で公開される。

国立情報学研究所(NII)が管理するリポジトリ sinetstream-android より、最新版のsinetstream-android-x.y.z.aarを手元にダウンロードする。

便宜的に、ダウンロード先を$HOME/Downloadsとして話を進める。

4.1.2 開発ソースへの組み込み

Android開発環境で作業する対象プログラムを仮にtestappとすると、 概略以下のようなディレクトリ内容になっているはずである。

% cd $(WORKDIR)/testapp
% ls -FC
app/          gradle/            gradlew      local.properties
build.gradle  gradle.properties  gradlew.bat  settings.gradle

アプリケーションソース格納用のappサブディレクトリ直下に、 ローカルライブラリ格納用のディレクトリlibsを用意する。 既にあればそれを使い、なければ作成する。 前項で取得したSINETStreamライブラリをそこに格納する。

% cd app
% mkdir libs
% cd libs
% cp $HOME/Downloads/sinetstream-android-x.y.z.aar .

4.1.3 リポジトリ追加

SINETStreamライブラリ、およびその依存ライブラリPaho MQTT Androidではそれぞれ参照方法が異なるため、個別に記述する。

SINETStreamライブラリは、目的のものを手動で手元にダウンロードして、 ローカルライブラリ格納用のlibsディレクトリに配置する。 それを参照するよう、 モジュールレベルのbuild.gradleに記述する。

repositories {
    flatDir {
        // For SINETStream library
        dirs "libs"
    }
}

Paho MQTT Androidライブラリは、ネット上の公開先(mavenブロック)を モジュールレベルのbuild.gradle記述 する。

repositories {
    maven {
        // The Paho MQTT Android
        url "https://repo.eclipse.org/content/repositories/paho-snapshots/"
    }
    mavenCentral()
}

4.1.4 依存関係追加

SINETStreamライブラリ、およびその依存ライブラリPaho MQTT Androidではそれぞれ参照方法が異なるため、個別に記述する。

4.1.4.1 SINETStreamライブラリ

SINETStreamライブラリは、 前述のようにローカルライブラリ格納用のlibsディレクトリに配置する。 当該ファイル名の本体部分と拡張子部分に分けて、 モジュールレベルのbuild.gradleビルド依存関係を追加する。

dependencies {
    // SINETStream for Android
    implementation(name: 'sinetstream-android-x.y.z', ext: 'aar')
}
4.1.4.2 Paho MQTT Androidライブラリ

Paho MQTT Androidライブラリは、ネット上の公開先(mavenリポジトリ)を以下の形式で指定する。

    implementation '<group-id>:<artifact-id>:<version>'

さて、第2章「モジュール構成」で述べたとおり、Paho MQTT AndroidライブラリはAndroid 12以降に対応しておらず、そのままではビルドできない。 NII開発の暫定ライブラリで代替するか否か、ユーザアプリケーションの動作環境に応じてモジュールレベルのbuild.gradleビルド依存関係を追加する。

将来Paho MQTTプロジェクトの活動が再開され、Paho MQTT Androidライブラリの不具合が修正されることを期待したい。

4.2 マニフェストファイルの記述

4.2.1 利用者権限追加

SINETStreamライブラリを利用するユーザアプリケーションは、 所用の権限uses-permission句)をビルド情報として宣言する必要がある。 さもないと当該アプリケーション実行時に権限エラーが発生する。

以下の内容をマニフェストファイル(AndroidManifest.xml)に設定すること。

<!-- Permissions for the external network (such like INTERNET) access -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<!-- Required for the Paho Android Service (Android 12+) -->
<uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" />

4.2.2 サービスコンポーネント追加

SINETStreamライブラリの下位層に位置するPaho MQTT Androidライブラリは、以下の2つの機能要素

から構成される。

すなわち、Paho MQTT Androidライブラリはアプリコンポーネントとしてサービス機能を提供している。 ユーザアプリケーションが同サービスと連携するため、その名称(service句)をマニフェストに定義する必要がある。

注意

この設定を忘れても「Paho MQTT Android」を利用するユーザプログラム自体は 起動するが、Androidシステムが当該サービスを起動しない。 このため、publishやsubscribeなどのAPI関数の処理が空回りする。 アプリケーションからの要求は受け付けられるものの、ネットワークとやりとり されない状態なのでエラーに気づきにくい。

以下の内容をマニフェストファイル(AndroidManifest.xml)に設定すること。

<application ... >
    <!-- MQTT service provided by Paho MQTT Android -->
    <service android:name="org.eclipse.paho.android.service.MqttService" />
</application>

4.3 SINETStreamライブラリの動作設定

本ライブラリの設定方法として、以下の2通りを用意する。

次節以降では、前者の設定ファイル方式について記述する。 後者の設定サーバ方式については別途記述する。

4.3.1 SINETStream設定ファイルの配置

本方式による設定の場合、アプリケーション固有のデータ領域にYAML形式の設定ファイル

を事前に用意しておく。ファイル名は固定である。 書式など詳細は、別紙Android版のSINETStream設定ファイルを参照のこと。

Android版クイックスタートガイドで示したサンプルアプリケーション2種では、 GUIによる設定画面を用意して「利用者の操作内容を元にSINETStream設定 ファイルを動的に自動生成する」手法を採用している。 こちらの実装内容を参照されたい。

4.3.2 基本設定

設定ファイルの記述内容は必須項目とオプション項目がある。 以下に示す項目は必ず記述する必要がある。

オプション項目が省略された場合、MqttConnectOptionsのコンストラクタ既定値が使われる。

4.3.3 接続先URIの決定方法

接続先サーバ(ブローカ)URIは一般的に以下のように表現される。

schema://host[:port]
^^^^^ 1) ^^^^^^^^^^^ 2)

SINETStream設定ファイルにおける項目「brokers」で指定するのは、 後述のように上記2)の「ホスト(+ポート)部分の羅列」である。 なお、上記1)のスキーマ部分はいくつかの条件の組み合わせで決まる。

transport tls schema
省略 省略 tcp
tcp なし tcp
tcp あり ssl
websockets なし ws
websockets あり wss

さらに、SSL/TLS通信を行うか否かの判定は、 後述するように設定項目「tls」の記述方法で変わる。 上記の「transport」および「tls」ともオプション項目であるため、 記述のバリエーションを頭に入れて設定しないと所望のスキーマが得られず、 サーバとの接続失敗で苦労することになる。

4.3.4 接続先ホスト・ポートが複数ある場合の振る舞い

SINETStream設定ファイルにおける項目「brokers」で指定する場合、 次の3通りの書式を受け付ける。

1) 単一の接続先

brokers: host1

2) 複数の接続先をコンマ接続でリスト指定

brokers: host1,host2:port2,host3

3) 複数の接続先をYAMLリスト形式で指定

brokers:
  - host1
  - host2:port2
  - host3
brokers: [host1, host2:port2, host3]

複数の接続先を指定した場合の振る舞いは以下のようになる。

出典MqttConnectOptions: setServerURIs

4.4 SSL/TLSの利用設定

SINETStreamライブラリを利用するユーザアプリケーションは、 対向の相手群(ブローカ)との通信路にSSL/TLSを利用することができる。

4.4.1 設定ファイルを用いる運用の場合

以下の各項目を実施する。

注意

事前導入したSSL/TLS証明書ファイル形式、および接続先ブローカの設定内容に相互矛盾がないよう留意する。 さもないとブローカ接続時のSSL/TLSハンドシェーク処理で失敗する。

4.4.2 コンフィグサーバを利用する運用の場合

SSL/TLSの設定はサーバ側で準備され、またSSL/TLS証明書データ自体も自動的にダウンロードされる。 すなわちAndroid端末側で特に対処すべきことはない。

4.5 開発成果物のAndroid端末への導入

開発環境AndroidStudioを準備し、ユーザアプリケーションを実装[1][2]すると、 APK(Android package)と呼ばれるアーカイブファイルが生成される。

APKとは、アプリケーションを構成する「コード、データ、およびリソースファイル」をパッケージとして一つにまとめたものである。 この生成物APKファイルを実行環境(エミュレータや実機)に導入する方法について述べる。

[1]: アプリの基礎
[2]: アプリをビルドして実行する

4.5.1 Androidエミュレータに導入する場合

以下の要領でAPKファイルをエミュレータに導入し、同エミュレータ上でアプリケーションを実行する。

  1. Android仮想デバイス(AVD: Android Virtual Device)の用意

開発環境AndroidStudio付属のAndroid仮想デバイス(AVD)ツールを用いて、 所用の諸元(画面解像度、APIレベル、CPU種別など)に 沿ったAVDを事前作成しておく。

  1. AVDの起動

目的の諸元を満たすAVDを起動するとAndroid端末イメージが表示される。 GUI経由で実機同様に操作したり、 遠隔操作(APK導入やデバッグなど)ができるようになる。

  1. アプリケーションの導入と起動

エミュレータが実行中にAndroidStudio上の「Run」コマンドを実行する。 必要に応じてソースが再構築され、生成APKファイルがエミュレータに導入される。 続けて、当該プログラムが自動的に動作を開始する。

4.5.2 Android実機に導入する場合

以下の要領でAPKファイルを実機に導入し、同機上でアプリケーションを実行する

  1. Android実機の設定画面を操作し、開発者モードを有効化する。
  2. 設定コマンドの開発者メニュー経由で「USBデバッグ」を有効化する。
  3. 実機と開発機材をUSBケーブルで接続する。
  4. 実機に「デバッグモードで接続して良いか」を確認するダイアログが表示される。 デバッグ接続を承認すると、AndroidStudioで認識される。
  5. この状態でAndroidStudio上の「Run」コマンドを実行する。

あるいは、開発機材上でAndroid Debug Bridge (adb)コマンドを直接操作することで、 対象APKファイルを実機に導入できる。

PC% adb install -r XXX.apk
Success

5. まとめ

SINETStreamライブラリを用いるアプリケーション開発者が留意すべき項目について、 一通り概説した。