[seasar-javadoc:311] Re: S2Container

[Koichi Kobayashi]

小林 (koichik) です．

Date:    Tue, 4 Jul 2006 08:09:35 +0900
From:    "Makoto Yonezawa" <stratosphire ＠ gmail.com>
To:      seasar-javadoc ＠ ml.seasar.org
Subject: [seasar-javadoc:298] Re: S2Container

> 了解です、ほんと大変ですよね^^;

いえいえ，自分は読んでるだけなので，皆さんより遥かにラクチンです．
それなのにボトルネックになりつつある今日この頃．．．
申し訳ないです．

以下，コメントです．

・getComponent(Object)

ちょっと今更ですが．．．

>      * キーを指定してコンポーネントを返します。

キーを指定するのは呼び出し側で，コンポーネントを返すのは
呼び出された側です．
ココは呼び出された側に統一して，

 * 指定されたキーに対応するコンポーネントを返します。

みたいな．
他のメソッドも同様で．


・register(Object component, String componentName)

>      * 名前付き<code>component</code>として登録します。

こういう場合は「<code>component</code>」ではなく「コンポーネント」が
いいような．
っていうか，

 * 名前を指定してコンポーネントを登録します。

でいいような．そうすると register(Object component) もカタカナの
コンポーネントでいいかも．


・getComponentDef(int index)

>      * 番号を指定してコンポーネント定義を返します。

さっきのと同様，指定するのと返すのは異なる立場なので，

 * 番号で指定された位置のコンポーネント定義を返します。


・hasDescendant(String path)

>      * <code>path</code>に対して、S2コンテナが読み込まれている場合<code>true</code>を返します。

「S2コンテナが読み込まれている」は微妙かなぁ．

 * <code>path</code>を読み込んだS2コンテナが存在する場合〜

とか．


・getDescendant(String path)

>      * <code>path</code>に対応する読み込み済みのS2コンテナを返します。

こちらも同様で，

 * <code>path</code>を読み込んだS2コンテナを返します。

とか．


・registerDescendant(S2Container descendant)

>      * ルートのS2コンテナに読み込み済みのS2コンテナを登録します。
>      * 
>      * @param descendant 読み込み済みのS2コンテナ

「ルートの」はコンテナ自身が意識しているわけではないので，メソッドの
説明からは外しましょう．
# S2ContainerFactory が意識してルートのこのメソッドを呼び出します．

 * <code>descendant</code>を子孫のコンテナとして登録します。
 * 
 * @param descendant 子孫のコンテナ

これじゃ分からないか？
「子孫のコンテナ」の説明を加えればいいかも？

 * <p>
 * 子孫のコンテナとは、このコンテナの子コンテナやその子コンテナです．
 * </p>

本当は「その子孫コンテナです」と書きたいのだけど，定義が再帰するのって
普通は分かりにくいよね？ なかなか悩ましい．．．


・getChild(int index)

>      * 番号を指定して子コンテナを返します。

さっきのと同様．


・getParentSize()

>      * インクルードしている親コンテナの数を返します。

このメソッドを呼ばれたコンテナが親コンテナをインクルード
しているように読めてしまいますが，インクルードしているのは
親コンテナで，このコンテナはインクルードされる方なので，

 * このコンテナをインクルードしている親コンテナの数を返します。


・getParent(int index)

>      * 番号を指定して親コンテナを返します。

さっきからのと同様．


・init()

>      * コンテナを初期化を行います。 
                 ^^

「の」


・getRoot()

>      * @param root S2コンテナ

「ルートの」を追加．


・getExternalContext()

>      * S2コンテナ外のオブジェクトを返します。

これは素直に

 * 外部コンテキストを返します。

で．

>      * <P>
>      * <code>ExternalContext</code>とは、リクエストなどから与えられるコンテキスト。
>      * <code>HttpServletRequest</code> や <code>HttpSession</code>，<code>ServletContext</code> など、
>      * <code>ServletAPI</code>をラッパーしています。
>      * </P>

この前，たしかに「Servlet API のラッパー」だと書きましたが，それは
ココでの説明用で，Javadoc に書いてあると違和感ありまくりです．(^^;
Servlet API をラップする実装もありますが，それはあくまで一つの実装に
すぎません．
そんなわけで (どんなわけで？)，

 * {@link ExternalContext 外部コンテキスト}は、
 * {@link InstanceDef#APPLICATION_NAME application}、
 * {@link InstanceDef#REQUEST_NAME request}，
 * {@link InstanceDef#SESSION_NAME session}の
 * 各{@link InstanceDef インスタンス定義}を提供するものです。
 * これらのインスタンス定義を使用するには
 * {@link ExternalContext 外部コンテキスト}を設定する必要があります。

みたいな．
あ，これは getter より setter に書いた方がいいな．
getExternalContext() は「〜を返します」だけでいいので，上に書いたのを
setExternalContext() に書いてください．


・getExternalContextComponentDefRegister()

>      * <code>ExternalContext</code>として登録するコンポーネントの定義を設定します。

getter/setter とコメントが逆になってます．(^^;
ともあれ (JW)，ExternalContextComponentDefRegister というのは
外部コンテキストが提供する諸々をコンポーネント定義として登録する
オブジェクトです．
例えば Web だと，HttpServletRequest のプロパティに自動バインド
されたりしますが，それは HttpServletRequest がコンポーネントとして
登録されているからです．
しかし，もはやコンテナは Servlet API に依存しないため，コンテナ自身が
HttpServletRequest をコンポーネントとして登録することはできません．
あるいは，S2JMS なんかだと javax.jms.Message をコンポーネントとして
登録したりしますが，当然コンテナはそんなことは知りません．
そこで登場するのが ExternalContextComponentDefRegister です．
そんなわけで (どんなわけで？)，

 * {@link ExternalContext 外部コンテキスト}が提供するオブジェクトを
 * コンポーネントとして登録するオブジェクトを返します。

「オブジェクト」を 2 回繰り返してるのがイマイチですが．．．


・registerMap(Object key, ComponentDef componentDef, S2Container container)

>      * コンポーネント定義の階層構造を定義します。

これは．．．
極めつけに説明が難しいですね．
S2Container になくてもよかったかなぁ (苦笑)．
ともあれ (JW)，こいつはですね，子のコンテナに登録された
コンポーネント (定義) を親のコンテナからも検索できるように
マップに登録するというものです．
マップってのは getComponent(Object) された時に対応する
コンポーネントを返すために使われるものです．
要するにこのメソッドは子のコンテナから親のコンテナを呼び出すだけで，
それ以外から呼び出されることは意図していません．
なので，インタフェースに持たせるべきではなかったかも．
でもでも，そうすると S2ContainerImpl で S2Container を
S2ContainerImpl にキャストして使わなきゃイケなくなったり
するんだよね．うーみゅ．．．

ともあれ (JW)，書くとしたらこんな感じか？

 * 子のコンテナ(<code>container</code>)に登録された
 * <code>componentDef</code>をこのコンテナから検索できるように
 * コンポーネント定義を管理するマップに登録します。

うーみゅ．．．
でもまぁ，これ以上書いてもしょうがない気もします．


だいたいこんな感じかなぁ．
さすがに全ての中心 S2Container，なかなか手強いですね．(^^;



-- 
<component name="koichik">
    <property name="fullName">"Koichi Kobayashi"</property>
    <property name="email">"koichik ＠ improvement.jp"</property>
    <property name="blog">"http://d.hatena.ne.jp/koichik"</property>
</component>