##
##
-## $Id: SimpleServer.pm,v 1.33 2007-08-08 12:09:19 mike Exp $
+## $Id: SimpleServer.pm,v 1.39 2007-08-20 10:59:50 mike Exp $
package Net::Z3950::SimpleServer;
@ISA = qw(Exporter AutoLoader DynaLoader);
@EXPORT = qw( );
-$VERSION = '1.06';
+$VERSION = '1.07';
bootstrap Net::Z3950::SimpleServer $VERSION;
# Register packages that we will use in translated RPNs
+package Net::Z3950::RPN::Node;
package Net::Z3950::APDU::Query;
+our @ISA = qw(Net::Z3950::RPN::Node);
package Net::Z3950::APDU::OID;
package Net::Z3950::RPN::And;
+our @ISA = qw(Net::Z3950::RPN::Node);
package Net::Z3950::RPN::Or;
+our @ISA = qw(Net::Z3950::RPN::Node);
package Net::Z3950::RPN::AndNot;
+our @ISA = qw(Net::Z3950::RPN::Node);
package Net::Z3950::RPN::Term;
+our @ISA = qw(Net::Z3950::RPN::Node);
package Net::Z3950::RPN::RSID;
+our @ISA = qw(Net::Z3950::RPN::Node);
package Net::Z3950::RPN::Attributes;
package Net::Z3950::RPN::Attribute;
+
+# Utility method for re-rendering Type-1 query back down to PQF
+package Net::Z3950::RPN::Node;
+
+sub toPQF {
+ my $this = shift();
+ my $class = ref $this;
+
+ if ($class eq "Net::Z3950::APDU::Query") {
+ my $res = "";
+ my $set = $this->{attributeSet};
+ $res .= "\@attrset $set " if defined $set;
+ return $res . $this->{query}->toPQF();
+ } elsif ($class eq "Net::Z3950::RPN::Or") {
+ return '@or ' . $this->[0]->toPQF() . ' ' . $this->[1]->toPQF();
+ } elsif ($class eq "Net::Z3950::RPN::And") {
+ return '@and ' . $this->[0]->toPQF() . ' ' . $this->[1]->toPQF();
+ } elsif ($class eq "Net::Z3950::RPN::AndNot") {
+ return '@not ' . $this->[0]->toPQF() . ' ' . $this->[1]->toPQF();
+ } elsif ($class eq "Net::Z3950::RPN::RSID") {
+ return '@set ' . $this->{id};
+ } elsif ($class ne "Net::Z3950::RPN::Term") {
+ die "unknown PQF node-type '$class'";
+ }
+
+ my $res = "";
+ foreach my $attr (@{ $this->{attributes} }) {
+ use Data::Dumper; print "considering attr: ", Dumper($attr);
+ $res .= "\@attr ";
+ my $set = $attr->{attributeSet};
+ $res .= "$set " if defined $set;
+ $res .= $attr->{attributeType} . "=" . $attr->{attributeValue} . " ";
+ }
+
+ return $res . $this->{term};
+}
+
+
# Must revert to original package for Autoloader's benefit
package Net::Z3950::SimpleServer;
=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 one day.)
-
=back
=over 4
=item C<attributeValue>
-An integer indicating the value of the attribute - for example, under
+An integer or string 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
=back
-Note that, at the moment, none of these classes have any methods at
+All of these classes except C<Attributes> and C<Attribute> are
+subclasses of the abstract class C<Net::Z3950::RPN::Node>. That class
+has a single method, C<toPQF()>, which may be used to turn an RPN
+tree, or part of one, back into a textual prefix query.
+
+Note that, apart to C<toPQF()>, 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
$args = {
## Client request
- GHANDLE => $obj ## Global handler specified at creation
- 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
+ RPN => $obj, ## Reference to a Net::Z3950::RPN::Term
+
NUMBER => xx, ## Number of requested terms
POS => yy, ## Position of starting point
## within returned list
...
];
-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.
+A better alternative to the TERM member is the the RPN
+member, which is a reference to a Net::Z3950::RPN::Term object
+representing the scan cloause. The structure of that object is the
+same as for Term objects included as part of the RPN tree passed to
+search handlers. This is more useful than the simple TERM because it
+includes attributes (e.g. access points associated with the term),
+which are discarded by the TERM element.
+
=head2 Close handler
The argument hash recieved by the close handler has two elements only: