67 lines
4.2 KiB
Markdown
67 lines
4.2 KiB
Markdown
# 2.2. Operation
|
|
|
|
## 2.2.1 目的
|
|
|
|
Operationは、Objectに対して実行できる操作を表す。
|
|
|
|
WIPでは、本文を読む、metadataを取得する、検索する、状態を変更するなど、Objectに対する行為をOperationとして公開する。
|
|
|
|
## 2.2.2 Interface
|
|
|
|
ObjectはOperation定義を直接持たず、一つのInterfaceを参照する。
|
|
|
|
Interfaceの定義は[WIP IDL](draft/wip-idl.md) documentそのものである。IDL documentに宣言された関数の集合が、そのInterfaceのOperation集合となる。Operation名、parameter、return type、短いdocumentationは一つの関数宣言としてまとめて定義し、別のOperation descriptorへ重複して記述しない。
|
|
|
|
複数のObjectが同じInterfaceを参照できる。これにより、Collectionから多数の同種Objectを取得する場合でも、Operation定義を各Objectへ重複して埋め込む必要がない。
|
|
|
|
HostはInterfaceについて、参照、IDLのlanguage identifier、source、およびcacheや同一性確認に利用できるdigestをClientへ提供する。ObjectはInterface参照だけを持ち、Clientは未知のInterface定義だけを取得してcacheできる。
|
|
|
|
## 2.2.3 Operation declaration
|
|
|
|
Operationは、WIP IDL内で関数形式により宣言する。
|
|
|
|
```wip
|
|
/// Returns items related to this Object.
|
|
operation get_related_items(
|
|
relation: Relation,
|
|
limit?: integer,
|
|
) -> {
|
|
items: [entry],
|
|
next_cursor?: string,
|
|
};
|
|
```
|
|
|
|
Parameterは常に名前付きとし、位置引数は用いない。引数を持たないOperationは空のparameter list `()`で宣言する。
|
|
|
|
```wip
|
|
operation refresh() -> unit;
|
|
```
|
|
|
|
Return typeには任意のWIP IDL型を使用できる。ただし、将来fieldを追加する可能性があるOperationではrecordを基本とする。
|
|
|
|
Operationの用途は`///` documentation commentで簡潔に説明する。長文documentationや大量のdomain dataをInterfaceへ埋め込むことは想定しない。
|
|
|
|
## 2.2.4 可視性
|
|
|
|
Hostは、主体の権限やrole / capabilityに基づいて、その主体へ公開するInterfaceを決定してよい。
|
|
|
|
Operationの可視性は、頻繁に変化する実行可否やdomain stateを表すものではなく、**その主体に対してどのInterfaceを公開するか**というprojectionとして扱う。
|
|
|
|
同じObjectでも、主体ごとに異なるInterface参照を返してよい。
|
|
|
|
WIPはOperationの`available` / `disabled`のような揮発的状態をInterfaceへ同期することを前提としない。現在状態を判断する必要がある場合は、必要に応じてdomain固有のOperationで観測する。最終的なauthorizationと実行条件の判定は`call_operation`時にHostが行う。
|
|
|
|
## 2.2.5 Operation Result
|
|
|
|
`call_operation`は、対象ObjectのInterfaceに宣言されたOperation名と、parameter listに従う名前付きargumentsを受け取る。結果はOperationのreturn typeに従う型付きvalueとして返す。
|
|
|
|
Operation Resultには、WIP IDLの`entry`型として新しいエントリのpathが含まれ得る。
|
|
|
|
`entry`は同じWorldspace内のcanonical absolute pathであり、wire上では文字列として表現する。Clientはreturn typeに従って`entry`型の位置を認識し、返されたpathを一時的な発見結果として扱う。通常の`string`や任意JSON値に含まれるpathらしい文字列を、エントリとして推測してはならない。
|
|
|
|
Clientは発見したpathを必要に応じて`fetch`または`fetch_tree`する。複数pathの取得は、それぞれ独立したCore操作をTransport Bindingでbatchする。Operation Resultへエントリ公開情報を先行同梱しない。
|
|
|
|
Operationの実行対象と、結果として発見されたエントリのTree上の位置は独立している。発見されたエントリは実行対象の子である必要はなく、親、兄弟、またはWorldspace内の任意の位置にあるエントリであってよい。
|
|
|
|
Operationがエントリpathを返したこと自体から、実行対象との間に親子関係や意味的関係を推論してはならない。親子関係はTree上の配置で表し、非内包の意味的関係はOperation名、resultのfield名、またはdomain固有のrelation型で表現する。
|