Message クラス

Message クラスは、ネットワークまたは処理空間全体で効率的に伝達されるようにメッセージを定義するために使用されます。メッセージはフィールド クラスを使用して定義されます。

Message は protorpc.messages モジュールによって提供されます。

はじめに

Message は、フィールド属性と、他の Message や Enum の定義のみを含むことができるという点で、通常のクラスよりも制限されています。このような制限が設けられているのは、Message クラスの構造そのものを、ネットワークまたは処理空間で転送し、クライアントで、または別のサーバーでも直接使用することを意図としているためです。そのため、言語と実装の相違により矛盾が発生することから、メソッドとフィールド以外の属性を構造情報とともに転送することはできません。

初期化と検証

Message オブジェクトにすべての必須フィールドがあり、ネストされたメッセージもすべて初期化されている場合、その Message オブジェクトは初期化済みとみなされます。

初期化されていない状態で check_initialized を呼び出すと、ValidationError が発生します。is_initialized は、オブジェクトが有効であるかどうかを示すブール値を返します。

Google プロトコル RPC は、Message オブジェクトが作成され、移入されると自動的に検証します。アプリケーションでは、指定した値が代入先のフィールドと互換性があるかどうかを Field インスタンスの validate() メソッドを使用して検証できます。このメソッドをメッセージに対して使用すると、メッセージのすべての値とそのサブメッセージが有効かどうかがチェックされます。フィールドに無効な値を代入すると ValidationError を送出します。

次の例では、架空の株取引アプリケーションで Message オブジェクトを作成、初期化しています。

from protorpc import messages

# Trade type.
class TradeType(messages.Enum):
    BUY = 1
    SELL = 2
    SHORT = 3
    CALL = 4

class Lot(messages.Message):
    price = messages.IntegerField(1, required=True)
    quantity = messages.IntegerField(2, required=True)

class Order(messages.Message):
    symbol = messages.StringField(1, required=True)
    total_quantity = messages.IntegerField(2, required=True)
    trade_type = messages.EnumField(TradeType, 3, required=True)
    lots = messages.MessageField(Lot, 4, repeated=True)
    limit = messages.IntegerField(5)

order = Order(symbol='GOOG',
              total_quantity=10,
              trade_type=TradeType.BUY)

lot1 = Lot(price=304,
           quantity=7)

lot2 = Lot(price=305,
           quantity=3)

order.lots = [lot1, lot2]

# Now object is initialized!
order.check_initialized()

コンストラクタ

Message クラスのコンストラクタは次のように定義されます:

class Message(**kwargs)

メッセージの内部状態を初期化します。

アプリケーションは、フィールド クラスに対応するキーワード引数を渡すことで、コンストラクタを介してメッセージを初期化します。次に例を示します。

class Date(Message)
    day = IntegerField(1)
    month = IntegerField(2)
    year = IntegerField(3)

クラス フィールドを定義したら、フィールド値を正確に呼び出すことができます。次の 2 つの呼び出しは同等です:

date = Date(day=6, month=6, year=1911)

これは次と同等です:

date = Date()
date.day = 6
date.month = 6
date.year = 1911

クラス メソッド

Message クラスには、次のクラス メソッドがあります:

all_fields()
すべてのフィールド定義オブジェクトを取得します。すべての値に対するイテレータを順不同で返します。
field_by_name(name)
フィールドを名前で取得します。名前に関連付けられた Field オブジェクトを返します。
指定された名前のフィールドが見つからない場合は KeyError を送出します。
field_by_number(number)
フィールドを数値で取得します。数値に関連付けられた Field オブジェクトを返します。
指定された数値のフィールドが見つからない場合は KeyError を送出します。

インスタンス メソッド

メッセージ インスタンスには、次のメソッドがあります。

check_initialized()
すべての必須フィールドが初期化されているかどうかをチェックします。
Message オブジェクトが初期化されていない場合は、ValidationError を送出します。
get_assigned_value(name)
属性に設定された値を取得します。値が設定されていない場合は None を返します。
引数:
name
取得する属性の名前。

属性に設定された値を返します。属性に値が設定されていない場合は None を返します。

is_initialized(name)
Message オブジェクトの初期化ステータスを取得します。メッセージが有効であれば True、有効でなければ False を返します。
reset(name)
フィールドに割り当てられた値をリセットします。つまり、デフォルト値が再設定されます。デフォルト値がない場合は None が設定されます。
引数:
name
リセットするフィールドの名前。