スキーマの定義

モバイルアプリから Thing を操作する際、スキーマを定義する必要があります。

ここでは、スキーマ、アクション、アクションリザルト、ステートの概念があることを前提に説明します。概要については スキーマ をご覧ください。

スキーマ

Android 上でスキーマを定義する際は以下を表すクラスを定義し、それをスキーマとしてまとめます。

  • コマンドを構成する、Action と ActionResult を定義したクラスの配列
  • ステートを取得するための TargetState クラス

ここでは、スキーマの例として、簡単なエアコンを定義します。このエアコンでは 3 つのアクションを同時に指定できるものとします。

  • TurnPower アクション：電源を入れるかどうかの boolean 値（true で電源を入れる）
  • SetPresetTemperature アクション：設定温度（15～30 の数値）
  • SetFanSpeed アクション：ファンの強さ（0～10 の数値）

また、ステートとして、これら 3 つの設定値に加え、現在の温度と湿度を参照できるものとします。

以下にこれらのコマンドとステートの実装例を示します。

コマンドの定義

スキーマのコマンド部分は、アクションとアクションリザルトを 1 つの組として、それらを表現する Java のクラスを定義します。

  • アクション

    Action のサブクラスとして、モバイルアプリから送信するアクションを定義します。アクションに含まれるパラメータを、クラスの public フィールドで定義すると、その値を Thing に送信できます。

    SDK 内部ではアクションのクラスを Java のリフレクションによって読み取り、最終的に JSON 形式で Thing へのパラメータを組み立てます。

  • アクションリザルト

    ActionResult のサブクラスとして、Thing からのアクションリザルトを受け取るクラスを定義します。

    常に空のクラスとして定義します。モバイルアプリからはスーパークラス ActionResult に実装されている実行結果を示すメソッドを参照して結果を取得します。

いずれのクラスでも、アクション名を返すメソッドをオーバライドする必要があります。このメソッドが返すアクション名が Action と ActionResult で一致しないと、登録時にエラーとなります。アクション名は Thing Interaction Framework 上に登録され、モバイルアプリや Thing からアクションを識別するために使用します。

冒頭で示した例の場合、以下のような合計 6 個のクラスを定義することになります。

TurnPower

public class TurnPower extends Action {
  public boolean power;

  @Override
  public String getActionName() {
    return "turnPower";
  }
}

public class TurnPowerResult extends ActionResult {

  @Override
  public String getActionName() {
    return "turnPower";
  }
}

SetPresetTemperature

public class SetPresetTemperature extends Action {
  public int presetTemperature;

  @Override
  public String getActionName() {
    return "setPresetTemperature";
  }
}

public class SetPresetTemperatureResult extends ActionResult {
  @Override
  public String getActionName() {
    return "setPresetTemperature";
  }
}

SetFanSpeed

public class SetFanSpeed extends Action {
  public int fanSpeed;

  @Override
  public String getActionName() {
    return "setFanSpeed";
  }
}

public class SetFanSpeedResult extends ActionResult {
  @Override
  public String getActionName() {
    return "setFanSpeed";
  }
}

ここでは、単純な例のため各クラスのフィールドは 1 つですが、複数のフィールドを定義したり、文字列、配列、ネストした Object などを定義することも可能です（JSON 文字列に変換できれば使用できます）。

ステートの定義

スキーマのステート部分は、Thing から読み取りたい情報を TargetState クラスのサブクラスのフィールドとして定義します。

冒頭で示した例の場合、以下のようなクラスを定義することになります。

public class AirConditionerState extends TargetState {
  public boolean power;
  public int presetTemperature;
  public int fanSpeed;
  public int currentTemperature;
  public int currentHumidity;
}

Thing 側では、以下のような JSON を使ってステートを登録する必要があります。モバイルアプリの ステート取得機能 では、Thing からの JSON 文字列を上記のクラスにマッピングして返すことができます。

{
  "power" : true,
  "presetTemperature" : 25,
  "fanspeed" : 5,
  "currentTemperature" : 28,
  "currentHumidity" : 65
}

スキーマの定義

最後に、コマンドとステートを、スキーマとして 1 つにまとめます。最終的に生成された schema を、初期化コードの実装 の ThingIFAPIBuilder.addSchema に渡します。

// Create a schema builder with parameters.
SchemaBuilder sb = SchemaBuilder.newSchemaBuilder("airConditioner",
      "AirConditioner-Demo",
      1, AirConditionerState.class);

// Add action classes to the schema builder.
sb.addActionClass(TurnPower.class, TurnPowerResult.class).
      addActionClass(SetPresetTemperature.class, SetPresetTemperatureResult.class).
      addActionClass(SetFanSpeed.class, SetFanSpeedResult.class);

// Create a schema.
Schema schema = sb.build();

  1. SchemaBuilder.newSchemaBuilder メソッドでスキーマ等を定義して、SchemaBuilder インスタンスを取得します。

    上記のサンプルでは、第 1 引数から順に以下のパラメータを渡しています。

    • Thing のタイプ：100 文字までの英数字、ハイフン、アンダースコアおよびピリオドが利用可能（将来の拡張用で Thing タイプごとに利用できる機能を定義できるようになる予定）
    • スキーマ名：スキーマを識別するための名前を指定
    • スキーマのバージョン：公開後、バージョンによってスキーマの更新を識別
    • ステートクラスのクラス情報

    上記のスキーマ名とスキーマバージョンは、次に指定するアクション名とともに Thing 側の アクションハンドラー のコールバック関数で Thing Interaction Framework から受信したアクションを識別するための情報として利用します。

  2. 取得した SchemaBuilder インスタンスに対して、アクションの実装クラス、アクションリザルトの実装クラスの組を順に登録します。

    ここでは、3 組のアクションを順に登録しています。

  3. 最後に build メソッドを呼び出すと Schema を取得できます。