<!--
   $FML: IO.sgml,v 1.3 2003/04/13 04:36:12 fukachan Exp $
-->

<chapter id="module.io.adapter">
	<title>
	IO へのアダプター層 (IO::Adapter クラス)
	</title>


<sect1 id="module.io.adapter.overview">
	<title>
	IO::Adapter の概要
	</title>

<para>
&fmldevel; でのメンバーリストの読み書き、例えばアドレスの登録/削除は
IO::Adapter という抽象クラスを通じて行ないます。ようは Unix で 
vfs/vnode インターフェイスの導入した時のような感じですね。
使い方は次のようになります。
<screen>
use IO::Adapter;
$obj = new IO::Adapter $map, $map_params;
$obj->open || croak("cannot open $map");
while ($x = $obj->get_next_key()) { ... }
$obj->close;
</screen>
</para>

<para>
$map は「map:識別子」となります。file: は省略可能です。
現在のところ $map は次のようなものが使えます。
<screen>
file:/var/spool/ml/elena/recipients
unix.group:root
nis.group:root
mysql:id
postgresql:id  (未実装、実装予定)
ldap:id        (未実装、実装予定)
</screen>
</para>

<para>
file: は通常のファイルです。
unix.group:root は /etc/group の root のエントリにあるユーザのリストを、
nis.group:root は NIS の root のエントリにあるユーザのリストです。
mysql:id は MySQL へのアクセスです。
mysql:id で指定されたパラメータを用います。
このパラメータは new IO::Adapter を実行する際に、
指定する必要があります。
</para>

</sect1>


<sect1 id="module.io.adapter.methods">
	<title>
	IO::Adapter のメソッド
	</title>

<para>
現在、IO::Adapter の提供する公式なメソッドは次の通りです。
<screen>
new()
open()
close()

get_next_key()

add(KEY)
delete(KEY)

getpos()
setpos(NUM)
eof()

touch()

find(REGEXP, $args)
</screen>
です。
</para>

<para>
KEY はデータベースのプライマリキーで、
通常メールアドレスです。
REGEXP は正規表現ですが、たいていはメールアドレスです。
</para>

<para>
多くのマップを同じように扱うために、
メソッドは極力最少限に、少数精鋭なものだけに限定する必要があります。
</para>

<para>
最低限のメソッド群の定義は実際に実装してみる実験を通じて選ばれました。
その際、ファイルの IO よりは、SQL との IO を想定しつつ、
メソッドの組を考えています。
そのため、&fml4; のファイルを前提にした処理とくらべると、
少し不自由に思えるでしょうが、
そのおかげで抽象化が高くなっています。
</para>

</sect1>


<sect1>
	<title>
	&fmldevel; で必要なメソッドの型
	</title>

<para>
get_next_key() のように引数なしか STR を引数にして STR を返り値にする
ものが多いです。これはファイルの一覧を見るとか、特定のアドレスに対する
何かの値を取り寄せるとかいう操作がよく使われるためです。
</para>

<para>
しかし、特定のアドレスに対する値が組になっているものがあります。
これは
<screen>
KEY_STR => [
     VALUE_STR_1
     VALUE_STR_2
     VALUE_STR_3
]
</screen>
のようなデータ構造が返ってくることを期待する場合です。
&fml4; の actives はメールアドレスに対していくつかのオプションの値を記
述するので、こういったデータ構造と考えられます。
<screen> 
例

rudo@nuinui.net	s=skip m=xxx.yyy.z # commnet

rudo@nuinui.net => [
        s=skip
        m=xxx.yyy.z
        # comment
]
</screen> 
</para>

<para>
まとめると引数は「ない」か」STR」なので STR とひとまとめにしても良いで
しょう。一方、返り値は STR か ARRAY_REF になります。
<screen>
引数    返り値
---------------------------------------
なし => STR

STR  => STR

なし => [STR, STR, ... ]

STR  => [STR, STR, ... ]
</screen>
</para>

</sect1>


<sect1 id="module.io.adapter.map.file">
	<title>
	file マップ	
	</title>

<para>
『file:ファイル名』もしくは単なる『ファイル名』は
ごく普通のテキストファイルへの IO を抽象化したものです。
</para>

</sect1>


<sect1 id="module.io.adapter.map.unixgroup">
	<title>
	unixgroup マップ	
	</title>

<para>
/etc/group を抽象化します。
当然 READ ONLY です。
</para>

<para>
/etc/group の
<screen>
wheel:*:0:root,rudo,kenken
</screen>
は IO::Adapter では unixgroup:wheel としてアクセスできます。
<screen>
$obj = new IO::Adapter "unixgroup:wheel";
</screen>
というオブジェクトに対し get_next_key() すると
グループのメンバーが順に返されます。
ちょうど
<screen>
root
rudo
kenken
</screen>
のようなファイルとみなされます。
つまり 3 行のファイルを読みだすようにみなされているわけですね。
</para>

</sect1>


<sect1 id="module.io.adapter.map.nis">
	<title>
	NIS マップ	
	</title>

<para>
/etc/group のケースとほぼ同様ですが、ソースが
NIS/YP から group にあたるものを引っ張ってくるところだけが異なります。
</para>

</sect1>


<sect1 id="module.io.adapter.map.mysql">
	<title>
	MySQL マップ	
	</title>

<para>
保守性をあげるためには、一箇所に設定をまとめておきたい。つまり、一つの 
cf ファイルにいろいろ書けるようにしておきたい。たとえば &fmldevel; の
場合、config.cf の中だけに SQL の設定を書いておきたいわけです。
</para>

<para>
そこで、[mysql:members] (から終りまで、もしくは次の =head 文まで)の
ブロックで、マップのタイプと識別子を表現しています。
<screen>
config.cf の記述例

member_maps     =       mysql:members

recipient_maps  =       mysql:recipients

[mysql:members]

sql_server      =       localhost
sql_user        =       fml
sql_password    =       uja
sql_database    =       fml
sql_table       =       ml

sql_find	=	select * from ...

		...
</screen>
</para>

<para>
IO::Adapter は
<screen>
new IO::Adapter "mysql:members", $config;
</screen>
のように呼び出します。
この $config は次のようなハッシュ・リファレンスになっていることが
期待されています。
<screen>
$config => {
	[mysql:members] => {
		sql_sever => localhost
			...	
	}
}
</screen>
FML::Config は .cf から上のようなハッシュを構成します。
よって IO::Adapter の new() の際には、
FML::Config のオブジェクトを引数で渡せば OK です。
</para>


<sect2>
	<title>
	議論:
		SQL 構文を config.cf に書くには？
		(参照: fml-devel 204)
	</title>

<para>
関数が呼ばれた時に始めて決まる変数もあるので
cf で全部定義することはできない。
そこで、lexical scope で取り扱われる変数の表現があれば解決だろうか？
現在では &amp;varname 記法(下記)を使っている。
</para>

<para>
例: 
以下は、受信者リストとメンバーリストが食い違う例なので、
アドレスの登録をする際に、fml_recepient という値が異なる。
その場合、member と recipient は少し異なる SQL 命令になるので
別々に定義する。
off/on 命令を無視するとか、
fml は sql からデータを読むだけで、
書き込むことはしないなら、
話は簡単になる。
<screen>
member_maps 	= 	mysql:members

recipient_maps 	= 	mysql:recipients


[mysql:members]

sql_server	=	localhost
sql_user	=	fml
sql_password	=	uja
sql_database	=	fml
sql_table	=	ml

sql_get_next_key =	select fml_address from $sql_table
			where fml_ml = '$ml_name'
					and
				fml_domain = '$ml_domain'

sql_getline	=	select * from $sql_table
			where fml_ml = '$ml_name'
					and
				fml_domain = '$ml_domain'

sql_add		=	insert into $sql_table
			values ('$ml_name', '$ml_domain', '&amp;address', 1, 1)

sql_delete	=	delete from $sql_table
			where	fml_ml = '$ml_name'
					and
				fml_domain = '$ml_domain'
					and
				fml_address = '&amp;address'

sql_find	=	select * from $sql_table
			where	fml_ml = '$ml_name'
					and
				fml_domain = '$ml_domain'
					and
				fml_address like '&amp;regexp'



[mysql:recipients]

sql_server	=	localhost
sql_user	=	fml
sql_password	=	uja
sql_database	=	fml
sql_table	=	ml

sql_get_next_key =	select fml_address from $sql_table
			where fml_ml = '$ml_name'
					and
				fml_domain = '$ml_domain'
					and
				fml_recipient = '1'

sql_getline	=	select * from $sql_table
			where fml_ml = '$ml_name'
					and
				fml_domain = '$ml_domain'
					and
				fml_recipient = '1'

sql_add		=	update ml
			set recipient = 1
			where fml_ml = '$ml_name'
					and
				fml_domain = '$ml_domain'
					and
				fml_address = '&amp;address'

sql_delete	=	update ml
			set recipient = 0
			where fml_ml = '$ml_name'
					and
				fml_domain = '$ml_domain'
					and
				fml_address = '&amp;address'


sql_find	=	select * from $sql_table
			where	fml_ml = '$ml_name'
					and
				fml_domain = '$ml_domain'
					and
				fml_recipient = '1'
					and
				fml_address like '&amp;regexp'
</screen>
</para>

</sect2>


</sect1>


</chapter>
