2013/02/18

Android:Service.dumpでサービスの状態をダンプする

Serviceにはdumpメソッドが用意されています。
これは下記コマンドが実行された時に、サービスの状態をダンプするメソッドです。
$ adb shell dumpsys activity service <yourservicename>
Service.dump
http://developer.android.com/reference/android/app/Service.html#dump(java.io.FileDescriptor, java.io.PrintWriter, java.lang.String[])

dumpメソッドにはPrintWriterインスタンスが引数として渡されます。
これにサービスの情報を入力すれば、ログとしてそれが出力されます。

・動作サンプル
$ adb shell dumpsys activity service yuki.test.messenger/.MyMessenger
MyMessenger.java
@Override
protected void dump(FileDescriptor fd, PrintWriter pw, String[] options) {
    pw.println("MyMessenger dump!!!");
}
-出力結果-
SERVICE yuki.test.messenger/.MyMessenger 41fa2ef0 pid=6151
  Client:
    MyMessenger dump!

Service.dumpメソッドを提供することで、開発者はサービスの情報を好きなタイミングで取得することが可能です。
※ただし、対象のサービスが実行中であることが前提です
ActivityManagerServiceもこのメソッドを提供しています。
ActivityManagerServiceをdumpすればデバッグ時に有益な情報を確認できます。
http://yuki312.blogspot.jp/2012/04/androidactivity.html

Object.toStringのそれと同じく、Service.dumpは非常に有益なメソッドです。
toStringをオーバライドする際の一般契約と同じように、dumpする内容は"簡素であり、読みやすく、有益な表現"であるべきでしょう。


●サンプルコード

Service.dumpの第三引数 options にはコマンド引数が格納されます。
$ adb shell dumpsys activity service yuki.test.messenger/.MyMessenger -a -b -c
であれば
 options[0] = "-a"
 options[1] = "-b"
 options[2] = "-c"
といった具合です。

これらを活用すれば、必要に応じたダンプ情報を得ることができます。
また、よくある"ヘルプコマンド"も実装可能です。

下記はそのサンプルコードです。
@Override
protected void dump(FileDescriptor fd, PrintWriter pw, String[] options) {
    boolean dumpAll = false;
    boolean dumpClient = false;
    boolean dumpMessage = false;
    boolean dumpState = false;

    int optionIndex = 0;
    while (optionIndex < options.length) {
        String option = options[optionIndex];
        if (TextUtils.isEmpty(option) || option.charAt(0) != '-') {
            break;
        }
        optionIndex++;

        if ("-a".equals(option) || "-all".equals(option)) {
            dumpAll = true;
        } else if ("-c".equals(option) || "-client".equals(option)) {
            dumpClient = true;
        } else if ("-m".equals(option) || "-message".equals(option)) {
            dumpMessage = true;
        } else if ("-s".equals(option) || "-state".equals(option)) {
            dumpState = true;
        }  else if ("-h".equals(option) || "-help".equals(option)) {
            pw.println("MyMessenger dump options:");
            pw.println("  [-a] [-c] [-m] [-s]");
            pw.println("    a[ll]: dump all info.");
            pw.println("    c[lient]: reply target.");
            pw.println("    m[essage]: handle message log.");
            pw.println("    s[tate]: service state change log.");
            return;
        } else {
            pw.println("Unkown argument: " + option + "; use -h for help.");
        }
    }

    pw.println("Service state");
    pw.println("    Service create time is " + new Date(mOnCreateTime));
    pw.println("    " + mCurrentState);
    pw.println();

    if (dumpClient || dumpAll) {
        pw.println("Client(" + mClients.size() + ")");
        for (ClientRecord cr : mClients.keySet()) {
            pw.println("    " + cr);
        }
        pw.println();
    }

    if (dumpMessage || dumpAll) {
        pw.println("Message Logs");
        for (MessageLog log: mMessageLogs) {
            pw.println("    " + log);
        }
        pw.println();
    }

    if (dumpState || dumpAll) {
        pw.println("ServiceState Logs");
        for (ServiceState.ServiceStateLog log: mCurrentState.getStateLogs()) {
            pw.println("    " + log);
        }
        pw.println();
    }
}
-出力結果-
・引数無し
$ adb shell dumpsys activity service yuki.test.messenger/.MyMessenger
SERVICE yuki.test.messenger/.MyMessenger 41fd0950 pid=6151
  Client:
    Service state
        Service create time is Sun Jan 06 03:58:13 GMT+00:00 1980
        Current service state is RUNNING
・引数指定(-c:クライアント情報出力, -m:メッセージ履歴出力)
$ adb shell dumpsys activity service yuki.test.messenger/.MyMessenger -c -m
SERVICE yuki.test.messenger/.MyMessenger 41fa2ef0 pid=6151
  Client:
    Service state
        Service create time is Sun Jan 06 03:58:28 GMT+00:00 1980
        Current service state is BLOCKED

    Client(2)
        ClientRecord [ PackageName=test.pkg1, ID=1, hash=b6f4c7b1 ]
        ClientRecord [ PackageName=test.pkg2, ID=1, hash=b6f4c7b2 ]

    Message Logs
        03:58:44.570: { what=3 when=-1ms }
        03:58:44.339: { what=2 when=-1ms }
        03:58:28.681: { what=1 when=-5ms }
・引数指定(-a:全情報出力)
$ adb shell dumpsys activity service yuki.test.messenger/.MyMessenger -a
SERVICE yuki.test.messenger/.MyMessenger 41fa2ef0 pid=6151
  Client:
    Service state
        Service create time is Sun Jan 06 03:58:28 GMT+00:00 1980
        Current service state is BLOCKED

    Client(2)
        ClientRecord [ PackageName=test.pkg1, ID=1, hash=b6f4c7b1 ]
        ClientRecord [ PackageName=test.pkg2, ID=1, hash=b6f4c7b2 ]

    Message Logs
        03:58:44.570: { what=3 when=-1ms }
        03:58:44.339: { what=2 when=-1ms }
        03:58:28.681: { what=1 when=-5ms }

    ServiceState Logs
        03:58:44.571: { RUNNING => BLOCKED }
        03:58:44.340: { NEW => RUNNING }
・引数指定(-h:ヘルプ)
$ adb shell dumpsys activity service yuki.test.messenger/.MyMessenger -h
SERVICE yuki.test.messenger/.MyMessenger 41fa2ef0 pid=6151
  Client:
    MyMessenger dump options:
      [-a] [-c] [-m] [-s]
        a[ll]: dump all info.
        c[lient]: reply target.
        m[essage]: handle message log.
        s[tate]: service state change log.
・引数指定(-p:サポートしない引数)
$ adb shell dumpsys activity service yuki.test.messenger/.MyMessenger -p
SERVICE yuki.test.messenger/.MyMessenger 41fa2ef0 pid=6151
  Client:
    Unkown argument: -p; use -h for help.
    Service state
        Service create time is Sun Jan 06 03:58:28 GMT+00:00 1980
        Current service state is BLOCKED

便利ですね。好きなタイミングで実行できるのが強力です。

注意すべき点として、、、
ログ出力の場合と同じく、dump情報で出力する情報には注意が必要です。
# Service.dumpで出力される情報はbugreportにも出力されます。
開発時以外に必要ないのであれば、ビルドタイプでdump情報を絞る等の対応を考えます。

以上です。
2013/02/14

Android:contentコマンドでContentProviderを呼び出す

Android4.1.1以降、コマンドラインユーティリティにcontentコマンドが追加されました。

サンプルコマンド:
$ content query --uri content://yuki.authority/
このコマンドは、コンテンツへのCRUD操作をコンテンツプロバイダ経由で実行します。
例えば、データベースレコードの検索や削除などが可能です。

SQLite3コマンドでも同様にデータベースの編集が可能ですが、
SQLite3コマンドの対象がデータベースであるのに対して、contentコマンドの対象はコンテンツプロバイダです。
これはつまり、
  • コンテンツプロバイダの簡単な動作確認として使用可能
  • コンテンツプロバイダを経由するため、コンテンツオブサーバへの通知も実行される
といったメリットがあります。


●contentコマンドの使い方

使い方は
& adb shell content
と入力すれば使い方が表示されます。

【query】
$ adb shell content query --uri <URI> [--projection <PROJECTION>] [--where <WHERE>] [--sort <SORT_ORDER>]

【insert】
$ adb shell content insert --uri <URI> --bind <BINDING> [--bind <BINDING>...]


【update】
$ adb shell content update --uri <URI> [--where <WHERE>]


【delete】
$ adb shell content delete --uri <URI> --bind <BINDING> [--bind <BINDING>...] [--where <WHERE>]

<URI>
    コンテンツプロバイダのURI
    (例)--uri content://hoge.authority

<PROJECTION>
    検索対象のカラム名を指定します。指定方法は <COLUMN_NAME>[:<COLUMN_NAME>...]
    (例)column1:column2:column3

<WHERE>
    SQLのWHERE句を指定します。
  (例)--where "column1='where_string'"

<SORT_OREDER>
    ソート対象の列を指定します。
   (例)--sort "column1 DESC"

<BINDING>
    次のフォーマットに従い、カラムにバインドする情報を指定します。
  <COLUMN_NAME>:<TYPE>:<COLUMN_VALUE>
  <TYPE>にはb - boolean, s - string, i - integer, l - long, f - float, d - doubleが指定可能です。
  (例)column:s:new_string


●動作確認

動作確認の対象となるテーブル情報は下記。

・Authority
yuki.authority

・テーブル情報
cid   name     type  
----  -------  --------
0     _id      INTEGER
1     number   INTEGER

・テーブル内容
_id         number
----------  ------------
1           1416078507
2           1355288181
3           380734541
4           254152153
5           18301077

【query】
# content query --uri content://yuki.authority/ --projection _id:number --where "_id BETWEEN 1 AND 3" --sort "_id DESC"
_id:number --where "_id BETWEEN 1 AND 3" --sort "_id DESC"
Row: 0 _id=3, number=380734541
Row: 1 _id=2, number=1355288181
Row: 2 _id=1, number=1416078507

【insert】
# content insert --uri content://yuki.authority/ --bind number:i:1234567
yuki.authority/ --bind number:i:1234567
-結果確認-
# content query --uri content://yuki.authority/ --projection _id:number --where "number=1234567" --sort "_id DESC"
_id:number --where "number=1234567" --sort "_id DESC"
Row: 0 _id=6, number=1234567

【update】
# content update --uri content://yuki.authority/ --bind number:i:9999
yuki.authority/ --bind number:i:9999
-結果確認-
# content query --uri content://yuki.authority/ --projection _id:number --where "number=9999"
_id:number --where "number=9999"
Row: 0 _id=1, number=9999
Row: 1 _id=2, number=9999
Row: 2 _id=3, number=9999
Row: 3 _id=4, number=9999
Row: 4 _id=5, number=9999
Row: 5 _id=6, number=9999

【delete】
# content delete --uri content://yuki.authority/ --where "_id=1"
yuki.authority/ --where "_id=1"
-結果確認-
# content query --uri content://yuki.authority/ --projection _id:number
om.example.testcprovider/ --projection _id:number
Row: 0 _id=2, number=9999
Row: 1 _id=3, number=9999
Row: 2 _id=4, number=9999
Row: 3 _id=5, number=9999
Row: 4 _id=6, number=9999

以上です。
2013/02/12

Android:DeathRecipientで他プロセスの死亡を検知する


Androidには他プロセスの死亡を検知する仕組みとしてDeathRecipientクラスが用意されています。
DeathRecipientは対象となるIBinderのホストプロセスの死亡をモニタします。

IBinder.DeathRecipient
http://developer.android.com/reference/android/os/IBinder.DeathRecipient.html

プロセス間通信時に、相手プロセスがkillされたタイミングを知ることができます。


●サンプルコード

下記はDeathRecipientを使用したサンプルコードです。
mDeathRecipient = new IBinder.DeathRecipient() {
    @Override
    public void binderDied() {
        if (mBinder != null)
            mBinder.unlinkToDeath(this, 0);
    }
};

mConnection = new ServiceConnection() {
    @Override
    public void onServiceConnected(ComponentName name, IBinder binder) {
        mBinder = binder;
        mBinder.linkToDeath(mDeathRecipient, 0);
    }
    ....
}
IBinderのホストプロセスが死亡するとbinderDied()がコールバックされます。


●ServiceConnection.onServiceDisconnectedとの違い

ServiceConnection.onServiceDisconnected()も同じような機能を持っています。
# というより、onServiceDisconnectedはDeathRecipient.binderDied()をトリガとしています。
# 参照:android.app.LoadedApk$DeathMonitor

ただし、サービスとの接続状態によっては次のような違いが出てきます。
【サービスバインド状態でのサービスホストプロセス死亡】
  • onServicedisconnectedがコールされる
  • binderDiedがコールされる

【非サービスバインド状態(サービスアンバインド後)のサービスホストプロセス死亡】
  • onServicedisconnectedはコールされない
  • binderDiedがコールされる

これは、
"サービスとの接続状態をモニタする(ServiceConnection)"
か、
"IBinderのホストプロセスの死亡をモニタする(DeathRecient)"
かの違いによるものです。


●API

・linkToDeath
対象となるBinderのホストプロセスが死亡した時の通知を受け取るRecipientを登録します。
ターゲットであるBinderが既に死亡している場合はRemoteExceptionが投げられます。

・unlinkToDeath
対象となるIBinderのホストプロセス死亡のモニタを解除します。
既に登録解除されたRecipientを引数指定するとNoSuchElementExceptionが投げられます。


●ちなみに

当然ですが、DeathRecipientは自プロセスの死亡まではlistenできません。
自プロセスがkillされると、登録したDeathRecipientインスタンスもろもろ解放されます。

2013/02/11

Android:Messengerの基本

プロセス間の双方向通信をサポートするサービスにはAIDLとMessengerが存在します。

AIDLとMessengerの主な違いは下記になります。

●AIDL
  • サービスホスト(以降ホスト)は.aidlを作成し、サービスクライアント(以降クライアント)はこれを取り込む必要がある
  • クライアントからのリクエストはBinderThread経由で、全てのリクエストが非同期通信となる
  • ホストは必要に応じてクライアントからのリクエストをスレッドセーフに扱う必要がある
  • .aidlに変更があった場合、クライアントも合わせてこれを更新する必要がある

●Messenger
  • ホストとクライアント間の通信はHandler-Messageの仕組みで実現されているため.aidlが不要
  • クライアントからのリクエストはHandler経由で通知され、全てのリクエストが同期通信となる
  • ホストとクライアント間のメッセージはMessageオブジェクトで表現される

Messengerはクライアントからのリクエストをシングルスレッドで処理するため、基本的にスレッドセーフで動作します。
また、メッセージがMessageオブジェクトで表現されるため.aidlファイルも不要です。
外部公開APIに変更があっても、.aidlファイルをクライアントに配布する必要がないため、
サービス側でMessageの規約(プロトコル)を更新するだけで済みます(互換性を意識する必要があります)

Messengerの難点として、"外部公開APIの直観性の低さ"があります。
AIDLでは外部公開APIはメソッドとして定義されます。
しかし、Messengerでは"Messageオブジェクトの組み立て方"でこれを表現する必要があります。
クライアントはMessengerと通信するためにメッセージの組み立て方を理解する必要があるのです。
(アプリローカルで使用されるHandler-Messageのそれと同じです)


●サンプルコード
Messengerを使用した双方向通信のスニペットです。

・クライアントサイド
public class MessengerClient extends Activity {
    private Messenger mServiceMessenger;
    private Messenger mSelfMessenger;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        ...
        mSelfMessenger = new Messenger(new ResponseHandler());
        mConnection = new ServiceConnection() {
            ...
            @Override
            public void onServiceConnected(ComponentName name, IBinder service) {
                mServiceMessenger = new Messenger(service);
            }
        };
        bindService(new Intent("yuki.test.messenger.START"),
                mConnection, Service.BIND_AUTO_CREATE);

        ((Button)findViewById(R.id.button1)).setOnClickListener(
                new View.OnClickListener() {
                    @Override
                    public void onClick(View v) {
                        if (mServiceMessenger != null) {
                            try {
                                Message msg = Message.obtain(null, 1);
                                msg.replyTo = mSelfMessenger;
                                mServiceMessenger.send(msg);
                            } catch (RemoteException e) {
                                e.printStackTrace();
                            }
                        }
                    }
                });
    }

    private class ResponseHandler extends Handler {
        @Override
        public void handleMessage(Message msg) {
            Log.e("yuki", "handle response=" + msg);
        }
    }
}

・ホストサイド
public class MessengerService extends Service {
    private Messenger mServiceMessenger;

    @Override
    public void onCreate() {
        super.onCreate();
        mServiceMessenger = new Messenger(new RequestHandler());
    }

    @Override
    public IBinder onBind(Intent intent) {
        return mServiceMessenger.getBinder();
    }

    private class RequestHandler extends Handler {
        @Override
        public void handleMessage(Message msg) {
            Log.e("yuki", "handle request=" + msg);

            if (msg.replyTo != null) {
                try {
                    msg.replyTo.send(Message.obtain()); // send response.
                } catch (RemoteException e) {
                    e.printStackTrace();
                }
            }
        }
    }
}

・クライアント⇒ホストへの通信
ホストはMessenger.getBinder()で得られるBinderをonBindコールバックで返します。
クライアントはonServiceConnectedコールバックで得られるBinderインスタンスをMessengerコンストラクタに
指定してMessengerオブジェクトを生成し、サービスとの通信路を確立します。
Messengerオブジェクトにメッセージをsendすればホストに届きます。

・ホスト⇒クライアントへの通信
クライアントはホストに渡すMessageオブジェクトのreplayToフィールドに自身のMessengerを設定します。
ホストはクライアントからのMessageオブジェクトからこれを取得し、クライアント⇒ホスト時と同様にメッセージを送信します。

・通信相手の不在
Messengerの対象となっているオブジェクト(クライアント or ホスト)が既にDeadObject化している場合はDeadObjectExceptionが投げられます。
クライアントもホストも通信相手はリモートプロセスとなるため、メッセージの送信にはRemoteExceptionのcatchが必要です。


●リクエストメッセージのキューイングによる処理遅延
Messengerはシングルスレッドモデルであるため、クライアントからのリクエストを逐次処理していきます。
※handleMessageはメインスレッド上で動作するのがデフォルトです
1つのリクエスト処理に時間が掛かると、次のリクエストを処理するのが遅れます。
これはつまり、ホストからの応答性が悪くなる可能性があるということです。
ホストとクライアントが1:多の関係にあり、リクエストの処理に手間取った場合この問題は顕著になります。

クライアントからのリクエスト処理(handleMessage)がメインスレッドで実行されることに注目します。
リクエスト処理で遅延が発生すると、onBindやonDestroy等他のメインスレッドで実行される処理にも影響が出ます。
サービスバインド要求等のリクエストも、それ以前にキューイングされたメッセージ"全て"が処理されてからでないと実行されません。

そのため、メインスレッド上でのリクエスト処理に手間取ると、
  •  bindServiceを実行しても中々サービスコネクトされない
  •  unbindServiceしたが、中々サービスがDestroyされない
といったことが起こりえます。

Messengerはシングルスレッドモデルです。
クライアントからのバインドやアンバインド要求もリクエストメッセージとして処理されるため、スレッドセーフが保証されます。
ホスト側のHandlerを別のHandlerThread(Looper)と紐付けたものをonBindで返せば、onBindやonDestroyが即実行されるようになりますが、 Messengerのメリットであるシングルスレッドモデルを崩すことになります。

・不在のクライアントからのリクエスト
クライアントからのリクエストはメッセージキューにキューイングされます。
クライアントがリクエストを送信し、ホスト側でメッセージキューからデキューされる間にクライアント側がいなくなるケースがあります。
クライアントが不在となっても、一度キューイングされたメッセージはホストに届きます。

2013/02/06

Android:エミュレータでマルチユーザ機能を確認する

JB4.2で正式にマルチユーザ機能が公開されました。
ICSから一部機能が搭載されはじめ、JB4.1では(隠された)UIが存在しましたがユーザを追加することはできませんでした。

●JB4.1でマルチユーザ機能の蓋開けを行う方法は下記。
1. 端末で利用できるユーザ数の上限を引き上げる
$ setprop fw.max_users 2
2. ユーザを作成する
$ pm create-user <userName>
3. ユーザを切り替える
[power]キー長押しの電源オプションにユーザが追加されているのでこれを選択(下図)


●JB4.2のエミュレータでマルチユーザ機能を確認する方法は下記。
JB4.2エミュレータでは、端末形状に関わらず fw.max_users値 が1で定義されています。
このため、マルチユーザ機能が蓋閉めされている状態です。
※JB4.2標準ではタブレットのみマルチユーザ機能がONになる
定数定義はframeworks/base/core/res/res/values/config.xmlのconfig_multiuserMaximumUsers

JB4.2エミュレータでマルチユーザ機能を確認するためには、ユーザ数の上限を引き上げる必要があります。
$ setprop fw.max_users 2
上記システムプロパティを編集すれば、マルチユーザ管理に必要なUIが表示されるようになります。


マルチユーザ環境下でのデータフォルダの扱い

下記はシングルユーザ時とマルチユーザ時のデータフォルダの扱いの違いです。

●シングルユーザ時
/data/data/。。。

●マルチユーザ時
ユーザを1名追加した後のデータフォルダ状態。
・ユーザ状態
Primary : 初期ユーザ
newOne  : 追加したユーザ

・Primaryユーザ用ディレクトリ
/data/data/。。。
/data/user/0/。。。

・newOneユーザ用ディレクトリ
/data/user/10/。。。

/data/userディレクトリに各ユーザ用のデータフォルダが作成される。
Primaryユーザ用のディレクトリは2つあるわけではなく、/data/user/0が/data/dataへのシンボリックリンクとして扱われます。
$ ls -la /data/user
lrwxrwxrwx root     root              2013-02-05 10:11 0 -> /data/data/
drwxrwx--x system   system            2013-02-06 06:34 10

蛇足

○設定アプリの[ユーザ]項目の表示/非表示判定箇所
com.android.settings.Settings.updateHeaderList(List<Header>)
} else if (id == R.id.user_settings) {
    if (!UserHandle.MU_ENABLED
            || !UserManager.supportsMultipleUsers()
            || Utils.isMonkeyRunning()) {
        target.remove(i);    // [ユーザ]項目を削除

android.os.UserManager.getMaxSupportedUsers()
public static int getMaxSupportedUsers() {
    // Don't allow multiple users on certain builds
    if (android.os.Build.ID.startsWith("JVP")) return 1;
    return SystemProperties.getInt("fw.max_users",
            Resources.getSystem().getInteger(
                R.integer.config_multiuserMaximumUsers));
}
# どうも"JVP"から始まるビルドIDはマルチユーザ強制非対応の様子。