.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "POD2::JA::KiokuDB::Tutorial 3pm"
.TH POD2::JA::KiokuDB::Tutorial 3pm "2022-05-23" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
POD2::JA::KiokuDB::Tutorial \- KiokuDBを始めよう
.SH "Install"
.IX Header "Install"
(インストール)
.PP
KiokuDBとバックエンドと一緒にインストールするには、Task::KiokuDBをインストールするのが一番簡単です。
.PP
KiokuDBはMooseと、いくつかのすぐに使えるモジュールに依存していますが、
特定のストレージモジュールには依存していません。
.PP
KiokuDBは複数のバックエンドのフロントエンドです。
\&\s-1DBI\s0が実際のデータベースへの接続にDBDを使っているのに似ています。
.PP
開発用やテストとして、メモリに保存するKiokuDB::Backend::Hashバックエンドを使うことができます。
プロダクションには、KiokuDB::Backend::DBDかKiokuDB::Backend::DBIかKiokuDB::Backend::BDB
をバックエンドとして推奨します。
.PP
KiokuDB::Backend::DBDをインストールして、以下のインストラクションを見てください。
.SH "CREATING A DIRECTORY HANDLE"
.IX Header "CREATING A DIRECTORY HANDLE"
(ディレクトリハンドルの作成)
.PP
KiokuDBディレクトリは、すべての仕事がされるメインのオブジェクトです。
.PP
すぐに使えるもっとも単純なディレクトリは次のように作れます:
.PP
.Vb 3
\&    my $dir = KiokuDB\->new(
\&        backend => KiokuDB::Backend::Hash\->new
\&    );
.Ve
.PP
このドキュメントの最後に、他のもっと面白いバックエンドの設定を紹介しますが、
とりあえず、やってみます。
.PP
いろいろなバックエンドに接続するためのDSN文字列を使うこともできます。
.PP
.Vb 1
\&    KiokuDB\->connect("hash");
\&
\&    KiokuDB\->connect("dbi:SQLite:dbname=foo", create => 1);
\&
\&    KiokuDB\->connect("bdb:dir=foo", create => 1);
.Ve
.PP
設定ファイルを使うこともできます。
.PP
.Vb 1
\&    KiokuDB\->connect("/path/to/my_db.yml");
.Ve
.PP
設定YAMLファイルです:
.PP
.Vb 6
\&    \-\-\-
\&    # these are basically the arguments for \*(Aqnew\*(Aq
\&    backend:
\&      class: KiokuDB::Backend::DBI
\&      dsn: dbi:SQLite:dbname=/tmp/test.db
\&      create: 1
.Ve
.SH "USING THE DBI BACKEND"
.IX Header "USING THE DBI BACKEND"
(DBIバックエンドを使う)
.PP
2つの理由で、このチュートリアルではDBIバックエンドを使います。
1つ目の理由は、\s-1DBI\s0がどこにでもあるからです。
2つ目の理由は、簡単に裏舞台を見ることが出来るからです。
KiokuDBが何をしているかをよりわかりやすくデモンストレーションできるからです。
.PP
この例ですべてのバックエンドがまったく同じように動きます。
.PP
以下で使う\f(CW$dir\fR変数は下記のように作られます:
.PP
.Vb 4
\&    my $dir = KiokuDB\->connect(
\&        "dbi:SQLite:dbname=kiokudb_tutorial.db",
\&        create => 1, # this causes the tables to be created
\&    );
.Ve
.PP
ユーザー名とパスワードで接続する場合、名前付きの引数を指定しないといけません:
.PP
.Vb 5
\&    my $dir = KiokuDB\->connect(
\&        $dsn,
\&        user     => $user,
\&        password => $password,
\&    );
.Ve
.SH "INSERTING OBJECTS"
.IX Header "INSERTING OBJECTS"
(オブジェクトのインサート)
.PP
Mooseを使った簡単なクラスを定義してみましょう:
.PP
.Vb 2
\&    package Person;
\&    use Moose;
\&
\&    has name => (
\&        isa => "Str",
\&        is  => "rw",
\&    );
.Ve
.PP
それをインスタント化します:
.PP
.Vb 1
\&    my $obj = Person\->new( name => "Homer Simpson" );
.Ve
.PP
下記のようにオブジェクトをデータベースに入れます:
.PP
.Vb 1
\&    my $scope = $dir\->new_scope;
\&
\&    my $homer_id = $dir\->store($obj);
.Ve
.PP
これは、KiokuDBのとても普通の使い方です。ですが、いくつか重要なことを示しています。
.PP
1番目に、スキーマは必要ありません。KiokuDBはテーブルのような何かを事前に定義する必要はありません。
オブジェクトの情報を取り出すために、Mooseを使うことができます。
.PP
2番目に、データベースに入っているすべてのオブジェクトにはIDがあります。
オブジェクトにIDを選ばなけれあば、KiokuDBが代わりにUUIDを割り当てます。
.PP
IDはリレーショナルデータベースのプライマリーキーのようなものです。
.PP
自分でオブジェクトにIDを振りたければ、次のようにすることができます:
.PP
.Vb 1
\&    $dir\->store( homer => $obj );
.Ve
.PP
3番目に、すべてのKiokuDB操作は\fBscope\fR内で行う必要があります。
スコープは上のような簡単な例では大して重要ではありませんが、
循環参照やweakリファレンスが使われるようになると、必要になります。
後でより詳細に見ていきます。
.SH "LOADING OBJECTS"
.IX Header "LOADING OBJECTS"
(オブジェクトの読み出し)
.PP
さて、データベースにHomerが入りました。\f(CW\*(C`store\*(C'\fRから得たIDで取り出せます。
.PP
.Vb 1
\&    my $homer = $dir\->lookup($homer_id);
.Ve
.PP
\&\f(CW$scope\fRと\f(CW$obj\fRは、スコープ内にあるとします。\f(CW$homer\fRと\f(CW$obj\fRは実際に、同じオブジェクトになります。
.PP
.Vb 2
\&    # this is true:
\&    refaddr($homer) == refaddr($obj)
.Ve
.PP
\&\fB生存しているオブジェクトセット\fR (KiokuDB::LiveObjects)内のオブジェクトが
\&\*(L"生存\*(R"しているかをKiokuDBが追跡しているからです。
.PP
オブジェクト既にメモリにあるなら、KiokuDBはインスタンスを
バックエンドから取得します。
.SH "WHAT WAS STORED"
.IX Header "WHAT WAS STORED"
(何が保存されたか)
.PP
データベースを覗いてみましょう:
.PP
.Vb 4
\&    % sqlite3 kiokudb_tutorial.db
\&    SQLite version 3.4.0
\&    Enter ".help" for instructions
\&    sqlite>
.Ve
.PP
データベースのスキーマには2つのテーブルがあります。\f(CW\*(C`entries\*(C'\fRと\f(CW\*(C`gin_index\*(C'\fRです:
.PP
.Vb 2
\&    sqlite> .tables
\&    entries    gin_index
.Ve
.PP
\&\f(CW\*(C`gin_index\*(C'\fRはより複雑なクエリに使われます。チュートリアルの最後に扱います。
.PP
さて、\f(CW\*(C`entries\*(C'\fRに近付いてよく見ましょう:
.PP
.Vb 9
\&    sqlite> .schema entries
\&    CREATE TABLE entries (
\&      id varchar NOT NULL,
\&      data blob NOT NULL,
\&      class varchar,
\&      root boolean NOT NULL,
\&      tied char(1),
\&      PRIMARY KEY (id)
\&    );
.Ve
.PP
メインのカラムは\f(CW\*(C`id\*(C'\fRと\f(CW\*(C`data\*(C'\fRです。KiokuDBにある、すべてのオブジェクトにはIDがあり、
プライマリキーとBLOBデータが関連付けられています。
.PP
DBIバックエンドのデフォルトのシリアライザーはKiokuDB::Serializer::JSONですので、
データを調査できます。
.PP
最初に、\f(CW\*(C`sqlite\*(C'\fRの出力モードを\f(CW\*(C`line\*(C'\fRにセットしましょう。大きいカラムでも
見やすくなります:
.PP
.Vb 1
\&    sqlite> .mode line
.Ve
.PP
テーブルからデータを取得します:
.PP
.Vb 3
\&    sqlite> select id, data from entries;
\&       id = 201C5B55\-E759\-492F\-8F20\-A529C7C02C8B
\&     data = {"_\|_CLASS_\|_":"Person","data":{"name":"Homer Simpson"},"id":"201C5B55\-E759\-492F\-8F20\-A529C7C02C8B","root":true}
.Ve
.PP
上記のように、\f(CW\*(C`name\*(C'\fR属性はblob内の\f(CW\*(C`data\*(C'\fRキーにオブジェクトのクラスとして保存されています。
.PP
\&\f(CW\*(C`data\*(C'\fRカラムはオブジェクトを再作成するのに必要なすべてのデータを含んでいます。
.PP
他のすべてのカラムは検索のためだけに使われます。後で、どのようにユーザー定義のカラムを
作るのかを見せます。
.PP
KiokuDB::Backend::DBDを使った場合は、ディスク上のフォーマットは、\f(CW\*(C`id\*(C'\fRから\f(CW\*(C`data\*(C'\fRのハッシュになり、
他の追加のカラムはありません。
.SH "OBJECT RELATIONSHIPS"
.IX Header "OBJECT RELATIONSHIPS"
(オブジェクトのリレーションシップ)
.PP
\&\f(CW\*(C`Person\*(C'\fRクラスに\f(CW\*(C`name\*(C'\fRよりも、もっと面白いデータを追加してみましょう:
.PP
.Vb 1
\&    package Person;
\&
\&    has spouse => (
\&        isa => "Person",
\&        is  => "rw",
\&        weak_ref => 1,
\&    );
.Ve
.PP
\&\f(CW\*(C`spouse\*(C'\fR属性は他のPersonオブジェクトのリファレンスを持ちます。
.PP
まずは、他のオブジェクトを作りましょう:
.PP
.Vb 3
\&    my $marge_id = $dir\->store(
\&        Person\->new( name => "Marge Simpson" ),
\&    );
.Ve
.PP
データベースに両方のオブジェクトを持たせます。2つを一緒にリンクしましょう:
.PP
.Vb 2
\&    {
\&        my $scope = $dir\->new_scope;
\&
\&        my ( $marge, $homer ) = $dir\->lookup( $marge_id, $homer_id );
\&
\&        $marge\->spouse($homer);
\&        $homer\->spouse($marge);
\&
\&        $dir\->store( $marge, $homer );
\&    }
.Ve
.PP
今、永続的な\fBオブジェクトグラフ\fRを作りました。これは、複数のオブジェクトが
お互いに参照しています。
.PP
\&\f(CW\*(C`spouse\*(C'\fRには\f(CW\*(C`weak_ref\*(C'\fRオプションがありましたので、この循環構造はリークしません。
.PP
データベースでオブジェクトが更新されたら、LinkDBは\f(CW\*(C`spouse\*(C'\fR属性を含むリファレンスを見て、
この関係はストレージ内でユニークなIDを使ってエンコードされます。
.PP
このグラフをロードするために、次のようにできます:
.PP
.Vb 2
\&    {
\&        my $scope = $dir\->new_scope;
\&
\&        my $homer = $dir\->lookup($homer_id);
\&
\&        print $homer\->spouse\->name; # Marge Simpson
\&    }
\&
\&    {
\&        my $scope = $dir\->new_scope;
\&
\&        my $marge = $dir\->lookup($marge_id);
\&
\&        print $marge\->spouse\->name; # Homer Simpson
\&
\&        refaddr($marge) == refaddr($marge\->spouse\->spouse); # true
\&    }
.Ve
.PP
KiokuDBが最初のオブジェクトをロードしたら、そのオブジェクトが依存している
すべてのオブジェクトがロードされます。\f(CW\*(C`spouse\*(C'\fR属性は他のオブジェクトを(IDで)
持っているので、インフレーション時にそのリンクを解決します。
.ie n .SS "The purpose of ""new_scope"""
.el .SS "The purpose of \f(CWnew_scope\fP"
.IX Subsection "The purpose of new_scope"
(\f(CW\*(C`new_scope\*(C'\fRの目的)
.PP
\&\f(CW\*(C`new_scope\*(C'\fRが重要になるところです。オブジェクトはデータベースからインフレートされ、
リファレンスカウントを増やすために、生存しているオブジェクトスコープに追加されます。
.PP
これがされていなければ、\f(CW\*(C`lookup\*(C'\fRから\f(CW$homer\fRが戻ってくる時までに、
\&\f(CW\*(C`spouse\*(C'\fR属性がクリアされます。マージする他のリファレンスがないからです。
.PP
次のコードが理由をデモンストレートします:
.PP
.Vb 3
\&    sub get_homer {
\&        my $homer = Person\->new( name => "Homer Simpson" );
\&        my $marge = Person\->new( name => "Marge Simpson" );
\&
\&        $homer\->spouse($marge);
\&        $marge\->spouse($homer);
\&
\&        return $homer;
\&
\&        # at this point $homer and $marge go out of scope
\&        # $homer has a refcount of 1 because it\*(Aqs the return value
\&        # $marge has a refcount of 0, and gets destroyed
\&        # the weak reference in $homer\->spouse is cleared
\&    }
\&
\&    my $homer = get_homer();
\&
\&    $homer\->spouse; # this returns undef
.Ve
.PP
次のイディオムを使って:
.PP
.Vb 2
\&    {
\&        my $scope = $dir\->new_scope;
\&
\&        # do all KiokuDB work in here
\&    }
.Ve
.PP
少なくとも必要である時間はオブジェクトが生きていることを確保できます。
.PP
Webアプリケーションのコンテキストでは、普通リクエストごとに新しいスコープを作ります。
実際、Catalyst::Model::KiokuDBは、自動的にそうしています。
.SH "REFERENCES IN THE DATABASE"
.IX Header "REFERENCES IN THE DATABASE"
(データベース内のリファレンス)
.PP
さて、データベースにオブジェクトグラフがあります。内部がどうなっているか見てみましょう。
.PP
.Vb 3
\&    sqlite> select id, data from entries;
\&       id = 201C5B55\-E759\-492F\-8F20\-A529C7C02C8B
\&     data = {"_\|_CLASS_\|_":"Person","data":{"name":"Homer Simpson","spouse":{"$ref":"05A8D61C\-6139\-4F51\-A748\-101010CC8B02.data"}},"id":"201C5B55\-E759\-492F\-8F20\-A529C7C02C8B","root":true}
\&
\&       id = 05A8D61C\-6139\-4F51\-A748\-101010CC8B02
\&     data = {"_\|_CLASS_\|_":"Person","data":{"name":"Marge Simpson","spouse":{"$ref":"201C5B55\-E759\-492F\-8F20\-A529C7C02C8B.data"}},"id":"05A8D61C\-6139\-4F51\-A748\-101010CC8B02","root":true}
.Ve
.PP
\&\f(CW\*(C`spouse\*(C'\fRフィールドがJSONオブジェクトということに気づくでしょう。
そして、その内部の\f(CW$ref\fRフィールドには、対象のオブジェクトのUUIDがあります。
.PP
データがロードされると、KiokuDBはロードさえていないオブジェクトへのリファレンスを
キューに入れて、オブジェクトグラフをメモリに常駐させるために、それらをロードします。
.PP
データがこのような方法で表現されている理由について知りたければ、
このフォーマットは、\f(CW\*(C`JPSON\*(C'\fRか JavaScript Persistent Object notation(<http://www.jpson.org>)と呼ばれています。
KiokuDB::Backend::Storableを使うと、KiokuDB::EntryとKiokuDB::Referenceオブジェクトは、
代わりに、storableフックでシリアライズされます。
.SH "OBJECT SETS"
.IX Header "OBJECT SETS"
(オブジェクトセット)
.PP
より複雑なリレーションシップ(1対1に限らない)は、Set::Objectでふつう簡単にモデル化できます。
.PP
\&\f(CW\*(C`Person\*(C'\fRクラスを拡張してそのようなリレーションシップを足してみましょう:
.PP
.Vb 1
\&    package Person;
\&
\&    has children => (
\&        does => "KiokuDB::Set",
\&        is   => "rw",
\&    );
.Ve
.PP
KiokuDB::Setオブジェクトは、Set::ObjectのKiokuDB用のラッパーです。
.PP
.Vb 1
\&    my @kids = map { Person\->new( name => $_ ) } qw(maggie lisa bart);
\&
\&    use KiokuDB::Util qw(set);
\&
\&    my $set = set(@kids);
\&
\&    $homer\->children($set);
\&
\&    $dir\->store($homer);
.Ve
.PP
\&\f(CW\*(C`set\*(C'\fRという便利な関数は新しいKiokuDB::Set::Transientオブジェクトを作ります。
一時的なセットはメモリスペースに存在するものです
(データベースからロードされたセットとは反対に)。
.PP
\&\f(CW\*(C`weak_set\*(C'\fRという便利な関数もあります。
循環構造(例えば、今の例に\f(CW\*(C`parent\*(C'\fR属性を追加する)を避けるために内部で使われている、
Set::Object::Weakで一時的なセットを作ります。
.PP
このオブジェクトは普通のSet::Objectとほとんど同じように振る舞います。
.PP
.Vb 1
\&    my @kids = $dir\->lookup($homer_id)\->children\->members;
.Ve
.PP
主な違いは、セットがデータベースから来るのがデフォルトで遅延されていることです。
\&\f(CW@kids\fRにあるオブジェクトは、実際に必要になるときまでロードされません。
.PP
このことにより、ユーザーのオブジェクトのカプセル化を壊すこと無しに、
部分的にロードされるので、データベースに巨大なオブジェクトグラフがあっても問題になりません。
この振る舞いはKiokuDB::Set::DefferedとKiokuDB::Set::Loadedで実装されています。
.PP
このセットオブジェクトは、遅延ロードの操作に最適化されています。
例えば、2つの遅延セットを横断するなら、横断するセットのみがロードされる必要があります。
.SH "THE TYPEMAP"
.IX Header "THE TYPEMAP"
KiokuDBにオブジェクトが保存される際に、KiokuDB::Collapserを通過します。
エントリーがバックエンドにインサートされる前に、KiokuDB::Entryに、
\&\*(L"平たく\*(R"されたオブジェクトを入れます。
.PP
collapserには、KiokuDB::TypeMapオブジェクトを使います。このオブジェクトは、
それぞれのタイプのオブジェクトがどのように破壊するかを教えます。
.PP
オブジェクトを取ってくる間、オブジェクトを再インフレートして、
ワーキングオブジェクトにするのに、同じtypemapが使われます。
.PP
typemapにないオブジェクトを保存しようとするとエラーになります。その理由は
すべてのタイプのオブジェクトを保存できるか分からないからです。(例えば、
\&\f(CW\*(C`DBI\*(C'\fRはソケット、オブジェクト。XSベースのモジュールは数値のような内部的な
ポインタを持ちます。そのアドレスは次回のロード時には正しくなくなっています)。
大半のオブジェクトは安全にシリアライズできるにもかかわらず、
わずかな報告されないもろさが、大きなデバッグの難しい問題を作るのはありがちなことです。
.PP
このルールの例外は、Mooseベースのオブジェクトです。Mooseの強大な
リフレクションサポートを通して、十分なメタ情報が利用できるので、
安全にシリアライズ出来ます。
.PP
加えて、標準のバックエンドは共通のオブジェクト(DateTime, Path::Classなど>)用に
デフォルトのtypemapを提供しています。KiokuDBにどんなカスタムのtypemapが渡されても、
デフォルトとマージされます。
.PP
それで、実際にKiokuDBにClass::Accessorベースのオブジェクトのようなものを保存させるには、
次のようにします:
.PP
.Vb 4
\&    KiokuDB\->new(
\&        backend => $backend,
\&        allow_classes => [qw(My::Object)],
\&    );
.Ve
.PP
これは次の省略形です:
.PP
.Vb 8
\&    my $dir = KiokuDB\->new(
\&        backend => $backend,
\&        typemap => KiokuDB::TypeMap\->new(
\&            entries => {
\&                "My::Object" => KiokuDB::TypeMap::Entry::Naive\->new,
\&            },
\&        ),
\&    );
.Ve
.PP
KiokuDB::TypeMap::Entry::Naiveは単純に再帰的にたどることで、
オブジェクトのナイーブな破壊を行います。
.PP
collapser は、オブジェクトを見つけると、KiokuDB::TypeMap::Resolverに、
オブジェクトのクラスに応じた、破壊ルーチンを尋ねます。
.PP
この検索は、典型的には、\f(CW\*(C`ref $object\*(C'\fRで行われ、継承を使いません。
スーパークラスで安全に使われているtypemapエントリーは、
必ずしもサブクラスで安全に使えるとは限らないからです。
継承されたエントリーに\fBしたい\fRなら、\f(CW\*(C`isa_entries\*(C'\fRを指定してください。
.PP
.Vb 5
\&    KiokuDB::TypeMap\->new(
\&        isa_entries => {
\&            "My::Object" => KiokuDB::TypeMap::Entry::Naive\->new,
\&        },
\&    );
.Ve
.PP
オブジェクトに通常の(\f(CW\*(C`ref\*(C'\fR keyed)エントリーが見つからなければ、
isaエントリーがオブジェクトスーパークラスのために探されます。
サブクラスエントリーはスーパークラスエントリーより前に試されます。
この検索の結果はキャッシュされるので、クラスごとに一回しか起こりません。
.SS "Typemap Entries"
.IX Subsection "Typemap Entries"
カスタムのシリアライズのフックが欲しければ、自分のオブジェクトを破壊するための
フックを指定できます。
.PP
.Vb 3
\&    KiokuDB::TypeMap::Entry::Callback\->new(
\&        collapse => sub {
\&            my $object = shift;
\&
\&            ...
\&
\&            return @some_args;
\&        },
\&        expand => sub {
\&            my ( $class, @some_args ) = @_;
\&
\&            ...
\&
\&            return $object;
\&        },
\&    );
.Ve
.PP
これらのフックはオブジェクトを破壊するときに、メソッドとして呼ばれます。
.PP
例えば、typemapのISAに関連するPath::Classは:
.PP
.Vb 5
\&    \*(AqPath::Class::Entity\*(Aq => KiokuDB::TypeMap::Entry::Callback\->new(
\&        intrinsic => 1,
\&        collapse  => "stringify",
\&        expand    => "new",
\&    );
.Ve
.PP
\&\f(CW\*(C`intrinsic\*(C'\fRフラグは次のセクションで述べます。
.PP
typemapエントリのもう一つの選択はKiokuDB::Typemap::Entry::Passthroughです。
バックエンドのシリアライズがネイティブにデータタイプを扱うことができると分かっていれば、
これは適切です。
.PP
例えば、オブジェクトに適切なStorableフックがあり(破壊する必要のあるサブオブジェクトを含まない)、
バックエンドには、KiokuDB::Backend::Serialize::Storableを使う場合です。
DateTimeはそのようにstorableが望むクラスの例です:
.PP
.Vb 1
\&    \*(AqDateTime\*(Aq => KiokuDB::Backend::Entry::Passthrough\->new( intrinsic => 1 )
.Ve
.SS "Intrinsic vs. First Class"
.IX Subsection "Intrinsic vs. First Class"
KiokuDBでは、すべてのオブジェクトに、通常、IDが割り当てられます。
オブジェクトが複数のオブジェクトに共有されている場合、このリレーションは維持されます。
.PP
しかし、いくつかのオブジェクトは望ましい振る舞いをしません。
それらは、DateTimeや、Path::Classエントリ、\s-1URI\s0オブジェクトのようなもので、
値を表現します。
.PP
KiokuDBは\fBintrinsicly\fRに、そのようなオブジェクトを、
そのオブジェクトにそれ自身のIDと新しいKiokuDB::Entryを作る代わりに、
破壊するよう要求できます。オブジェクトが直接破壊できれば、親の構造の中に入ります。
.PP
破壊され、共有されたリファレンスは、もともと2つの区別されたコピーとして
データーベースからロードされます。ですので、一つをアップデートしても、
もう一方には影響がありません。
.PP
例えば、下記のようなコードを動かしたとして:
.PP
.Vb 1
\&    use Path::Class;
\&
\&    my $path = file(qw(path to foo));
\&
\&    $obj_1\->file($path);
\&
\&    $obj_2\->file($path);
\&
\&    $dir\->store( $obj_1, $obj_2 );
.Ve
.PP
データがインサートされるときには、下記は真ですが、
\&\f(CW$obj_1\fRと\f(CW$obj_2\fRがデーターベースからロードされると、もはや真ではありません:
.PP
.Vb 1
\&    refaddr($obj_1\->file) == refaddr($obj_2\->file)
.Ve
.PP
\&\f(CW$obj_1\fRと\f(CW$obj_2\fRの両方が\f(CW$path\fRのコピーだからです。
.PP
この現象は、通常、変異されず、複製されたり置き換えられたりするオブジェクトに適しています。
そのようなオブジェクトのためには、最初のクラスエントリが独自のIDでバックエンドに作られるのは、
望まれていないからです。
.SS "The Default Typemap"
.IX Subsection "The Default Typemap"
それぞれのバックエンドには、デフォルトのtypemapがついています。
それには、共通のCPANモジュールオブジェクトのために、いくつか共通のビルトインのエントリもあります。
KiokuDB::TypeMap::Defaultにより詳細があります。
.SH "SIMPLE SEARCHES"
.IX Header "SIMPLE SEARCHES"
(単純な検索)
.PP
ほとんどのバックエンドが効率的ではないものの、便利な単純な検索があります。
これは、エントリをスキャンして、フィールドにマッチさせます。
.PP
このAPIを使いたいなら、KiokuDB::Backend::DBIを使うことをおすすめします。
単純亜検索はSQLのwhere節を使って実装でき、より効率的だからです。
(ただし、手でカラムをセットアップしないといけませんが)
.PP
\&\f(CW\*(C`search\*(C'\fRメソッドに引数としてハッシュリファレンスのみを渡して呼びます。
単純な検索機能が呼び出され、Data::Stream::Bulkが結果と一緒に戻ってきます:
.PP
.Vb 1
\&    my $stream = $dir\->search({ name => "Homer Simpson" });
\&
\&    while ( my $block = $stream\->next ) {
\&        foreach my $object ( @$block ) {
\&            # $object\->name eq "Homer Simpson"
\&       }
\&    }
.Ve
.PP
正確なAPIはまだ決められていません。将来的に、DBIx::Class 0.09のシンタックスと
互換にするつもりです。
.SS "\s-1DBI SEARCH COLUMNS\s0"
.IX Subsection "DBI SEARCH COLUMNS"
この簡単な検索APIを使うには、DBIバックエンドにカラムを設定しなければいけません。
.PP
検索するために、'name'カラムを作りましょう:
.PP
.Vb 5
\&    my $dir = KiokuDB\->connect(
\&        "dbi:SQLite:dbname=foo",
\&        columns => [
\&            # specify extra columns for the \*(Aqentries\*(Aq table
\&            # in the same format you pass to DBIC\*(Aqs add_columns
\&
\&            name => {
\&                data_type => "varchar",
\&                is_nullable => 1, # probably important
\&            },
\&        ],
\&    );
.Ve
.PP
スキーマを手で変更することもできますし、また、データをバックアップするのに、\f(CW\*(C`kioku dump\*(C'\fRを使い、
データベースを削除し、\f(CW\*(C`create => 1\*(C'\fRで接続し、\f(CW\*(C`kioku load\*(C'\fRを使うことも出来ます。
.PP
このカラムを埋め込むために、Homerをロードして、更新する必要があります:
.PP
.Vb 4
\&    {
\&        my $s = $dir\->new_scope;
\&        $dir\->update( $dir\->lookup( $homer_id ) );
\&    }
.Ve
.PP
データベースでは次のようになります:
.PP
.Vb 2
\&       id = 201C5B55\-E759\-492F\-8F20\-A529C7C02C8B
\&     name = Homer Simpson
.Ve
.SH "GETTING STARTED WITH BDB"
.IX Header "GETTING STARTED WITH BDB"
(BDBを始めよう)
.PP
KiokuDBでもっとも成熟したバックエンドは、KiokuDB::Backend::DBDです(訳注:DBIのほうが安定しているとYAPC::Asia 2009で聞きました)。
十分に動きますし、多くの機能をサポートします。
オブジェクトのインデックスのカスタマイズやトランザクションを提供する
Search::GINのようなインテグレーションもあります。
.PP
KiokuDB::Backend::DBIはより新しいですが、そこまでテストされていません。
ですが、トランザクションもサポートしますし、クエリベースのSearch::GINもあります。
これも、なかなかよく動きます。ですが、KiokuDB::Backend::BDBと同じくらい速くはありません
(訳注:YAPC::Asia 2009では、ほぼ変わらないと聞きました)
.SS "Installing KiokuDB::Backend::BDB"
.IX Subsection "Installing KiokuDB::Backend::BDB"
KiokuDB::Backend::BDBは、BerkeleyDBモジュールが必要です。
また、最近のバージョンのBerkeley DB自身も必要です。Berkeley DBは、以下のURLにあります。
<http://www.oracle.com/technology/software/products/berkeley\-db/db/index.html>.
.PP
BerkeleyDB(ライブラリ)は通常、\f(CW\*(C`/usr/local/BerkeleyDB.4.7\*(C'\fRにインストールされます。
ですが、BerkeleyDB(モジュール)は、\f(CW\*(C`/usr/local/BerkeleyDB\*(C'\fRを見ようとします。
ですので、シンボリックリンクを作っておけば、インストールが簡単になります。
.PP
BerkeleyDBがインストールできれば、KiokuDB::Backend::BDBは問題なくインストールできるはずです。
KiokuDBと一緒に使うことができます。
.SS "Using KiokuDB::Backend::BDB"
.IX Subsection "Using KiokuDB::Backend::BDB"
BDBバックエンドを使うために、ストレージを作らなければいけません。
このために、\f(CW\*(C`create\*(C'\fRフラグを渡さなければいけません。
.PP
.Vb 6
\&    my $backend = KiokuDB::Backend::BDB\->new(
\&        manager => {
\&            home   => Path::Class::Dir\->new(qw(path to storage)),
\&            create => 1,
\&        },
\&    );
.Ve
.PP
BDBバックエンドは、BerkeleyDB::Managerを使って、たくさんのBerkeleyDBの下働きを行います。
BerkeleyDB::Managerオブジェクトは\f(CW\*(C`manager\*(C'\fR属性で提供される引数を使って、インスタンス化されます。
.PP
これで、ストレージがつくられました。このバックエンドを、以前と同様に使います。
.PP
.Vb 1
\&    my $dir = KiokuDB\->new( backend => $backend );
.Ve
.PP
その後のオープンには、\f(CW\*(C`create\*(C'\fR属性が真である必要はありませんが、真であっても特に害はありません。
.PP
この\f(CW\*(C`connect\*(C'\fRは上記のものと同じです:
.PP
.Vb 1
\&    my $dir = KiokuDB\->connect( "bdb:dir=path/to/storage", create => 1 );
.Ve
.SH "TRANSACTIONS"
.IX Header "TRANSACTIONS"
(トランザクション)
.PP
いくつかのバックエンド(KiokuDB::Backend::Role::TXNロールをするもの)は、トランザクションが使えるものがあります。
.PP
DBIx::Classに慣れているなら、すぐわかるでしょう:
.PP
.Vb 3
\&    $dir\->txn_do(sub {
\&        $dir\->store($obj);
\&    });
.Ve
.PP
BerkeleyDBレベルのトランザクションを作ります。データベースへのすべての変更は
ブロックが綺麗に実行されたら、コミットされます。
.PP
何らかのエラーが起きれば、トランザクションはロールバックされます。
変更は次の読み込みでは、見えません。
.PP
KiokuDB生きているインスタンスには触れません。ですので、次のようにすると
.PP
.Vb 2
\&    $dir\->txn_do(sub {
\&        my $scope = $dir\->new_scope;
\&
\&        $obj\->name("Dancing Hippy");
\&        $dir\->store($obj);
\&
\&        die "an error";
\&    });
.Ve
.PP
\&\f(CW\*(C`name\*(C'\fR属性はロールバック\fBされません\fR。\f(CW\*(C`store\*(C'\fRオペレーションだけが、元に戻ります。
.PP
トランザクションは適切にネストできます。また、ほとんどのバックエンドで、一般的に
書き込みのパフォーマンスが良くなります。
.SH "QUERIES"
.IX Header "QUERIES"
(クエリ)
.PP
KiokuDB::Backend::BDB::GINはKiokuDB::Backend::BDBのサブクラスで、
Serach::GINインテグレーションを提供しています。
.PP
Search::GINはインデックスとクエリーオブジェクトのフレームワークです。
Postgresの内部GIN apiにインスパイアされました。
GINは、Generalized Inverted Indexes(訳注:汎用転置索引)の略です。
.PP
Search::GINを使うと、任意の検索キーをオブジェクトにタイしてインデックスできます。
そして、それらのオブジェクトをクエリで検索できます。
.PP
例えば、Search::GINがサポートする、すぐに使える、予めある検索の一つに、クラスインデックスがあります。
Search::GIN::Extract::Callback を使って、オブジェクトにカスタムのインデックスを作りましょう:
.PP
.Vb 5
\&    my $dir = KiokuDB\->new(
\&        backend => KiokuDB::Backend::BDB::GIN\->new(
\&            extract => Search::GIN::Extract::Callback\->new(
\&                extract => sub {
\&                    my ( $obj, $extractor, @args ) = @_;
\&
\&                    if ( $obj\->isa("Person") ) {
\&                        return {
\&                            type => "user",
\&                            name => $obj\->name,
\&                        };
\&                    }
\&
\&                    return;
\&                },
\&            ),
\&        ),
\&    );
\&
\&    $dir\->store( @random_objects );
.Ve
.PP
オブジェクトを検索するために、マニュアルキー検索クエリを使います:
.PP
.Vb 5
\&    my $query = Search::GIN::Query::Manual\->new(
\&        values => {
\&            type => "person",
\&        },
\&    );
\&
\&    my $stream = $dir\->search($query);
.Ve
.PP
結果として、検索結果を表すData::Stream::Bulkオブジェクトが返ります。
次のようにイテレートできます。
.PP
.Vb 5
\&    while ( my $block = $stream\->next ) {
\&        foreach my $person ( @$block ) {
\&            print "found a person: ", $person\->name;
\&        }
\&    }
.Ve
.PP
また、より単純に、メモリに全結果をロードしてもかまわないなら:
.PP
.Vb 1
\&    my @people = $stream\->all;
.Ve
.PP
Search::GINはまだ未成熟です。ドキュメントも書いているところです。
ですが、このような単純な検索は動きますし、Search::GIN::Extract::Classのような
予めある解決を含んでいます。
.PP
つまり、現在は動きますが、新しく開発をするときには、これに注意してください。
.SH "翻訳について"
.IX Header "翻訳について"
翻訳者：加藤敦 (ktat@cpan.org)
.PP
Perlドキュメント日本語訳 Project にて、
Perlモジュール、ドキュメントの翻訳を行っております。
.PP
.Vb 4
\& http://perldocjp.sourceforge.jp/
\& http://sourceforge.jp/projects/perldocjp/
\& http://www.freeml.com/ctrl/html/MLInfoForm/perldocjp@freeml.com
\& http://www.perldoc.jp/
.Ve