perl/lib/IDZebra/Resultset.pm

   1 # $Id: Resultset.pm,v 1.9 2003-03-06 23:32:10 pop Exp $
   2 #
   3 # Zebra perl API header
   4 # =============================================================================
   5 package IDZebra::Resultset;
   6
   7 use strict;
   8 use warnings;
   9
  10 BEGIN {
  11     use IDZebra;
  12     use IDZebra::Logger qw(:flags :calls);
  13     use Scalar::Util qw(weaken);
  14     use Carp;
  15     our $VERSION = do { my @r = (q$Revision: 1.9 $ =~ /\d+/g); sprintf "%d."."%02d" x $#r, @r };
  16     our @ISA = qw(IDZebra::Logger);
  17 }
  18
  19 1;
  20 # -----------------------------------------------------------------------------
  21 # Class constructors, destructor
  22 # -----------------------------------------------------------------------------
  23 sub new {
  24     my ($proto,$session, %args) = @_;
  25     my $class = ref($proto) || $proto;
  26     my $self = {};
  27     bless ($self, $class);
  28
  29     $self->{session} = $session;
  30     weaken ($self->{session});
  31
  32     $self->{odr_stream} = IDZebra::odr_createmem($IDZebra::ODR_DECODE);
  33
  34     $self->{name}        = $args{name};
  35     $self->{recordCount} = $args{recordCount};
  36     $self->{errCode}     = $args{errCode};
  37     $self->{errString}   = $args{errString};
  38
  39     return ($self);
  40 }
  41
  42 sub recordCount {
  43     my ($self) = @_;
  44     return ($self->{recordCount});
  45 }
  46 sub count {
  47     my ($self) = @_;
  48     return ($self->{recordCount});
  49 }
  50
  51 sub errCode {
  52     my ($self) = @_;
  53     return ($self->{errCode});
  54 }
  55
  56 sub errString {
  57     my ($self) = @_;
  58     return ($self->{errCode});
  59 }
  60
  61 # =============================================================================
  62 sub DESTROY {
  63     my $self = shift;
  64
  65 #    print STDERR "Destroy RS\n";
  66     # Deleteresultset?
  67
  68     my $stats = 0;
  69     if ($self->{session}{zh}) {
  70         my $r = IDZebra::deleteResultSet($self->{session}{zh},
  71                                          0, #Z_DeleteRequest_list,
  72                                          1,[$self->{name}],
  73                                          $stats);
  74     }
  75
  76     if ($self->{odr_stream}) {
  77         IDZebra::odr_reset($self->{odr_stream});
  78         IDZebra::odr_destroy($self->{odr_stream});
  79         $self->{odr_stream} = undef;
  80     }
  81
  82     delete($self->{session});
  83 }
  84 # -----------------------------------------------------------------------------
  85 sub records {
  86     my ($self, %args) = @_;
  87
  88     unless ($self->{session}{zh}) {
  89         croak ("Session is closed or out of scope");
  90     }
  91     my $from = $args{from} ? $args{from} : 1;
  92     my $to   = $args{to}   ? $args{to}   : $self->{recordCount};
  93
  94     if (($to-$from) >= 1000) {
  95         if ($args{to}) {
  96             croak ("Cannot fetch more than 1000 records at a time");
  97         } else {
  98             $to = $from + 999;
  99         }
 100     }
 101
 102     my $elementSet   = $args{elementSet}   ? $args{elementSet}    : 'R';
 103     my $schema       = $args{schema}       ? $args{schema}        : '';
 104     my $recordSyntax = $args{recordSyntax} ? $args{recordSyntax}  : '';
 105
 106     my $class        = $args{class}        ? $args{class}         : '';
 107
 108
 109     my $ro = IDZebra::RetrievalObj->new();
 110     IDZebra::records_retrieve($self->{session}{zh},
 111                               $self->{odr_stream},
 112                               $self->{name},
 113                               $elementSet,
 114                               $schema,
 115                               $recordSyntax,
 116                               $from,
 117                               $to,
 118                               $ro);
 119
 120     my @res = ();
 121
 122     for (my $i=$from; $i<=$to; $i++) {
 123         my $rec = IDZebra::RetrievalRecord->new();
 124         IDZebra::record_retrieve($ro, $self->{odr_stream}, $rec, $i-$from+1);
 125         if ($class) {
 126
 127         } else {
 128             push (@res, $rec);
 129         }
 130     }
 131
 132     IDZebra::odr_reset($self->{odr_stream});
 133
 134     return (@res);
 135 }
 136
 137 # ============================================================================
 138 sub sort {
 139     my ($self, $sortspec, $setname) = @_;
 140
 141     unless ($self->{session}{zh}) {
 142         croak ("Session is closed or out of scope");
 143     }
 144
 145     unless ($setname) {
 146         return ($_[0] = $self->{session}->sortResultsets($sortspec,
 147                                                  $self->{session}->_new_setname, ($self)));
 148         return ($_[0]);
 149     } else {
 150         return ($self->{session}->sortResultsets($sortspec,
 151                                                  $setname, ($self)));
 152     }
 153 }
 154
 155 # ============================================================================
 156 __END__
 157
 158 =head1 NAME
 159
 160 IDZebra::Resultset - Representation of Zebra search results
 161
 162 =head1 SYNOPSIS
 163
 164   $count = $rs->count;
 165
 166   printf ("RS Status is %d (%s)\n", $rs->errCode, $rs->errString);
 167
 168   my @recs = $rs->records(from => 1,
 169                           to   => 10);
 170
 171 =head1 DESCRIPTION
 172
 173 The I<Resultset> object represents results of a Zebra search. Contains number of hits, search status, and can be used to sort and retrieve the records.
 174
 175 =head1 PROPERTIES
 176
 177 The folowing properties are available, trough object methods and the object hash reference:
 178
 179 =over 4
 180
 181 =item B<errCode>
 182
 183 The error code returned from search, resulting the Resultset object.
 184
 185 =item B<errString>
 186
 187 The optional error string
 188
 189 =item B<recordCount>
 190
 191 The number of hits (records available) in the resultset
 192
 193 =item B<count>
 194
 195 Just the synonym for I<recordCount>
 196
 197 =back
 198
 199 =head1 RETRIEVING RECORDS
 200
 201 In order to retrieve records, use the I<records> method:
 202
 203   my @recs = $rs->records();
 204
 205 By default this is going to return an array of IDZebra::RetrievalRecord objects. The possible arguments are:
 206
 207 =over 4
 208
 209 =item B<from>
 210
 211 Retrieve records from the given position. The first record corresponds to position 1. If not specified, retrieval starts from the first record.
 212
 213 =item B<to>
 214
 215 The last record position to be fetched. If not specified, all records are going to be fetched, starting from position I<from>.
 216
 217 =item B<elementSet>
 218
 219 The element set used for retrieval. If not specified 'I<R>' is used, which will return the "record" in the original format (ie.: without extraction, just as the original file, or data buffer in the update call).
 220
 221 =item B<schema>
 222
 223 The schema used for retrieval. The default is "".
 224
 225 =item B<recordSyntax>
 226
 227 The record syntax for retrieval. The default is SUTRS.
 228
 229 =back
 230
 231 =head1 SORTING
 232
 233 You can sort resultsets by calling:
 234
 235   $rs1->sort($sort_expr);
 236
 237 or create a new sorted resultset:
 238
 239   $rs2 = $rs1->sort($sort_expr);
 240
 241 The sort expression has the same format as described in the I<yaz_client> documentation. For example:
 242
 243   $rs1->sort('1=4 id');
 244
 245 will sort thr results by title, in a case insensitive way, in descending order, while
 246
 247   $rs1->sort('1=4 a');
 248
 249 will sort ascending by titles.
 250
 251 =head1 COPYRIGHT
 252
 253 Fill in
 254
 255 =head1 AUTHOR
 256
 257 Peter Popovics, pop@technomat.hu
 258
 259 =head1 SEE ALSO
 260
 261 Zebra documentation, IDZebra::ResultSet, IDZebra::RetrievalRecord manpages.
 262
 263 =cut