##
-## Copyright (c) 2000-2004, Index Data.
+## Copyright (c) 2000-2006, Index Data.
##
## Permission to use, copy, modify, distribute, and sell this software and
## its documentation, in whole or in part, for any purpose, is hereby granted,
##
##
-## $Id: SimpleServer.pm,v 1.20 2004-05-28 20:14:28 sondberg Exp $
+## $Id: SimpleServer.pm,v 1.33 2007-08-08 12:09:19 mike Exp $
package Net::Z3950::SimpleServer;
@ISA = qw(Exporter AutoLoader DynaLoader);
@EXPORT = qw( );
-$VERSION = '0.08';
+$VERSION = '1.06';
bootstrap Net::Z3950::SimpleServer $VERSION;
my $self = shift;
my @args = @_;
+ ### This modal internal interface, in which we set a bunch of
+ # globals and then call start_server(), is asking for
+ # trouble. Instead, we should just pass the $self object
+ # as a parameter into start_server().
+ if (defined($self->{GHANDLE})) {
+ set_ghandle($self->{GHANDLE});
+ }
if (defined($self->{INIT})) {
set_init_handler($self->{INIT});
}
if (defined($self->{SCAN})) {
set_scan_handler($self->{SCAN});
}
+ if (defined($self->{SORT})) {
+ set_sort_handler($self->{SORT});
+ }
+ if (defined($self->{EXPLAIN})) {
+ set_explain_handler($self->{EXPLAIN});
+ }
start_server(@args);
}
package Net::Z3950::RPN::Or;
package Net::Z3950::RPN::AndNot;
package Net::Z3950::RPN::Term;
+package Net::Z3950::RPN::RSID;
package Net::Z3950::RPN::Attributes;
package Net::Z3950::RPN::Attribute;
}
}
-
## Register custom event handlers:
+ my $z = new Net::Z3950::SimpleServer(GHANDLE = $someObject,
+ INIT => \&my_init_handler,
+ CLOSE => \&my_close_handler,
+ SEARCH => \&my_search_handler,
+ FETCH => \&my_fetch_handler);
- my $z = new Net::Z3950::SimpleServer( INIT => \&my_init_handler,
- CLOSE => \&my_close_handler,
- SEARCH => \&my_search_handler,
- FETCH => \&my_fetch_handler);
## Launch server:
-
$z->launch_server("ztest.pl", @ARGV);
=head1 DESCRIPTION
the Perl script to the server. The server calls the registered
subroutines to field incoming requests from Z39.50 clients.
-A reference to an anonymous hash is passed to each handle. Some of
+A reference to an anonymous hash is passed to each handler. Some of
the entries of these hashes are to be considered input and others
output parameters.
-The Perl programmer specifies the event handles for the server by
-means of the the SimpleServer object constructor
+The Perl programmer specifies the event handlers for the server by
+means of the SimpleServer object constructor
my $z = new Net::Z3950::SimpleServer(
INIT => \&my_init_handler,
SEARCH => \&my_search_handler,
PRESENT => \&my_present_handler,
SCAN => \&my_scan_handler,
- FETCH => \&my_fetch_handler);
+ FETCH => \&my_fetch_handler,
+ EXPLAIN => \&my_explain_handler);
+
+In addition, the arguments to the constructor may include GHANDLE, a
+global handle which is made available to each invocation of every
+callback function. This is typically a reference to either a hash or
+an object.
-After the custom event handles are declared, the server is launched
+If you want your SimpleServer to start a thread (threaded mode) to
+handle each incoming Z39.50 request instead of forking a process
+(forking mode), you need to register the handlers by symbol rather
+than by code reference. Thus, in threaded mode, you will need to
+register your handlers this way:
+
+ my $z = new Net::Z3950::SimpleServer(
+ INIT => "my_package::my_init_handler",
+ CLOSE => "my_package::my_close_handler",
+ ....
+ .... );
+
+where my_package is the Perl package in which your handler is
+located.
+
+After the custom event handlers are declared, the server is launched
by means of the method
$z->launch_server("MyServer.pl", @ARGV);
are documented in the YAZ toolkit manual: The section on
application invocation: <http://www.indexdata.dk/yaz/yaz-7.php>
+In particular, you need to use the -T switch to start your SimpleServer
+in threaded mode.
+
=head2 Init handler
The init handler is called whenever a Z39.50 client is attempting
## this member contains user name
PASS => "yyy" ## Under same conditions, this member
## contains the password in clear text
+ GHANDLE => $obj ## Global handler specified at creation
HANDLE => undef ## Handler of Perl data structure
};
$args = {
## Request parameters:
+ GHANDLE => $obj ## Global handler specified at creation
HANDLE => ref, ## Your session reference.
SETNAME => "id", ## ID of the result set
REPL_SET => 0, ## Replace set if already existing?
See below for details.
+=item C<Net::Z3950::RPN::RSID>
+
+A reference to a result-set ID indicating a previous search. The ID
+of the result-set is in the C<id> element.
+
=back
(I guess I should make a superclass C<Net::Z3950::RPN::Node> and make
-all of these subclasses of it. Not done that yet, but will do soon.)
+all of these subclasses of it. Not done that yet, but will do one day.)
=back
$args = {
## Client/server request:
+ GHANDLE => $obj ## Global handler specified at creation
HANDLE => ref, ## Reference to datastructure
SETNAME => "id", ## Result set ID
START => xxx, ## Start position
$args = {
## Client/server request:
+ GHANDLE => $obj ## Global handler specified at creation
HANDLE => ref ## Reference to data structure
SETNAME => "id" ## ID of the requested result set
OFFSET => nnn ## Record offset number
REQ_FORM => "n.m.k.l"## Client requested format OID
COMP => "xyz" ## Formatting instructions
+ SCHEMA => "abc" ## Requested schema, if any
## Handler response:
ERR_STR => "" ## Error string
SUR_FLAG => 0 ## Surrogate diagnostic flag
REP_FORM => "n.m.k.l"## Provided format OID
+ SCHEMA => "abc" ## Provided schema, if any
};
The REP_FORM value has by default the REQ_FORM value but can be set to
$args = {
## Client request
+ GHANDLE => $obj ## Global handler specified at creation
HANDLE => $ref ## Reference to data structure
TERM => 'start', ## The start term
NUMBER => xx, ## Number of requested terms
=head2 Close handler
-The argument hash recieved by the close handler has one element only:
+The argument hash recieved by the close handler has two elements only:
$args = {
## Server provides:
+
+ GHANDLE => $obj ## Global handler specified at creation
HANDLE => ref ## Reference to data structure
};
after this call. If you need to close down a connection to your server
or something similar, this is the place to do it.
+=head2 Support for SRU and SRW
+
+Since release 1.0, SimpleServer includes support for serving the SRU
+and SRW protocols as well as Z39.50. These ``web-friendly'' protocols
+enable similar functionality to that of Z39.50, but by means of rich
+URLs in the case of SRU, and a SOAP-based web-service in the case of
+SRW. These protocols are described at
+http://www.loc.gov/sru
+
+In order to serve these protocols from a SimpleServer-based
+application, it is necessary to launch the application with a YAZ
+Generic Frontend Server (GFS) configuration file, which can be
+specified using the command-line argument C<-f> I<filename>. A
+minimal configuration file looks like this:
+
+ <yazgfs>
+ <server>
+ <cql2rpn>pqf.properties</cql2rpn>
+ </server>
+ </yazgfs>
+
+This file specifies only that C<pqf.properties> should be used to
+translate the CQL queries of SRU and SRW into corresponding Z39.50
+Type-1 queries. For more information about YAZ GFS configuration,
+including how to specify an Explain record, see the I<Virtual Hosts>
+section of the YAZ manual at
+http://indexdata.com/yaz/doc/server.vhosts.tkl
+
+The mapping of CQL queries into Z39.50 Type-1 queries is specified by
+a file that indicates which BIB-1 attributes should be generated for
+each CQL index, relation, modifiers, etc. A typical section of this
+file looks like this:
+
+ index.dc.title = 1=4
+ index.dc.subject = 1=21
+ index.dc.creator = 1=1003
+ relation.< = 2=1
+ relation.le = 2=2
+
+This file specifies the BIB-1 access points (type=1) for the Dublin
+Core indexes C<title>, C<subject> and C<creator>, and the BIB-1
+relations (type=2) corresponding to the CQL relations C<E<lt>> and
+C<E<lt>=>. For more information about the format of this file, see
+the I<CQL> section of the YAZ manual at
+http://indexdata.com/yaz/doc/tools.tkl#tools.cql
+
+The YAZ distribution include a sample CQL-to-PQF mapping configuration
+file called C<pqf.properties>; this is sufficient for many
+applications, and a good base to work from for most others.
+
+If a SimpleServer-based application is run without this SRU-specific
+configuration, it can still serve SRU; however, CQL queries will not
+be translated, but passed straight through to the search-handler
+function, as the C<CQL> member of the parameters hash. It is then the
+responsibility of the back-end application to parse and handle the CQL
+query, which is most easily done using Ed Summers' fine C<CQL::Parser>
+module, available from CPAN at
+http://search.cpan.org/~esummers/CQL-Parser/
+
=head1 AUTHORS
-Anders Sønderberg (sondberg@indexdata.dk) and Sebastian Hammer
-(quinn@indexdata.dk). Substantial contributions made by Mike Taylor
-(mike@miketaylor.org.uk).
+Anders Sønderberg (sondberg@indexdata.dk),
+Sebastian Hammer (quinn@indexdata.dk),
+Mike Taylor (indexdata.com).
=head1 SEE ALSO