Tamino::Tran::Cursor - The L<Tamino> driver's class implementing cursors.

    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_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 => []);
    }

    $c->close;

    $c->close;

    $xml = $c->fetch();
    $xml = $c->fetch($num);
    $xml = $c->fetch($num, $pos);

    Tamino::Tran::Cursor->fetch_size($num);
    $c->fetch_size($num);

use strict;

package Tamino::Tran::Cursor;
use base qw/Class::Accessor Class::Data::Inheritable/;

__PACKAGE__->mk_classdata($_) for qw/fetch_size/;
__PACKAGE__->mk_ro_accessors(qw/tran handle scrollable vague result/);
__PACKAGE__->mk_accessors(qw/fetch_size _prefetched _pos error/);

__PACKAGE__->fetch_size(8);

sub new ($@) {
    my $class = shift;
    my %args = @_;
      
    my $data = delete $args{data} or return;
                  
    $class = ref $class || $class;
    my $self = $class->SUPER::new({
        tran        => $args{tran},
        scrollable  => !!$args{scrollable},
        vague       => !!$args{vague},
        fetch_size  => $args{fetch_size} || __PACKAGE__->fetch_size,
        result      => $args{result},
    });
    
    $data->{_cursor} = 'open';
    $data->{_scroll} = $args{scrollable} ? 'yes' : 'no';
    $data->{_sensitive} = $args{vague} ? 'vague' : 'no';
    
    $self->{_pos} = $args{pos} || 1;
    unless($args{no_fetch}) {
        $data->{_position} = $self->{_pos};
        $data->{_quantity} = $self->{fetch_size};
    }
    
    my $q = $self->tran->_cmd($data, result => $self->{result}, _twig_handlers => {
        'ino:cursor' => sub {
            my ($twig,$cur) = @_;
            $self->{handle} = $cur->{'ino:handle'};
            $self->_get_pos($cur);
            1;
        }
    });
    return unless defined $q;
    
    $self->{_prefetched} = $q unless($args{no_fetch});
    return unless($q && $self->{handle});
    return $self;
}

sub close ($) {
    my ($self) = @_;
    if($self->{handle} && defined $self->tran->_cmd({_cursor => 'close', _handle => $self->{handle}})) {
        $self->{handle} = undef;
        return 1;
    }
    return 0;
}

sub fetch ($;$$) {
    my ($self, $n, $pos) = @_;
    if(my $r = $self->{_prefetched}) {
        $self->{_prefetched} = undef;
        return $r;
    }
    return unless defined $self->{_pos};
    return $self->tran->_cmd({
            _cursor => 'fetch',
            _handle => $self->{handle},
            _position => $pos || $self->{_pos},
            _quantity => $n || $self->{fetch_size},
        },
        result => $self->result,
        _twig_handlers => {
            'ino:cursor' => sub {
                my ($twig,$cur) = @_;
                return 1 if($cur->{'ino:handle'} != $self->{handle}); # FIXME
                $self->_get_pos($cur);
                1;
            }
        }
    );
}

sub _get_pos ($$) {
    my ($self, $cur) = @_;
    if(exists $cur->{'ino:next'}) {
        $self->{_pos} = $cur->{'ino:next'}->{'ino:position'};
    } else {
        $self->tran->error("No more data");
        $self->{_pos} = undef;
    }
}

sub DESTROY {
    $_[0]->close;
}

1;