lib/ZOOM.pod

   1 # $Id: ZOOM.pod,v 1.4 2005-11-16 14:54:43 mike Exp $
   2
   3 use strict;
   4 use warnings;
   5
   6 =head1 NAME
   7
   8 ZOOM - Perl extension implementing the ZOOM API for Information Retrieval
   9
  10 =head1 SYNOPSIS
  11
  12  use ZOOM;
  13  eval {
  14      $conn = new ZOOM::Connection($host, $port)
  15      $conn->option(preferredRecordSyntax => "usmarc");
  16      $rs = $conn->search_pqf('@attr 1=4 dinosaur');
  17      $n = $rs->size();
  18      print $rs->record(0)->render();
  19  };
  20  if ($@) {
  21      print "Error ", $@->code(), ": ", $@->message(), "\n";
  22  }
  23
  24 =head1 DESCRIPTION
  25
  26 This module provides a nice, Perlish implementation of the ZOOM
  27 Abstract API described and documented at http://zoom.z3950.org/api/
  28
  29 the ZOOM module is implemented as a set of thin classes on top of the
  30 non-OO functions provided by this distribution's C<Net::Z3950::ZOOM>
  31 module, which in
  32 turn is a thin layer on top of the ZOOM-C code supplied as part of
  33 Index Data's YAZ Toolkit.  Because ZOOM-C is also the underlying code
  34 that implements ZOOM bindings in C++, Visual Basic, Scheme, Ruby, .NET
  35 (including C#) and other languages, this Perl module works compatibly
  36 with those other implementations.  (Of course, the point of a public
  37 API such as ZOOM is that all implementations should be compatible
  38 anyway; but knowing that the same code is running is reassuring.)
  39
  40 The ZOOM module provides two enumerations (C<ZOOM::Error> and
  41 C<ZOOM::Event>), a single utility function C<diag_str()> in the C<ZOOM>
  42 package itself, and eight classes:
  43 C<ZOOM::Exception>,
  44 C<ZOOM::Options>,
  45 C<ZOOM::Connection>,
  46 C<ZOOM::Query>,
  47 C<ZOOM::ResultSet>,
  48 C<ZOOM::Record>,
  49 C<ZOOM::ScanSet>
  50 and
  51 C<ZOOM::Package>.
  52 Of these, the Query class is abstract, and has two concrete
  53 subclasses:
  54 C<ZOOM::Query::CQL>
  55 and
  56 C<ZOOM::Query::PQF>.
  57 Many useful ZOOM applications can be built using only the Connection,
  58 ResultSet, Record and Exception classes, as in the example
  59 code-snippet above.
  60
  61 A typical application will begin by creating an Connection object,
  62 then using that to execute searches that yield ResultSet objects, then
  63 fetching records from the result-sets to yield Record objects.  If an
  64 error occurs, an Exception object is thrown and can be dealt with.
  65
  66 More sophisticated applications might also browse the server's indexes
  67 to create a ScanSet, from which indexed terms may be retrieved; others
  68 might send ``Extended Services'' Packages to the server, to achieve
  69 non-standard tasks such as database creation and record update.
  70 Searching using a query syntax other than PQF can be done using an
  71 query object of one of the Query subclasses.  Finally, sets of options
  72 may be manipulated independently of the objects they are associated
  73 with using an Options object.
  74
  75 In general, method calls throw an exception if anything goes wrong, so
  76 you don't need to test for success after each call.  See the section
  77 below on the Exception class for details.
  78
  79 =head1 UTILITY FUNCTION
  80
  81 =head2 ZOOM::diag_str()
  82
  83  $msg = ZOOM::diag_str(ZOOM::Error::INVALID_QUERY);
  84
  85 Returns a human-readable English-language string corresponding to the
  86 error code that is its own parameter.  This works for any error-code
  87 returned from
  88 C<ZOOM::Exception::code()>,
  89 C<ZOOM::Connection::error_x()>
  90 or
  91 C<ZOOM::Connection::errcode()>,
  92 irrespective of whether it is a member of the C<ZOOM::Error>
  93 enumeration or drawn from the BIB-1 diagnostic set.
  94
  95 =head1 CLASSES
  96
  97 The eight ZOOM classes are described here in ``sensible order'':
  98 first, the four commonly used classes, in the he order that they will
  99 tend to be used in most programs (Connection, ResultSet, Record,
 100 Exception); then the four more esoteric classes in descending order of
 101 how often they are needed.
 102
 103 With the exception of the Options class, which is an extension to the
 104 ZOOM model, the introduction to each class includes a link to the
 105 relevant section of the ZOOM Abstract API.
 106
 107 =head2 ZOOM::Connection
 108
 109  $conn = new ZOOM::Connection("indexdata.dk:210/gils");
 110  print("server is '", $conn->option("serverImplementationName"), "'\n");
 111  $conn->option(preferredRecordSyntax => "usmarc");
 112  $conn->option_binary(iconBlob => "foo\0bar");
 113  $rs = $conn->search_pqf('@attr 1=4 mineral');
 114  $ss = $conn->scan('@attr 1=1003 a');
 115  if ($conn->errcode() != 0) {
 116     die("somthing went wrong: " . $conn->errmsg())
 117  }
 118  $conn->destroy()
 119
 120 This class represents a connection to an information retrieval server,
 121 using an IR protocol such as ANSI/NISO Z39.50, SRW (the
 122 Search/Retrieve Webservice), SRU (the Search/Retrieve URL) or
 123 OpenSearch.  Not all of these protocols require a low-level connection
 124 to be maintained, but the Connection object nevertheless provides a
 125 location for the necessary cache of configuration and state
 126 information, as well as a uniform API to the connection-oriented
 127 facilities (searching, index browsing, etc.), provided by these
 128 protocols.
 129
 130 See the description of the C<Connection> class in the ZOOM Abstract
 131 API at
 132 http://zoom.z3950.org/api/zoom-current.html#3.2
 133
 134 =head3 Methods
 135
 136 =head4 new()
 137
 138  $conn = new ZOOM::Connection("indexdata.dk", 210);
 139  $conn = new ZOOM::Connection("indexdata.dk/gils:210");
 140  $conn = new ZOOM::Connection("tcp:indexdata.dk/gils:210");
 141  $conn = new ZOOM::Connection("http:indexdata.dk/gils:210");
 142
 143 I<###>
 144
 145 create
 146 connect
 147 error_x
 148 errcode
 149 errmsg
 150 addinfo
 151 option
 152 option_binary
 153 search
 154 search_pqf
 155 scan
 156 package
 157 destroy
 158
 159 =head2 ZOOM::ResultSet
 160
 161 I<###>
 162
 163 =head2 ZOOM::Record
 164
 165 I<###>
 166
 167 =head2 ZOOM::Exception
 168
 169 In general, method calls throw an exception (of class
 170 C<ZOOM::Exception>) if anything goes wrong, so you don't need to test
 171 for success after each call.  Exceptions are caught by enclosing the
 172 main code in an C<eval{}> block and checking C<$@> on exit from that
 173 block, as in the code-sample above.
 174
 175 There are a small number of exceptions to this rule.
 176 I<###>
 177
 178 =head2 ZOOM::ScanSet
 179
 180 I<###>
 181
 182 =head2 ZOOM::Package
 183
 184 I<###>
 185
 186 =head2 ZOOM::Query
 187
 188 I<###>
 189
 190 =head2 ZOOM::Options
 191
 192 I<###>
 193
 194 =head1 ENUMERATIONS
 195
 196 The ZOOM module provides two enumerations that list possible return
 197 values from particular functions.  They are described in the following
 198 sections.
 199
 200 =head2 ZOOM::Error
 201
 202  if ($@->code() == ZOOM::Error::QUERY_PQF) {
 203      return "your query was not accepted";
 204  }
 205
 206 This class provides a set of manifest constants representing some of
 207 the possible error codes that can be raised by the ZOOM module.  The
 208 methods that return error-codes are
 209 C<ZOOM::Exception::code()>,
 210 C<ZOOM::Connection::error_x()>
 211 and
 212 C<ZOOM::Connection::errcode()>.
 213
 214 The C<ZOOM::Error> class provides the constants
 215 C<NONE>,
 216 C<CONNECT>,
 217 C<MEMORY>,
 218 C<ENCODE>,
 219 C<DECODE>,
 220 C<CONNECTION_LOST>,
 221 C<INIT>,
 222 C<INTERNAL>,
 223 C<TIMEOUT>,
 224 C<UNSUPPORTED_PROTOCOL>,
 225 C<UNSUPPORTED_QUERY>,
 226 C<INVALID_QUERY>,
 227 C<CREATE_QUERY>,
 228 C<QUERY_CQL>,
 229 C<QUERY_PQF>,
 230 C<SORTBY>,
 231 C<CLONE>
 232 and
 233 C<PACKAGE>,
 234 each of which specifies a client-side error.  Since errors may also be
 235 diagnosed by the server, and returned to the client, error codes may
 236 also take values from the BIB-1 diagnostic set of Z39.50, listed at
 237 the Z39.50 Maintenance Agency's web-site at
 238 http://www.loc.gov/z3950/agency/defns/bib1diag.html
 239
 240 All error-codes, whether client-side from the C<ZOOM::Error>
 241 enumeration or server-side from the BIB-1 diagnostic set, can be
 242 translated into human-readable messages by passing them to the
 243 C<ZOOM::diag_str()> utility function.
 244
 245 =head2 ZOOM::Event
 246
 247  if ($conn->last_event() == ZOOM::Event::CONNECT) {
 248      print "Connected!\n";
 249  }
 250
 251 In applications that need it - mostly complex multiplexing
 252 applications - The C<ZOOM::Connection::last_event()> method is used to
 253 return an indication of the last event that occurred on a particular
 254 connection.  It always returns a value drawn from this enumeration,
 255 that is, one of C<NONE>, C<CONNECT>, C<SEND_DATA>, C<RECV_DATA>,
 256 C<TIMEOUT>, C<UNKNOWN>, C<SEND_APDU>, C<RECV_APDU>, C<RECV_RECORD> or
 257 C<RECV_SEARCH>.
 258
 259 You almost certainly don't need to know about this.  Frankly, I'm not
 260 sure how to use it myself.
 261
 262 =head1 SEE ALSO
 263
 264 The ZOOM abstract API,
 265 http://zoom.z3950.org/api/zoom-current.html
 266
 267 The C<Net::Z3950::ZOOM> module, included in the same distribution as this one.
 268
 269 The C<Net::Z3950> module, which this one supersedes.
 270
 271 The BIB-1 diagnostic set of Z39.50,
 272 http://www.loc.gov/z3950/agency/defns/bib1diag.html
 273
 274 =head1 AUTHOR
 275
 276 Mike Taylor, E<lt>mike@indexdata.comE<gt>
 277
 278 =head1 COPYRIGHT AND LICENCE
 279
 280 Copyright (C) 2005 by Index Data.
 281
 282 This library is free software; you can redistribute it and/or modify
 283 it under the same terms as Perl itself, either Perl version 5.8.4 or,
 284 at your option, any later version of Perl 5 you may have available.
 285
 286 =cut
 287
 288 1;