.. Objects

============
オブジェクト
============

.. For each object you want to appear in your sequence diagram, type:

シーケンス図の中に登場するオブジェクトは以下の形式のテキストで表現されます::

   <名前>:<タイプ>[<フラグ>] "<ラベル>"

..  <name>:<Type>[<flags>] "<label>"

.. or:

もうひとつは以下の形式になります::

   /<名前>:<タイプ>[<フラグ>] "<ラベル>"

..  /<name>:<Type>[<flags>] "<label>"
      
.. into the text area. This represents an instance of class <Type>, named <name> which will be shown as a lifeline. <name>. The [<flags>] and "<label>" parts are optional:

これらのテキストを、テキストエリアの中で入力していきます。\ ``<タイプ>``\ という型を持ち、\ ``<名前>``\ を持つインスタンスが生成され、ライフラインとしてみることができます。\ ``[<フラグ>]``\ と\ ``"ラベル"``\ はオプションになります。

.. If you specify a quoted label, it will be used to label the object with, otherwise the object's label will be derived from the name and the type.

引用符でくくられたラベルを設定すると、オブジェクトのラベルとして使用されます。設定しなかった場合には、名前とタイプ名から構成されたラベルが使用されます。

.. Invisible objects

見えないオブジェクト
====================

.. If <name> is prefixed with a '/', the lifeline will be invisible until the instance is created by a 'new' message to <name> (see below).

もしも\ ``<名前>``\ の前に\ ``'/'``\ をつけると、ライフラインが見えなくなります。この\ ``<名前>``\ オブジェクトに対して、\ ``'new'``\ メッセージが送信されると初めてライフラインが表示されるようになります。詳細は後で述べます。

.. Flags

フラグ
======

.. An object declaration can be followed by a sequence of <flags> between square brackets. Four flags (a,p,r,x) are supported:

オブジェクト宣言の後ろには、角括弧で囲んで、フラグをいくつか書くことができます。\ ``a``, ``p``, ``r``, ``x``\ の4つのフラグがサポートされています(訳注:5つあるが？):

.. a-nonymous

(a)アノニマス(無名)
-------------------

.. The object is anonymous, so the name (which must still be there in order to be able to reference the lifeline) will not appear on the diagram, just a colon followed by the type. This flag is useless if a <label> is specified.

オブジェクトを無名に設定します。図の中で名前が表示されなくなり、タイプ名との境目となるコロン(:)より後だけになります。ただし、ライフラインの指示で必要なため、テキスト表現の中では仮の名前を設定する必要があります。このフラグは、<ラベル>が指定された場合には無効になります。

.. r-ole

(r)ロール
---------

.. The label of the lifeline will not be underlined.

ライフラインのラベルにアンダーラインが付かなくなります。

.. p-rocess

(p)プロセス
-----------

.. The object behaves like an actor (see below), but it is represented by a box with a thick border, not by a figure.

オブジェクトはアクターのように振舞います。ただし、人の絵ではなく、太枠で囲まれたボックスとして表現されます。

.. e-external

(e)外部
----------

.. (Only) a process can be declared to be external, which means that it represents an external entity with the ability to send "found" messages, but not appearing on the diagram. Messages originating from an external process are represented by arrows starting with filled circles.

プロセスのみ外部と宣言をすることができます。これを宣言すると、\ ``"found"``\ メッセージを送信することが可能な、外部のエンティティになりますが、図の中には表示されなくなります。外部プロセスから来るメッセージは、塗りつぶされた円で始まる矢印として表現されます。

.. x-auto-destruction

(x)自動破棄
-----------

.. The object is destroyed when it has sent its last answer, denoted by a cross below its lifeline. One might interpret this as automatic destruction of non-persistent objects by a garbage collector.

オブジェクトは最後の返答をしたあとに破棄されるようになります。破棄はライフラインの最後にバツ印が付くことで表現されます。これは、ガーベジコレクタによって、非永続オブジェクトが自動的に破棄されたという風に解釈ができます。

.. There are other flags, relevant for multithreading .

これら以外にも、マルチスレッドに関するフラグがいくつかあります。

.. Actors

アクター
========

.. If <Type> is 'Actor', the lifeline belongs to an actor. An actor is always active and sends asynchronous messages. It cannot send messages to itself. Also, it cannot receive answers (see below). In order to send an answer to an actor, one must use an explicit message.

もし\ ``<タイプ>``\ として\ ``'Actor'``\ が指定されると、ライフラインはアクターに属すようになります。アクターは常にアクティブで、非同期にメッセージを送ることができます。自分自身にメッセージを送ることはできません。当然、返信を受け取ることもできません(以下参照)。アクターに対して返信を送る場合には、明示的なメッセージを使用する必要があります。

.. Messages

==========
メッセージ
==========

.. The lines in the message section have the following format:

メッセージセクションの行は、以下のようなフォーマットで記述します

..  <caller>[<s>]:<answer>=<callee>[m].<message>

::

  <呼び出し元>[<s>]:<返信>=<呼びだし先>[m].<メッセージ>

.. <caller> is the name of an object that has been declared in the object section. It is either the first one to send a message or has received a message before and not yet answered to it. Otherwise it is not active and cannot send a message.[<s>] is optional and refines the specification of the caller object.

``<呼び出し元>``\ はオブジェクトセクションで定義済みのオブジェクトの名前を指定します。このオブジェクトは、最初にメッセージを送信するケースと、メッセージを受け取っているが、まだ返事を返していないという両方のケースでも記述することができます。アクティブになっていない場合にはメッセージを送信することはできません。\ ``[<s>]``\ はオプションの引数で、呼び出し元オブジェクトの定義を詳細化します。

.. If <s> is a number, it denotes the 'level' of the caller: A caller may have received k messages to which it has yet to answer. Then <s> can range from 0 to k-1. Before <caller> sends the message, it will answer to the <s> most recent messages.

もしも\ ``<s>``\ に数値が指定された場合には、呼び出し元の'レベル'を意味します。呼び出し元オブジェクトはk個のメッセージを受け取ります。このとき、\ ``<s>``\ には0～k-1までの数値を入れることができます。\ ``<呼び出し元>``\ がメッセージを送る前に、最近の\ ``<s>``\ 個のメッセージに対して答えるようになります。

.. note::

   (訳注)以下の二つのスクリプトを入力して比較してみてください。

   (A)パターン::

     a:A
     b:B

     a[2]:a.test
     a[0]:b.call

   (B)パターン::

     a:A
     b:B

     a[2]:a.test
     a[1]:b.call

   1を入れると、ネストを一段戻ってからメッセージを送付していることが分かります。

.. If <s> is not a number, it is a mnemonic. A mnemonic can be defined for a callee (by using the optional [<m>] part). If <s> is a mnemonic that has been defined for the object <caller> and <caller> is still active, <caller>[<s>] references this object.

``<s>``\ が数値でなかった場合には、ニーモニックとして扱われます。ニーモニックは呼び出し先に対して、オプションの\ ``[<m>]``\ 部を利用して定義されます。もしも\ ``<s>``\ が\ ``<呼び出し元>``\ オブジェクトに対して定義されており、\ ``<呼び出し元>``\ がアクティブの場合には、\ ``<呼び出し元>[<s>]``\ はこのオブジェクトを参照します。


.. <answer>= is optional and <answer> is simply a string representing the answer to the message. This string is used as a label of a dashed arrow from the <callee> to the <caller> lifeline. Note that there cannot be answers to messages sent by and to actors.

``<answer>=``\ はオプションのパラメータです。\ ``<answer>``\ には、メッセージの返り値に関する、シンプルな文字列表現を入れます。

.. <callee>. is optional and <callee> denotes the object that receives the message represented by the string <message>, which is used as a label of an arrow from <caller> to <callee>. If no <callee> is specified, <message> is interpreted as an description of a simple action (not another invocation of a method/procedure) performed by the caller.

``<呼び出し先>.``\ はオプションで、\ ``<呼び出し先>``\ は文字列形式の<メッセージ>を受け取るオブジェクトをあらわします。\ ``<メッセージ>``\ は、\ ``<呼び出し元>``\ から\ ``<呼び出し先>``\ に対して作成される矢印のラベルとして使用されます。もしも\ ``<呼び出し先>``\ が指定されなかった場合には、呼び出し元自身が実行する、単純なアクションとして解釈され、他のオブジェクトに対するメソッドやプロシージャの呼び出しにはなりません。

.. [<m>] is optional and <m> is a mnemonic containing at least one character that is not a digit. As long as the callee is active, it can be referenced as a caller by its name followed by [<m>].

``[<m>]``\ はオプションで、\ ``<m>``\ に対しては一文字以上の文字列のニーモニックを指定します。数値であってはいけません。呼び出し先がアクティブな場合には、呼び出し元のオブジェクトを、\ ``[<m>]``\ で指定した名前で参照できるようになります。

.. note::

   (訳注):どのようにすればこの機能が動くのか分かっていません。

.. <message> can consist of more than one line, separated by (a literal) \n.


``<メッセージ>``\ には1行以上のテキストを書くことができます。必要に応じて\ ``\n``\ で区切ってください。

.. Constructors

コンストラクタ
==============

.. Messages that are named ' new ' or that start with ' new( ' are special messages. They can be sent only once to objects that were declared with a '/' before their names. On receiving a 'new' message, the object will be created and its lifeline will become visible.

``'new'``\ という名前のメッセージもしくは、\ ``'new('``\ から始まるメッセージは、特別なメッセージとして扱われます。これらのメッセージは、オブジェクト宣言時に\ ``'/'``\ を先頭に付加されたオブジェクトの対して、一回だけ送ることができます。\ ``'new'``\ メッセージを受信すると、そのオブジェクトはライフライン上に作成されて、見えるようになります。

.. Destructors

デストラクタ
============

.. Messages that are named ' destroy ' or that start with ' destroy( ' are also special. They can only be sent to an object that is not active. After receiving the destroy-message, the object may become active for the last time and, for example, send some destroy messages to other objects. But after this last activity ended, the object is destroyed (denoted by a cross below its lifeline) and cannot be reclaimed.

``'destroy'``\ という名前のメッセージもしくは、\ ``'destroy('``\ から始まるメッセージも、特別なメッセージとして扱われます。これはアクティブではないオブジェクトにしか送ることはできません。\ ``'destroy'``\ メッセージを受け取ると、一時的にアクティブになり、他のオブジェクトに\ ``'destroy'``\ メッセージを送ったりすることができます。その最後の活動が終わると、オブジェクトが破棄されます。ライフラインの最後にバツ印が付きます。その状態になると、それ以上メッセージを受け取ることはできなくなります。

.. Actor messages

アクター・メッセージ
====================

.. Actors can only send and receive asynchronous messages that return immediately. An asynchronous message will be generated that is sent back to the actor when the activity that was started by his message is finished.

アクターはメッセージの送信と、すぐに返ってくる非同期メッセージの受信のみを行うことができます。非同期メッセージは、アクターのメッセージによって開始されたアクティビティが終了したことを通知する場合に使用されます。

.. If an actor sends a message to an ordinary object, all activities will be finished before. An actor should typically send the first message of the diagram, but this is not necessary, sequences without even a single actor are still supported.

もしもアクターが通常のオブジェクトに対してメッセージを送信すると、すべてのアクティビティはその前に終了します。通常、アクターはシーケンス図の最初のメッセージの送信を行いますが、必ずしもそうである必要はありません。アクターが一人もいないシーケンス図もサポートしています。

.. Broadcast messages

メッセージのブロードキャスト
============================

.. See multithreading .

マルチスレッドのドキュメントを参照してください。

.. Annotations

==============
アノテーション
==============

.. Diagrams can be annotated in three different ways.

図にアノテーション(注釈)をつける方法は３種類あります。

.. Source text comments

ソーステキストコメント
======================

.. First, you may insert lines starting with a '#' in the textual description. These lines serve as comments and will not be interpreted, unless they start with '#!', which indicates an active comment.

テキスト記述の中で、\ ``'#'``\ から始まる行を書くと、コメントになります。これらの行に何を書いても、図には何も書かれません。ただし、アクティブコメントとして解釈される\ ``'#!'``\ を除きます。

.. Title

タイトル
--------

.. A line of the form:

以下の形式で書くと図のタイトルを指定することができます::

  #![<title>]
          
.. specifies a diagram title. If it is present, the diagram will be surrounded by a frame, with the title written at the top left corner of the frame.

もしタイトルが指定されると、図が枠で囲まれて、その枠の左上にタイトルが記述されます。

.. Description

説明
-----------

.. A sequence of lines of the form:

以下の形式の行を書くと、図の上側にかかれるテキストとして解釈されます::

  #!>>
  #!A paragraph
  #!of text describing
  #!what is going on.
  #!<<

.. is interpreted as text that will be written above the diagram.

.. Fragments

フラグメント
============

.. Second, a sequence of messages can be declared to be a fragment of the diagram. A fragment is represented by a frame surrounding those messages. It has a type (for example: alt, cond, or opt), appearing in the top-left corner, and a text, appearing in square brackets at the top of the frame. The text typically represents a condition. For example:

2つめの方法として、一連のメッセージを図のフラグメント(１部)として宣言することができます。フラグメントは、これらのメッセージを囲む、枠として表現されます。フラグメントはタイプ(例えば、alt(別案), cond(条件), opt(オプション))を持ちます。これは枠の左上の角に書かれます。また、枠の左上の四角い枠の中に書かれるテキストを記述することもできます::

  [c:<タイプ> <テキスト>]
    foo:bar.message_1
    foo:bar.message_2
    ...
    foo:bar.message_n
  [/c]


.. [c:<type> <text>]
     foo:bar.message_1
     foo:bar.message_2
     ...
     foo:bar.message_n
   [/c]

Fragments can be slightly abused: if you write [c <text>] (without the colon), all of the text will appear in the small box in the top left corner.
Fragments may contain sections. To open a new section, insert a line of the form:

フラグメントはこのような用途とはまた別の使い方をすることもできます。コロン(:)をつけないで、\ ``[c <text>]``\ と書くと、すべてのテキストが枠の左上の角の小さい箱の中に書かれます。フラグメントはセクションも持つことができます。新しいセクションを開く場合には、以下のような形式の行を挿入します::

  --何らかのテキスト

..  --some text

.. The effect is that a dashed line is drawn from the left to the right end of the current fragment frame, with "some text" being written below this line.

この行を挿入すると現在のフラグメントの左端から右端まで、点線が引かれて、その線の下に\ ``'何らかのテキスト'``\ とテキストが表示されます。

.. Notes

ノート
======

.. Third, there are notes. These appear in a box resembling a piece of paper that is arranged to the right of a lifeline. Notes are a part of the message section. The top of the box is where an arrow belonging to a message specified at the same position in the text would appear. The syntax is similar to a here-document delimited by an asterisk followed by a number (without the <<):

3つめのアノテーションはノートです。ノートを記述すると、付箋紙を模したボックスがライフラインの右側に現れます。ノートはメッセージセクションの一部です。ボックスは、ボックスが属するメッセージの矢印の、テキストが表示されているのと同じ位置の上段配置されます。文法としては番号が後ろに付いて、\ ``<<``\ のない、ヒアドキュメントとほぼ同じです::

  *<番号> <名前>
  複数
  行の
  ノート
  *<数値>

..  *<num> <name>
    multi-
    line
    note
    *<num>

.. <name> is the name of the lifeline such that the note is to the right of it. <num> is the unique number identifying the note. You can refer to this number anywhere in the code - even before the note - in order to associate the note to messages or lifelines. For this you add one of the following prefixes to a message or the name of a lifeline:

``<名前>``\ はノートを表示する位置のすぐ左のライフラインの名前です。\ ``<番号>``\ はノートを識別する、ユニークな数値を入れます。スクリプトのどこであっても、この数値を使ってノートを参照して、ノートとメッセージ、もしくはライフラインを関連付けすることができます。ノートが宣言される前であっても問題ありません。実際に参照する場合には、以下のようにして、メッセージもしくはライフライン名の前に、関連する数値の参照を追加します:

.. * (<num>). A line will be drawn from the note box with the number <num> to the message arrow or to the current vertical position of the lifeline.
.. * (<num>,<anum>). This can only be the prefix of a message. The effect is the same as above, if <num> is not empty. Additionally, there will be a line drawn from the note box <anum> to the arrow belonging to the answer of the message

* (``<番号>``): ``<番号>``\ を持つノートのボックスから、メッセージの矢印、あるいは現在のライフラインに対して垂直な位置に対する破線が引かれます。
* (``<番号>``, ``<返答番号>``): これは、メッセージの前にのみ設定することができます。ライフラインには設定できません。もしも\ ``<番号>``\ が空でない場合には、上記の書き方と同じ結果になります。これに加えて、\ ``<返答番号>``\ が指定されたノートの箱から、メッセージの返答部を表す矢印に対してラインが引かれます。

.. Example:

サンプル::

    *5 foo
      fooはbarのwaitメソッドをコールします。
    *5
    *6 foo
      fooはbarを待ちます
    *6
    *7 foo
      barの準備が完了しました
    *7
    
    (5,7)foo:ready=bar.wait()
    (6)foo
     bar:何かする
    (6)foo
    bar:さらに何かする
        

..  *5 foo
      foo calls bar's wait method
    *5
    *6 foo
      foo is waiting for bar
    *6
    *7 foo
      bar is ready
    *7
    
    (5,7)foo:ready=bar.wait()
    (6)foo
     bar:do something
    (6)foo
    bar:do something more


.. If you use a "+" instead of a "*", the note box will consume as much vertical space as it needs and there will not be any message arrow or other note box beside it. When using "*", the note box will consume its own vertical space only if it is followed by a message arrow that is adjacent to one its both neighbour lifelines.

``"*"``\ の代わりに\ ``"+"``\ を使用すると、ノートのボックスは必要なだけ垂直な空間を消費します。同じ水平な空間には、メッセージの矢印や、ノートのボックスが来ることがなくなります。\ ``"*"``\ を使用すると、ノートのボックスは、もっとも近所のライフラインをつなぐメッセージの矢印に属している場合のみ、縦方向の空間を消費するようになります。

``"+"``\ を使用した例::

  foo:Foo
  bar:Bar

  +6 foo
     fooはbarを待っている
  +6
  +7 bar
     barの準備が完了
  +7
  
  (7)foo:ready=bar.wait()
  (6)foo

``"*"``\ を使用した例::

  foo:Foo
  bar:Bar

  *6 foo
     fooはbarを待っている
  *6
  +7 bar
     barの準備が完了
  +7
  
  (7)foo:ready=bar.wait()
  (6)foo


.. There are no direct associations between notes and objects. If one wishes to note something concerning an object or actor, she or he should specify a note belonging to the corresponding lifeline before any message has been specified.

ノートとオブジェクトを直接関連付けする方法はありません。もしも、オブジェクトかアクターに対して、何か気になることを記述したい場合には、メッセージが何か定義される前に該当するライフラインにノートを付加することで行うことができます。

.. Links

リンク
------

.. A single-lined note that starts with "link:" is interpreted as a link to another sequence diagram. The part of the line that follows is a URI (see RFC 3986 ) of an sd file. If the URI is relative, it is resolved against the location of the file of the current diagram. Example:

``"link:"``\ で始まる一行ノートは、他のシーケンス図へのリンクであると解釈されます。その行の残りの部分は他のsdファイルへのURI(RFC 3986参照)になります。もしも相対パスとしてURIが記述された場合には、現在のシーケンス図のファイルを起点としたパスとして解決されます::

  #ファイル"a.sd"の開始
  a:A
  
  *1 a
  link:b.sd
  *1 a
  #終了

.. #BEGIN of file "a.sd"
   a:A
   
   *1 a
   link:b.sd
   *1 a
   #END

::

  #ファイル"b.sd"の開始
  #"a.sd"と同じディレクトリに置かれている
  b:B
  #終了


.. #BEGIN of file "b.sd",
   #located in the same directory as "a.sd"
   b:B
   #END

.. When the note in the "a.sd" diagram is clicked, "b.sd" will be opened.

ここで、\ :file:`a.sd`\ の図の中のノートをクリックすると、\ :file:`b.sd`\ がオープンされます。

.. There is a problem when the characters behind "link:" contain spaces. This is a bad URI syntax. Spaces must be replaced by "%20". Especially on Windows, where directory names with spaces are far from being exceptional - for instance "Program Files" - one may easily run into this problem when trying to specify absolute paths.

もしも\ ``"link:"``\ の後ろの文字がスペースを含んでいると、厄介なことが発生します。これはURIの文法としては間違っているからです。スペースを記述する場合には、\ ``"%20"``\ に置換する必要があります。特にWindowsでは\ :file:`"Program files"`\ などのように、スペースを含むディレクトリ名が、例外とは言えないぐらい頻繁に使用されています。絶対パスで指定しようした場合には1度ならず、何度も間違って実行してしまうでしょう。

.. Those characters are interpreted as a URI for the sake of platform independence. This means that even on the Windows platform, "/" is to be used as a separator in a path to a file. Absolute path names should start with "file:/".

これらの文字列をURIとして処理する目的は、プラットフォーム間で共通の記述をさせたかったからです。そのため、Windowsのプラットフォーム上であっても、パスとファイルの区切り文字には\ ``"/"``\ を使用しなければならないということも示しています。絶対パスを指定したい場合には、書き出しは\ ``"file:/"``\ としなければなりません。