view release on metacpan or  search on metacpan

lib/Data/TagDB.pm  view on Meta::CPAN

=head1 VERSION

version v0.12

=head1 SYNOPSIS

    use Data::TagDB;

    my $db = Data::TagDB->new($dsn, ...);
    # or:
    my $db = Data::TagDB->new($dbh);

    # Create new database:
    use Data::TagDB::Migration;
    my Data::TagDB $db = Data::TagDB::Migration->create(...);

This module implements SQL based universal tag databases. Such databases can be used to store any kind of (semantic) data.

This module and it's submodule implement creation of databases, migration (to most current scheme),
adding data and reading data from the database.

For an introduction see L<Data::TagDB::Tutorial>.

The instances of L<Data::TagDB::Tag> repesent any kind of object (may it be file, user account or a real life object like a tree).
It provides some convenience functions such as to query objects for their name.

L<Data::TagDB::Factory> (via L</factory>) is provided for easy creation of new tags.

B<Note:>
Correct transaction management can improve performance I<significantly>. Sometimes the improvement can be by a factor of a few thousand.
Applications should therefore consider to group requests into transactions. This is also true for read only requests.

B<Note:>
Future versions of this module will depend on L<Data::Identifier>.

B<Note:>
This module supports SQLite and PostgreSQL (experimental).

=head1 METHODS

=head2 new

    my $db = Data::TagDB->new($dsn, ...);
    # or:
    my $db = Data::TagDB->new($dbh);

Returns a new object that can be used for lookups.
Either an already connected L<DBI> handle can be passed or
data source that is then passed to L<DBI/connect> internally.

If a open handle is passed, the same restrictions apply as for L</dbh>.

=head2 dbh

    my $dbh = $db->dbh;

Returns the current L<DBI> connection.

This connection can be used to call any transaction independent method on the handle.
It can for example be used to call L<DBI/ping> to keep the connection alive.

If methods are called that depend on the state of the transaction logic
(such as performing an SELECT or UPDATE) the state of the transaction B<must> be managed via
this module. See L</begin_work>.

The same holds true for any open handle passed to L</new>. When passed the handle must
not be in any active transaction and must not be used outside this module to change the transaction
state of the handle.

It is also wise to avoid interacting with the tables managed by this module. This may result in the
internal states being in a wrong state. It is however generally safe (but for the restrictions given above)
to interact with tables outside of the use of this module.

As table names that are in use by this module depend on the version of the schema that is currently active
(and may change in future) it is most wise to have any custom tables in a seperate namespace of some kind
(the exact ways to do this may depend on the type of database used).

=head2 disconnect

    $db->disconnect

This disconnects from the database backend. It also renders this object useless.

=head2 tag_by_id

    my Data::TagDB::Tag $tag = $db->tag_by_id($type => $id);
    # or:
    my Data::TagDB::Tag $tag = $db->tag_by_id($hint => $id);
    # or:
    my Data::Identifier $id = ...;
    my Data::TagDB::Tag $tag = $db->tag_by_id($id);
    # e.g:
    my Data::TagDB::Tag $tag = $db->tag_by_id(uuid => 'abc...');

Gets a tag by an an identifier of the provided type. The type must be a C<Data::TagDB::Tag> or a
a string that is a valid hint.

If only argument is provided the argument must be an instance of L<Data::Identifier>.

=head2 tag_by_specification

    my Data::TagDB::Tag $tag = $db->tag_by_specification($specification, style => $style [, %opts ]);

Gets a tag by specification according to a style.
This method is mostly useful to parse user input and find the corresponding tag.

B<Note:>
This method is experimental. It may change prototype, and behaviour or may be removed in future versions without warning.
Role matching depends on L<Data::TagDB::Tag/cloudlet> and is subject to its status.

The following styles are supported:

=over

=item C<ise>

The given specification is an UUID, OID, or URI.

=item C<tagpool>