[openrtm-commit:02286] r914 - trunk/OpenRTM-aist-Java/jp.go.aist.rtm.RTC/src/jp/go/aist/rtm/RTC
openrtm ＠ openrtm.org
openrtm ＠ openrtm.org
2017年 1月 20日 (金) 18:36:47 JST
Author: win-ei
Date: 2017-01-20 18:36:47 +0900 (Fri, 20 Jan 2017)
New Revision: 914
Modified:
trunk/OpenRTM-aist-Java/jp.go.aist.rtm.RTC/src/jp/go/aist/rtm/RTC/FsmProfileListener.java
trunk/OpenRTM-aist-Java/jp.go.aist.rtm.RTC/src/jp/go/aist/rtm/RTC/FsmStructureListener.java
trunk/OpenRTM-aist-Java/jp.go.aist.rtm.RTC/src/jp/go/aist/rtm/RTC/PostFsmActionListener.java
trunk/OpenRTM-aist-Java/jp.go.aist.rtm.RTC/src/jp/go/aist/rtm/RTC/PostFsmActionListenerType.java
trunk/OpenRTM-aist-Java/jp.go.aist.rtm.RTC/src/jp/go/aist/rtm/RTC/PreFsmActionListener.java
trunk/OpenRTM-aist-Java/jp.go.aist.rtm.RTC/src/jp/go/aist/rtm/RTC/PreFsmActionListenerType.java
Log:
[FSM4RTC,doc] FSM listeners documentations have been updated.
Modified: trunk/OpenRTM-aist-Java/jp.go.aist.rtm.RTC/src/jp/go/aist/rtm/RTC/FsmProfileListener.java
===================================================================
--- trunk/OpenRTM-aist-Java/jp.go.aist.rtm.RTC/src/jp/go/aist/rtm/RTC/FsmProfileListener.java 2017-01-20 08:04:21 UTC (rev 913)
+++ trunk/OpenRTM-aist-Java/jp.go.aist.rtm.RTC/src/jp/go/aist/rtm/RTC/FsmProfileListener.java 2017-01-20 09:36:47 UTC (rev 914)
@@ -8,36 +8,125 @@
* {@.ja FsmProfileListener クラス}
* {@.en FsmProfileListener class}
* <p>
- * {@.ja OMG RTC仕様で定義されている以下のコンポーネントアクショントについ
- * て、
+ * {@.ja FsmProfileListener クラスは、FSMのProfileに関連したアクションのコー
+ * ルバックを実現するリスナーオブジェクトの基底クラスである。FSM
+ * Profileのアクションの動作をフックしたい場合、以下の例のように、こ
+ * のクラスを継承したコールバックオブジェクトを定義し、適切なコールバッ
+ * ク設定関数からRTObjectに対してコールバックオブジェクトをセットする
+ * 必要がある。
+ *
+ * <pre>
+ * Class MyListeneri extends public FsmProfileListener {
+ * public String m_name;
+ * public MyListener(final String name){
+ * m_namei = name;
+ * }
+ *
+ * public void operator()(final FsmProfile fsmprof) {
+ * System.out.println("Listner name: " + m_name);
+ * };
+ * };
+ * </pre>
+ *
+ * このようにして定義されたリスナクラスは、以下のようにRTObjectに対し
+ * て、セットされる。
+ *
+ * <pre>
+ * protected ReturnCode_t onInitialize() {
+ * addFsmProfileListener(SET_FSM_PROFILE,
+ * new MyListener("prof listener"));
+ * :
+ * </pre>
+ *
+ * 第1引数の "SET_FSM_PROFILE" は、コールバックをフックするポイン
+ * トであり、以下の値を取ることが可能である。なお、すべてのコールバッ
+ * クポイントが実装されているとは限らず、これらが呼び出されるかどうか
+ * は、FSMサービスの実装に依存する。
+ *
* <ul>
- * <li> on_init()
- * <li> on_entry()
- * <li> on_do()
- * <li> on_exit()
- * <li> on_state_update()
+ * <li> - SET_FSM_PROFILE : FSM Profile設定時
+ * <li> - GET_FSM_PROFILE : FSM Profile取得時
+ * <li> - ADD_FSM_STATE : FSMにStateが追加された
+ * <li> - REMOVE_FSM_STATE : FSMからStateが削除された
+ * <li> - ADD_FSM_TRANSITION : FSMに遷移が追加された
+ * <li> - REMOVE_FSM_TRANSITION : FSMから遷移が削除された
+ * <li> - BIND_FSM_EVENT : FSMにイベントがバインドされた
+ * <li> - UNBIND_FSM_EVENT : FSMにイベントがアンバインドされた
* </ul>
- * 各アクションに対応するユーザーコードが呼ばれる直前のタイミング
- * でコールされるリスなクラスの基底クラス。
+ *
+ * 第2引数はリスナオブジェクトのポインタである。第3引数はオブジェクト
+ * 自動削除フラグであり、true の場合は、RTObject削除時に自動的にリス
+ * ナオブジェクトが削除される。falseの場合は、オブジェクトの所有権は
+ * 呼び出し側に残り、削除は呼び出し側の責任で行わなければならない。
+ * RTObject のライフサイクル中にコールバックが必要ならば上記のような
+ * 呼び出し方で第3引数を true としておくとよい。逆に、コールバックを
+ * 状況等に応じてセットしたりアンセットしたりする必要がある場合は
+ * falseとして置き、リスナオブジェクトのポインタをメンバ変数などに保
+ * 持しておき、addFsmProfileListener()/removeFsmProfileListener() に
+ * より、セットとアンセットを管理するといった使い方も可能である。}
+ *
+ * {@.en
+ * FsmProfileListener class is a base class for the listener
+ * objects which realize callback to hook FSM Profile related actions.
+ * To hook execution just before a FSM profile action, the callback object
+ * should be defined as follows, and set to RTObject through
+ * appropriate callback set function.
+ *
+ * <pre>
+ * Class MyListeneri extends public FsmProfileListener {
+ * public String m_name;
+ * public MyListener(final String name){
+ * m_namei = name;
+ * }
+ *
+ * public void operator()(final FsmProfile fsmprof) {
+ * System.out.println("Listner name: " + m_name);
+ * };
+ * };
+ * </pre>
+ *
+ * The listener class defined above is set to RTObject as follows.
+ *
+ * <pre>
+ * protected ReturnCode_t onInitialize() {
+ * addFsmProfileListener(SET_FSM_PROFILE,
+ * new MyListener("prof listener"));
+ * :
+ * </pre>
+ *
+ * The first argument "SET_FSM_PROFILE" specifies callback hook
+ * point, and the following values are available. Not all the
+ * callback points are implemented. It depends on the FSM service
+ * implementations.
+ *
* <ul>
- * <li> PRE_ON_INIT:
- * <li> PRE_ON_ENTRY:
- * <li> PRE_ON_DO:
- * <li> PRE_ON_EXIT:
- * <li> PRE_ON_STATUS_CHANGED:
- * </ul>}
- * {@.en This class is abstract base class for listener classes that
- * provides callbacks for various events in rtobject.
- * <ul>
- * <li> on_init()
- * <li> on_entry()
- * <li> on_do()
- * <li> on_exit()
- * <li> on_state_update()
+ * <li> - SET_FSM_PROFILE : Setting FSM Profile
+ * <li> - GET_FSM_PROFILE : Getting FSM Profile
+ * <li> - ADD_FSM_STATE : A State added to the FSM
+ * <li> - REMOVE_FSM_STATE : A State removed from FSM
+ * <li> - ADD_FSM_TRANSITION : A transition added to the FSM
+ * <li> - REMOVE_FSM_TRANSITION : A transition removed from FSM
+ * <li> - BIND_FSM_EVENT : An event bounded to the FSM
+ * <li> - UNBIND_FSM_EVENT : An event unbounded to the FSM
* </ul>
- * </ul>}
- * </p>
*
+ * The second argument is a pointers to the listener object. The
+ * third argument is a flag for automatic object destruction. When
+ * "true" is given to the third argument, the given object in second
+ * argument is automatically destructed with RTObject. In the "false
+ * " case, the ownership of the object is left in the caller side,
+ * and then destruction of the object must be done by users'
+ * responsibility.
+ *
+ * It is good for setting "true" as third argument, if the listener
+ * object life span is equals to the RTObject's life cycle. On the
+ * otehr hand, if callbacks are required to set/unset depending on
+ * its situation, the third argument could be "false". In that
+ * case, listener objects pointers must be stored to member
+ * variables, and set/unset of the listener objects shoud be
+ * paerformed throguh
+ * addFsmProfileListener()/removeFsmProfileListener() functions}
+ *
*/
public abstract class FsmProfileListener implements Observer{
public void update(Observable o, Object obj) {
Modified: trunk/OpenRTM-aist-Java/jp.go.aist.rtm.RTC/src/jp/go/aist/rtm/RTC/FsmStructureListener.java
===================================================================
--- trunk/OpenRTM-aist-Java/jp.go.aist.rtm.RTC/src/jp/go/aist/rtm/RTC/FsmStructureListener.java 2017-01-20 08:04:21 UTC (rev 913)
+++ trunk/OpenRTM-aist-Java/jp.go.aist.rtm.RTC/src/jp/go/aist/rtm/RTC/FsmStructureListener.java 2017-01-20 09:36:47 UTC (rev 914)
@@ -8,36 +8,112 @@
* {@.ja FsmStructureListener クラス}
* {@.en FsmStructureListener class}
* <p>
- * {@.ja OMG RTC仕様で定義されている以下のコンポーネントアクショントについ
- * て、
+ * {@.ja FsmStructureListener クラスは、FSM Structureのアクションに関するコー
+ * ルバックを実現するリスナーオブジェクトの基底クラスである。FSM
+ * Structure のアクションの直後の動作をフックしたい場合、以下の例のよ
+ * うに、このクラスを継承したコールバックオブジェクトを定義し、適切な
+ * コールバック設定関数からRTObjectに対してコールバックオブジェクトを
+ * セットする必要がある。
+ *
+ * <pre>
+ * class MyListener extnds FsmStructureListener {
+ * public String m_name;
+ * public MyListener(final String name) {
+ * m_name = name;
+ * }
+ * public void operator()(FsmStructure pprof) {
+ * System.out.println("Listner name: " + m_name);
+ * };
+ * };
+ * </pre>
+ *
+ * このようにして定義されたリスナクラスは、以下のようにRTObjectに対し
+ * て、セットされる。
+ *
+ * <pre>
+ * protected ReturnCode_t onInitialize() {
+ * addFsmStructureListener(SET_FSM_STRUCTURE,
+ * new MyListener("set structure listener"));
+ * :
+ * </pre>
+ *
+ * 第1引数の "SET_FSM_STRUCTURE" は、コールバックをフックするポイン
+ * トであり、以下の値を取ることが可能である。なお、すべてのコールバッ
+ * クポイントが実装されているとは限らず、これらが呼び出されるかどうか
+ * は、FSMの実装に依存する。
+ *
* <ul>
- * <li> on_init()
- * <li> on_entry()
- * <li> on_do()
- * <li> on_exit()
- * <li> on_state_update()
+ * <li> - SET_FSM_STRUCTURE: FSM構造の設定
+ * <li> - GET_FSM_STRUCTURE: FSM構造の取得
* </ul>
- * 各アクションに対応するユーザーコードが呼ばれる直前のタイミング
- * でコールされるリスなクラスの基底クラス。
+ *
+ * 第2引数はリスナオブジェクトのポインタである。第3引数はオブジェクト
+ * 自動削除フラグであり、true の場合は、RTObject削除時に自動的にリス
+ * ナオブジェクトが削除される。falseの場合は、オブジェクトの所有権は
+ * 呼び出し側に残り、削除は呼び出し側の責任で行わなければならない。
+ * RTObject のライフサイクル中にコールバックが必要ならば上記のような
+ * 呼び出し方で第3引数を true としておくとよい。逆に、コールバックを
+ * 状況等に応じてセットしたりアンセットしたりする必要がある場合は
+ * falseとして置き、リスナオブジェクトのポインタをメンバ変数などに保
+ * 持しておき、
+ * RTObject_impl::addPostFsmActionListener()/removePostFsmActionListener()
+ * により、セットとアンセットを管理するといった使い方も可能である。}
+ * {@.en PostFsmActionListener class is a base class for the listener
+ * objects which realize callback to hook FSM structure profile
+ * related actions. To hook execution just before a FSM action, the
+ * callback object should be defined as follows, and set to RTObject
+ * through appropriate callback set function.
+ *
+ * <pre>
+ * class MyListener extnds FsmStructureListener {
+ * public String m_name;
+ * public MyListener(final String name) {
+ * m_name = name;
+ * }
+ * public void operator()(FsmStructure pprof) {
+ * System.out.println("Listner name: " + m_name);
+ * };
+ * };
+ * </pre>
+ *
+ * The listener class defined above is set to RTObject as follows.
+ *
+ * <pre>
+ * protected ReturnCode_t onInitialize() {
+ * addFsmStructureListener(SET_FSM_STRUCTURE,
+ * new MyListener("set structure listener"));
+ * :
+ * :
+ * </pre>
+ *
+ * The first argument "SET_FSM_STRUCTURE" specifies callback hook
+ * point, and the following values are available. Not all the
+ * callback points are implemented. It depends on the FSM
+ * implementations.
+ *
* <ul>
- * <li> PRE_ON_INIT:
- * <li> PRE_ON_ENTRY:
- * <li> PRE_ON_DO:
- * <li> PRE_ON_EXIT:
- * <li> PRE_ON_STATUS_CHANGED:
- * </ul>}
- * {@.en This class is abstract base class for listener classes that
- * provides callbacks for various events in rtobject.
- * <ul>
- * <li> on_init()
- * <li> on_entry()
- * <li> on_do()
- * <li> on_exit()
- * <li> on_state_update()
+ * <li> - SET_FSM_STRUCTURE: Setting FSM structure
+ * <li> - GET_FSM_STRUCTURE: Getting FSM structure
* </ul>
- * </ul>}
- * </p>
*
+ * The second argument is a pointers to the listener object. The
+ * third argument is a flag for automatic object destruction. When
+ * "true" is given to the third argument, the given object in second
+ * argument is automatically destructed with RTObject. In the "false
+ * " case, the ownership of the object is left in the caller side,
+ * and then destruction of the object must be done by users'
+ * responsibility.
+ *
+ * It is good for setting "true" as third argument, if the listener
+ * object life span is equals to the RTObject's life cycle. On the
+ * otehr hand, if callbacks are required to set/unset depending on
+ * its situation, the third argument could be "false". In that
+ * case, listener objects pointers must be stored to member
+ * variables, and set/unset of the listener objects shoud be
+ * paerformed throguh
+ * RTObject_impl::addPostFsmActionListener()/removePostFsmActionListener()
+ * functions.}
+ *
*/
public abstract class FsmStructureListener implements Observer{
public void update(Observable o, Object obj) {
Modified: trunk/OpenRTM-aist-Java/jp.go.aist.rtm.RTC/src/jp/go/aist/rtm/RTC/PostFsmActionListener.java
===================================================================
--- trunk/OpenRTM-aist-Java/jp.go.aist.rtm.RTC/src/jp/go/aist/rtm/RTC/PostFsmActionListener.java 2017-01-20 08:04:21 UTC (rev 913)
+++ trunk/OpenRTM-aist-Java/jp.go.aist.rtm.RTC/src/jp/go/aist/rtm/RTC/PostFsmActionListener.java 2017-01-20 09:36:47 UTC (rev 914)
@@ -8,36 +8,119 @@
* {@.ja PostFsmActionListener クラス}
* {@.en PostFsmActionListener class}
* <p>
- * {@.ja OMG RTC仕様で定義されている以下のコンポーネントアクショントについ
- * て、
+ * {@.ja PostFsmActionListener クラスは、Fsmのアクションに関するコールバック
+ * を実現するリスナーオブジェクトの基底クラスである。FSMのアクション
+ * の直後の動作をフックしたい場合、以下の例のように、このクラスを継承
+ * したコールバックオブジェクトを定義し、適切なコールバック設定関数か
+ * らRTObjectに対してコールバックオブジェクトをセットする必要がある。
+ *
+ * <pre>
+ * class MyListener extends PostFsmActionListener {
+ * public String m_name;
+ * public MyListener(final String name) {
+ * m_namei = name;
+ * }
+ *
+ * public void operator()(final String state_name, ReturnCode_t ret) {
+ * System.out.println("Listner name: " + m_name);
+ * System.out.println("Current state: " + state_name);
+ * };
+ * };
+ * </pre>
+ *
+ * このようにして定義されたリスナクラスは、以下のようにRTObjectに対し
+ * て、セットされる。
+ *
+ * <pre>
+ * protected ReturnCode_t onInitialize() {
+ * addPostFsmActionListener(POST_ON_STATE_CHANGE,
+ * new MyListener("init listener"));
+ * :
+ * </pre>
+ *
+ * 第1引数の "POST_ON_STATE_CHANGE" は、コールバックをフックするポイン
+ * トであり、以下の値を取ることが可能である。なお、すべてのコールバッ
+ * クポイントが実装されているとは限らず、これらが呼び出されるかどうか
+ * は、FSMの実装に依存する。
* <ul>
- * <li> on_init()
- * <li> on_entry()
- * <li> on_do()
- * <li> on_exit()
- * <li> on_state_update()
+ * <li> - POST_ON_INIT: init 直後
+ * <li> - POST_ON_ENTRY: entry 直後
+ * <li> - POST_ON_DO: do 直後
+ * <li> - POST_ON_EXIT: exit 直後
+ * <li> - POST_ON_STATE_CHANGE: 状態遷移直後
* </ul>
- * 各アクションに対応するユーザーコードが呼ばれる直前のタイミング
- * でコールされるリスなクラスの基底クラス。
+ *
+ * 第2引数はリスナオブジェクトのポインタである。第3引数はオブジェクト
+ * 自動削除フラグであり、true の場合は、RTObject削除時に自動的にリス
+ * ナオブジェクトが削除される。falseの場合は、オブジェクトの所有権は
+ * 呼び出し側に残り、削除は呼び出し側の責任で行わなければならない。
+ * RTObject のライフサイクル中にコールバックが必要ならば上記のような
+ * 呼び出し方で第3引数を true としておくとよい。逆に、コールバックを
+ * 状況等に応じてセットしたりアンセットしたりする必要がある場合は
+ * falseとして置き、リスナオブジェクトのポインタをメンバ変数などに保
+ * 持しておき、
+ * RTObject_impl::addPostFsmActionListener()/removePostFsmActionListener()
+ * により、セットとアンセットを管理するといった使い方も可能である。}
+ * {@.en PostFsmActionListener class is a base class for the listener
+ * objects which realize callback to hook FSM related post-actions.
+ * To hook execution just before a FSM action, the callback object
+ * should be defined as follows, and set to RTObject through
+ * appropriate callback set function.
+ *
+ * <pre>
+ * class MyListener extends PostFsmActionListener {
+ * public String m_name;
+ * public MyListener(final String name) {
+ * m_namei = name;
+ * }
+ *
+ * public void operator()(final String state_name, ReturnCode_t ret) {
+ * System.out.println("Listner name: " + m_name);
+ * System.out.println("Current state: " + state_name);
+ * };
+ * };
+ * </pre>
+ *
+ * The listener class defined above is set to RTObject as follows.
+ *
+ * <pre>
+ * protected ReturnCode_t onInitialize() {
+ * addPostFsmActionListener(POST_ON_STATE_CHANGE,
+ * new MyListener("init listener"));
+ * :
+ * </pre>
+ *
+ * The first argument "POST_ON_STATE_CHANGE" specifies callback hook
+ * point, and the following values are available. Not all the
+ * callback points are implemented. It depends on the FSM
+ * implementations.
+ *
* <ul>
- * <li> POST_ON_INIT:
- * <li> POST_ON_ENTRY:
- * <li> POST_ON_DO:
- * <li> POST_ON_EXIT:
- * <li> POST_ON_STATUS_CHANGED:
- * </ul>}
- * {@.en This class is abstract base class for listener classes that
- * provides callbacks for various events in rtobject.
- * <ul>
- * <li> on_init()
- * <li> on_entry()
- * <li> on_do()
- * <li> on_exit()
- * <li> on_state_update()
+ * <li> - POST_ON_INIT: just after "init" action
+ * <li> - POST_ON_ENTRY: just after "entry" action
+ * <li> - POST_ON_DO: just after "do" action
+ * <li> - POST_ON_EXIT: just after "exit" action
+ * <li> - POST_ON_STATE_CHANGE: just after state transition action
* </ul>
- * </ul>}
- * </p>
*
+ * The second argument is a pointers to the listener object. The
+ * third argument is a flag for automatic object destruction. When
+ * "true" is given to the third argument, the given object in second
+ * argument is automatically destructed with RTObject. In the "false
+ * " case, the ownership of the object is left in the caller side,
+ * and then destruction of the object must be done by users'
+ * responsibility.
+ *
+ * It is good for setting "true" as third argument, if the listener
+ * object life span is equals to the RTObject's life cycle. On the
+ * otehr hand, if callbacks are required to set/unset depending on
+ * its situation, the third argument could be "false". In that
+ * case, listener objects pointers must be stored to member
+ * variables, and set/unset of the listener objects shoud be
+ * paerformed throguh
+ * RTObject_impl::addPostFsmActionListener()/removePostFsmActionListener()
+ * functions.}
+ *
*/
public abstract class PostFsmActionListener implements Observer{
public void update(Observable o, Object obj) {
Modified: trunk/OpenRTM-aist-Java/jp.go.aist.rtm.RTC/src/jp/go/aist/rtm/RTC/PostFsmActionListenerType.java
===================================================================
--- trunk/OpenRTM-aist-Java/jp.go.aist.rtm.RTC/src/jp/go/aist/rtm/RTC/PostFsmActionListenerType.java 2017-01-20 08:04:21 UTC (rev 913)
+++ trunk/OpenRTM-aist-Java/jp.go.aist.rtm.RTC/src/jp/go/aist/rtm/RTC/PostFsmActionListenerType.java 2017-01-20 09:36:47 UTC (rev 914)
@@ -3,21 +3,26 @@
* {@.ja PostFsmActionListener のタイプ}
* {@.en The types of PostFsmActionListener}
* <p>
- * {@.ja <ul>
- * <li> POST_ON_INIT: on_init 直前
- * <li> POST_ON_ENTRY: on_entry 直前
- * <li> POST_ON_DO: on_do 直前
- * <li> POST_ON_EXIT: on_exit 直前
- * <li> POST_ON_STATE_CAHNGE: 状態遷移直前
+ * {@.ja PostFsmActionListener には以下のフックポイントが定義されている。こ
+ * れらが呼び出されるかどうかは、FSMの実装に依存する。
+ * <ul>
+ * <li> - POST_ON_INIT: init 直後
+ * <li> - POST_ON_ENTRY: entry 直後
+ * <li> - POST_ON_DO: do 直後
+ * <li> - POST_ON_EXIT: exit 直後
+ * <li> - POST_ON_STATE_CHANGE: 状態遷移直後
* </ul>}
- * {@.en <ul>
- * <li> POST_ON_INIT: on_init 直前
- * <li> POST_ON_ENTRY: on_entry 直前
- * <li> POST_ON_DO: on_do 直前
- * <li> POST_ON_EXIT: on_exit 直前
- * <li> POST_ON_STATE_CAHNGE:
+ * {@.en PostFsmActionListener has the following hook points. If these
+ * listeners are actually called or not called are depends on FSM
+ * implementations.
+ * <ul>
+ * <li> - POST_ON_INIT: just after "init" action
+ * <li> - POST_ON_ENTRY: just after "entry" action
+ * <li> - POST_ON_DO: just after "do" action
+ * <li> - POST_ON_EXIT: just after "exit" action
+ * <li> - POST_ON_STATE_CHANGE: just after state transition action
* </ul>}
- * </p>
+ *
*/
public class PostFsmActionListenerType {
public static final int POST_ON_INIT = 0;
Modified: trunk/OpenRTM-aist-Java/jp.go.aist.rtm.RTC/src/jp/go/aist/rtm/RTC/PreFsmActionListener.java
===================================================================
--- trunk/OpenRTM-aist-Java/jp.go.aist.rtm.RTC/src/jp/go/aist/rtm/RTC/PreFsmActionListener.java 2017-01-20 08:04:21 UTC (rev 913)
+++ trunk/OpenRTM-aist-Java/jp.go.aist.rtm.RTC/src/jp/go/aist/rtm/RTC/PreFsmActionListener.java 2017-01-20 09:36:47 UTC (rev 914)
@@ -8,34 +8,130 @@
* {@.ja PreFsmActionListener クラス}
* {@.en PreFsmActionListener class}
* <p>
- * {@.ja OMG RTC仕様で定義されている以下のコンポーネントアクショントについ
- * て、
+ * {@.ja PreFsmActionListener クラスは、Fsmのアクションに関するコールバック
+ * を実現するリスナーオブジェクトの基底クラスである。FSMのアクション
+ * の直前の動作をフックしたい場合、以下の例のように、このクラスを継承
+ * したコールバックオブジェクトを定義し、適切なコールバック設定関数か
+ * らRTObjectに対してコールバックオブジェクトをセットする必要がある。
+ *
+ * <pre>
+ * class MyListener extends PreFsmActionListener {
+ *
+ * public String m_name;
+ * public MyListener(final String name) {
+ * m_namei = name;
+ * }
+ *
+ * public void operator()(final String state_name)
+ * {
+ * System.out.println("Listner name: " + m_name);
+ * System.out.println("Current state: " + state_name);
+ * };
+ * };
+ * </pre>
+ *
+ * このようにして定義されたリスナクラスは、以下のようにRTObjectに対し
+ * て、セットされる。
+ *
+ * <pre>
+ * protected ReturnCode_t onInitialize() {
+ * {
+ * addPreFsmActionListener(PRE_ON_STATE_CHANGE,
+ * new MyListener("init listener"));
+ * :
+ * :
+ * :
+ * </pre>
+ *
+ * 第1引数の "PRE_ON_STATE_CHANGE" は、コールバックをフックするポイン
+ * トであり、以下の値を取ることが可能である。なお、すべてのコールバッ
+ * クポイントが実装されているとは限らず、これらが呼び出されるかどうか
+ * は、FSMの実装に依存する。
+ *
* <ul>
- * <li> on_init()
- * <li> on_entry()
- * <li> on_do()
- * <li> on_exit()
- * <li> on_state_update()
+ * <li> - PRE_ON_INIT: init 直前
+ * <li> - PRE_ON_ENTRY: entry 直前
+ * <li> - PRE_ON_DO: do 直前
+ * <li> - PRE_ON_EXIT: exit 直前
+ * <li> - PRE_ON_STATE_CHANGE: 状態遷移直前
* </ul>
- * 各アクションに対応するユーザーコードが呼ばれる直前のタイミング
- * でコールされるリスなクラスの基底クラス。
+ *
+ * 第2引数はリスナオブジェクトのポインタである。第3引数はオブジェクト
+ * 自動削除フラグであり、true の場合は、RTObject削除時に自動的にリス
+ * ナオブジェクトが削除される。falseの場合は、オブジェクトの所有権は
+ * 呼び出し側に残り、削除は呼び出し側の責任で行わなければならない。
+ * RTObject のライフサイクル中にコールバックが必要ならば上記のような
+ * 呼び出し方で第3引数を true としておくとよい。逆に、コールバックを
+ * 状況等に応じてセットしたりアンセットしたりする必要がある場合は
+ * falseとして置き、リスナオブジェクトのポインタをメンバ変数などに保
+ * 持しておき、
+ * RTObject_impl::addPreFsmActionListener()/removePreFsmActionListener()
+ * により、セットとアンセットを管理するといった使い方も可能である。}
+ *
+ * {@.en PreFsmActionListener class is a base class for the listener
+ * objects which realize callback to hook FSM related pre-actions.
+ * To hook execution just before a FSM action, the callback object
+ * should be defined as follows, and set to RTObject through
+ * appropriate callback set function.
+ *
+ * <pre>
+ * class MyListener extends PreFsmActionListener {
+ *
+ * public String m_name;
+ * public MyListener(final String name) {
+ * m_namei = name;
+ * }
+ *
+ * public void operator()(final String state_name)
+ * {
+ * System.out.println("Listner name: " + m_name);
+ * System.out.println("Current state: " + state_name);
+ * };
+ * };
+ * </pre>
+ *
+ * The listener class defined above is set to RTObject as follows.
+ *
+ * <pre>
+ * protected ReturnCode_t onInitialize() {
+ * {
+ * addPreFsmActionListener(PRE_ON_STATE_CHANGE,
+ * new MyListener("init listener"));
+ * :
+ * :
+ * :
+ * </pre>
+ *
+ * The first argument "PRE_ON_STATE_CHANGE" specifies callback hook
+ * point, and the following values are available. Not all the
+ * callback points are implemented. It depends on the FSM
+ * implementations.
+ *
* <ul>
- * <li> PRE_ON_INIT:
- * <li> PRE_ON_ENTRY:
- * <li> PRE_ON_DO:
- * <li> PRE_ON_EXIT:
- * <li> PRE_ON_STATUS_CHANGED:
- * </ul>}
- * {@.en This class is abstract base class for listener classes that
- * provides callbacks for various events in rtobject.
- * <ul>
- * <li> on_init()
- * <li> on_entry()
- * <li> on_do()
- * <li> on_exit()
- * <li> on_state_update()
+ * <li> - PRE_ON_INIT: just before "init" action
+ * <li> - PRE_ON_ENTRY: just before "entry" action
+ * <li> - PRE_ON_DO: just before "do" action
+ * <li> - PRE_ON_EXIT: just before "exit" action
+ * <li> - PRE_ON_STATE_CHANGE: just before state transition action
* </ul>
- * </ul>}
+ *
+ * The second argument is a pointers to the listener object. The
+ * third argument is a flag for automatic object destruction. When
+ * "true" is given to the third argument, the given object in second
+ * argument is automatically destructed with RTObject. In the "false
+ * " case, the ownership of the object is left in the caller side,
+ * and then destruction of the object must be done by users'
+ * responsibility.
+ *
+ * It is good for setting "true" as third argument, if the listener
+ * object life span is equals to the RTObject's life cycle. On the
+ * otehr hand, if callbacks are required to set/unset depending on
+ * its situation, the third argument could be "false". In that
+ * case, listener objects pointers must be stored to member
+ * variables, and set/unset of the listener objects shoud be
+ * paerformed throguh
+ * RTObject_impl::addPreFsmActionListener()/removePreFsmActionListener()
+ * functions.}
* </p>
*
*/
Modified: trunk/OpenRTM-aist-Java/jp.go.aist.rtm.RTC/src/jp/go/aist/rtm/RTC/PreFsmActionListenerType.java
===================================================================
--- trunk/OpenRTM-aist-Java/jp.go.aist.rtm.RTC/src/jp/go/aist/rtm/RTC/PreFsmActionListenerType.java 2017-01-20 08:04:21 UTC (rev 913)
+++ trunk/OpenRTM-aist-Java/jp.go.aist.rtm.RTC/src/jp/go/aist/rtm/RTC/PreFsmActionListenerType.java 2017-01-20 09:36:47 UTC (rev 914)
@@ -3,19 +3,24 @@
* {@.ja PreFsmActionListener のタイプ}
* {@.en The types of PreFsmActionListener}
* <p>
- * {@.ja <ul>
+ * {@.ja PreFsmActionListener には以下のフックポイントが定義されている。こ
+ * れらが呼び出されるかどうかは、FSMの実装に依存する。
+ * <ul>
* <li> PRE_ON_INIT: on_init 直前
* <li> PRE_ON_ENTRY: on_entry 直前
* <li> PRE_ON_DO: on_do 直前
* <li> PRE_ON_EXIT: on_exit 直前
* <li> PRE_ON_STATE_CAHNGE: 状態遷移直前
* </ul>}
- * {@.en <ul>
- * <li> PRE_ON_INIT: on_init 直前
- * <li> PRE_ON_ENTRY: on_entry 直前
- * <li> PRE_ON_DO: on_do 直前
- * <li> PRE_ON_EXIT: on_exit 直前
- * <li> PRE_ON_STATE_CAHNGE:
+ * {@.en PreFsmActionListener has the following hook points. If these
+ * listeners are actually called or not called are depends on FSM
+ * implementations.
+ * <ul>
+ * <li> - PRE_ON_INIT: just before "init" action
+ * <li> - PRE_ON_ENTRY: just before "entry" action
+ * <li> - PRE_ON_DO: just before "do" action
+ * <li> - PRE_ON_EXIT: just before "exit" action
+ * <li> - PRE_ON_STATE_CHANGE: just before state transition action
* </ul>}
* </p>
*/
More information about the openrtm-commit
mailing list