2011/02/02

Slim3 JSON機能の説明(非公式)

(2/7更新)
(2/26更新)
(12/22更新 @Jsonはフィールド直接指定になりました)

Slim3 JSON機能のドキュメントを書き始めました。まだ非公式なものですが、ひと通り書き終わったら公式へのマージを提案する予定です。でも、公式は英語なんですよね。どうしたものか。まぁ、いきなり下手な英語で書くより、まずは日本語でちゃんと書いたほうが良いはず。

というわけで、下記ドキュメントの草案です。若干改行が変ですが、evernoteに書きなぐってexportしたものを貼っつけてるためだと思います。これにあとJSON入出力のカスタマイズ方法を書いて一段落とする予定です。(書きました!)

概要
 Slim3のJSON機能は、モデル(@org.slim3.datastore.Modelアノテーションが付加されたクラス)のJSON変換機能を提供します。JSON変換は、org.slim3.datastore.ModelMeta<M>に定義される以下のメソッドを呼び出すことにより行われます。

モデルのJSON文字列への変換:
  • String modelToJson(Object model);
  • String modelToJson(Object model, int maxDepth);
  • String modelsToJson(Object[] models);
  • String modelsToJson(Object[] models, int maxDepth);
JSON文字列のモデルへの変換:

  • M jsonToModel(String json);
  • M jsonToModel(String json, int maxDepth);
  • M[] jsonToModels(String json);
  • M[] jsonToModels(String json, int maxDepth);
 例えばTestModelというモデルに対してJSON変換機能を使用するコードは、次のようになります。

TestModel m = new TestModel();
m.setValue(1);
String json = TestModelMeta.get().modelToJson(m);
System.out.println(json); // {"value": 1}
TestModel m2 = TestModelMeta.get().jsonToModel(json);
Assert.assertEquals(m.getValue(), m2.getValue());


JSON変換の制御
 フィールドにJSONアノテーション(@org.slim3.datastore.json.JSON)を指定することで、JSON変換の振る舞いを変更できます。以下にJSONアノテーションで指定できるパラメータを示します。

パラメータ名 デフォルト 説明
ignore boolean false このアトリビュートを無視します。JSON出力に含まれず、JSON入力時にも読み込まれません。
ignoreNull boolean true アトリビュートがnullの場合、何も出力しません。falseの場合は、"null"が出力されます。
alias String 空文字列 アトリビュートのJSON文字列内での名前を指定します。
coder Class<? extends JsonCoder> Default.class JSON入出力を行うJsonCoderのクラスを指定します。ここに独自のクラスを指定することで、JSON入出力のカスタマイズを行うことができます(後述)。

 例えばプロパティを無視したり、エイリアスを設定したりする場合、以下のように記述します。

@Model
class TestModel{
  ...
  @Json(ignore=true)
  private String ignoredValue;
  @Json(alise="foo")
  private String bar;
}


対応する値型
 Slim3のJSON変換機能は、以下の値型に対応します。また、後述するカスタマイズを行えば、これ以外の型に対応したり、入出力方法を変更する事ができます。

Javaクラス
JSON表現
java.lang.String, com.google.appengine.api.datastore.Text
文字列。cipher=trueの場合、JSON内では暗号化されます。
"text":"hello"
byte[], com.google.appengine.api.datastore.ShortBlob, com.google.appengine.api.datastore.Blob
バイト列のBase64文字列。
"blob":"mMB4qZAgtBKJq0d1LBGTCA=="
boolean, java.lang.Boolean
ブール値(true or false)。
"value":true
short, java.lang.Short, int, java.lang.Integer, long, java.lang.Long
整数。
"value":100
float, java.lang.Float, double, java.lang.Double
小数。
"value":1.0
java.util.Date
整数(Date.getTime()が返す値)。
"value":10233400
java.lang.Enum
文字列(Enum.name()が返す値)。
"value":"MONDAY"
com.google.appengine.api.users.User
ネストしたJSON文字列(User.getEmail()等の値をJSONエンコード)。
"user":{"authDomain":"authDomain","email":"user@test.com"}
com.google.appengine.api.datastore.Key
文字列(KeyFactory.keyToString(Key)の実行結果)。
"key":"aglzbGltMy1nZW5yCwsSBHRlc3QY6AcM"
com.google.appengine.api.datastore.Category
文字列(Category.getCategory()の値)。
"category":"partOfSpeech"
com.google.appengine.api.datastore.Email
文字列(Email.getEmail()の値)。
"mail":"user@domain.tld"
com.google.appengine.api.datastore.GeoPt
ネストしたJSON文字列(GeoPt.getLatitude()及びGeoPt.getLongitude()の値をJSONエンコード)。
"geopt":{"latitude":10.0,"longitude":10.0}
com.google.appengine.api.datastore.IMHandle
ネストしたJSON文字列(IMHandle.getAddress()及びIMHandle.getProtocol()の値をJSONエンコード)。
"handle":{"address":"handle","protocol":"xmpp"}
com.google.appengine.api.datastore.Link
文字列(Link.getValue()の値)。
"link":"linkValue"
com.google.appengine.api.datastore.PhoneNumber
文字列(PhoneNumber.getNumber()の値)。
"phone":"000-000-000"
com.google.appengine.api.datastore.PostalAddress
文字列(PostalAddress.getAddress()の値)。
"address":"Tokyo, Japan"
com.google.appengine.api.datastore.Rating
整数(Rating.getRating()の値)。
"rating":100
com.google.appengine.api.blobstore.BlobKey
文字列(BlobKey.getKeyString()の値)。
"blobkey":"Q3PqkweYlb4iWpp0BVw"
org.slim3.datastore.ModelRef<M>
文字列(モデルのkeyに対してKeyFactory.keyToString(key)した結果)。
"ref":{"key":"lskfo2ijalefkwejfwlke",value:100}

 また上記サポートする型のコレクションにも対応しています。対応するコレクションクラスはjava.util.List, java.util.Set, java.util.SortedSetで、JSON文字列からモデルを作成する際は、それぞれjava.util.ArrayList、java.util.HashSet、java.util.TreeSetをnewして要素を追加したものがセットされます。


ModelRef<M>の展開
 デフォルトではJSONアノテーションのcoderパラメータにorg.slim3.datastore.json.Defaultが指定されたものとして扱われ、このクラスは、ModelRefを参照先のモデルのキーに変換します。参照先のモデルの内容を展開したい場合、org.slim3.datastore.json.Expandedを指定して下さい。このクラスは、参照先のモデルの内容を展開し、そのモデルがさらにModelRefを持っている場合も展開します。展開のネストの深さは、modelToJsonメソッドやjsonToModelメソッドの、maxDepth引数で制限できます。
 以下にコード例を示します。

@Model
class TestModel{
  ...
  @Json(coder=Expanded.class)
  private ModelRef<TestModel> ref = new ModelRef<TestModel>(TestModel.class);
}
...
TestModel m = new TestModel();
TestModelMeta.get().modelToJson(m, 3);  // 3階層まで展開


JSON入出力のカスタマイズ
 JSONアノテーションのcoderパラメータにJSON入出力を行うクラスを指定することにより、JSON変換の振る舞いを変更することができます。デフォルトではorg.slim3.datastore.json.Defaultが指定されており、slim3が対応するデータ型のJSON入出力が行われます。slim3ではもう一つ、org.slim3.datastore.json.Expandedが用意されていて、これをModelRef<M>型のフィールドに対して使用すると、ModelRef<M>が参照しているオブジェクトも展開します。
 slim3が対応していないデータ型を使う場合や入出力方法を変更したい場合は、org.slim3.datastore.json.Defaultから継承したクラスを作成し、encode/decodeメソッドをオーバーライドして下さい。
 下記にjava.awt.Pointの入出力をサポートするクラスの例を示します。

class CustomCoder extends org.slim3.datastore.json.Default{
  public void encode(JsonWriter writer, Object value){
    if(value instanceof java.awt.Point){
      java.awt.Point pt = (java.awt.Point)value;
      writer.beginObject();
      writer.writeValueProperty("x", pt.x);
      writer.writeValueProperty("y", pt.y);
      writer.endObject();
    } else{
      super.encode(writer, value);
  }
  public <T> T decode(JsonReader reader, T defaultValue, Class<T> clazz){
    if(java.awt.Point.isAssignableFrom(clazz)){
      try{
        int x = Integer.parseInt(reader.readProperty("x");
        int y = Integer.parseInt(reader.readProperty("y");
        return clazz.cast(new Point(x, y));
      } catch(NumberFormatException e){
      }
    }
    return defaultValue;
  }
}

 java.awt.PointクラスのフィールドをJSON入出力の対象にするには、上記のCustomCoderをcoderパラメータに指定します。

import java.awt.Point;

@Model
class TestModel{
  public Key getKey(){
    return key;
  }

  public void setKey(Key key){
    this.key = key;
  }

  public Point getPoint(){
    return point;
  }

  public void setPoint(Point point){
    this.point = point;
  }

  @Attribute(primariKey=true)
  private Key key;

  @Attribute(persistent=false)
  @Json(coder=CustomCoder.class)
  private Point point;

}

 上記のように指定すると、java.awt.Point型のpointフィールドのJSON入出力がおこなえるようになります。

TestModel m = new TestModel();
m.setPoint(new Point(10, 20));
String json = TestModelMeta.get().modelToJson(m); // {"point":{"x":10,"y":20}}
TestModel m2 = TestModelMeta.get().jsonToModel(json);
Assert.assertEquals(m.x, m2.x);
Assert.assertEquals(m.y, m2.y); 

0 件のコメント: