.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "SRU 3pm" .TH SRU 3pm "2022-06-17" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" SRU \- Search and Retrieval by URL .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& ## a simple CGI example \& \& use SRU::Request; \& use SRU::Response; \& \& ## create CGI object \& my $cgi = CGI\->new(); \& \& ## create a SRU request object from the CGI object \& my $request = SRU::Request\->newFromCGI( $cgi ); \& \& ## create a SRU response based from the request \& my $response = SRU::Response\->newFromRequest( $request ); \& \& if ( $response\->type() eq \*(Aqexplain\*(Aq ) { \& ... \& } elsif ( $response\->type() eq \*(Aqscan\*(Aq ) { \& ... \& } elsif ( $response\->type() eq \*(AqsearchRetrieve\*(Aq ) { \& ... \& } \& \& ## print out the response \& print $cgi\->header( \-type => \*(Aqtext/xml\*(Aq ); \& print $response\->asXML(); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \s-1SRU\s0 package provides a framework for working with the Search and Retrieval by \s-1URL\s0 (\s-1SRU\s0) protocol developed by the Library of Congress. \s-1SRU\s0 defines a web service for searching databases containing metadata and objects. \s-1SRU\s0 often goes under the name \s-1SRW\s0 which is a \s-1SOAP\s0 version of the protocol. You can think of \s-1SRU\s0 as a RESTful version of \s-1SRW,\s0 since all the requests are simple URLs instead of \s-1XML\s0 documents being sent via some sort of transport layer. .PP You might be interested in \s-1SRU\s0 if you want to provide a generic \s-1API\s0 for searching a data repository and a mechanism for returning metadata records. \&\s-1SRU\s0 defines three verbs: explain, scan and searchRetrieve which define the requests and responses in a \s-1SRU\s0 interaction. .PP This set of modules attempts to provide a framework for building an \s-1SRU\s0 service. The distribution is made up of two sets of Perl modules: modules in the SRU::Request::* namespace which represent the three types of requests; and modules in the SRU::Response::* namespace which represent the various responses. .PP Typical usage is that a request object is created using a factory method in the SRU::Request module. The factory is given either a \s-1URI\s0 or a \s-1CGI\s0 object for the \s-1HTTP\s0 request. SRU::Request will look at the \s-1URI\s0 and build the appropriate request object: SRU::Request::Explain, SRU::Request::Scan or SRU::Request::SearchRetrieve. .PP Once you've got a request object you can build a response object by using the factory method \fBnewFromRequest()\fR in SRU::Request. This method will examine the request and build the corresponding result object which you can then populate with result data appropriately. When you are finished populating the response object with results you can call \fBasXML()\fR on it to get the full \s-1XML\s0 for your response. .PP To understand the meaning of the various requests and their responses you'll want to read the docs at the Library of Congress. A good place to start is this simple introductory page: http://www.loc.gov/standards/sru/simple.html For more information about working with the various request and response objects in this distribution see the \s-1POD\s0 in the individual packages: .IP "\(bu" 4 SRU::Request .IP "\(bu" 4 SRU::Request::Explain .IP "\(bu" 4 SRU::Request::Scan .IP "\(bu" 4 SRU::Request::SearchRetrieve .IP "\(bu" 4 SRU::Response .IP "\(bu" 4 SRU::Response::Explain .IP "\(bu" 4 SRU::Response::Scan .IP "\(bu" 4 SRU::Response::SearchRetrieve .IP "\(bu" 4 SRU::Server .PP Questions and comments are more than welcome. This software was developed as part of a National Science Foundation grant for building distributed library systems in the Ockham Project. More about Ockham can be found at http://www.ockham.org. .SH "DEPENDENCIES" .IX Header "DEPENDENCIES" To use SRU::Server and Catalyst::Controller::SRU, one must install CGI::Application and Catalyst, respectively. In a future release Catalyst::Controller::SRU might be moved to an independent module. .SH "TODO" .IX Header "TODO" .IP "\(bu" 4 create a client (SRU::Client) .IP "\(bu" 4 allow searchRetrieve responses to be retrieved as \s-1RSS\s0 .IP "\(bu" 4 make sure SRU::Server can function like real-world \s-1SRU\s0 interfaces .IP "\(bu" 4 handle \s-1CQL\s0 parsing errors .IP "\(bu" 4 better argument checking in response constructors .SH "AUTHORS" .IX Header "AUTHORS" Ed Summers .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2013 by Ed Summers. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.