X-Git-Url: http://git.indexdata.com/?p=simpleserver-moved-to-github.git;a=blobdiff_plain;f=SimpleServer.pm;h=5a8e32d6c9d2ec48debb1c3576b0c84a06b31832;hp=cc6c7d00081111116ad453d3e8e60000b3d7f1e9;hb=398e2d2769ff83b45a4a2cdc1b4a5a61a9196724;hpb=03aac9fd7958d065157b3c5878bf5a7c76420a0f diff --git a/SimpleServer.pm b/SimpleServer.pm index cc6c7d0..5a8e32d 100644 --- a/SimpleServer.pm +++ b/SimpleServer.pm @@ -26,7 +26,32 @@ ## ## $Log: SimpleServer.pm,v $ -## Revision 1.8 2001-08-29 10:29:51 sondberg +## Revision 1.14 2002-03-06 11:30:02 mike +## Add RPN structure documentation to SimpleServer.pm's POD. +## Add README to MANIFEST. +## +## Revision 1.13 2002/03/06 11:02:04 mike +## Added simple README file, derived from POD comments in SimpleServer.pm +## Fixed my (Mike Taylor's) email address +## +## Revision 1.12 2002/03/05 20:52:22 sondberg +## Version 0.05 so that we can release the thing at CPAN. +## +## Revision 1.11 2002/03/05 20:49:56 sondberg +## Added a couple of lines of documentation. +## +## Revision 1.10 2002/02/28 11:21:57 mike +## Add RPN structure to search-handler argument hash. +## +## Revision 1.9 2001/08/29 11:48:36 sondberg +## Added routines +## +## Net::Z3950::SimpleServer::ScanSuccess +## Net::Z3950::SimpleServer::ScanPartial +## +## and a bit of documentation. +## +## Revision 1.8 2001/08/29 10:29:51 sondberg ## Added some documentation of scan. ## ## Revision 1.7 2001/08/24 14:00:20 sondberg @@ -53,7 +78,7 @@ require AutoLoader; @EXPORT = qw( ); -$VERSION = '0.02'; +$VERSION = '0.05'; bootstrap Net::Z3950::SimpleServer $VERSION; @@ -102,6 +127,20 @@ sub launch_server { } +# Register packages that we will use in translated RPNs +package Net::Z3950::APDU::Query; +package Net::Z3950::APDU::OID; +package Net::Z3950::RPN::And; +package Net::Z3950::RPN::Or; +package Net::Z3950::RPN::AndNot; +package Net::Z3950::RPN::Term; +package Net::Z3950::RPN::Attributes; +package Net::Z3950::RPN::Attribute; + +# Must revert to original package for Autoloader's benefit +package Net::Z3950::SimpleServer; + + # Autoload methods go after =cut, and are processed by the autosplit program. 1; @@ -271,6 +310,7 @@ mous hash. The structure is the following: DATABASES => ["xxx"], ## Reference to a list of data- ## bases to search QUERY => "query", ## The query expression + RPN => $obj, ## Reference to a Net::Z3950::APDU::Query ## Response parameters: @@ -315,6 +355,134 @@ it is perfectly legal to not accept boolean operators, but you SHOULD try to return good error codes if you run into something you can't or won't support. +A more convenient alternative to the QUERY member may be the RPN +member, which is a reference to a Net::Z3950::APDU::Query object +representing the RPN query tree. The structure of that object is +supposed to be self-documenting, but here's a brief summary of what +you get: + +=over 4 + +=item * + +C is a hash with two fields: + +Z<> + +=over 4 + +=item C + +Optional. If present, it is a reference to a +C. This is a string of dot-separated integers +representing the OID of the query's top-level attribute set. + +=item C + +Mandatory: a refererence to the RPN tree itself. + +=back + +=item * + +Each node of the tree is an object of one of the following types: + +Z<> + +=over 4 + +=item C + +=item C + +=item C + +These three classes are all arrays of two elements, each of which is a +node of one of the above types. + +=item C + +See below for details. + +=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.) + +=back + +=over 4 + +=item * + +C is a hash with two fields: + +Z<> + +=over 4 + +=item C + +A string containing the search term itself. + +=item C + +A reference to a C object. + +=back + +=item * + +C is an array of references to +C objects. (Note the plural/singular +distinction.) + +=item * + +C is a hash with three elements: + +Z<> + +=over 4 + +=item C + +Optional. If present, it is dot-separated OID string, as above. + +=item C + +An integer indicating the type of the attribute - for example, under +the BIB-1 attribute set, type 1 indicates a ``use'' attribute, type 2 +a ``relation'' attribute, etc. + +=item C + +An integer indicating the value of the attribute - for example, under +BIB-1, if the attribute type is 1, then value 4 indictates a title +search and 7 indictates an ISBN search; but if the attribute type is +2, then value 4 indicates a ``greater than or equal'' search, and 102 +indicates a relevance match. + +=back + +=back + +Note that, at the moment, none of these classes have any methods at +all: the blessing into classes is largely just a documentation thing +so that, for example, if you do + + { use Data::Dumper; print Dumper($args->{RPN}) } + +you get something fairly human-readable. But of course, the type +distinction between the three different kinds of boolean node is +important. + +By adding your own methods to these classes (building what I call +``augmented classes''), you can easily build code that walks the tree +of the incoming RPN. Take a look at C for a +sample implementation of such an augmented classes technique. + + =head2 Present handler The presence of a present handler in a SimpleServer front-end is optional. @@ -424,7 +592,7 @@ an index of a book, you always find something! The parameters exchanged are ERR_CODE => 0, ## Error code ERR_STR => '', ## Diagnostic message NUMBER => zz, ## Number of returned terms - STATUS => ScanSuccess, ## ScanSuccess/ScanFailure + STATUS => $status, ## ScanSuccess/ScanFailure ENTRIES => $entries ## Referenced list of terms }; @@ -445,7 +613,14 @@ should point at a data structure of this kind, ... ]; - + +The $status flag should be assigned one of two values: + + Net::Z3950::SimpleServer::ScanSuccess On success (default) + Net::Z3950::SimpleServer::ScanPartial Less 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 @@ -463,15 +638,12 @@ or something similar, this is the place to do it. =head1 AUTHORS Anders Sønderberg (sondberg@indexdata.dk) and Sebastian Hammer -(quinn@indexdata.dk). +(quinn@indexdata.dk). Substantial contributions made by Mike Taylor +(mike@miketaylor.org.uk). =head1 SEE ALSO -perl(1). - Any Perl module which is useful for accessing the database of your choice. =cut - -