XIRDの使いかたなど

注意:この文章はREADME.jaから手動で生成しています。必ずしも最新の内容をさしているとは限らないことに御注意してください。最新の内容は、同梱のREADME.ja をみてください。

XIRDを使用するまでの簡単な流れ

準備として config.xirdを記述する。
RDBを起動しておく。
引数にconfig.xirdを与えてxird_dbd.rbを実行。
引数にconfig.xirdを与えてxird_dbi.rbを実行。
望みの動作を行うXMLをXMLRPCを利用してxird_dbiを起動したホストに対して送る

config.xirdでxird_dbd.rbおよびRDBのホスト名を指定できるため、RDB、 xird_dbd.rb、xird_dbi.rbは、必ずしも同一ホストで起動する必要はありません。

使い方

準備: config.xirdの書き方

例:

<config>
  <database>
    <xird_dbd> localhost </xird_dbd>
    <dbname> test-db </dbname>
    <hostname> localhost </hostname>
    <username> someone </username>
    <password />
    <dbtype> Pg </dbtype>
    <primary_key>xird_serial</primary_key>
    <primary_table> test </primary_table>
  </database>

 <mapper>
    <mapping>
      <example>
        <map datatype="real" accept_null="true">
      </example>
      <id>
        <map table="test" datatype="varchar(13)" accept_null="false">
      </id>     
         : 
    </mapping>
  </mapper>
</config>

xird_dbd: XIRD DBDが動作しているホスト名を記述してください。
dbname, hostname, username, password: RDBMSに関しての情報を記述してください。
dbtype: XIRD DBDが使用するRDBMSを記述します。 DBIで定義されている記法で記述してください。(例: PostgreSQL=Pg, MysQL=mysql)
primary_key: XIRD全体で使用するプライマリキーを書いてください。このprimary_keyは、 primary_tableに含まれている必要があります。また、primary_keyは、RDBでserial型など、自動的に増加するカラムである必要があります。
primary_table: 特に指定がないかぎり、後述のmapでは、ここで指定したtableに入っているものとします。また、プライマリキーが入っているテーブルです。
map: field_nameとしては、<map>タグの親が使われます。(この例ではidとなります) <map>タグは複数書くことができます。
table属性: <map>タグの中のtable属性は、このmapが含まれているRDBのtableを指定します。省略すると、<primary_table>タグで指定したtableとなります。
datatype属性: <map>タグの中のdatatype属性は、RDBMSで使用されるDataTypeを記述します。
accept_null属性: <map>タグの中のaccept_null属性は、値がnullでも許されるかどうかを決定します。この属性は主にINSERT時に使われます。この属性がfalseであるならば、null を許しません。従って、この属性を持つmapのデータを入れずにデータを追加するとエラーとなります。

xirdの起動

xird_dbi.rbとxird_dbd.rbを起動してください。

% ruby xird_dbi.rb -d -l dbi.log config.xird
% ruby xird_dbd.rb -d -l dbd.log config.xird

-d: デーモンとして起動します。(ただし、xird_dbdでのデーモン化はまだ不具合があります)
-l: ログファイルを指定します。ログには上書きではなく追記されます。

xird_dbi.rb、xird_dbd.rb、RDBMSはそれぞれ別ホストで起動することが可能です。

同一ホストの場合でも別ホストの場合でもconfig ファイルの以下の部分を適切に記述してください。

<config>
 <xird_dbd>  <- ここにxird_dbdのホスト名を入れてください
 <hostname>  <- ここにRDBMSのホスト名を入れてください
</config>

使いかた

ここまででXIRDを使う準備が整いました。

- 基本部分 - データの取得 - データの更新

に分けて解説します。データの追加や削除も更新の一部として記述されています。

基本部分

xirdを使用するためには、XMLRPCを使います。ただし、XMLRPCを利用して、 XMLをそのまま投げます。

返答もそのままXMLできますので、それを好きなようにparseしてください。

rubyでの利用例

同梱のtest.rbをみてください。

result = server.call("xird.getSnap", query_xml)

のようにデータの取得やデータの更新のところで解説するXML(query_xml)をそのまま送信します。

phpでの利用例

php(version 4)で簡単にXIRDを利用できるライブラリがあります。(まだ未公開)

詳細は公開時に別途解説しますが、

$message = new XML_RPC_Message('xird.getSnap',array($query));

のように同様にXML($query)をそのまま送信します。

データの取得

<xird:query>タグ内に、取得したい要素名を名前にし、Text要素を空にしたタグを記入したXMLを作成します。(Text要素を入れたタグは、条件式とみなされます)

XMLRPCで、メソッド名を"getSnap"、引数を作成したXMLにして、xird_dbiに送信します。(xird_dbiのポート番号は初期状態では8080です)

xird_dbiからの返り値として、空にしたタグに値が含まれて戻ってきます。

条件式指定方法

<xird:query>
<xird:where>

の二つが利用できます。

1. <xird:query>に書く

<xird:query>タグ内で、値が入っているものを条件式とみなします。

例: 
 <xird:query>
   <nutrition>
      <id>4901005167537</id>
   </nutrition>
 </xird:query>

この例では条件式を id = 4901005167537 とします。

2. <xird:where>に書く

<xird:where>タグを利用することで、複数条件を指定することができます。 <xird:where>タグの中に含まれるタグ内で、値が入っているものを条件式とみなします。この時、複数のタグがある場合、それらは並列とみなし、ANDでつなぎます。

例:

<xird>
  <xird:where>
     <id>4901005167537</id>
     <energy>80</energy>
  </xird:where>
</xird>

というXMLを送信すると、XIRDは、

id=4901005167537 AND energy=80

という条件式とみなします。

例:

Query: この例では条件式指定に<xird:query>を利用しています。この場合、enery=581という条件が設定されます。

<?xml version="1.0" encoding="iso-2022-jp" ?>
<xird>
  <xird:query>
    <nutrition>
       <id></id>
       <energy>581</energy>
       <protein />
       <company />
       <product />
    </nutrition>
  </xird:query>
</xird>

Answer:

<?xml version='1.0' encoding='UTF-8'?>
<xird>
  <xird:result>
    <xird:row serial_no='3'>
      <id>4951928302676</id>
      <protein>0.0</protein>
      <company>東チョコS</company>
      <product>おかしの便り ライスチョコ</product>
    </xird:row>
    <xird:row serial_no='8'>
      <id>test</id>
      <protein>0.0</protein>
      <company>ダミーデータ</company>
      <product>ダミーデータ</product>
    </xird:row>
  </xird:result>
  <xird:hash>4e1bfd0ce75dccd59895d473ba626bee</xird:hash>
</xird>

DBの中に、条件(energyが581)にマッチするデータが二つあったため、 XMLの中にも二つのデータが入って返ってきました。これら一つ一つには、serial_noという属性が入っています。 (このserial_noはデータの更新の時に使用します)

もしも、なんらかのエラーが発生した場合、<xird:query>はそのままで <xird:error>タグ内にエラー内容が記述されて返ってきます。

データの更新

データのUPDATE、INSERT、DELTEを同じ手法で行うことが出きます。

最初に条件を指定して、データの取得を行います。 XIRDから返ってきたXMLの中に<xird:hash>タグが含まれているはずです。

このHashの値を<xird:hash>にいれた上で、以下のタグを入力してください。一つのデータを示すために<xird:row>で囲む必要があります。

データを更新したい場合: <xird:query><xird:row>タグの serial_noを更新したいデータの serial_no と同じにし、Text要素に更新する値を入れてください。
データを追加したい場合: <xird:query><xird:row>タグ中に追加したい値を入力してください。 serial_noを記載する必要はありません。自動的に付加されるはずです。
データを削除したい場合: 削除したいserial_noを持つ<xird:row>タグの要素を空要素にします。

これらのXMLは少々複雑ですので、例を見てください。

こうしてできあがったXMLをXMLRPCで、メソッド名を"setSnap"、引数を作成したXMLとして、XIRD DBIに送信します。(ポート番号は初期状態では8080です)

XIRDからの返り値として、空にしたタグに値が含まれて戻ってきます。

例1:

Query: この例では、先ほどの例で取得したデータから

serial_no="3"のデータを変更
データを追加 (serial_noが記載されていない)

しています。

<?xml version="1.0" encoding="iso-2022-jp" ?>
<xird>
  <xird:query>
        <xird:row serial_no='3'>
          <product>すっごくおいしいもの</product>
        </xird:row>
        <xird:row>
          <product>高タンパク質食品</product>
          <energy>581</energy>
          <protein>9999.0</protein>
        </xird:row>
  </xird:query>
  <xird:hash>4e1bfd0ce75dccd59895d473ba626bee</xird:hash>
</xird>

Answer:

<?xml version='1.0'?>
<xird>
  <xird:query>
        <xird:row serial_no='3'>
          <product>すっごくおいしいもの</product>
        </xird:row>
        <xird:row serial_no='10'>

p <product>高タンパク質食品</product>

<energy>581</energy>
<protein>9999.0</protein>

</xird:row>

</xird:query>
<xird:hash>4e1bfd0ce75dccd59895d473ba626bee</xird:hash>

</xird>

例2:

Query: この例では、先ほどの例で取得したデータから

データを削除 (serial_no="3"は空要素しか持たないため)

しています。

<?xml version="1.0" encoding="iso-2022-jp" ?>
<xird>
  <xird:query>
        <xird:row serial_no='3'>
        </xird:row>
  </xird:query>
  <xird:hash>4e1bfd0ce75dccd59895d473ba626bee</xird:hash>
</xird>

Answer:

<?xml version='1.0'?>
<xird>
  <xird:query>
  </xird:query>
  <xird:hash>4e1bfd0ce75dccd59895d473ba626bee</xird:hash>
</xird>

もしも、なんらかのエラーが発生した場合、<xird:error>タグ内にエラー内容が記述され、返答されます。

注意

データを追加する場合、NULLが許されてないカラムに値が入っていないとエラーが返ってきます。NULLが許されるかなどはconfigにかかれているはずです。

xird_compiler.rb

xird_compilerは、config.xirdからCREATE TABLEの雛型を作成するプログラムです。

% ruby xird_compiler.rb config.xird

と実行すると、標準出力にCREATE TABLEの雛型が標準出力に表示されます。この出力で大抵のRDBMSでは動作します。

ただし、Primary Keyに関しては各RDBMSで共通のデータ型が存在しないため、手動で追加する必要があります。

また、それ以外にもエラーが発生する場合や、細かな設定を行いたい場合は、 xird_compilerの出力を適当なファイルに保存し、手動で変更を行ってください。

xird_compilerはあくまで雛型を作成するプログラムであり、どのようなRDBMS でも動作することを保証するものではありません。