X-Git-Url: http://git.indexdata.com/?p=simpleserver-moved-to-github.git;a=blobdiff_plain;f=SimpleServer.pm;h=f6a4c399b84b02263b068638fb756ea986cb4d5c;hp=a29563434a3392389072499d78bcc18ae6be2ddb;hb=eb69046dd58ade30eada3a5ec5f2d4c05fb3b9b5;hpb=6a3d1dfe0107b554945ddc1c55ccd7478ae26a90 diff --git a/SimpleServer.pm b/SimpleServer.pm index a295634..f6a4c39 100644 --- a/SimpleServer.pm +++ b/SimpleServer.pm @@ -1,5 +1,5 @@ ## -## 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, @@ -25,7 +25,7 @@ ## ## -## $Id: SimpleServer.pm,v 1.21 2004-06-04 09:57:00 sondberg Exp $ +## $Id: SimpleServer.pm,v 1.35 2007-08-15 13:21:22 mike Exp $ package Net::Z3950::SimpleServer; @@ -39,7 +39,7 @@ require AutoLoader; @ISA = qw(Exporter AutoLoader DynaLoader); @EXPORT = qw( ); -$VERSION = '0.08'; +$VERSION = '1.06'; bootstrap Net::Z3950::SimpleServer $VERSION; @@ -69,6 +69,13 @@ sub launch_server { 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}); } @@ -83,6 +90,12 @@ sub launch_server { 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); } @@ -95,6 +108,7 @@ package Net::Z3950::RPN::And; 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; @@ -144,15 +158,14 @@ Net::Z3950::SimpleServer - Simple Perl API for building Z39.50 servers. } } - ## 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 @@ -208,7 +221,13 @@ means of the SimpleServer object constructor 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. If you want your SimpleServer to start a thread (threaded mode) to handle each incoming Z39.50 request instead of forking a process @@ -261,6 +280,7 @@ The argument hash passed to the init handler has the form ## 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 }; @@ -290,6 +310,7 @@ mous hash. The structure is the following: $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? @@ -390,10 +411,15 @@ node of one of the above types. See below for details. +=item C + +A reference to a result-set ID indicating a previous search. The ID +of the result-set is in the C element. + =back (I guess I should make a superclass C 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 @@ -494,6 +520,7 @@ The informations exchanged between client and present handle are: $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 @@ -520,11 +547,13 @@ The parameters exchanged between the server and the fetch handler are $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: @@ -535,6 +564,7 @@ The parameters exchanged between the server and the fetch handler are 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 @@ -566,7 +596,10 @@ an index of a book, you always find something! The parameters exchanged are $args = { ## Client request - HANDLE => $ref ## Reference to data structure + GHANDLE => $obj, ## Global handler specified at creation + HANDLE => $ref, ## Reference to data structure + DATABASES => ["xxx"], ## Reference to a list of data- + ## bases to search TERM => 'start', ## The start term NUMBER => xx, ## Number of requested terms POS => yy, ## Position of starting point @@ -600,20 +633,23 @@ should point at a data structure of this kind, ... ]; -The $status flag should be assigned one of two values: +The $status flag is only meaningful after a successful scan, and +should be assigned one of two values: - Net::Z3950::SimpleServer::ScanSuccess On success (default) - Net::Z3950::SimpleServer::ScanPartial Less terms returned than requested + Net::Z3950::SimpleServer::ScanSuccess Full success (default) + Net::Z3950::SimpleServer::ScanPartial Fewer terms returned than requested The STEP member contains the requested number of entries in the term-list between two adjacent entries in the response. =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 }; @@ -621,11 +657,70 @@ What ever data structure the HANDLE value points at goes out of scope 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. A +minimal configuration file looks like this: + + + + pqf.properties + + + +This file specifies only that C 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 +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, 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