=encoding utf-8

=pod

=head1 NAME

=begin original

KiokuDB::Tutorial - Getting started with L<KiokuDB>

=end original

KiokuDB::Tutorial - L<KiokuDB>を始めよう

=head1 Install

(インストール)

=begin original

The easiest way to install L<KiokuDB> and a number of backends is
L<Task::KiokuDB>.

=end original

L<KiokuDB>とバックエンドを一緒にインストールするには、L<Task::KiokuDB>をインストールするのが一番簡単です。

=begin original

L<KiokuDB> depends on L<Moose> and a few other modules out of the box, but no
specific storage module.

=end original

L<KiokuDB>はL<Moose>と、いくつかのすぐに使えるモジュールに依存していますが、
特定のストレージモジュールには依存していません。

=begin original

L<KiokuDB> is a frontend to several backends, much like L<DBI> uses DBDs to
connect to actual databases.

=end original

L<KiokuDB>は複数のバックエンドのフロントエンドです。
L<DBI>が実際のデータベースへの接続にDBDを使っているのに似ています。

=begin original

For development and testing you can use the L<KiokuDB::Backend::Hash> backend,
which is an in memory store, but for production L<KiokuDB::Backend::BDB> or
L<KiokuDB::Backend::DBI> are the recommended backends.

=end original

開発用やテストとして、メモリに保存するL<KiokuDB::Backend::Hash>バックエンドを使うことができます。
プロダクションには、L<KiokuDB::Backend::DBD>かL<KiokuDB::Backend::DBI>をバックエンドとして推奨します。

=begin original

See below for instructions on getting L<KiokuDB::Backend::BDB> installed.

=end original

L<KiokuDB::Backend::DBD>をインストールして、以下のインストラクションを見てください。

=head1 CREATING A DIRECTORY

(ディレクトリの作成)

=begin original

A KiokuDB directory is the object that contains all the common functionality
regardless of the backend.

=end original

KiokuDBディレクトリはオブジェクトで、バックエンド以外のすべての共通の機能を含みます。

=begin original

The simplest directory ready for use can be created like this:

=end original

すぐに使えるもっとも単純なディレクトリは次のように作れます:

    my $dir = KiokuDB->new(
        backend => KiokuDB::Backend::Hash->new
    );

=begin original

We will revisit other more interesting backend configuration later in this
document, but for now this will do.

=end original

このドキュメントの最後に、他のもっと面白いバックエンドの設定を紹介しますが、
とりあえず、やってみます。

=begin original

You can also use DSN strings to connect to the various backends:

=end original

いろいろなバックエンドに接続するためのDSN文字列を使うこともできます。

    KiokuDB->connect("hash");

    KiokuDB->connect("dbi:SQLite:dbname=foo", create => 1);

    KiokuDB->connect("bdb:dir=foo", create => 1);

=begin original

Or use a configuration file

=end original

または、設定ファイルでも

    KiokuDB->connect("/path/to/my_db.yml");
    KiokuDB->connect("/path/to/dir");

=begin original

With a configuration file like this:

=end original

設定ファイルは次のようになります:

    backend:
      class: KiokuDB::Backend::DBI
      dsn: dbi:SQLite:dbname=/tmp/test.db
      create: 1

=head1 USING THE DBI BACKEND

(DBIバックエンドを使う)

=begin original

During this tutorial we will be using the DBI backend for two reasons. The
first is L<DBI>'s ubiquity - almost everyone has used and knows how to install
and use it. The second the possibility of easily looking behind the scenes, to
more clearly demonstrate what L<KiokuDB> is doing.

=end original

2つの理由で、このチュートリアルではDBIバックエンドを使います。
1つ目の理由は、L<DBI>がどこにでもあるからです - ほとんどすべての人がインストール方法も
使い方も知っています。2つ目の理由は、簡単に裏舞台を見ることが出来るからです。
L<KiokuDB>が何をしているかをよりわかりやすくデモンストレーションできるからです。

=begin original

That said, the examples will work with all backends exactly the same.

=end original

この例ですべてのバックエンドがまったく同じように動きます。

=begin original

The C<$dir> variable used below is created like this:

=end original

以下で使うC<$dir>変数は下記のように作られます:

    my $dir = KiokuDB->connect(
        "dbi:SQLite:dbname=kiokudb_tutorial.db",
        create => 1,
    );

=begin original

Note that if you are connecting with a username and password you must specify
these as named arguments:

=end original

ユーザー名とパスワードで接続する場合、名前付きの引数を指定しないといけません:

    my $dir = KiokuDB->connect(
        $dsn,
        user     => $user,
        password => $password,
    );

=head1 INSERTING OBJECTS

(オブジェクトのインサート)

=begin original

Let's start by defining a simple class using L<Moose>:

=end original

L<Moose>を使った簡単なクラスを定義してみましょう:

    package Person;
    use Moose;

    has name => (
        isa => "Str",
        is  => "rw",
    );

=begin original

We can instantiate it:

=end original

それをインスタント化します:

    my $obj = Person->new( name => "Homer Simpson" );

=begin original

and insert the object to the database as follows:

=end original

下記のようにオブジェクトをデータベースに入れます:

    my $scope = $dir->new_scope;

    my $homer_id = $dir->store($obj);

=begin original

This is very trivial use of L<KiokuDB>, but it illustrates a few important
things.

=end original

これは、L<KiokuDB>のとても普通の使い方です。ですが、いくつか重要なことを示しています。

=begin original

First, no schema is necessary. L<KiokuDB> can use L<Moose> to introspect your
object without needing to predefine anything like tables.

=end original

1番目に、スキーマは必要ありません。L<KiokuDB>はテーブルのような何かを事前に定義する必要はありません。
オブジェクトの情報を取り出すために、L<Moose>を使うことができます。

=begin original

Second, every object in the database has an ID. If you don't choose an ID for
an object, L<KiokuDB> will assign a UUID instead. The ID is like a primary key
in a relational database. If you want to choose an ID for your object, you can
do something like:

=end original

2番目に、データベースに入っているすべてのオブジェクトにはIDがあります。
オブジェクトにIDを選ばなけれあば、L<KiokuDB>が代わりにUUIDを割り当てます。
IDはリレーショナルデータベースのプライマリーキーのようなものです。
自分でオブジェクトにIDを振りたければ、次のようにすることができます:

    $dir->store( homer => $obj );

=begin original

and C<$obj>'s ID will be C<homer>. If you don't provide an ID a UUID will be
assigned automatically.

=end original

これで、C<$obj>のIDはC<homer>になります。IDを与えなければ、UUIDが自動的にふられます。

=begin original

Third, all L<KiokuDB> operations need to be performed within a B<scope>. The
scope does not apply to a simple example like the above, but becomes necessary
once weak references are used. We will look into that in more detail later.

=end original

3番目に、すべてのL<KiokuDB>操作はB<scope>内で行う必要があります。
スコープは上のような簡単な例には適しませんが、weakリファレンスが使われるようになると、
必要になります。後でより詳細に見ていきます。

=head1 LOADING OBJECTS

(オブジェクトの読み出し)

=begin original

So now that Homer has been inserted into the database, we can fetch him out of
there using the ID we got from C<store>.

=end original

さて、データベースにHomerが入りました。C<store>から得たIDで取り出せます。

    my $homer = $dir->lookup($homer_id);

=begin original

Assuming that C<$scope> and C<$obj> are still in scope, C<$homer> and C<$obj>
will actually be the same reference:

=end original

C<$scope>とC<$obj>は、スコープ内にあるとします。C<$homer>とC<$obj>は実際に、同じリファレンスになります。

    refaddr($homer) == refaddr($obj)

=begin original

This is because L<KiokuDB> tracks which objects are "live" in the
B<live object set> (L<KiokuDB::LiveObjects>).

=end original

B<生存しているオブジェクトセット> (L<KiokuDB::LiveObjects>)内のオブジェクトが
"生存"しているかをL<KiokuDB>が追跡しているからです。

=begin original

If C<$obj> and C<$scope> are no longer in scope you'd need to create a new
scope, and then fetch the object from the database again:

=end original

C<$obj>とC<$scope>が、もうスコープにいなければ、新しいスコープを作らなければいけません。
それから、再びデータベースからオブジェクトを取り出します:

    my $scope = $dir->new_scope;

    my $homer = $dir->lookup($homer_id);

=begin original

In this case since the original instance of Homer is no longer live, but has
been garbage collected by Perl, L<KiokuDB> will fetch it from the backend.

=end original

このケースではHomerのオリジナルのインスタンスはもはや生きておらず、
Perlによりガベージコレクトされています。
L<KiokuDB>はインスタンスをバックエンドから取得します。

=head1 WHAT WAS STORED

(何が保存されたか)

=begin original

Let's peek into the database momentarily. Launch the SQL command line tool to
your database:

=end original

すぐにデータベースを覗いてみましょう。SQLコマンドラインツールを起動しましょう:

    % sqlite3 kiokudb_tutorial.db
    SQLite version 3.4.0
    Enter ".help" for instructions
    sqlite>

=begin original

The database schema has two tables, C<entries> and C<gin_index>:

=end original

データベースのスキーマには2つのテーブルがあります。C<entries>とC<gin_index>です:

    sqlite> .tables
    entries    gin_index

=begin original

C<gin_index> is used for more complex queries, and we'll get back to it at the
end of the tutorial.

=end original

C<gin_index>はより複雑なクエリに使われます。チュートリアルの最後に扱います。

=begin original

Let's have a closer look at C<entries>:

=end original

C<entries>をよく見ましょう:

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

=begin original

The main columns are C<id> and C<data>. In L<KiokuDB> every object has an ID
which serves as a primary key and a BLOB of data associated with it.

=end original

メインのカラムはC<id>とC<data>です。L<KiokuDB>にある、すべてのオブジェクトにはIDがあり、
プライマリキーとBLOBデータが関連付けられています。

=begin original

Since the default serializer for the DBI backend is
L<KiokuDB::Serializer::JSON>, we can peek at the data.

=end original

DBIバックエンドのデフォルトのシリアライザーはL<KiokuDB::Serializer::JSON>ですので、
データを覗き見ることができます。

=begin original

First we'll set C<sqlite>'s output mode to C<line>. This is easier to read with large columns:

=end original

最初に、C<sqlite>の出力モードをC<line>にセットしてください。大きいカラムでも見やすくなります:

    sqlite> .mode line

=begin original

And select the data from the table:

=end original

テーブルからデータを取得します:

    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}

=begin original

As you can see the C<name> attribute is stored under the C<data> key inside the
blob, as is the object's class.

=end original

上記のように、C<name>属性はblob内のC<data>キーにオブジェクトのクラスとして保存されています。

=begin original

The C<data> column contains all of the data necessary to recreate the object.

=end original

C<data>カラムはオブジェクトを再作成するのに必要なすべてのデータを含んでいます。

=begin original

All the other columns are used solely for lookups. Later on we'll show how to
create more search columns.

=end original

他のすべてのカラムは単に検索のために使われます。後で、どのように検索用のカラムを作るのかを見せます。

=begin original

When using L<KiokuDB::Backend::BDB> the on-disk format is actually a hash of
C<id> to C<data>.

=end original

L<KiokuDB::Backend::DBD>を使った場合は、ディスク上のフォーマットは、実際には、C<id>からC<data>のハッシュになります。

=head1 OBJECT RELATIONSHIPS

(オブジェクトのリレーションシップ)

=begin original

Let's extend the C<Person> class to hold some more interesting data than just a
C<name>:

=end original

C<Person>クラスにC<name>よりも、もっと面白いデータを追加してみましょう:

    package Person;

    has spouse => (
        isa => "Person",
        is  => "rw",
        weak_ref => 1,
    );

=begin original

This new C<spouse> attribute will hold a reference to another person object.

=end original

C<spouse>属性は他のPersonオブジェクトのリファレンスを持ちます。

=begin original

Let's first create and insert another object:

=end original

まずは、他のオブジェクトを作りましょう:

    my $marge_id = $dir->store(
        Person->new( name => "Marge Simpson" ),
    );

=begin original

Now that we have both objects in the database, let's link them together:

=end original

データベースに両方のオブジェクトを持たせます。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 );
    }

=begin original

Now we have created a persistent B<object graph>, that is several objects which
point to each other.

=end original

今、永続的なB<オブジェクトグラフ>を作りました。これは、複数のオブジェクトが
お互いに参照しています。

=begin original

The reason C<spouse> had the C<weak_ref> option was so that this circular
structure will not leak.

=end original

C<spouse>にはC<weak_ref>オプションがありましたので、この循環構造はリークしません。

=begin original

When then objects are updated in the database, L<KiokuDB> sees that their
C<spouse> attribute contains references, and this relationship will be encoded
using their unique ID in storage.

=end original

データベースでオブジェクトが更新されたら、L<LinkDB>はC<spouse>属性を含むリファレンスを見て、
この関係はストレージ内でユニークなIDを使ってエンコードされます。

=begin original

To load the graph, we can do something like this:

=end original

このグラフをロードするために、次のようにできます:

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

=begin original

When L<KiokuDB> is loading the initial object, all the objects the object
depends on will also be loaded. The C<spouse> attribute contains a
reference to another object (by ID), and this link is resolved at inflation
time.

=end original

L<KiokuDB>が最初のオブジェクトをロードしたら、そのオブジェクトが依存している
すべてのオブジェクトがロードされます。C<spouse>属性は他のオブジェクトを(IDで)
持っているので、インフレーション時にそのリンクを解決します。

=head2 The purpose of C<new_scope>

(C<new_scope>の目的)

=begin original

This is where C<new_scope> becomes important. As objects are inflated from the
database, they are pushed onto the live object scope, in order to increase
their reference count.

=end original

C<new_scope>が重要になるところです。オブジェクトはデータベースからインフレートされ、
リファレンスカウントを増やすために、生存しているオブジェクトスコープに追加されます。

=begin original

If this was not done, by the time C<$homer> was returned from C<lookup> his
C<spouse> attribute would have been cleared because there is no other reference
to Marge.

=end original

これがされていなければ、C<lookup>からC<$homer>が戻ってくる時までに、
C<spouse>属性がクリアされます。マージする他のリファレンスがないからです。

=begin original

If, on the other hand the circular structure was not weak, it would have to be
broken manually, which is very error prone.

=end original

もし、一方で、循環構造がweakでなければ、手で壊さなければいけません。
これは、とてもエラーになりやすいです。

=begin original

By using this idiom:

=end original

次のイディオムを使って:

    {
        my $scope = $dir->new_scope;

        # do all KiokuDB work in here
    }

=begin original

You are ensuring that the objects live at least as long as is necessary.

=end original

少なくとも必要である時間はオブジェクトが生きていることを確保できます。

=begin original

In a web application context usually you create one new scope per request.

=end original

Webアプリケーションのコンテキストでは、普通リクエストごとに新しいスコープを作ります。

=begin original

While scopes can nest, this is not a requirement.

=end original

スコープがネストできるなら、必須ではありません。

=begin original

You are free to create as many or as few scopes as you like, as long as there
is at least one, but note that child scopes refer to their parents to ensure
that all objects that were already live at the time that a scope is created are
still alive.

=end original

少なくとも一つのスコープがあれば、好きなだけ多くの、または、少ないスコープを作ることができます。
その時に作られたスコープにすでにあるすべてのオブジェクトを確実にする親を参照している子供のスコープもまだ生きています。

=head1 REFERENCES IN THE DATABASE

(データベース内のリファレンス)

=begin original

Now that we have an object graph in the database let's have another look at
what's inside.

=end original

さて、データベースにオブジェクトグラフがあります。内部がどうなっているか見てみましょう。

    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}

=begin original

You'll notice the C<spouse> field has a JSON object with a C<$ref> field inside
it holding the UUID of the target object.

=end original

C<spouse>フィールドがJSONオブジェクトということに気づくでしょう。
そして、その内部のC<$ref>フィールドには、対象のオブジェクトのUUIDがあります。

=begin original

When data is loaded L<KiokuDB> queues up references to unloaded objects and
then loads them in order to materialize the memory resident object graph.

=end original

データがロードされると、L<KiokuDB>はロードさえていないオブジェクトへのリファレンスを
キューに入れて、オブジェクトグラフをメモリに常駐させるために、それらをロードします。

=begin original

If you're curious about why the data is represented this way, this format is
called C<JSPON>, or JavaScript Persistent Object Notation
(L<http://www.jspon.org/>). When using L<KiokuDB::Backend::Storable> the
L<KiokuDB::Entry> and L<KiokuDB::Reference> objects are serialized with their
storable hooks instead.

=end original

データがこのような方法で表現されている理由について知りたければ、
このフォーマットは、C<JPSON>か JavaScript Persistent Object notation(L<http://www.jpson.org>)と呼ばれています。
L<KiokuDB::Backend::Storable>を使うと、L<KiokuDB::Entry>とL<KiokuDB::Reference>オブジェクトは、
代わりに、storableフックでシリアライズされます。

=head1 OBJECT SETS

(オブジェクトセット)

=begin original

More complex relationships (not necessarily 1 to 1) are fairly easy to model
with L<Set::Object>.

=end original

より複雑なリレーションシップ(1対1に限らない)は、L<Set::Object>でかなり簡単にモデル化できます。

=begin original

Let's extend the C<Person> class to add such a relationship:

=end original

C<Person>クラスを拡張してそのようなリレーションシップを足してみましょう:

    package Person;

    has children => (
        does => "KiokuDB::Set",
        is   => "rw",
    );

=begin original

L<KiokuDB::Set> objects are L<KiokuDB> specific wrappers for L<Set::Object>.

=end original

L<KiokuDB::Set>オブジェクトは、L<Set::Object>のL<KiokuDB>用のラッパーです。


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

=begin original

The C<set> convenience function creates a new L<KiokuDB::Set::Transient>
object. A transient set is one which started its life in memory space.

=end original

C<set>という便利な関数は新しいL<KiokuDB::Set::Transient>オブジェクトを作ります。
一時的なセットはメモリスペースに存在するものです。

=begin original

The C<weak_set> convenience function also exists, creating a transient set with
L<Set::Object::Weak> used internally to help avoid circular structures (for
instance if setting a C<parent> attribute in our example).

=end original

C<weak_set>という便利な関数もあります。
循環構造(例えば、今の例にC<parent>属性を追加する)を避けるために内部で使われている、
L<Set::Object::Weak>で一時的なセットを作ります。

=begin original

The set object behaves pretty much like a normal L<Set::Object>:

=end original

このオブジェクトは普通のL<Set::Object>とほとんど同じように振る舞います。

    my @kids = $dir->lookup($homer_id)->children->members;

=begin original

The main difference is that sets coming from the database are deferred by
default, that is the objects in C<@kids> are not loaded until they are actually
needed.

=end original

主な違いは、セットがデータベースから来るのがデフォルトで遅延されていることです。
C<@kids>にあるオブジェクトは、実際に必要になるときまでロードされません。

=begin original

This allows large object graphs to exist in the database, while only being
partially loaded, without breaking the encapsulation of user objects. This
behavior is implemented in L<KiokuDB::Set::Deferred> and
L<KiokuDB::Set::Loaded>.

=end original

このことにより、ユーザーのオブジェクトのカプセル化を壊すこと無しに、
部分的にロードされるので、データベースに巨大なオブジェクトグラフがあっても問題になりません。
この振る舞いはL<KiokuDB::Set::Deffered>とL<KiokuDB::Set::Loaded>で実装されています。

=begin original

This set object is optimized to make most operations defer loading. For
instance, if you intersect two deferred sets, only the members of the
intersection set will need to be loaded.

=end original

このセットオブジェクトは、遅延ロードの操作に最適化されています。
例えば、2つの遅延セットを横断するなら、横断するセットのみがロードされる必要があります。

=head1 THE TYPEMAP

=begin original

Storing an object with L<KiokuDB> involves passing it to L<KiokuDB::Collapser>,
the object that "flattens" objects into L<KiokuDB::Entry> before the entries
are inserted into the backend.

=end original

L<KiokuDB>にオブジェクトが保存される際に、L<KiokuDB::Collapser>を通過します。
エントリーがバックエンドにインサートされる前に、L<KiokuDB::Entry>に、
"平たく"されたオブジェクトを入れます。

=begin original

The collapser uses a L<KiokuDB::TypeMap> object that tells it how objects of
each type should be collapsed.

=end original

collapserには、L<KiokuDB::TypeMap>オブジェクトを使います。このオブジェクトは、
それぞれのタイプのオブジェクトがどのように破壊するかを教えます。

=begin original

During retrieval of objects the same typemap is used to reinflate objects back
into working objects.

=end original

オブジェクトを取ってくる間、オブジェクトを再インフレートして、
ワーキングオブジェクトにするのに、同じtypemapが使われます。

=begin original

Trying to store an object that is not in the typemap is an error. The reason
behind this is that many objects depend on runtime states (for instance C<DBI>
handles need a socket, objects based on XS modules have an internal pointer as
an integer), and even though the majority of objects are safe to serialize,
even a small bit of unreported fragility is usually enough to create large,
hard to debug problems.

=end original

typemapにないオブジェクトを保存しようとするとエラーになります。
ランタイムの状態に依存する多くのオブジェクトがあるためです(例えば、C<DBI>はソケット、オブジェクト。
XSベースのモジュールは数値のような内部的なポインタを持ちます)。
大半のオブジェクトは安全にシリアライズできるにもかかわらず、
わずかな報告されないもろさが、大きなデバッグの難しい問題を作るのはありがちなことです。

=begin original

An exception to this rule is L<Moose> based objects, because they have
sufficient meta information available through L<Moose>'s powerful reflection
support in order to be safely serialized.

=end original

このルールの例外は、L<Moose>ベースのオブジェクトです。L<Moose>の強大な
リフレクションサポートを通して、十分なメタ情報が利用できるので、
安全にシリアライズ出来ます。

=begin original

Additionally, the standard backends provide a default typemap for common
objects (L<DateTime>, L<Path::Class>, etc), which by default is merged with any
custom typemap you pass to L<KiokuDB>.

=end original

加えて、標準のバックエンドは共通のオブジェクト(L<DateTime>, L<Path::Class>など>)用に
デフォルトのtypemapを提供しています。L<KiokuDB>にどんなカスタムのtypemapが渡されても、
デフォルトとマージされます。

=begin original

So, in order to actually get L<KiokuDB> to store things like L<Class::Accessor>
based objects, you can do something like this:

=end original

それで、実際にL<KiokuDB>にL<Class::Accessor>ベースのオブジェクトのようなものを保存させるには、
次のようにします:

    my $dir = KiokuDB->new(
        backend => $backend,
        typemap => KiokuDB::TypeMap->new(
            entries => {
                "My::Object" => KiokuDB::TypeMap::Entry::Naive->new,
            },
        ),
    );

=begin original

L<KiokuDB::TypeMap::Entry::Naive> is a type map entry that performs naive
collapsing of the object, by simply walking it recursively.

=end original

L<KiokuDB::TypeMap::Entry::Naive>は単純に再帰的にたどることで、
オブジェクトのナイーブな破壊を行います。

=begin original

When the collapser encounters an object it will ask
L<KiokuDB::TypeMap::Resolver> for a collapsing routine based on the class of
the object.

=end original

collapser は、オブジェクトを見つけると、L<KiokuDB::TypeMap::Resolver>に、
オブジェクトのクラスに応じた、破壊ルーチンを尋ねます。

=begin original

This lookup is typically performed by C<ref $object>, not using inheritance,
because a typemap entry that is safe to use with a superclass isn't necessarily
safe to use with a subclass. If you B<do> want inherited entries, specify
C<isa_entries>:

=end original

この検索は、典型的には、C<ref $object>で行われ、継承を使いません。
スーパークラスで安全に使われているtypemapエントリーは、
必ずしもサブクラスで安全に使えるとは限らないからです。
継承されたエントリーにB<したい>なら、C<isa_entries>を指定してください。

    KiokuDB::TypeMap->new(
        isa_entries => {
            "My::Object" => KiokuDB::TypeMap::Entry::Naive->new,
        },
    );

=begin original

If no normal (C<ref> keyed) entry is found for an object, the isa entries are
searched for a superclass of that object. Subclass entries are tried before
superclass entries. The result of this lookup is cached, so it only happens
once per class.

=end original

オブジェクトに通常の(C<ref> keyed)エントリーが見つからなければ、
isaエントリーがオブジェクトスーパークラスのために探されます。
サブクラスエントリーはスーパークラスエントリーより前に試されます。
この検索の結果はキャッシュされるので、クラスごとに一回しか起こりません。

=head2 Typemap Entries

=begin original

If you want to do custom serialization hooks, you can specify hooks to collapse
your object:

=end original

カスタムのシリアライズのフックが欲しければ、自分のオブジェクトを破壊するための
フックを指定できます。


    KiokuDB::TypeMap::Entry::Callback->new(
        collapse => sub {
            my $object = shift;

            ...

            return @some_args;
        },
        expand => sub {
            my ( $class, @some_args ) = @_;

            ...

            return $object;
        },
    );

=begin original

These hooks are called as methods on the object to be collapsed.

=end original

これらのフックはオブジェクトを破壊するときに、メソッドとして呼ばれます。

=begin original

For instance the L<Path::Class> related typemap ISA entry is:

=end original

例えば、typemapのISAに関連するL<Path::Class>は:

    'Path::Class::Entity' => KiokuDB::TypeMap::Entry::Callback->new(
        intrinsic => 1,
        collapse  => "stringify",
        expand    => "new",
    );

=begin original

The C<intrinsic> flag is discussed in the next section.

=end original

C<intrinsic>フラグは次のセクションで述べます。

=begin original

Another option for typemap entries is L<KiokuDB::TypeMap::Entry::Passthrough>,
which is appropriate when you know the backend's serialization can handle that
data type natively.

=end original

typemapエントリのもう一つの選択はL<KiokuDB::Typemap::Entry::Passthrough>です。
バックエンドのシリアライズがネイティブにデータタイプを扱うことができると分かっていれば、
これは適切です。

=begin original

For example, if your object has a L<Storable> hook which you know is
appropriate (e.g. contains no sub objects that need to be collapsible) and your
backend uses L<KiokuDB::Backend::Serialize::Storable>. L<DateTime> is an
example of a class with such storable hopes:

=end original

例えば、オブジェクトに適切なL<Storable>フックがあり(破壊する必要のあるサブオブジェクトを含まない)、
バックエンドには、L<KiokuDB::Backend::Serialize::Storable>を使う場合です。
L<DateTime>はそのようにstorableが望むクラスの例です:

    'DateTime' => KiokuDB::Backend::Entry::Passthrough->new( intrinsic => 1 )

=head2 Intrinsic vs. First Class

=begin original

In L<KiokuDB> every object is normally assigned an ID, and if the object is
shared by several objects this relationship will be preserved.

=end original

L<KiokuDB>では、すべてのオブジェクトに、通常、IDが割り当てられます。
オブジェクトが複数のオブジェクトに共有されている場合、このリレーションは維持されます。

=begin original

However, for some objects this is not the desired behavior. These are objects
that represent values, like L<DateTime>, L<Path::Class> entries, L<URI>
objects, etc.

=end original

しかし、いくつかのオブジェクトは望ましい振る舞いをしません。
それらは、L<DateTime>や、L<Path::Class>エントリ、L<URI>オブジェクトのようなもので、
値を表現します。

=begin original

L<KiokuDB> can be asked to collapse such objects B<intrinsicly>, that is
instead of creating a new L<KiokuDB::Entry> with its own ID for the object, the
object gets collapsed directly into its parent's structures.

=end original

L<KiokuDB>はB<intrinsicly>に、そのようなオブジェクトを、
そのオブジェクトにそれ自身のIDと新しいL<KiokuDB::Entry>を作る代わりに、
破壊するよう要求できます。オブジェクトが直接破壊できれば、親の構造の中に入ります。

=begin original

This means that shared references that are collapsed intrinsically will be
loaded back from the database as two distinct copies, so updates to one will
not affect the other.

=end original

破壊され、共有されたリファレンスは、もともと2つの区別されたコピーとして
データーベースからロードされます。ですので、一つをアップデートしても、
もう一方には影響がありません。

=begin original

For instance, when we run the following code:

=end original

例えば、下記のようなコードを動かしたとして:

    use Path::Class;

    my $path = file(qw(path to foo));

    $obj_1->file($path);

    $obj_2->file($path);

    $dir->store( $obj_1, $obj_2 );

=begin original

While the following is true when the data is being inserted, it will no longer
be true when C<$obj_1> and C<$obj_2> are loaded from the database:

=end original

データがインサートされるときには、下記は真ですが、
C<$obj_1>とC<$obj_2>がデーターベースからロードされると、もはや真ではありません:

    refaddr($obj_1->file) == refaddr($obj_2->file)

=begin original

This is because both C<$obj_1> and C<$obj_2> each got its own copy of C<$path>.

=end original

C<$obj_1>とC<$obj_2>の両方がC<$path>のコピーだからです。

=begin original

This behavior is usually more appropriate for objects that aren't mutated, but
are instead cloned and replaced, and for which creating a first class entry in
the backend with its own ID is undesired.

=end original

この現象は、通常、変異されず、複製されたり置き換えられたりするオブジェクトに適しています。
そのようなオブジェクトのためには、最初のクラスエントリが独自のIDでバックエンドに作られるのは、
望まれていないからです。

=head2 The Default Typemap

=begin original

Each backend comes with a default typemap, with some built in entries for
common CPAN modules' objects. L<KiokuDB::TypeMap::Default> contains more
details.

=end original

それぞれのバックエンドには、デフォルトのtypemapがついています。
それには、共通のCPANモジュールオブジェクトのために、いくつか共通のビルトインのエントリもあります。
L<KiokuDB::TypeMap::Default>により詳細があります。

=head1 SIMPLE SEARCHES

(単純な検索)

=begin original

Most backends support an inefficient but convenient simple search, which scans
the entries and matches fields.

=end original

ほとんどのバックエンドが効率的ではないものの、便利な単純な検索があります。
ろえは、エントリをスキャンして、フィールドにマッチさせます。

=begin original

If you want to make use of this API we suggest using L<KiokuDB::Backend::DBI>
since simple searching is implemented using an SQL where clause, which is much
more efficient (you do have to set up the column manually though).

=end original

このAPIを使いたいなら、L<KiokuDB::Backend::DBI>を使うことをおすすめします。
単純亜検索はSQLのwhere節を使って実装でき、より効率的だからです。
(ただし、手でカラムをセットアップしないといけませんが)

=begin original

Calling the C<search> method with a hash reference as the only argument invokes
the simple search functionality, returning a L<Data::Stream::Bulk> with the
results:

=end original

C<search>メソッドに引数としてハッシュリファレンスのみを渡して呼びます。
単純な検索機能が呼び出され、L<Data::Stream::Bulk>が結果と一緒に戻ってきます:

    my $stream = $dir->search({ name => "Homer Simpson" });

    while ( my $block = $stream->next ) {
        foreach my $object ( @$block ) {
            # $object->name eq "Homer Simpson"
       }
    }

=begin original

This exact API is intentionally still underdefined. In the future it will be
compatible with L<DBIx::Class> 0.09's syntax.

=end original

正確なAPIはまだ決められていません。将来的に、L<DBIx::Class> 0.09のシンタックスと
互換にするつもりです。

=head2 DBI SEARCH COLUMNS

=begin original

In order to make use of the simple search API we need to configure columns for
our DBI backend.

=end original

この簡単な検索APIを使うには、DBIバックエンドにカラムを設定しなければいけません。

=begin original

Let's create a 'name' column to search by:

=end original

検索するために、'name'カラムを作りましょう:

    my $dir = KiokuDB->connect(
        "dbi:SQLite:dbname=foo",
        columns => [
            # specify extra columns for the 'entries' table
            # in the same format you pass to DBIC's add_columns

            name => {
                data_type => "varchar",
                is_nullable => 1, # probably important
            },
        ],
    );

=begin original

You can either alter the schema manually, or use C<kioku dump> to back up your
data, delete the database, connect with C<< create => 1 >> and then use
C<kioku load>.

=end original

スキーマを手で変更することもできますし、また、データをバックアップするのに、C<kioku dump>を使い、
データベースを削除し、C<< create => 1 >>で接続し、C<kioku load>を使うことも出来ます。

=begin original

To populate this column we'll need to load Homer and update him:

=end original

このカラムを埋め込むために、Homerをロードして、更新する必要があります:

    {
        my $s = $dir->new_scope;
        $dir->update( $dir->lookup( $homer_id ) );
    }

=begin original

And this is what it looks in the database:

=end original

データベースでは次のようになります:

       id = 201C5B55-E759-492F-8F20-A529C7C02C8B
     name = Homer Simpson

=head1 GETTING STARTED WITH BDB

(BDBを始めよう)

=begin original

The most mature backend for L<KiokuDB> is L<KiokuDB::Backend::BDB>. It performs
very well, and supports many features, like L<Search::GIN> integration to
provide customized indexing of your objects and transactions.

=end original

L<KiokuDB>でもっとも成熟したバックエンドは、L<KiokuDB::Backend::DBD>です(訳注:DBIのほうが安定しているとYAPC::Asia 2009で聞きました)。
十分に動きますし、多くの機能をサポートします。
オブジェクトのインデックスのカスタマイズやトランザクションを提供する
L<Search::GIN>のようなインテグレーションもあります。

=begin original

L<KiokuDB::Backend::DBI> is newer and not as tested, but also supports
transactions and L<Search::GIN> based queries. It performs quite well too, but
isn't as fast as L<KiokuDB::Backend::BDB>.

=end original

L<KiokuDB::Backend::DBI>はより新しいですが、そこまでテストされていません。
ですが、トランザクションもサポートしますし、クエリベースのL<Search::GIN>もあります。
これも、なかなかよく動きます。ですが、L<KiokuDB::Backend::BDB>と同じくらい速くはありません
(訳注:YAPC::Asia 2009では、ほぼ変わらないと聞きました)

=head2 Installing L<KiokuDB::Backend::BDB>

=begin original

L<KiokuDB::Backend::BDB> needs the L<BerkeleyDB> module, and a recent version
of Berkeley DB itself, which can be found here:
L<http://www.oracle.com/technology/software/products/berkeley-db/db/index.html>.

=end original

L<KiokuDB::Backend::BDB>は、L<BerkeleyDB>モジュールが必要です。
また、最近のバージョンのBerkeley DB自身も必要です。Berkeley DBは、以下のURLにあります。
L<http://www.oracle.com/technology/software/products/berkeley-db/db/index.html>.

=begin original

BerkeleyDB (the library) normally installs into C</usr/local/BerkeleyDB.4.7>,
while L<BerkeleyDB> (the module) looks for it in C</usr/local/BerkeleyDB>, so
adding a symbolic link should make installation easy.

=end original

BerkeleyDB(ライブラリ)は通常、C</usr/local/BerkeleyDB.4.7>にインストールされます。
ですが、L<BerkeleyDB>(モジュール)は、C</usr/local/BerkeleyDB>を見ようとします。
ですので、シンボリックリンクを作っておけば、インストールが簡単になります。

=begin original

Once you have L<BerkeleyDB> installed, L<KiokuDB::Backend::BDB> should install
without problem and you can use it with L<KiokuDB>.

=end original

L<BerkeleyDB>がインストールできれば、L<KiokuDB::Backend::BDB>は問題なくインストールできるはずです。
L<KiokuDB>と一緒に使うことができます。

=head2 Using L<KiokuDB::Backend::BDB>

=begin original

To use the BDB backend we must first create the storage. To do this the
C<create> flag must be passed:

=end original

BDBバックエンドを使うために、ストレージを作らなければいけません。
このために、C<create>フラグを渡さなければいけません。

    my $backend = KiokuDB::Backend::BDB->new(
        manager => {
            home   => Path::Class::Dir->new(qw(path to storage)),
            create => 1,
        },
    );

=begin original

The BDB backend uses L<BerkeleyDB::Manager> to do a lot of the L<BerkeleyDB>
gruntwork. The L<BerkeleyDB::Manager> object will be instantiated using the
arguments provided in the C<manager> attribute.

=end original

BDBバックエンドは、L<BerkeleyDB::Manager>を使って、たくさんのL<BerkeleyDB>の下働きを行います。
L<BerkeleyDB::Manager>オブジェクトはC<manager>属性で提供される引数を使って、インスタンス化されます。

=begin original

Now that the storage is created we can make use of this backend, much like before:

=end original

これで、ストレージがつくられました。このバックエンドを、以前と同様に使います。

    my $dir = KiokuDB->new( backend => $backend );

=begin original

Subsequent opens will not require the C<create> argument to be true, but it
doesn't hurt.

=end original

その後のオープンには、C<create>属性が真である必要はありませんが、真であっても特に害はありません。

=begin original

This C<connect> call is equivalent to the above:

=end original

このC<connect>は上記のものと同じです:

    my $dir = KiokuDB->connect( "bdb:dir=path/to/storage", create => 1 );

=head1 TRANSACTIONS

(トランザクション)

=begin original

Some backends (ones which do the L<KiokuDB::Backend::Role::TXN> role) can be used
with transactions.

=end original

いくつかのバックエンド(L<KiokuDB::Backend::Role::TXN>ロールをするもの)は、トランザクションが使えるものがあります。

=begin original

If you are familiar with L<DBIx::Class> this should be very familiar:

=end original

L<DBIx::Class>に慣れているなら、すぐわかるでしょう:

    $dir->txn_do(sub {
        $dir->store($obj);
    });

=begin original

This will create a L<BerkeleyDB> level transaction, and all changes to the
database are committed if the block was executed cleanly.

=end original

L<BerkeleyDB>レベルのトランザクションを作ります。データベースへのすべての変更は
ブロックが綺麗に実行されたら、コミットされます。

=begin original

If any error occurred the transaction will be rolled back, and the changes will
not be visible to subsequent reads.

=end original

何らかのエラーが起きれば、トランザクションはロールバックされます。
変更は次の読み込みでは、見えません。

=begin original

Note that L<KiokuDB> does B<not> touch live instances, so if you do something
like

=end original

L<KiokuDB>生きているインスタンスには触れません。ですので、次のようにすると

    $dir->txn_do(sub {
        my $scope = $dir->new_scope;

        $obj->name("Dancing Hippy");
        $dir->store($obj);

        die "an error";
    });

=begin original

the C<name> attribute is B<not> rolled back, it is simply the C<store>
operation that gets reverted.

=end original

C<name>属性はロールバックB<されません>。C<store>オペレーションだけが、元に戻ります。

=begin original

Transactions will nest properly, and with most backends they generally increase
write performance as well.

=end original

トランザクションは適切にネストできます。また、ほとんどのバックエンドで、一般的に
書き込みのパフォーマンスが良くなります。

=head1 QUERIES

(クエリ)

=begin original

L<KiokuDB::Backend::BDB::GIN> is a subclass of L<KiokuDB::Backend::BDB> that
provides L<Search::GIN> integration.

=end original

L<KiokuDB::Backend::BDB::GIN>はL<KiokuDB::Backend::BDB>のサブクラスで、
L<Serach::GIN>インテグレーションを提供しています。

=begin original

L<Search::GIN> is a framework to index and query objects, inspired by Postgres'
internal GIN api. GIN stands for Generalized Inverted Indexes.

=end original

L<Search::GIN>はインデックスとクエリーオブジェクトのフレームワークです。
Postgresの内部GIN apiにインスパイアされました。
GINは、Generalized Inverted Indexes(訳注:汎用転置索引)の略です。

=begin original

Using L<Search::GIN> arbitrary search keys can be indexed for your objects, and
these objects can then be looked up using queries.

=end original

L<Search::GIN>を使うと、任意の検索キーをオブジェクトにタイしてインデックスできます。
そして、それらのオブジェクトをクエリで検索できます。

=begin original

For instance, one of the pre canned searches L<Search::GIN> supports out of the
box is class indexing. Let's use L<Search::GIN::Extract::Callback> to do custom
indexing of our objects:

=end original

例えば、L<Search::GIN>がサポートする、すぐに使える、予めある検索の一つに、クラスインデックスがあります。
L<Search::GIN::Extract::Callback> を使って、オブジェクトにカスタムのインデックスを作りましょう:

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

=begin original

To look up the objects, we use the a manual key lookup query:

=end original

オブジェクトを検索するために、マニュアルキー検索クエリを使います:

    my $query = Search::GIN::Query::Manual->new(
        values => {
            type => "person",
        },
    );

    my $stream = $dir->search($query);

=begin original

The result is L<Data::Stream::Bulk> object that represents the search results.
It can be iterated as follows:

=end original

結果として、検索結果を表すL<Data::Stream::Bulk>オブジェクトが返ります。
次のようにイテレートできます。

    while ( my $block = $stream->next ) {
        foreach my $person ( @$block ) {
            print "found a person: ", $person->name;
        }
    }

=begin original

Or even more simply, if you don't mind loading the whole resultset into memory:

=end original

また、より単純に、メモリに全結果をロードしてもかまわないなら:

    my @people = $stream->all;

=begin original

L<Search::GIN> is very much in its infancy, and is very under documented.
However it does work for simple searches such as this and contains pre canned
solutions like L<Search::GIN::Extract::Class>.

=end original

L<Search::GIN>はまだ未成熟です。ドキュメントも書いているところです。
ですが、このような単純な検索は動きますし、L<Search::GIN::Extract::Class>のような
予めある解決を含んでいます。

=begin original

In short, it works today, but watch this space for new developments.

=end original

つまり、現在は動きますが、新しく開発をするときには、これに注意してください。

=head1 翻訳について

翻訳者：加藤敦 (ktat@cpan.org)

Perlドキュメント日本語訳 Project にて、
Perlモジュール、ドキュメントの翻訳を行っております。

 http://perldocjp.sourceforge.jp/
 http://sourceforge.jp/projects/perldocjp/
 http://www.freeml.com/ctrl/html/MLInfoForm/perldocjp@freeml.com
 http://www.perldoc.jp/