2011-06-05

okuaymaのオリジナルプロトコルの仕様を表にまとめした。
からり表が大きく見にくくなってしまいました...orz
以降okuyama側に変更があった場合もこの表をメンテナンスしてきます。

事前説明ですが、
1.各要素間のセパレータは","になります。
2.Encode指定という部分はBase64でのEncode指定を意味します。
  送信側でEncodeで○となっている部分はBase64でエンコードしてから送信することを意味し、
  返却側はサーバからEncodeされた値が返されることを意味しますので、Decodeして使用してください。
3.追記
  2010/01/03:肝心なことを書き忘れてました。プロトコルの終端の区切りは"\r\n"です。
  2010/01/04:Valueにブランク(サイズ0の値)を指定したい場合はBase64 エンコードをせずに"(B)"という文字列を指定してください。
                      okuyama側でブランクとして扱われます。
  2010/01/04:Key値にブランク(サイズ0の値)は指定できません。エラーとしてください。
  2010/01/04:Tag値に"(B)"を指定した場合は、okuyama側でTag指定なしとして処理されます。
  2011/06/06:incrValue、decrValue、getMultiValue、getTagValues、removeTagFromKey、setValueAndCreateIndex、searchValueのプロトコルを追記しました。

メ
ソッド名

処理内容

説
明

サー
バから返却される値

第2
要素

第3
要素

第4
要素

第5
要素

第6
要素

第1

要素

第2
要素

第3
要素

第4
要素

initClient

保存可能な最大サイズをMasterNodeへ問い合わせる

値

true

数値

Valueのbyte長

Encode

例

0,true,1048576

setValue

値を保存する(Tagの有り無しで転送の第3要素が変化する)

値

Key値

Tag値

Tagを指定しない場合は"(B)"を連結する。存在する場合はTag文字列を":"をセパレータに連結する

分散ロック値

"0"固定

Value値

"true" or "false" or
"error"

正常に保存出来た場合は"true".なんだかの理由により論理的(サイズオーバーなど)に保存できない場合は"false".サーバ側でエラーの場合は
"error"

"OK" or メッセージ

返却第2要素が"true"の場合は"OK"になる."false"や、"error"の場合はメッセージが格納される

Encode

○

(B)の場合は×

Tagが存在する場合は1Tag単位でエンコード

○

例

例1正常保存)
1,true,OK

例2Value値サイズオーバー) 1,false,Value Length Error

getValue

Keyを指定して値を取得

値

Key値

"true" or "false" or
"error"

値が取得出来た場合は"true".取得できない、なんだかの理由により論理的(サイズオーバーなど)に取得できない場合は"false".サーバ側でエ
ラーの場合は"error"

Value値 or メッセージ

返却第2要素が"true"の場合はValueになる."false"や、"error"の場合はメッセージが格納される

Encode

○

○ or ×

返却値の第2要素が"true"の場合は○.それ意外は×

例

例1値あり)
2,true,dmFsdWUx

例2値なし) 2,false,

例3Key値サイズオーバー) 2,false,Key Length Error

getTagKeys

Tagを指定することでKey値を取得する

値

Tag値

"true" or
"false"

削除済みのKey-Valueセットの扱い.trueを指定すると、削除済みでもKey値は返される

falseを指定すると、削除済みのKey値は返されない.

Value値 or メッセージ

返却第2要素が"true"の場合は同じTagが打たれているKey値の連結文字列になるになる.セパレータは":"

"false"や、"error"の場合はメッセージが格納される

Encode

○

○ or ×

返却値の第2要素が"true"の場合は○.それ意外は×

例

例1Key値あり)
4,true,dGFnc2FtcGxlZGF0YWtleV8w:a2V5MQ==:a2V5Mw==

例2値なし) 4,false,

例3Tag値サイズオーバー) 4,false,Tag Length Error

removeValue

Key値を指定することでKey-Valueセットを削除する

値

Key値

分散ロック値

"0"固定

"true" or "false" or
"error"

値が削除出来た場合は"true".取得できない、なんだかの理由により論理的(サイズオーバーなど)に取得できない場合は"false".サーバ側でエ
ラーの場合は"error"

Value値 or メッセージ

返却第2要素が"true"の場合は削除対象のValue値

"false"や、"error"の場合はメッセージが格納される

Encode

○

○ or ×

返却値の第2要素が"true"の場合は○.それ意外は×

例

例1Key値あり)
5,true,c2F2ZWRhdGF2YWx1ZXN0cl8w

例2値なし) 5,false,

例3Key値サイズオーバー) 5,false,Key Length Error

setNewValue

値を保存する(Tagの有り無しで転送の第3要素が変化する)

既に同値のKeyがサーバに存在する場合は失敗する

memcachedの"add"命令に相当する

値

Key値

Tag値

Tagを指定しない場合は"(B)"を連結する。存在する場合はTag文字列を":"をセパレータに連結する

分散ロック値

"0"固定

Value値

"true" or "false" or
"error"

正常に保存出来た場合は"true".なんだかの理由により論理的(既にKeyが存在する.サイズオーバーなど)に保存できない場合は"false".
サーバ側でエラーの場合は"error"

"OK" or メッセージ

返却第2要素が"true"の場合は"OK"になる."false"や、"error"の場合はメッセージが格納される

Encode

○

(B)の場合は×

Tagが存在する場合は1Tag単位でエンコード

○

例

例1成功)
6,true,OK

例2失敗) 6,false,NG:Data has already been registered

getValueVersionCheck

値を取得すると同時に該当Key-ValueセットのVersionNoも返す

memcachedの"gets"命令に相当する

値

Key値

Value値 or メッセージ

返却第2要素が"true"の場合はValueになる."false"や、"error"の場合はメッセージが格納される

VersionNo値(数値)

Encode

○

例

例1取得成功)
15,true,dmFsdWUx,0

例2取得成功VersionNo値が"2") 15,true,dmFsdWUx,2

例3値なし) 15,false,,

setValueVersionCheck

Key-Valueのセットを更新する.この際に、VersionNoを同時に渡し、VersionNoがサーバ側で変更されていない場合のみ処理が成功
する

memcachedの"cas"命令に相当する

値

Key値

Tag値

Tagを指定しない場合は"(B)"を連結する。存在する場合はTag文字列を":"をセパレータに連結する

分散ロック値

"0"固定

Value値

VersionNo値

getValueVersionCheckで取得した値

"true" or "false" or
"error"

正しく更新出来た場合は"true".更新出来ない、なんだかの理由により論理的(サイズオーバーなど)に取得できない場合は"false".サーバ側で
エラーの場合は"error"

"OK" or メッセージ

返却第2要素が"true"の場合は"OK"になる."false"や、"error"の場合はメッセージが格納される

Encode

○

(B)の場合は×

Tagが存在する場合は1Tag単位でエンコード

○

例

例1更新成功)
16,true,OK

例2更新失敗) 16,false,NG:Data has already been updated

incrValue

数値を加算処理を行う。

加算する対象のKey-Valueはあらかじめ登録しておく必要がある。

登録済みのValueが数値ではない

Key-Valueセットに実行すると、Valueが０に初期化される。

memcachedの"incr"命令に相当する

値

Key値

分散ロック値

"0"固定

Value値

(数値のみ)

"true" or "false"

正しく更新出来た場合は"true".更新出来ない、なんだかの理由により論理的(サイズオーバーなど)に更新出来ない場合は"false"

演算結果or メッセージ

返却第2要素が"true"の場合は加算後の結果数値になる."false"の場合はメッセージが格納される

Encode

○

例

例1更新成功)
13,true,Nw=

例2更新失敗) 13,false,NG

decrValue

数値を減算処理を行う。

減算する対象のKey-Valueはあらかじめ登録しておく必要がある。

登録済みのValueが数値ではない

Key-Valueセットに実行すると、Valueが０に初期化される。

0よりも小さい値の減算は出来ない。

つまり0に減算を行っても0のままとなる

memcachedの"decr"命令に相当する

値

Key値

分散ロック値

"0"固定

Value値

(数値のみ)

"true" or "false"

正しく更新出来た場合は"true".更新出来ない、なんだかの理由により論理的(サイズオーバーなど)に更新出来ない場合は"false"

演算結果or メッセージ

返却第2要素が"true"の場合は加算後の結果数値になる."false"の場合はメッセージが格納される

Encode

○

例

例1更新成功)
14,true,Nw=

例2更新失敗) 14,false,NG

getMultiValue

Keyを複数指定して値を取得

memcachedのgetコマンドにKey値を

複数個並べて一度に取得する

命令(GetMulti)に相当

値

Key値

(カンマ区切りで取得したい

Key値を複数指定)

22 or

"END"

"true" or "false"

値が取得出来た場合は"true".取得できない、なんだかの理由により論理的(サイズオーバーなど)に取得できない場合は"false"

指定したKey値の順番にValueが

改行区切りで返される。

Value値

返却第2要素が"true"の場合はValueになる."false"の場合はこの値はない

Encode

○

(特記事項)

上記の返却文字列は1つのKeyとValueのセット単位で改行(LF)区切りで返される

つまり改行(LF)区切りでNetworkから読み出し、その単位が送信したKey値の順番に

紐付く結果となる。そして最後に"END"という文字列が終了を意味するマーカー

として返却され処理は終了となる。

例

例1)
22,true,dmFsdWUxMA==

22,false,

22,true,dmFsdWUxMg==

22,true,dmFsdWUxMw==

END

※上記は"key12"はデータとして存在しない場合の返却例である。

getTagValues

Tagを指定して、そのTagが登録されている、KeyとValueのセットを取得する。

挙動としてはgetMultiValueと非常ににているが、返却される値が、Keyと

Valueの連結文字列になっている部分が異なる。

値

Tag値

(複数指定は不可)

23 or

"END"

"true"

エンコードされたKey値

エンコードされたValue値

Encode

○

(特記事項)

上記の返却文字列は1つ紐付くのデータ単位で改行(LF)区切りで返される

つまり改行(LF)区切りでNetworkから読み出し、その単位デコードを行い処理する。

返却される第3要素はKey値をBase64でエンコードした値となる

返却される第4要素は第3要素のKey値に紐付くValue値をBase64でエンコードした

値となるそして最後に"END"という文字列が終了を意味するマーカーとして返却され

処理は終了となる。

例

例1)
23,true,dGFnc2FtcGxlZGF0YWtleV80,dGFnc2FtcGxlc2F2ZWRhdGFfNA==

23,true,dGFnc2FtcGxlZGF0YWtleV8w,dGFnc2FtcGxlc2F2ZWRhdGFfMA==

23,true,dGFnc2FtcGxlZGF0YWtleV8x,dGFnc2FtcGxlc2F2ZWRhdGFfMQ==

23,true,dGFnc2FtcGxlZGF0YWtleV8y,dGFnc2FtcGxlc2F2ZWRhdGFfMg==

END

removeTagFromKey

Tag値とそのTag値に紐付くをKey指定することでTagとの紐付きを削
除できる。

値

Tag値

Key値

分散ロック値

"0"固定

"true" or "false" or
"error"

値が削除出来た場合は"true"。論理的理由指定のKey値とTag値の紐付きが無いなど)に
より削除できない場合は"false".サーバ側でエ
ラーの場合は"error"

返却第2要素が"true"の場合はなし

"false"や、"error"の場合はメッセージが格納される

Encode

○

例

例1値あり)
40,true,

例2値なし) 40,false,

例3Key値サイズオーバー) 40,false,Key Length Error

setValueAndCreateIndex

値を保存する

保存と同時に全文検索用の検索Indexを

作成する。

作成時の解析方式は、N-Gram

作成するIndexのグルーピィングや、N-GramのNの長さを指定できる。

デフォルトの挙動では1(ユニグラム)、2(バイグラム)、3（トリグラム)文字でインデックスが

作成される。

値

Key値

Tag値

Tagを指定しない場合は"(B)"を連結する。存在する場合はTag文字列を":"をセパレータに連結する

分散ロック値

"0"固定

Value値

第6要素	第7要素	第8要素
グループ名作成される検索Indexが所属するグループ名グループ指定しない場合は、 "(B)"を連結	Indexの最短の長さ数字指定デフォルト "1"を指定すること	Indexの最長の長さ数字指定デフォルト"3"を指定すること

※表を拡張するのが大変なのでまとめて

ここにかきました。

"true" or "false" or
"error"

正常に保存出来た場合は"true".なんだかの理由により論理的(サイズオーバーなど)に保存できない場合は"false".サーバ側でエラーの場合は
"error"

"OK" or メッセージ

返却第2要素が"true"の場合は"OK"になる."false"や、"error"の場合はメッセージが格納される

Encode

○

(B)の場合は×

Tagが存在する場合は1Tag単位でエンコード

○

○

(B）の場合は×

※表を拡張するのが大変なのでまとめて

ここにかきました。

例

例1正常保存)
42,true,OK

例2Value値サイズオーバー) 42,false,Value Length Error

searchValue

検索したいWordを指定して、setValueAndCreateIndexで登録した

Valueに文字検索を行う

検索Indexを限定するグループ指定や、

検索時に検索WordをN-Gram方式で分解

する長さを指定できる。

値

検索

文字列群

複数指定する場合は文字列を":"をセパレータに連結する

複数検索条件の挙動

(AND or OR)

"1"=AND

"2"=OR

検索対象Indexのグルー
プ名

グループなし

okuyamaooの日記

okuyamaプロトコル仕様表