[seasar-javadoc:741] Re: S2ContainerFactory

[Koichi Kobayashi]

小林 (koichik) です．

Date:    Tue, 12 Dec 2006 09:21:02 +0900
From:    "Jundo Ishikawa" <jundo.ishikawa ＠ gmail.com>
To:      seasar-javadoc ＠ ml.seasar.org
Subject: [seasar-javadoc:740]  S2ContainerFactory

> 　お疲れ様です。メールがずっと流れないのもなんか寂しいので、まだ途中なのです
> が、とりあえず１度投げてみることにしました。

ありがとうございます！！

> 現状、publicなフィールド・メソッ
> ドにしか、コメントをつけていません。たぶん、protectedなところもコメントをつ
> けるんですよね？

どうしましょうねぇ？
protected って標準だと Javadoc に出ちゃうんですよね．
継承して使う利用者向けという意味では Javadoc 書くべき
なんですが，自分の場合 public じゃなければ無条件に
protected なんで，無駄に Javadoc 多くなっちゃうかも．
悩ましいですね．

> 　あと、ComponentDefに登録すると起用の定数アノテーションもコメントはつけた方
> が良いでしょうか？　〜用の定数アノテーションですといったコメントになりそうで
> すが。

定数アノテーションかぁ．(^^;
これは悩みますね．public だし，何も書かないと Javadoc で
見たときの見栄えが悪いですよねぇ．でも中身は．．．
とりあえず「定数アノテーション」って一言書いて終了とか？


以下，Javadoc へのコメントです．

■クラスコメント

>  * S2コンテナを構築するためのクラスです。

「S2コンテナを構築するためのファクトリクラスです」と
した方がいいかも．

> S2コンテナの構築方法は、
>  * 初期化用diconファイルによって指定することが出来ます。

うーん，「初期化用dicon」ではなくて「コンフィグレーションdicon」
の方が嬉しいかなぁ．
この dicon を読み込んだコンテナを保持するフィールドは
configurationContainer だし，内部的には configuration〜 で
揃ってると思います．
初期化とはちょっとニュアンス (？) が違うような．．．

> 初期化用diconファイルは、 システムプロパティ<code>org.seasar.framework.container.factory.config</code>に指定されたdiconファイルか、
>  * 指定が無ければクラスパス上の<code>s2container.dicon</code>が読み込まれます。

ここは s2container.dicon の方を先に書いて，システムプロパティで
変更することもできるというのを後にする方がいいかも．
あまり指定することはないと考えているので．

それから，S2ContainerFactory というクラスの構成について
説明があってもいいかと．
S2ContainerFactory の基本的な API は static メソッドだけど，
その実装は Provider インタフェースの実装クラスに委譲すること，
デフォルトの実装クラスとして DefaultProvider が提供されるけど
コンフィグレーション dicon で変更できること．
その構成を行うのが Configurator で，デフォルトの実装クラスとして
DefaultConfigurator が提供されるけど，これもコンフィグレーション
dicon で変更できること．

それ以前にコンフィグレーション dicon について一言
あるべきかも．大変だと思うけど．(^^;

後はクラスローダーについて追記してもらえるといいかなぁ．
重要なのは，コンテナの作成に使われるクラスローダーが
スレッドのコンテキストクラスローダーに設定されると
いうことです．

■DEFAULT_BUILDER_NAME

>      * S2コンテナファクトリの初期化用diconファイルに指定する、 既定のS2コンテナビルダのコンポーネント名を表す定数です。

「指定する」はちょっと分かりにくい感じ．
「登録する」あるいは「設定する」の方がよさげ．
「S2コンテナビルダ」は S2ContainerBuilder へ @link してください．

■create(final String path)

スレッドのコンテキストクラスローダーが使われるということを
記述してください．

>      * @return 構築済みのS2コンテナ

「構築された」の方がよさげ．

■create(final String path, final ClassLoader classLoader)

>      * 指定された設定ファイルに基づき、 指定されたクラスローダ上にS2コンテナを構築して返します。

「クラスローダ上」は見慣れない表現のような．
「クラスローダを使用して」でいいような．

>      * @param classLoader
>      *            S2コンテナを構築する対象のクラスローダ

クラスローダーが「構築する対象」は変な感じ．
「S2コンテナの構築に使用されるクラスローダ」とか．

>      * @return 構築済みのS2コンテナ

同上．

■include(final S2Container parent, final String path)

>      * 指定された設定ファイルからS2コンテナを構築し、 指定された親S2コンテナに対してインクルードした状態で返します。

親を返すのか子を返すのか分かりにくいかも．
戻り値については @return で書けばいいから

 * 指定された設定ファイルからS2コンテナを構築し、親S2コンテナにインクルードします．

とか．

■configure()

>      * システムプロパティに指定された初期化用diconファイルに基づいて、 S2コンテナファクトリを構成します。

「システムプロパティ〜」は主じゃないので最初の文からは外し，
「S2コンテナファクトリを構成します」だけで．
<p>〜</p> の方では説明お願いします．

■configure(final String configFile)

>      * 指定された初期化用diconファイルに基づき、 S2コンテナファクトリを設定します。

configure() にあわせて「設定します」ではなく「構成します」で．

■Provider

>      * S2コンテナの構築に関する機能を提供するインターフェースです。

 * S2コンテナファクトリの振る舞いを提供します．

の方が気分かなぁ (気分？)．
本体の static メソッドから委譲されてくるって一言
あるとよさげ．
このインタフェースのメソッドについては本体のメソッドと
同様ということで．

■DefaultProvider

>      * S2コンテナファクトリに対して、 既定のS2コンテナ構築機能を提供するクラスです。

 * S2コンテナファクトリの振る舞いを提供するデフォルトの実装クラスです．

の方が気分かなぁ (気分？)．
そういえば，default は「デフォルト」ではなくて「既定」で
統一？
既定だと規定やら基底やら汽艇やらとごっちゃになりそうな
気のせいが．．． ごっちゃになるのはおいらの頭ですが．

重要なポイントとして，DefaultProvider は dicon というか
create() に渡されたパスの拡張子をコンポーネント名として
コンフィグレーションコンテナから S2ContainerBuilder を
ルックアップします．
もし Builder が取得できればそれを使います．
取得できなければデフォルトの Builder (コンポーネント名
DEFAULT_BUILDER_NAME でルックアップしたもの) を使います．
ということを書いてもらえると嬉しいです．
これを利用すると，例えば拡張子 properties を扱う
Builder なんかも簡単に登録できます．
# テストケースにある

■Configurator

>      * S2コンテナファクトリを設定するためのインターフェースです。

 * S2コンテナおよびS2コンテナファクトリの振る舞いを構成します。

の方が気分かなぁ (気分？)．
実は Configurator ってファクトリだけじゃなくて S2 全体を
コンフィグレーションしてるんですよね．
後，本体の configure() が呼ばれたときに S2コンテナ
ファクトリを構成すると一言あるとよさげ．

■DefaultConfigurator

>      * S2コンテナファクトリの既定の設定方法を提供するクラスです。

 * S2コンテナ及びS2コンテナファクトリの振る舞いを構成するデフォルトの実装クラスです。

の方が気分かなぁ (気分？)．
ともあれ (JW)，ここはかなりの力作ですね．(^^;
コンフィグレーションする項目については，ファクトリに関連する
項目と，コンテナに関連する項目で分けて書いた方がいいかも．


ともあれ (JW)，かなーりの難関だと思いますが
この調子で頑張ってください！！


-- 
<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>