NAME

Tamino::Tran - The Tamino driver's main class wrapping Tamino API.

SYNOPSIS

    use Tamino;
    
    my $tamino_client = Tamino->new(
        server      => '127.0.0.1/tamino'
        db          => 'mydb'
    );
    
    # $t will be a Tamino::Tran object                                 
    my $t = $tamino_client->begin_tran
        or die $tamino_client->error;
        
    $c = $t->xquery(q{for $x in input()/ return $x}) or die $t->error;
    
    $c = $t->xquery_cursor(q{
        for $x in collection('mycollection')/doctype/xxx[@yyy=%s][zzz='%s']
        return $x
    }, "('y1','y2')", "z1") or die $t->error;

    while($xml_bare_simple_tree = $c->fetch) {
        print XML::Simple::XMLout($xml_bare_simple_tree, KeyAttr => []);
    }

    $t->delete(q{for $x in input()/doc[@bad='yes'] return $x}) or die $t->error;

DESCRIPTION

This is just an API wrapper. This driver is based on LWP::UserAgent, XML::Bare, and inherits from Class::Accessor and Class::Data::Inheritable.

CONSTRUCTOR

Constructor is called internally by Tamino class object.

METHODS

connect

    $t->connect or die $t->error;
Starts new transaction session. Transaction is started implicitly by the first DB update action. After this call, all operations are made in transaction context.

disconnect

    $t->disconnect or die $t->error;
Ends transaction session. All uncommitted data is rolled back. After this call, all operations are made in non-transactional context.

commit

    $t->commit or die $t->error;
Commit changes. If you want such thing as autocommit - just don't start transaction session ($t = $tamino_client->begin();)

rollback

    $t->rollback or die $t->error;

Rollback changes.

prepare

    my $stmt = $t->prepare($query, \%vars) or die $t->error;
    my $stmt = $t->prepare(q{for $x in input()/xxx[@yyy=$y][zzz=$z]}, {
        y => 'string',
        z => 'xs:integer'
    }) or die $t->error;
Initializes a prepared statement. The $query is compiled by server, and can be executed later with parameters. Available only with Tamino v4.4+

The \%vars paramter specifies parameter types. Paramter names specified without $ sign.

Returns Tamino::Tran::Prepared object.

xquery

    my $xml = $t->xquery($query_fmt, @args) or die $t->error;
    my $xml = $t->xquery(q{
        for $x in collection('mycollection')/doctype/xxx[@yyy=%s][zzz='%s']
        return $x
    }, "('y1','y2')", "z1") or die $t->error;
    print XML::Simple::XMLout($xml);
Returns XML::Simple-like tree object representing the result of sprintf($query_fmt, @args)-X-Query This sprintf trick is used to avoid interpolation crap, because X-Query uses the same $var-form variables, just like we do. Look at plaintext method if you want to get plain-text XMLs.

xquery_cursor

    my $cursor = $t->xquery_cursor($query_fmt, [\%cursor_opts,] @args) or die $t->error;
The same as "xquery", except that it opens cursor for the X-Query and returns Tamino::Tran::Cursor object.

Pass a HASHREF as 2-nd parameter to specify cursor options, otherwise it will be treated as the first of args cursor_options can be:

scrollable => 1

vague => 1

fetch_size => 1

no_fetch => 1 this tells Tamino server not to fetch-on-open.

For What-This-All-Means read Tamino Documentation.

xql

    my $xml = $t->xql($query_fmt, @args) or die $t->error;
    print XML::Simple::XMLout($xml);
The same as "xquery", except that it uses XQuery, not X-Query. What is the difference? I don't know. Read the documentation for Tamino.

xql_cursor

    my $cursor = $t->xql_cursor($query_fmt, \%cursor_opts, @args) or die $t->error;
The same as "xquery_cursor", except that it uses XQuery, not X-Query. What is the difference? I don't know. Read the documentation for Tamino.

delete

    $t->delete($xquery_fmt, @args) or die $t->error;
Delete documents matching the X-Query. Parameters are the same as for "xquery".

process

    $t->process( [ { name => $name, id => $id, data => \$xml, %options } , ... ], %OPTIONS );
Takes ARRAYREF of documents and submit a PROCESS command, which does the following for each document:

Replaces document if name and/or id specified (the document MUST exists, and name MUST match id). Returns TRUE on success.

Stores new document if neither name nor id was specified. Returns ARRAYREF of HASHREFs of id, name and collection.

data parameter is a scalarref poiting to the [XML] document or an XML::Twig::Elt object.

%options may include:

escape => 1 to specify that data is an not XML string, so it will be escaped.

base64 => 1 to Base64-encode data string.

collection => $my_collection_name to specify where to store documents. You MUST provide this attribute if you haven't pass it into Tamino constructor, otherwise the default "ino:etc" collection will be used.

%OPTIONS may include:

encoding => $enc to specify encoding of DOCUMENTS being processed.

MISC METHODS

error

messages

    print $t->messages; # any messages from server.
    warn $t->error;

forcearray

    $t->forcearray(qw/tag1 tag2/);
    $t->forcearray([qw/tag1 tag2/]);

Force these tags to be represented as an array, even if there is only one.

plaintext

    $t->plaintext($boolean);

If true, all requests that return an XML tree will return a SCALARREF to plain XML data

encoding

    $t->encoding('other_encoding'); # change encoding

TRANSACTION CONTROL METHODS

    $t->isolation_level($level);    
    $t->lock_mode($mode);    
    $t->lock_wait($wait);

Set new transaction options. The same as "begin_tran" in Tamino options.

SUBCLASSING

You can subclass Tamino::Tran. You can tell Tamino::Tran to use subclassed XML::Twig, XML::Twig::Elt, Tamino::Tran::Prepared, Tamino::Tran::Cursor by saying:

    $obj->xml_twig_class("My::XML::Twig");
    $obj->xml_twig_elt_class("My::XML::Twig::Elt");
    
    $obj->prepared_class("My::Tamino::Tran::Prepared");
    $obj->cursor_class("My::Tamino::Tran::Cursor");

where $obj can be an object, so changes are made to that object, or 'Tamino::Tran' - class name, so changes are made class-wide, excepting existing objects.

CPAN RT