osrf_ctl.sh -a start_router
OpenSRF, pronounced “Open Surf”, is the Open Service Request Framework. It was designed as an architecture on which one could easily build scalable applications.
Built on JSON-over-XMPP. XML can be used, but JSON is much less verbose.
OpenSRF offers scalability via its clustering architecture; a service that is a bottleneck can be moved onto its own server; or multiple instances of the service can be run on many servers. Services can themselves be clients of other services.
OpenSRF uses memcached to cache requests and responses for some services. For example, the contents of the configuration files are cached by the opensrf.settings service when that service starts, and if you change a setting in one of those configuration files, you must restart the opensrf.settings service to update its data. You must then restart any of the services that make use of that setting to make the change take effect.
Supports Perl, C, and Python as services and clients, and Java as a client. JavaScript can access services via HTTP translator and gateway. JSON library converts messages to/from native structures for ease of development.
Walk through the configuration files, explaining why we put the values into the files that we do:
opensrf_core.xml
Distinguish between public and private services for security of Web-based applications.
Deprecated HTTP gateway versus OpenSRF-over-HTTP
opensrf.xml
|
Tip
|
In a clustered OpenSRF instance, these files are normally hosted on a network share so that each member of the cluster can read them. |
|
Note
|
I won't go through this during a live session. Perhaps I can cut this out entirely… |
Issue the following commands as the opensrf user. If you are running OpenSRF on a single-server machine, you can use the -l flag to force the hostname to be treated as localhost.
Start the OpenSRF router:
osrf_ctl.sh -a start_router
|
Important
|
The router must only run on a single machine in a given brick. |
Start all OpenSRF Perl services defined for a given hostname:
osrf_ctl.sh -a start_perl
|
Tip
|
You can start an individual Perl service using: |
opensrf-perl.pl -s <service-name> -a start -p <PID-directory>
Start all OpenSRF C services defined for a given hostname:
osrf_ctl.sh -a start_c
Issue the following commands as the opensrf user. If you are running OpenSRF on a single-server machine, you can use the -l flag to force the hostname to be treated as localhost.
Stop the OpenSRF router:
osrf_ctl.sh -a stop_router
Stop all OpenSRF Perl services defined for a given hostname:
osrf_ctl.sh -a stop_perl
|
Tip
|
You can stop an individual Perl service using: |
opensrf-perl.pl -s <service-name> -a stop -p <PID-directory>
Stop all OpenSRF C services defined for a given hostname:
osrf_ctl.sh -a stop_c
|
Important
|
PID files for OpenSRF services are stored and looked up in /openils/var/run by default with osrf_ctl.sh, and in /tmp/ with opensrf-perl.pl. For a clustered server instance of Evergreen, you must store the PIDs on a directory that is local to each server, or else one of your cluster servers may try killing processes on itself that actually have PIDs on other servers. |
Show internal documentation for methods. Do some stupid srfsh tricks (introspect for one) and show docgen.xsl in action.
Show how methods are registered, along with global initialization, child initialization, and associated destructors. OpenSRF::UnixServer is where we want to look to see how these optional methods are invoked in Perl.
Note that arguments are converted between native data structures and JSON for us for free.
See OpenSRF/src/perl/lib/OpenSRF/UnixServer.pm to understand how the optional methods for initializing and cleaning up OpenSRF services are invoked:
initialize()
child_init()
child_exit()
Services are implemented as Perl functions. Each service needs to be registered with:
__PACKAGE__->register_method(
method => 'method name',
api_name => 'api name',
api_level => 1,
argc => # of args,
signature => {
desc => “Description”,
params => [
{
name => 'parameter name',
desc => 'parameter description',
type => '(array|hash|number|string)'
}
],
return => {
desc => 'Description of return value',
type => '(array|hash|number|string)'
}
}
);
This is the simplest possible OpenSRF client written in Perl:
use OpenSRF::System; # 1
OpenSRF::System->bootstrap_client(config_file => $ARGV[0]); # 2
my $session = OpenSRF::AppSession->create("open-ils.resolver"); # 3
my $request = $session->request("open-ils.resolver.resolve_holdings", "issn", "0022-362X" )->gather(); # 4
$session->disconnect(); # 5
The OpenSRF::System module gives our program access to the core OpenSRF client functionality.
The bootstrap_client() method reads the opensrf_core.xml file and sets up communication with the OpenSRF router.
The OpenSRF::Appsession→create() instance method asks the router if it can connect to the named service. If the router determines that the service is accessible (either the opensrf credentials are on the private domain, which gives it access to all public and private services; or the service is on a public domain, which is accessible to both public and private opensrf credentials), it returns an OpenSRF session with a connection to the named service.
The OpenSRF::Appsession→request() method invokes a method of the associated service to return a request object. Invoking the gather() method on the returned request object returns a single result.
|
Note
|
If the service is expected to return multiple results, you should loop over it with recv() instead. But then, that wouldn't be the simplest possible client anymore would it? |
The OpenSRF::Appsession→disconnect() instance method disconnects from the service, enabling that child to go on and handle other requests.
See OpenSRF/src/python/osrf/apps/example.py
The optional methods for initializing and cleaning up are:
global_init()
child_init()
child_exit()
Build a new OpenSRF service.
The challenge: implement a service that caches responses from some other Web service (potentially cutting down on client-side latency for something like OpenLibrary / Google Books / xISBN services, and avoiding timeouts if the target service is not dependable). Our example will be to build an SFX lookup service. This has the additional advantage of enabling XmlHttpRequest from JavaScript by hosting the services on the same domain.
Let's start with the simplest possible implementation – a CGI script.
#!/usr/bin/perl
use strict;
use warnings;
use CGI;
use LWP::UserAgent;
use XML::LibXML;
use JSON::XS;
my $q = CGI->new;
my $issn = $q->param("issn");
my $isbn = $q->param("isbn");
my $url_base = 'http://sfx.scholarsportal.info/laurentian';
my $url_args = '?url_ver=Z39.88-2004&url_ctx_fmt=infofi/fmt:kev:mtx:ctx' .
'&ctx_enc=UTF-8&ctx_ver=Z39.88-2004&rfr_id=info:sid/conifer' .
'&sfx.ignore_date_threshold=1&sfx.response_type=multi_obj_detailed_xml' .
'&__service_type=getFullTxt';
if ($issn) {
$url_args .= "&rft.issn=$issn";
} elsif ($isbn) {
$url_args .= "&rft.isbn=$isbn";
}
my $ua = LWP::UserAgent->new;
$ua->agent("SameOrigin/1.0");
my $req = HTTP::Request->new(GET => "$url_base$url_args");
my $res = $ua->request($req);
print $q->header('text/json');
my $xml = $res->content;
my $parser = XML::LibXML->new();
my $parsed_sfx = $parser->parse_string($xml);
my (@targets) = $parsed_sfx->findnodes('//target');
my @sfx_result;
foreach my $target (@targets) {
my $public_name = $target->findvalue('./target_public_name');
my $target_url = $target->findvalue('.//target_url');
my $target_coverage = $target->findvalue('.//coverage_statement');
my $target_embargo = $target->findvalue('.//embargo_statement');
push @sfx_result, {
public_name => $public_name,
coverage => $target_coverage,
embargo => $target_embargo,
url => $target_url
};
}
print encode_json(\@sfx_result);
Hopefully you can follow what this CGI script is doing. It works, but it has all the disadvantages of CGI: the environment needs to be built up on every request, and it doesn't remember anything from the previous times it was called, etc.
So now we want to turn this into an OpenSRF service. Start by ripping out the CGI stuff, as we won't need that any more.
To turn this into an OpenSRF service, we create a new Perl module (OpenILS::Application::ResolverResolver). We no longer have to convert results between Perl and JSON values, as OpenSRF will handle that for us. We now have to register the method with OpenSRF.