# $Id: ZOOM.pod,v 1.4 2005-11-16 14:54:43 mike Exp $

use strict;
use warnings;

=head1 NAME

ZOOM - Perl extension implementing the ZOOM API for Information Retrieval

=head1 SYNOPSIS

 use ZOOM;
 eval {
     $conn = new ZOOM::Connection($host, $port)
     $conn->option(preferredRecordSyntax => "usmarc");
     $rs = $conn->search_pqf('@attr 1=4 dinosaur');
     $n = $rs->size();
     print $rs->record(0)->render();
 };
 if ($@) {
     print "Error ", $@->code(), ": ", $@->message(), "\n";
 }

=head1 DESCRIPTION

This module provides a nice, Perlish implementation of the ZOOM
Abstract API described and documented at http://zoom.z3950.org/api/

the ZOOM module is implemented as a set of thin classes on top of the
non-OO functions provided by this distribution's C<Net::Z3950::ZOOM>
module, which in 
turn is a thin layer on top of the ZOOM-C code supplied as part of
Index Data's YAZ Toolkit.  Because ZOOM-C is also the underlying code
that implements ZOOM bindings in C++, Visual Basic, Scheme, Ruby, .NET
(including C#) and other languages, this Perl module works compatibly
with those other implementations.  (Of course, the point of a public
API such as ZOOM is that all implementations should be compatible
anyway; but knowing that the same code is running is reassuring.)

The ZOOM module provides two enumerations (C<ZOOM::Error> and
C<ZOOM::Event>), a single utility function C<diag_str()> in the C<ZOOM>
package itself, and eight classes:
C<ZOOM::Exception>,
C<ZOOM::Options>,
C<ZOOM::Connection>,
C<ZOOM::Query>,
C<ZOOM::ResultSet>,
C<ZOOM::Record>,
C<ZOOM::ScanSet>
and
C<ZOOM::Package>.
Of these, the Query class is abstract, and has two concrete
subclasses:
C<ZOOM::Query::CQL>
and
C<ZOOM::Query::PQF>.
Many useful ZOOM applications can be built using only the Connection,
ResultSet, Record and Exception classes, as in the example
code-snippet above.

A typical application will begin by creating an Connection object,
then using that to execute searches that yield ResultSet objects, then
fetching records from the result-sets to yield Record objects.  If an
error occurs, an Exception object is thrown and can be dealt with.

More sophisticated applications might also browse the server's indexes
to create a ScanSet, from which indexed terms may be retrieved; others
might send ``Extended Services'' Packages to the server, to achieve
non-standard tasks such as database creation and record update.
Searching using a query syntax other than PQF can be done using an
query object of one of the Query subclasses.  Finally, sets of options
may be manipulated independently of the objects they are associated
with using an Options object.

In general, method calls throw an exception if anything goes wrong, so
you don't need to test for success after each call.  See the section
below on the Exception class for details.

=head1 UTILITY FUNCTION

=head2 ZOOM::diag_str()

 $msg = ZOOM::diag_str(ZOOM::Error::INVALID_QUERY);

Returns a human-readable English-language string corresponding to the
error code that is its own parameter.  This works for any error-code
returned from
C<ZOOM::Exception::code()>,
C<ZOOM::Connection::error_x()>
or
C<ZOOM::Connection::errcode()>,
irrespective of whether it is a member of the C<ZOOM::Error>
enumeration or drawn from the BIB-1 diagnostic set.

=head1 CLASSES

The eight ZOOM classes are described here in ``sensible order'':
first, the four commonly used classes, in the he order that they will
tend to be used in most programs (Connection, ResultSet, Record,
Exception); then the four more esoteric classes in descending order of
how often they are needed.

With the exception of the Options class, which is an extension to the
ZOOM model, the introduction to each class includes a link to the
relevant section of the ZOOM Abstract API.

=head2 ZOOM::Connection

 $conn = new ZOOM::Connection("indexdata.dk:210/gils");
 print("server is '", $conn->option("serverImplementationName"), "'\n");
 $conn->option(preferredRecordSyntax => "usmarc");
 $conn->option_binary(iconBlob => "foo\0bar");
 $rs = $conn->search_pqf('@attr 1=4 mineral');
 $ss = $conn->scan('@attr 1=1003 a');
 if ($conn->errcode() != 0) {
    die("somthing went wrong: " . $conn->errmsg())
 }
 $conn->destroy()

This class represents a connection to an information retrieval server,
using an IR protocol such as ANSI/NISO Z39.50, SRW (the
Search/Retrieve Webservice), SRU (the Search/Retrieve URL) or
OpenSearch.  Not all of these protocols require a low-level connection
to be maintained, but the Connection object nevertheless provides a
location for the necessary cache of configuration and state
information, as well as a uniform API to the connection-oriented
facilities (searching, index browsing, etc.), provided by these
protocols.

See the description of the C<Connection> class in the ZOOM Abstract
API at
http://zoom.z3950.org/api/zoom-current.html#3.2

=head3 Methods

=head4 new()

 $conn = new ZOOM::Connection("indexdata.dk", 210);
 $conn = new ZOOM::Connection("indexdata.dk/gils:210");
 $conn = new ZOOM::Connection("tcp:indexdata.dk/gils:210");
 $conn = new ZOOM::Connection("http:indexdata.dk/gils:210");

I<###>

create
connect
error_x
errcode
errmsg
addinfo
option
option_binary
search
search_pqf
scan
package
destroy

=head2 ZOOM::ResultSet

I<###>

=head2 ZOOM::Record

I<###>

=head2 ZOOM::Exception

In general, method calls throw an exception (of class
C<ZOOM::Exception>) if anything goes wrong, so you don't need to test
for success after each call.  Exceptions are caught by enclosing the
main code in an C<eval{}> block and checking C<$@> on exit from that
block, as in the code-sample above.

There are a small number of exceptions to this rule.
I<###>

=head2 ZOOM::ScanSet

I<###>

=head2 ZOOM::Package

I<###>

=head2 ZOOM::Query

I<###>

=head2 ZOOM::Options

I<###>

=head1 ENUMERATIONS

The ZOOM module provides two enumerations that list possible return
values from particular functions.  They are described in the following
sections.

=head2 ZOOM::Error

 if ($@->code() == ZOOM::Error::QUERY_PQF) {
     return "your query was not accepted";
 }

This class provides a set of manifest constants representing some of
the possible error codes that can be raised by the ZOOM module.  The
methods that return error-codes are
C<ZOOM::Exception::code()>,
C<ZOOM::Connection::error_x()>
and
C<ZOOM::Connection::errcode()>.

The C<ZOOM::Error> class provides the constants
C<NONE>,
C<CONNECT>,
C<MEMORY>,
C<ENCODE>,
C<DECODE>,
C<CONNECTION_LOST>,
C<INIT>,
C<INTERNAL>,
C<TIMEOUT>,
C<UNSUPPORTED_PROTOCOL>,
C<UNSUPPORTED_QUERY>,
C<INVALID_QUERY>,
C<CREATE_QUERY>,
C<QUERY_CQL>,
C<QUERY_PQF>,
C<SORTBY>,
C<CLONE>
and
C<PACKAGE>,
each of which specifies a client-side error.  Since errors may also be
diagnosed by the server, and returned to the client, error codes may
also take values from the BIB-1 diagnostic set of Z39.50, listed at
the Z39.50 Maintenance Agency's web-site at
http://www.loc.gov/z3950/agency/defns/bib1diag.html

All error-codes, whether client-side from the C<ZOOM::Error>
enumeration or server-side from the BIB-1 diagnostic set, can be
translated into human-readable messages by passing them to the
C<ZOOM::diag_str()> utility function.

=head2 ZOOM::Event

 if ($conn->last_event() == ZOOM::Event::CONNECT) {
     print "Connected!\n";
 }

In applications that need it - mostly complex multiplexing
applications - The C<ZOOM::Connection::last_event()> method is used to
return an indication of the last event that occurred on a particular
connection.  It always returns a value drawn from this enumeration,
that is, one of C<NONE>, C<CONNECT>, C<SEND_DATA>, C<RECV_DATA>,
C<TIMEOUT>, C<UNKNOWN>, C<SEND_APDU>, C<RECV_APDU>, C<RECV_RECORD> or
C<RECV_SEARCH>.

You almost certainly don't need to know about this.  Frankly, I'm not
sure how to use it myself.

=head1 SEE ALSO

The ZOOM abstract API,
http://zoom.z3950.org/api/zoom-current.html

The C<Net::Z3950::ZOOM> module, included in the same distribution as this one.

The C<Net::Z3950> module, which this one supersedes.

The BIB-1 diagnostic set of Z39.50,
http://www.loc.gov/z3950/agency/defns/bib1diag.html

=head1 AUTHOR

Mike Taylor, E<lt>mike@indexdata.comE<gt>

=head1 COPYRIGHT AND LICENCE

Copyright (C) 2005 by Index Data.

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.4 or,
at your option, any later version of Perl 5 you may have available.

=cut

1;