lib/ZOOM.pod

   1 # $Id: ZOOM.pod,v 1.5 2005-11-16 15:36:16 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');/usr/local/src/mike/records/acc-ounts/cheques-
 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:210/gils");
 140  $conn = new ZOOM::Connection("tcp:indexdata.dk:210/gils");
 141  $conn = new ZOOM::Connection("http:indexdata.dk:210/gils");
 142
 143 Creates a new Connection object, and immediately connects it to the
 144 specified server.  If you want to make a new Connection object but
 145 delay forging the connection, use the C<create()> and C<connect()>
 146 methods instead.
 147
 148 This constructor can be called with two arguments or a single
 149 argument.  In the former case, the arguments are the name and port
 150 number of the Z39.50 server to connect to; in the latter case, the
 151 single argument is a YAZ service-specifier string of the form
 152
 153 =over 4
 154
 155 =item
 156
 157 [I<scheme>:]I<host>[:I<port>][/I<databaseName>]
 158
 159 =back
 160
 161 In which the I<host> and I<port> parts are as in the two-argument
 162 form, the I<databaseName> if provided specifies the name of the
 163 database to be used in subsequent searches on this connection, and the
 164 optional I<scheme> (default C<tcp>) indicates what protocol should be
 165 used.  At present, the following schemes are supported:
 166
 167 =over 4
 168
 169 =item tcp
 170
 171 Z39.50 connection.
 172
 173 =item ssl
 174
 175 Z39.50 connection encrypted using SSL (Secure Sockets Layer).  Not
 176 many servers support this, but Index Data's Zebra is one that does.
 177
 178 =item unix
 179
 180 Z39.50 connection on a Unix-domain (local) socket, in which case the
 181 I<hostname> portion of the string is instead used as a filename in the
 182 local filesystem.
 183
 184 =item http
 185
 186 SRW connection using SOAP over HTTP.
 187
 188 =back
 189
 190 Support for SRU will follow in the fullness of time.
 191
 192 =head4 create()
 193
 194 =head4 connect()
 195
 196 =head4 error_x() / errcode() / errmsg() / addinfo()
 197
 198 =head4 option() / option_binary()
 199
 200 =head4 search() / search_pqf()
 201
 202 =head4 scan()
 203
 204 =head4 package()
 205
 206 =head4 destroy()
 207
 208 =head2 ZOOM::ResultSet
 209
 210 I<###>
 211
 212 =head2 ZOOM::Record
 213
 214 I<###>
 215
 216 =head2 ZOOM::Exception
 217
 218 In general, method calls throw an exception (of class
 219 C<ZOOM::Exception>) if anything goes wrong, so you don't need to test
 220 for success after each call.  Exceptions are caught by enclosing the
 221 main code in an C<eval{}> block and checking C<$@> on exit from that
 222 block, as in the code-sample above.
 223
 224 There are a small number of exceptions to this rule.
 225 I<###>
 226
 227 =head2 ZOOM::ScanSet
 228
 229 I<###>
 230
 231 =head2 ZOOM::Package
 232
 233 I<###>
 234
 235 =head2 ZOOM::Query
 236
 237 I<###>
 238
 239 =head2 ZOOM::Options
 240
 241 I<###>
 242
 243 =head1 ENUMERATIONS
 244
 245 The ZOOM module provides two enumerations that list possible return
 246 values from particular functions.  They are described in the following
 247 sections.
 248
 249 =head2 ZOOM::Error
 250
 251  if ($@->code() == ZOOM::Error::QUERY_PQF) {
 252      return "your query was not accepted";
 253  }
 254
 255 This class provides a set of manifest constants representing some of
 256 the possible error codes that can be raised by the ZOOM module.  The
 257 methods that return error-codes are
 258 C<ZOOM::Exception::code()>,
 259 C<ZOOM::Connection::error_x()>
 260 and
 261 C<ZOOM::Connection::errcode()>.
 262
 263 The C<ZOOM::Error> class provides the constants
 264 C<NONE>,
 265 C<CONNECT>,
 266 C<MEMORY>,
 267 C<ENCODE>,
 268 C<DECODE>,
 269 C<CONNECTION_LOST>,
 270 C<INIT>,
 271 C<INTERNAL>,
 272 C<TIMEOUT>,
 273 C<UNSUPPORTED_PROTOCOL>,
 274 C<UNSUPPORTED_QUERY>,
 275 C<INVALID_QUERY>,
 276 C<CREATE_QUERY>,
 277 C<QUERY_CQL>,
 278 C<QUERY_PQF>,
 279 C<SORTBY>,
 280 C<CLONE>
 281 and
 282 C<PACKAGE>,
 283 each of which specifies a client-side error.  Since errors may also be
 284 diagnosed by the server, and returned to the client, error codes may
 285 also take values from the BIB-1 diagnostic set of Z39.50, listed at
 286 the Z39.50 Maintenance Agency's web-site at
 287 http://www.loc.gov/z3950/agency/defns/bib1diag.html
 288
 289 All error-codes, whether client-side from the C<ZOOM::Error>
 290 enumeration or server-side from the BIB-1 diagnostic set, can be
 291 translated into human-readable messages by passing them to the
 292 C<ZOOM::diag_str()> utility function.
 293
 294 =head2 ZOOM::Event
 295
 296  if ($conn->last_event() == ZOOM::Event::CONNECT) {
 297      print "Connected!\n";
 298  }
 299
 300 In applications that need it - mostly complex multiplexing
 301 applications - The C<ZOOM::Connection::last_event()> method is used to
 302 return an indication of the last event that occurred on a particular
 303 connection.  It always returns a value drawn from this enumeration,
 304 that is, one of C<NONE>, C<CONNECT>, C<SEND_DATA>, C<RECV_DATA>,
 305 C<TIMEOUT>, C<UNKNOWN>, C<SEND_APDU>, C<RECV_APDU>, C<RECV_RECORD> or
 306 C<RECV_SEARCH>.
 307
 308 You almost certainly don't need to know about this.  Frankly, I'm not
 309 sure how to use it myself.
 310
 311 =head1 SEE ALSO
 312
 313 The ZOOM abstract API,
 314 http://zoom.z3950.org/api/zoom-current.html
 315
 316 The C<Net::Z3950::ZOOM> module, included in the same distribution as this one.
 317
 318 The C<Net::Z3950> module, which this one supersedes.
 319
 320 The documentation for the ZOOM-C module of the YAZ Toolkit, which this
 321 module is built on.  Specifically, its lists of options are useful.
 322 http://indexdata.com/yaz/doc/zoom.tkl
 323
 324 The BIB-1 diagnostic set of Z39.50,
 325 http://www.loc.gov/z3950/agency/defns/bib1diag.html
 326
 327 =head1 AUTHOR
 328
 329 Mike Taylor, E<lt>mike@indexdata.comE<gt>
 330
 331 =head1 COPYRIGHT AND LICENCE
 332
 333 Copyright (C) 2005 by Index Data.
 334
 335 This library is free software; you can redistribute it and/or modify
 336 it under the same terms as Perl itself, either Perl version 5.8.4 or,
 337 at your option, any later version of Perl 5 you may have available.
 338
 339 =cut
 340
 341 1;