+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>\r
-<chapter xml:id="opensrf" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="EN"\r
- xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">\r
- <chapterinfo>\r
- <title>OpenSRF</title>\r
- </chapterinfo>\r
- <abstract id="openSRF_abstract">\r
- <simpara>One of the claimed advantages of\r
- Evergreen over alternative integrated library systems is the underlying Open\r
- Service Request Framework (OpenSRF, pronounced "open surf") architecture. This\r
- article introduces OpenSRF, demonstrates how to build OpenSRF services through\r
- simple code examples, and explains the technical foundations on which OpenSRF\r
- is built. This chapter was taken from Dan Scott's <emphasis>Easing gently into OpenSRF</emphasis> article, June, 2010.</simpara>\r
- </abstract>\r
- <section id="_introducing_opensrf">\r
- <title>Introducing OpenSRF</title>\r
- <indexterm><primary>OpenSRF</primary></indexterm>\r
- <simpara>OpenSRF is a message routing network that offers scalability and failover\r
- support for individual services and entire servers with minimal development and\r
- deployment overhead. You can use OpenSRF to build loosely-coupled applications\r
- that can be deployed on a single server or on clusters of geographically\r
- distributed servers using the same code and minimal configuration changes.\r
- Although copyright statements on some of the OpenSRF code date back to Mike\r
- Rylander’s original explorations in 2000, Evergreen was the first major\r
- application to be developed with, and to take full advantage of, the OpenSRF\r
- architecture starting in 2004. The first official release of OpenSRF was 0.1 in\r
- February 2005 (<ulink url="http://evergreen-ils.org/blog/?p=21">http://evergreen-ils.org/blog/?p=21</ulink>), but OpenSRF’s development\r
- continues a steady pace of enhancement and refinement, with the release of\r
- 1.0.0 in October 2008 and the most recent release of 1.2.2 in February 2010.</simpara>\r
- <simpara>OpenSRF is a distinct break from the architectural approach used by previous\r
- library systems and has more in common with modern Web applications. The\r
- traditional "scale-up" approach to serve more transactions is to purchase a\r
- server with more CPUs and more RAM, possibly splitting the load between a Web\r
- server, a database server, and a business logic server. Evergreen, however, is\r
- built on the Open Service Request Framework (OpenSRF) architecture, which\r
- firmly embraces the "scale-out" approach of spreading transaction load over\r
- cheap commodity servers. The <ulink url="http://evergreen-ils.org/blog/?p=56">initial GPLS\r
- PINES hardware cluster</ulink>, while certainly impressive, may have offered the\r
- misleading impression that Evergreen requires a lot of hardware to run.\r
- However, Evergreen and OpenSRF easily scale down to a single server; many\r
- Evergreen libraries run their entire library system on a single server, and\r
- most OpenSRF and Evergreen development occurs on a virtual machine running on a\r
- single laptop or desktop image.</simpara>\r
- <simpara>Another common concern is that the flexibility of OpenSRF’s distributed\r
- architecture makes it complex to configure and to write new applications. This\r
- article demonstrates that OpenSRF itself is an extremely simple architecture on\r
- which one can easily build applications of many kinds – not just library\r
- applications – and that you can use a number of different languages to call and\r
- implement OpenSRF methods with a minimal learning curve. With an application\r
- built on OpenSRF, when you identify a bottleneck in your application’s business\r
- logic layer, you can adjust the number of the processes serving that particular\r
- bottleneck on each of your servers; or if the problem is that your service is\r
- resource-hungry, you could add an inexpensive server to your cluster and\r
- dedicate it to running that resource-hungry service.</simpara>\r
- <simplesect id="_programming_language_support">\r
- <title>Programming language support</title>\r
- <simpara>If you need to develop an entirely new OpenSRF service, you can choose from a\r
- number of different languages in which to implement that service. OpenSRF\r
- client language bindings have been written for C, Java, JavaScript, Perl, and\r
- Python, and service language bindings have been written for C, Perl, and Python.\r
- This article uses Perl examples as a lowest common denominator programming\r
- language. Writing an OpenSRF binding for another language is a relatively small\r
- task if that language offers libraries that support the core technologies on\r
- which OpenSRF depends:</simpara>\r
- <itemizedlist>\r
- <listitem>\r
- <simpara>\r
- <ulink url="http://tools.ietf.org/html/rfc3920">Extensible Messaging and Presence\r
- Protocol</ulink> (XMPP, sometimes referred to as Jabber) - provides the base messaging\r
- infrastructure between OpenSRF clients and services\r
- </simpara>\r
- <indexterm><primary>XMPP</primary></indexterm>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- <ulink url="http://json.org">JavaScript Object Notation</ulink> (JSON) - serializes the content\r
- of each XMPP message in a standardized and concise format\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- <ulink url="http://memcached.org">memcached</ulink> - provides the caching service\r
- </simpara>\r
- <indexterm><primary>memcached</primary></indexterm>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- <ulink url="http://tools.ietf.org/html/rfc5424">syslog</ulink> - the standard UNIX logging\r
- service\r
- </simpara>\r
- <indexterm><primary>syslog</primary></indexterm>\r
- </listitem>\r
- </itemizedlist>\r
- <simpara>Unfortunately, the\r
- <ulink url="http://evergreen-ils.org/dokuwiki/doku.php?id=osrf-devel:primer">OpenSRF\r
- reference documentation</ulink>, although augmented by the\r
- <ulink url="http://evergreen-ils.org/dokuwiki/doku.php?id=osrf-devel:terms">OpenSRF\r
- glossary</ulink>, blog posts like <ulink url="http://evergreen-ils.org/blog/?p=36">the description\r
- of OpenSRF and Jabber</ulink>, and even this article, is not a sufficient substitute\r
- for a complete specification on which one could implement a language binding.\r
- The recommended option for would-be developers of another language binding is\r
- to use the Python implementation as the cleanest basis for a port to another\r
- language.</simpara>\r
- <indexterm><primary>Python</primary></indexterm>\r
- </simplesect>\r
- </section>\r
- <section id="writing_an_opensrf_service">\r
- <title>Writing an OpenSRF Service</title>\r
- <simpara>Imagine an application architecture in which 10 lines of Perl or Python, using\r
- the data types native to each language, are enough to implement a method that\r
- can then be deployed and invoked seamlessly across hundreds of servers. You\r
- have just imagined developing with OpenSRF – it is truly that simple. Under the\r
- covers, of course, the OpenSRF language bindings do an incredible amount of\r
- work on behalf of the developer. An OpenSRF application consists of one or more\r
- OpenSRF services that expose methods: for example, the <literal>opensrf.simple-text</literal>\r
- <ulink url="http://svn.open-ils.org/trac/OpenSRF/browser/trunk/src/perl/lib/OpenSRF/Application/Demo/SimpleText.pm">demonstration\r
- service</ulink> exposes the <literal>opensrf.simple-text.split()</literal> and\r
- <literal>opensrf.simple-text.reverse()</literal> methods. Each method accepts zero or more\r
- arguments and returns zero or one results. The data types supported by OpenSRF\r
- arguments and results are typical core language data types: strings, numbers,\r
- booleans, arrays, and hashes.</simpara>\r
- <simpara>To implement a new OpenSRF service, perform the following steps:</simpara>\r
- <orderedlist numeration="arabic">\r
- <listitem>\r
- <simpara>\r
- Include the base OpenSRF support libraries\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- Write the code for each of your OpenSRF methods as separate procedures\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- Register each method\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- Add the service definition to the OpenSRF configuration files\r
- </simpara>\r
- </listitem>\r
- </orderedlist>\r
- <simpara>For example, the following code implements an OpenSRF service. The service\r
- includes one method named <literal>opensrf.simple-text.reverse()</literal> that accepts one\r
- string as input and returns the reversed version of that string:</simpara>\r
-<programlisting language="perl" linenumbering="unnumbered">\r
-#!/usr/bin/perl\r
-\r
-package OpenSRF::Application::Demo::SimpleText;\r
-\r
-use strict;\r
-\r
-use OpenSRF::Application;\r
-use parent qw/OpenSRF::Application/;\r
-\r
-sub text_reverse {\r
- my ($self , $conn, $text) = @_;\r
- my $reversed_text = scalar reverse($text);\r
- return $reversed_text;\r
-}\r
-\r
-__PACKAGE__->register_method(\r
- method => 'text_reverse',\r
- api_name => 'opensrf.simple-text.reverse'\r
-);\r
-</programlisting>\r
- <simpara>Ten lines of code, and we have a complete OpenSRF service that exposes a single\r
- method and could be deployed quickly on a cluster of servers to meet your\r
- application’s ravenous demand for reversed strings! If you’re unfamiliar with\r
- Perl, the <literal>use OpenSRF::Application; use parent qw/OpenSRF::Application/;</literal>\r
- lines tell this package to inherit methods and properties from the\r
- <literal>OpenSRF::Application</literal> module. For example, the call to\r
- <literal>__PACKAGE__->register_method()</literal> is defined in <literal>OpenSRF::Application</literal> but due to\r
- inheritance is available in this package (named by the special Perl symbol\r
- <literal>__PACKAGE__</literal> that contains the current package name). The <literal>register_method()</literal>\r
- procedure is how we introduce a method to the rest of the OpenSRF world.</simpara>\r
- <simplesect id="serviceRegistration">\r
- <title>Registering a service with the OpenSRF configuration files</title>\r
- <simpara>Two files control most of the configuration for OpenSRF:</simpara>\r
- <itemizedlist>\r
- <listitem>\r
- <simpara>\r
- <literal>opensrf.xml</literal> contains the configuration for the service itself, as well as\r
- a list of which application servers in your OpenSRF cluster should start\r
- the service.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- <literal>opensrf_core.xml</literal> (often referred to as the "bootstrap configuration"\r
- file) contains the OpenSRF networking information, including the XMPP server\r
- connection credentials for the public and private routers. You only need to touch\r
- this for a new service if the new service needs to be accessible via the\r
- public router.\r
- </simpara>\r
- <indexterm><primary>configuration files</primary><secondary>opensrf_core.xml</secondary></indexterm>\r
- </listitem>\r
- </itemizedlist>\r
- <simpara>Begin by defining the service itself in <literal>opensrf.xml</literal>. To register the\r
- <literal>opensrf.simple-text</literal> service, add the following section to the <literal><apps></literal>\r
- element (corresponding to the XPath <literal>/opensrf/default/apps/</literal>):</simpara>\r
- <indexterm><primary>configuration files</primary><secondary>opensrf.xml</secondary></indexterm>\r
-<programlisting language="xml" linenumbering="unnumbered">\r
-<apps>\r
- <opensrf.simple-text> <co id="CO1-1"/> \r
- <keepalive>3</keepalive><co id="CO1-2"/> \r
- <stateless>1</stateless><co id="CO1-3"/>\r
- <language>perl</language><co id="CO1-4"/> \r
- <implementation>OpenSRF::Application::Demo::SimpleText</implementation><co id="CO1-5"/> \r
- <max_requests>100</max_requests><co id="CO1-6"/> \r
- <unix_config>\r
- <max_requests>1000</max_requests> <co id="CO1-7"/> \r
- <unix_log>opensrf.simple-text_unix.log</unix_log> <co id="CO1-8"/> \r
- <unix_sock>opensrf.simple-text_unix.sock</unix_sock><co id="CO1-9"/> \r
- <unix_pid>opensrf.simple-text_unix.pid</unix_pid> <co id="CO1-10"/> \r
- <min_children>5</min_children> <co id="CO1-11"/> \r
- <max_children>15</max_children><co id="CO1-12"/> \r
- <min_spare_children>2</min_spare_children><co id="CO1-13"/> \r
- <max_spare_children>5</max_spare_children> <co id="CO1-14"/> \r
- </unix_config>\r
- </opensrf.simple-text>\r
-\r
- <!-- other OpenSRF services registered here... -->\r
-</apps>\r
-</programlisting>\r
- <calloutlist>\r
- <callout arearefs="CO1-1">\r
- <simpara>\r
- The element name is the name that the OpenSRF control scripts use to refer\r
- to the service.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO1-2">\r
- <simpara>\r
- The <literal><keepalive></literal> element specifies the interval (in seconds) between\r
- checks to determine if the service is still running.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO1-3">\r
- <simpara>\r
- The <literal><stateless></literal> element specifies whether OpenSRF clients can call\r
- methods from this service without first having to create a connection to a\r
- specific service backend process for that service. If the value is <literal>1</literal>, then\r
- the client can simply issue a request and the router will forward the request\r
- to an available service and the result will be returned directly to the client.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO1-4">\r
- <simpara>\r
- The <literal><language></literal> element specifies the programming language in which the\r
- service is implemented.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO1-5">\r
- <simpara>\r
- The <literal><implementation></literal> element pecifies the name of the library or module\r
- in which the service is implemented.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO1-6">\r
- <simpara>\r
- (C implementations only): The <literal><max_requests></literal> element, as a direct child\r
- of the service element name, specifies the maximum number of requests a process\r
- serves before it is killed and replaced by a new process.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO1-7">\r
- <simpara>\r
- (Perl implementations only): The <literal><max_requests></literal> element, as a direct\r
- child of the <literal><unix_config></literal> element, specifies the maximum number of requests\r
- a process serves before it is killed and replaced by a new process.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO1-8">\r
- <simpara>\r
- The <literal><unix_log></literal> element specifies the name of the log file for\r
- language-specific log messages such as syntax warnings.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO1-9">\r
- <simpara>\r
- The <literal><unix_sock></literal> element specifies the name of the UNIX socket used for\r
- inter-process communications.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO1-10">\r
- <simpara>\r
- The <literal><unix_pid></literal> element specifies the name of the PID file for the\r
- master process for the service.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO1-11">\r
- <simpara>\r
- The <literal><min_children></literal> element specifies the minimum number of child\r
- processes that should be running at any given time.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO1-12">\r
- <simpara>\r
- The <literal><max_children></literal> element specifies the maximum number of child\r
- processes that should be running at any given time.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO1-13">\r
- <simpara>\r
- The <literal><min_spare_children></literal> element specifies the minimum number of idle\r
- child processes that should be available to handle incoming requests. If there\r
- are fewer than this number of spare child processes, new processes will be\r
- spawned.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO1-14">\r
- <simpara>\r
- The`<max_spare_children>` element specifies the maximum number of idle\r
- child processes that should be available to handle incoming requests. If there\r
- are more than this number of spare child processes, the extra processes will be\r
- killed.\r
- </simpara>\r
- </callout>\r
- </calloutlist>\r
- <simpara>To make the service accessible via the public router, you must also\r
- edit the <literal>opensrf_core.xml</literal> configuration file to add the service to the list\r
- of publicly accessible services:</simpara>\r
- <formalpara><title>Making a service publicly accessible in <literal>opensrf_core.xml</literal></title><para>\r
-<programlisting language="xml" linenumbering="unnumbered">\r
-<router><co id="CO2-1"/> \r
- <!-- This is the public router. On this router, we only register applications\r
- which should be accessible to everyone on the opensrf network -->\r
- <name>router</name>\r
- <domain>public.localhost</domain><co id="CO2-2"/>\r
- <services>\r
- <service>opensrf.math</service>\r
- <service>opensrf.simple-text</service> <co id="CO2-3"/> \r
- </services>\r
-</router>\r
-</programlisting>\r
- </para></formalpara>\r
- <calloutlist>\r
- <callout arearefs="CO2-1">\r
- <simpara>\r
- This section of the <literal>opensrf_core.xml</literal> file is located at XPath\r
- <literal>/config/opensrf/routers/</literal>.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO2-2">\r
- <simpara>\r
- <literal>public.localhost</literal> is the canonical public router domain in the OpenSRF\r
- installation instructions.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO2-3">\r
- <simpara>\r
- Each <literal><service></literal> element contained in the <literal><services></literal> element\r
- offers their services via the public router as well as the private router.\r
- </simpara>\r
- </callout>\r
- </calloutlist>\r
- <simpara>Once you have defined the new service, you must restart the OpenSRF Router\r
- to retrieve the new configuration and start or restart the service itself.</simpara>\r
- </simplesect>\r
- <simplesect id="_calling_an_opensrf_method">\r
- <title>Calling an OpenSRF method</title>\r
- <indexterm><primary>srfsh</primary></indexterm>\r
- <simpara>OpenSRF clients in any supported language can invoke OpenSRF services in any\r
- supported language. So let’s see a few examples of how we can call our fancy\r
- new <literal>opensrf.simple-text.reverse()</literal> method:</simpara>\r
- <simplesect id="_calling_opensrf_methods_from_the_srfsh_client">\r
- <title>Calling OpenSRF methods from the srfsh client</title>\r
- <simpara><literal>srfsh</literal> is a command-line tool installed with OpenSRF that you can use to call\r
- OpenSRF methods. To call an OpenSRF method, issue the <literal>request</literal> command and\r
- pass the OpenSRF service and method name as the first two arguments; then pass\r
- one or more JSON objects delimited by commas as the arguments to the method\r
- being invoked.</simpara>\r
- <simpara>The following example calls the <literal>opensrf.simple-text.reverse</literal> method of the\r
- <literal>opensrf.simple-text</literal> OpenSRF service, passing the string <literal>"foobar"</literal> as the\r
- only method argument:</simpara>\r
-<programlisting language="sh" linenumbering="unnumbered">\r
-$ srfsh\r
-srfsh # request opensrf.simple-text opensrf.simple-text.reverse "foobar"\r
-\r
-Received Data: "raboof"\r
-\r
-=------------------------------------\r
-Request Completed Successfully\r
-Request Time in seconds: 0.016718\r
-=------------------------------------\r
-</programlisting>\r
- </simplesect>\r
- <simplesect id="opensrfIntrospection">\r
- <title>Getting documentation for OpenSRF methods from the srfsh client</title>\r
- <simpara>The <literal>srfsh</literal> client also gives you command-line access to retrieving metadata\r
- about OpenSRF services and methods. For a given OpenSRF method, for example,\r
- you can retrieve information such as the minimum number of required arguments,\r
- the data type and a description of each argument, the package or library in\r
- which the method is implemented, and a description of the method. To retrieve\r
- the documentation for an opensrf method from <literal>srfsh</literal>, issue the <literal>introspect</literal>\r
- command, followed by the name of the OpenSRF service and (optionally) the\r
- name of the OpenSRF method. If you do not pass a method name to the <literal>introspect</literal>\r
- command, <literal>srfsh</literal> lists all of the methods offered by the service. If you pass\r
- a partial method name, <literal>srfsh</literal> lists all of the methods that match that portion\r
- of the method name.</simpara>\r
- <note><simpara>The quality and availability of the descriptive information for each\r
- method depends on the developer to register the method with complete and\r
- accurate information. The quality varies across the set of OpenSRF and\r
- Evergreen APIs, although some effort is being put towards improving the\r
- state of the internal documentation.</simpara></note>\r
-<programlisting language="sh" linenumbering="unnumbered">\r
-srfsh# introspect opensrf.simple-text "opensrf.simple-text.reverse"\r
---> opensrf.simple-text\r
-\r
-Received Data: {\r
- "__c":"opensrf.simple-text",\r
- "__p":{\r
- "api_level":1,\r
- "stream":0, <co id="CO3-1"/>\r
- "object_hint":"OpenSRF_Application_Demo_SimpleText",\r
- "remote":0,\r
- "package":"OpenSRF::Application::Demo::SimpleText", <co id="CO3-2"/>\r
- "api_name":"opensrf.simple-text.reverse",<co id="CO3-3"/>\r
- "server_class":"opensrf.simple-text",\r
- "signature":{ <co id="CO3-4"/>\r
- "params":[ <co id="CO3-5"/>\r
- {\r
- "desc":"The string to reverse",\r
- "name":"text",\r
- "type":"string"\r
- }\r
- ],\r
- "desc":"Returns the input string in reverse order\n", <co id="CO3-6"/>\r
- "return":{ <co id="CO3-7"/>\r
- "desc":"Returns the input string in reverse order",\r
- "type":"string"\r
- }\r
- },\r
- "method":"text_reverse", <co id="CO3-8"/>\r
- "argc":1 <co id="CO3-9"/>\r
- }\r
-}\r
-</programlisting>\r
- <calloutlist>\r
- <callout arearefs="CO3-1">\r
- <simpara>\r
- <literal>stream</literal> denotes whether the method supports streaming responses or not.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO3-2">\r
- <simpara>\r
- <literal>package</literal> identifies which package or library implements the method.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO3-3">\r
- <simpara>\r
- <literal>api_name</literal> identifies the name of the OpenSRF method.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO3-4">\r
- <simpara>\r
- <literal>signature</literal> is a hash that describes the parameters for the method.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO3-5">\r
- <simpara>\r
- <literal>params</literal> is an array of hashes describing each parameter in the method;\r
- each parameter has a description (<literal>desc</literal>), name (<literal>name</literal>), and type (<literal>type</literal>).\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO3-6">\r
- <simpara>\r
- <literal>desc</literal> is a string that describes the method itself.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO3-7">\r
- <simpara>\r
- <literal>return</literal> is a hash that describes the return value for the method; it\r
- contains a description of the return value (<literal>desc</literal>) and the type of the\r
- returned value (<literal>type</literal>).\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO3-8">\r
- <simpara>\r
- <literal>method</literal> identifies the name of the function or method in the source\r
- implementation.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO3-9">\r
- <simpara>\r
- <literal>argc</literal> is an integer describing the minimum number of arguments that\r
- must be passed to this method.\r
- </simpara>\r
- </callout>\r
- </calloutlist>\r
- </simplesect>\r
- <simplesect id="_calling_opensrf_methods_from_perl_applications">\r
- <title>Calling OpenSRF methods from Perl applications</title>\r
- <simpara>To call an OpenSRF method from Perl, you must connect to the OpenSRF service,\r
- issue the request to the method, and then retrieve the results.</simpara>\r
-<programlisting language="perl" linenumbering="unnumbered">\r
-#/usr/bin/perl\r
-use strict;\r
-use OpenSRF::AppSession;\r
-use OpenSRF::System;\r
-\r
-OpenSRF::System->bootstrap_client(config_file => '/openils/conf/opensrf_core.xml');<co id="CO4-1"/>\r
-\r
-my $session = OpenSRF::AppSession->create("opensrf.simple-text");<co id="CO4-2"/>\r
-\r
-print "substring: Accepts a string and a number as input, returns a string\n";\r
-my $result = $session->request("opensrf.simple-text.substring", "foobar", 3);<co id="CO4-3"/>\r
-my $request = $result->gather(); <co id="CO4-4"/>\r
-print "Substring: $request\n\n";\r
-\r
-print "split: Accepts two strings as input, returns an array of strings\n";\r
-$request = $session->request("opensrf.simple-text.split", "This is a test", " ");<co id="CO4-5"/>\r
-my $output = "Split: [";\r
-my $element;\r
-while ($element = $request->recv()) { <co id="CO4-6"/>\r
- $output .= $element->content . ", "; <co id="CO4-7"/>\r
-}\r
-$output =~ s/, $/]/;\r
-print $output . "\n\n";\r
-\r
-print "statistics: Accepts an array of strings as input, returns a hash\n";\r
-my @many_strings = [\r
- "First I think I'll have breakfast",\r
- "Then I think that lunch would be nice",\r
- "And then seventy desserts to finish off the day"\r
-];\r
-\r
-$result = $session->request("opensrf.simple-text.statistics", @many_strings); <co id="CO4-8"/>\r
-$request = $result->gather(); <co id="CO4-9"/>\r
-print "Length: " . $result->{'length'} . "\n";\r
-print "Word count: " . $result->{'word_count'} . "\n";\r
-\r
-$session->disconnect(); <co id="CO4-10"/>\r
-</programlisting>\r
- <calloutlist>\r
- <callout arearefs="CO4-1">\r
- <simpara>\r
- The <literal>OpenSRF::System->bootstrap_client()</literal> method reads the OpenSRF\r
- configuration information from the indicated file and creates an XMPP client\r
- connection based on that information.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO4-2">\r
- <simpara>\r
- The <literal>OpenSRF::AppSession->create()</literal> method accepts one argument - the name\r
- of the OpenSRF service to which you want to want to make one or more requests -\r
- and returns an object prepared to use the client connection to make those\r
- requests.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO4-3">\r
- <simpara>\r
- The <literal>OpenSRF::AppSession->request()</literal> method accepts a minimum of one\r
- argument - the name of the OpenSRF method to which you want to make a request -\r
- followed by zero or more arguments to pass to the OpenSRF method as input\r
- values. This example passes a string and an integer to the\r
- <literal>opensrf.simple-text.substring</literal> method defined by the <literal>opensrf.simple-text</literal>\r
- OpenSRF service.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO4-4">\r
- <simpara>\r
- The <literal>gather()</literal> method, called on the result object returned by the\r
- <literal>request()</literal> method, iterates over all of the possible results from the result\r
- object and returns a single variable.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO4-5">\r
- <simpara>\r
- This <literal>request()</literal> call passes two strings to the <literal>opensrf.simple-text.split</literal>\r
- method defined by the <literal>opensrf.simple-text</literal> OpenSRF service and returns (via\r
- <literal>gather()</literal>) a reference to an array of results.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO4-6">\r
- <simpara>\r
- The <literal>opensrf.simple-text.split()</literal> method is a streaming method that\r
- returns an array of results with one element per <literal>recv()</literal> call on the\r
- result object. We could use the <literal>gather()</literal> method to retrieve all of the\r
- results in a single array reference, but instead we simply iterate over\r
- the result variable until there are no more results to retrieve.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO4-7">\r
- <simpara>\r
- While the <literal>gather()</literal> convenience method returns only the content of the\r
- complete set of results for a given request, the <literal>recv()</literal> method returns an\r
- OpenSRF result object with <literal>status</literal>, <literal>statusCode</literal>, and <literal>content</literal> fields as\r
- we saw in <link linkend="OpenSRFOverHTTP">the HTTP results example</link>.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO4-8">\r
- <simpara>\r
- This <literal>request()</literal> call passes an array to the\r
- <literal>opensrf.simple-text.statistics</literal> method defined by the <literal>opensrf.simple-text</literal>\r
- OpenSRF service.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO4-9">\r
- <simpara>\r
- The result object returns a hash reference via <literal>gather()</literal>. The hash\r
- contains the <literal>length</literal> and <literal>word_count</literal> keys we defined in the method.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO4-10">\r
- <simpara>\r
- The <literal>OpenSRF::AppSession->disconnect()</literal> method closes the XMPP client\r
- connection and cleans up resources associated with the session.\r
- </simpara>\r
- </callout>\r
- </calloutlist>\r
- </simplesect>\r
- </simplesect>\r
- <simplesect id="_accepting_and_returning_more_interesting_data_types">\r
- <title>Accepting and returning more interesting data types</title>\r
- <simpara>Of course, the example of accepting a single string and returning a single\r
- string is not very interesting. In real life, our applications tend to pass\r
- around multiple arguments, including arrays and hashes. Fortunately, OpenSRF\r
- makes that easy to deal with; in Perl, for example, returning a reference to\r
- the data type does the right thing. In the following example of a method that\r
- returns a list, we accept two arguments of type string: the string to be split,\r
- and the delimiter that should be used to split the string.</simpara>\r
- <formalpara><title>Basic text splitting method</title><para>\r
-<programlisting language="perl" linenumbering="unnumbered">\r
-sub text_split {\r
- my $self = shift;\r
- my $conn = shift;\r
- my $text = shift;\r
- my $delimiter = shift || ' ';\r
-\r
- my @split_text = split $delimiter, $text;\r
- return \@split_text;\r
-}\r
-\r
-__PACKAGE__->register_method(\r
- method => 'text_split',\r
- api_name => 'opensrf.simple-text.split'\r
-);\r
-</programlisting>\r
- </para></formalpara>\r
- <simpara>We simply return a reference to the list, and OpenSRF does the rest of the work\r
- for us to convert the data into the language-independent format that is then\r
- returned to the caller. As a caller of a given method, you must rely on the\r
- documentation used to register to determine the data structures - if the developer has\r
- added the appropriate documentation.</simpara>\r
- </simplesect>\r
- <simplesect id="_accepting_and_returning_evergreen_objects">\r
- <title>Accepting and returning Evergreen objects</title>\r
- <simpara>OpenSRF is agnostic about objects; its role is to pass JSON back and forth\r
- between OpenSRF clients and services, and it allows the specific clients and\r
- services to define their own semantics for the JSON structures. On top of that\r
- infrastructure, Evergreen offers the fieldmapper: an object-relational mapper\r
- that provides a complete definition of all objects, their properties, their\r
- relationships to other objects, the permissions required to create, read,\r
- update, or delete objects of that type, and the database table or view on which\r
- they are based.</simpara>\r
- <indexterm><primary>Fieldmapper</primary></indexterm>\r
- <simpara>The Evergreen fieldmapper offers a great deal of convenience for working with\r
- complex system objects beyond the basic mapping of classes to database\r
- schemas. Although the result is passed over the wire as a JSON object\r
- containing the indicated fields, fieldmapper-aware clients then turn those\r
- JSON objects into native objects with setter / getter methods for each field.</simpara>\r
- <simpara>All of this metadata about Evergreen objects is defined in the\r
- fieldmapper configuration file (<literal>/openils/conf/fm_IDL.xml</literal>), and access to\r
- these classes is provided by the <literal>open-ils.cstore</literal>, <literal>open-ils.pcrud</literal>, and\r
- <literal>open-ils.reporter-store</literal> OpenSRF services which parse the fieldmapper\r
- configuration file and dynamically register OpenSRF methods for creating,\r
- reading, updating, and deleting all of the defined classes.</simpara>\r
- <formalpara><title>Example fieldmapper class definition for "Open User Summary"</title><para>\r
-<programlisting language="xml" linenumbering="unnumbered">\r
-<class id="mous" controller="open-ils.cstore open-ils.pcrud"\r
- oils_obj:fieldmapper="money::open_user_summary"\r
- oils_persist:tablename="money.open_usr_summary"\r
- reporter:label="Open User Summary"> <co id="CO5-1"/>\r
- <fields oils_persist:primary="usr" oils_persist:sequence=""> <co id="CO5-2"/> \r
- <field name="balance_owed" reporter:datatype="money" /> <co id="CO5-3"/> \r
- <field name="total_owed" reporter:datatype="money" />\r
- <field name="total_paid" reporter:datatype="money" />\r
- <field name="usr" reporter:datatype="link"/>\r
- </fields>\r
- <links>\r
- <link field="usr" reltype="has_a" key="id" map="" class="au"/><co id="CO5-4"/> \r
- </links>\r
- <permacrud xmlns="http://open-ils.org/spec/opensrf/IDL/permacrud/v1"><co id="CO5-5"/> \r
- <actions>\r
- <retrieve permission="VIEW_USER"><co id="CO5-6"/> \r
- <context link="usr" field="home_ou"/><co id="CO5-7"/>\r
- </retrieve>\r
- </actions>\r
- </permacrud>\r
-</class>\r
-</programlisting>\r
- </para></formalpara>\r
- <calloutlist>\r
- <callout arearefs="CO5-1">\r
- <simpara>\r
- The <literal><class></literal> element defines the class:\r
- </simpara>\r
- <itemizedlist>\r
- <listitem>\r
- <simpara>\r
- The <literal>id</literal> attribute defines the <emphasis>class hint</emphasis> that identifies the class both\r
- elsewhere in the fieldmapper configuration file, such as in the value of the\r
- <literal>field</literal> attribute of the <literal><link></literal> element, and in the JSON object itself when\r
- it is instantiated. For example, an "Open User Summary" JSON object would have\r
- the top level property of <literal>"__c":"mous"</literal>.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The <literal>controller</literal> attribute identifies the services that have direct access\r
- to this class. If <literal>open-ils.pcrud</literal> is not listed, for example, then there is\r
- no means to directly access members of this class through a public service.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The <literal>oils_obj:fieldmapper</literal> attribute defines the name of the Perl\r
- fieldmapper class that will be dynamically generated to provide setter and\r
- getter methods for instances of the class.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The <literal>oils_persist:tablename</literal> attribute identifies the schema name and table\r
- name of the database table that stores the data that represents the instances\r
- of this class. In this case, the schema is <literal>money</literal> and the table is\r
- <literal>open_usr_summary</literal>.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The <literal>reporter:label</literal> attribute defines a human-readable name for the class\r
- used in the reporting interface to identify the class. These names are defined\r
- in English in the fieldmapper configuration file; however, they are extracted\r
- so that they can be translated and served in the user’s language of choice.\r
- </simpara>\r
- </listitem>\r
- </itemizedlist>\r
- </callout>\r
- <callout arearefs="CO5-2">\r
- <simpara>\r
- The <literal><fields></literal> element lists all of the fields that belong to the object.\r
- </simpara>\r
- <itemizedlist>\r
- <listitem>\r
- <simpara>\r
- The <literal>oils_persist:primary</literal> attribute identifies the field that acts as the\r
- primary key for the object; in this case, the field with the name <literal>usr</literal>.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The <literal>oils_persist:sequence</literal> attribute identifies the sequence object\r
- (if any) in this database provides values for new instances of this class. In\r
- this case, the primary key is defined by a field that is linked to a different\r
- table, so no sequence is used to populate these instances.\r
- </simpara>\r
- </listitem>\r
- </itemizedlist>\r
- </callout>\r
- <callout arearefs="CO5-3">\r
- <simpara>\r
- Each <literal><field></literal> element defines a single field with the following attributes:\r
- </simpara>\r
- <itemizedlist>\r
- <listitem>\r
- <simpara>\r
- The <literal>name</literal> attribute identifies the column name of the field in the\r
- underlying database table as well as providing a name for the setter / getter\r
- method that can be invoked in the JSON or native version of the object.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The <literal>reporter:datatype</literal> attribute defines how the reporter should treat\r
- the contents of the field for the purposes of querying and display.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The <literal>reporter:label</literal> attribute can be used to provide a human-readable name\r
- for each field; without it, the reporter falls back to the value of the <literal>name</literal>\r
- attribute.\r
- </simpara>\r
- </listitem>\r
- </itemizedlist>\r
- </callout>\r
- <callout arearefs="CO5-4">\r
- <simpara>\r
- The <literal><links></literal> element contains a set of zero or more <literal><link></literal> elements,\r
- each of which defines a relationship between the class being described and\r
- another class.\r
- </simpara>\r
- <itemizedlist>\r
- <listitem>\r
- <simpara>\r
- The <literal>field</literal> attribute identifies the field named in this class that links\r
- to the external class.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The <literal>reltype</literal> attribute identifies the kind of relationship between the\r
- classes; in the case of <literal>has_a</literal>, each value in the <literal>usr</literal> field is guaranteed\r
- to have a corresponding value in the external class.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The <literal>key</literal> attribute identifies the name of the field in the external\r
- class to which this field links.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The rarely-used <literal>map</literal> attribute identifies a second class to which\r
- the external class links; it enables this field to define a direct\r
- relationship to an external class with one degree of separation, to\r
- avoid having to retrieve all of the linked members of an intermediate\r
- class just to retrieve the instances from the actual desired target class.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The <literal>class</literal> attribute identifies the external class to which this field\r
- links.\r
- </simpara>\r
- </listitem>\r
- </itemizedlist>\r
- </callout>\r
- <callout arearefs="CO5-5">\r
- <simpara>\r
- The <literal><permacrud></literal> element defines the permissions that must have been\r
- granted to a user to operate on instances of this class.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO5-6">\r
- <simpara>\r
- The <literal><retrieve></literal> element is one of four possible children of the\r
- <literal><actions></literal> element that define the permissions required for each action:\r
- create, retrieve, update, and delete.\r
- </simpara>\r
- <itemizedlist>\r
- <listitem>\r
- <simpara>\r
- The <literal>permission</literal> attribute identifies the name of the permission that must\r
- have been granted to the user to perform the action.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The <literal>contextfield</literal> attribute, if it exists, defines the field in this class\r
- that identifies the library within the system for which the user must have\r
- prvileges to work. If a user has been granted a given permission, but has not been\r
- granted privileges to work at a given library, they can not perform the action\r
- at that library.\r
- </simpara>\r
- </listitem>\r
- </itemizedlist>\r
- </callout>\r
- <callout arearefs="CO5-7">\r
- <simpara>\r
- The rarely-used <literal><context></literal> element identifies a linked field (<literal>link</literal>\r
- attribute) in this class which links to an external class that holds the field\r
- (<literal>field</literal> attribute) that identifies the library within the system for which the\r
- user must have privileges to work.\r
- </simpara>\r
- </callout>\r
- </calloutlist>\r
- <simpara>When you retrieve an instance of a class, you can ask for the result to\r
- <emphasis>flesh</emphasis> some or all of the linked fields of that class, so that the linked\r
- instances are returned embedded directly in your requested instance. In that\r
- same request you can ask for the fleshed instances to in turn have their linked\r
- fields fleshed. By bundling all of this into a single request and result\r
- sequence, you can avoid the network overhead of requiring the client to request\r
- the base object, then request each linked object in turn.</simpara>\r
- <simpara>You can also iterate over a collection of instances and set the automatically\r
- generated <literal>isdeleted</literal>, <literal>isupdated</literal>, or <literal>isnew</literal> properties to indicate that\r
- the given instance has been deleted, updated, or created respectively.\r
- Evergreen can then act in batch mode over the collection to perform the\r
- requested actions on any of the instances that have been flagged for action.</simpara>\r
- </simplesect>\r
- <simplesect id="_returning_streaming_results">\r
- <title>Returning streaming results</title>\r
- <simpara>In the previous implementation of the <literal>opensrf.simple-text.split</literal> method, we\r
- returned a reference to the complete array of results. For small values being\r
- delivered over the network, this is perfectly acceptable, but for large sets of\r
- values this can pose a number of problems for the requesting client. Consider a\r
- service that returns a set of bibliographic records in response to a query like\r
- "all records edited in the past month"; if the underlying database is\r
- relatively active, that could result in thousands of records being returned as\r
- a single network request. The client would be forced to block until all of the\r
- results are returned, likely resulting in a significant delay, and depending on\r
- the implementation, correspondingly large amounts of memory might be consumed\r
- as all of the results are read from the network in a single block.</simpara>\r
- <simpara>OpenSRF offers a solution to this problem. If the method returns results that\r
- can be divided into separate meaningful units, you can register the OpenSRF\r
- method as a streaming method and enable the client to loop over the results one\r
- unit at a time until the method returns no further results. In addition to\r
- registering the method with the provided name, OpenSRF also registers an additional\r
- method with <literal>.atomic</literal> appended to the method name. The <literal>.atomic</literal> variant gathers\r
- all of the results into a single block to return to the client, giving the caller\r
- the ability to choose either streaming or atomic results from a single method\r
- definition.</simpara>\r
- <simpara>In the following example, the text splitting method has been reimplemented to\r
- support streaming; very few changes are required:</simpara>\r
- <formalpara><title>Text splitting method - streaming mode</title><para>\r
-<programlisting language="perl" linenumbering="unnumbered">\r
-sub text_split {\r
- my $self = shift;\r
- my $conn = shift;\r
- my $text = shift;\r
- my $delimiter = shift || ' ';\r
-\r
- my @split_text = split $delimiter, $text;\r
- foreach my $string (@split_text) { <co id="CO6-1"/>\r
- $conn->respond($string);\r
- }\r
- return undef;\r
-}\r
-\r
-__PACKAGE__->register_method(\r
- method => 'text_split',\r
- api_name => 'opensrf.simple-text.split',\r
- stream => 1<co id="CO6-2"/>\r
-);\r
-</programlisting>\r
- </para></formalpara>\r
- <calloutlist>\r
- <callout arearefs="CO6-1">\r
- <simpara>\r
- Rather than returning a reference to the array, a streaming method loops\r
- over the contents of the array and invokes the <literal>respond()</literal> method of the\r
- connection object on each element of the array.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO6-2">\r
- <simpara>\r
- Registering the method as a streaming method instructs OpenSRF to also\r
- register an atomic variant (<literal>opensrf.simple-text.split.atomic</literal>).\r
- </simpara>\r
- </callout>\r
- </calloutlist>\r
- </simplesect>\r
- <simplesect id="_error_warning_info_debug">\r
- <title>Error! Warning! Info! Debug!</title>\r
- <simpara>As hard as it may be to believe, it is true: applications sometimes do not\r
- behave in the expected manner, particularly when they are still under\r
- development. The service language bindings for OpenSRF include integrated\r
- support for logging messages at the levels of ERROR, WARNING, INFO, DEBUG, and\r
- the extremely verbose INTERNAL to either a local file or to a syslogger\r
- service. The destination of the log files, and the level of verbosity to be\r
- logged, is set in the <literal>opensrf_core.xml</literal> configuration file. To add logging to\r
- our Perl example, we just have to add the <literal>OpenSRF::Utils::Logger</literal> package to our\r
- list of used Perl modules, then invoke the logger at the desired logging level.</simpara>\r
- <simpara>You can include many calls to the OpenSRF logger; only those that are higher\r
- than your configured logging level will actually hit the log. The following\r
- example exercises all of the available logging levels in OpenSRF:</simpara>\r
-<programlisting language="perl" linenumbering="unnumbered">\r
-use OpenSRF::Utils::Logger;\r
-my $logger = OpenSRF::Utils::Logger;\r
-# some code in some function\r
-{\r
- $logger->error("Hmm, something bad DEFINITELY happened!");\r
- $logger->warn("Hmm, something bad might have happened.");\r
- $logger->info("Something happened.");\r
- $logger->debug("Something happened; here are some more details.");\r
- $logger->internal("Something happened; here are all the gory details.")\r
-}\r
-</programlisting>\r
- <simpara>If you call the mythical OpenSRF method containing the preceding OpenSRF logger\r
- statements on a system running at the default logging level of INFO, you will\r
- only see the INFO, WARN, and ERR messages, as follows:</simpara>\r
- <formalpara><title>Results of logging calls at the default level of INFO</title><para>\r
-<screen>\r
-[2010-03-17 22:27:30] opensrf.simple-text [ERR :5681:SimpleText.pm:277:] \r
-[2010-03-17 22:27:30] opensrf.simple-text [WARN:5681:SimpleText.pm:278:] \r
-[2010-03-17 22:27:30] opensrf.simple-text [INFO:5681:SimpleText.pm:279:] \r
-</screen>\r
- </para></formalpara>\r
- <simpara>If you then increase the the logging level to INTERNAL (5), the logs will\r
- contain much more information, as follows:</simpara>\r
- <formalpara><title>Results of logging calls at the default level of INTERNAL</title><para>\r
-<screen>\r
-[2010-03-17 22:48:11] opensrf.simple-text [ERR :5934:SimpleText.pm:277:] \r
-[2010-03-17 22:48:11] opensrf.simple-text [WARN:5934:SimpleText.pm:278:] \r
-[2010-03-17 22:48:11] opensrf.simple-text [INFO:5934:SimpleText.pm:279:] \r
-[2010-03-17 22:48:11] opensrf.simple-text [DEBG:5934:SimpleText.pm:280:] \r
-[2010-03-17 22:48:11] opensrf.simple-text [INTL:5934:SimpleText.pm:281:] \r
-[2010-03-17 22:48:11] opensrf.simple-text [ERR :5934:SimpleText.pm:283:] \r
-[2010-03-17 22:48:21] opensrf.simple-text [INTL:5934:Cache.pm:125:] \r
-[2010-03-17 22:48:21] opensrf.simple-text [DEBG:5934:Application.pm:579:] \r
-[2010-03-17 22:48:21] opensrf.simple-text [DEBG:5934:Application.pm:586:] \r
-[2010-03-17 22:48:21] opensrf.simple-text [DEBG:5934:Application.pm:190:] \r
-[2010-03-17 22:48:21] opensrf.simple-text [INTL:5934:AppSession.pm:780:] Calling queue_wait(0)\r
-[2010-03-17 22:48:21] opensrf.simple-text [INTL:5934:AppSession.pm:769:] Resending...0\r
-[2010-03-17 22:48:21] opensrf.simple-text [INTL:5934:AppSession.pm:450:] In send\r
-[2010-03-17 22:48:21] opensrf.simple-text [DEBG:5934:AppSession.pm:506:] \r
-[2010-03-17 22:48:21] opensrf.simple-text [DEBG:5934:AppSession.pm:506:] \r
-...\r
-</screen>\r
- </para></formalpara>\r
- <simpara>To see everything that is happening in OpenSRF, try leaving your logging level\r
- set to INTERNAL for a few minutes - just ensure that you have a lot of free disk\r
- space available if you have a moderately busy system!</simpara>\r
- </simplesect>\r
- <simplesect id="_caching_results_one_secret_of_scalability">\r
- <title>Caching results: one secret of scalability</title>\r
- <indexterm><primary>search results</primary><secondary>caching</secondary></indexterm>\r
- <simpara>If you have ever used an application that depends on a remote Web service\r
- outside of your control — say, if you need to retrieve results from a\r
- microblogging service — you know the pain of latency and dependability (or the\r
- lack thereof). To improve the response time for OpenSRF services, you can take\r
- advantage of the support offered by the <literal>OpenSRF::Utils::Cache</literal> module for\r
- communicating with a local instance or cluster of <literal>memcache</literal> daemons to store\r
- and retrieve persistent values. The following example demonstrates caching\r
- by sleeping for 10 seconds the first time it receives a given cache key and\r
- cannot retrieve a corresponding value from the cache:</simpara>\r
- <formalpara><title>Simple caching OpenSRF service</title><para>\r
-<programlisting language="perl" linenumbering="unnumbered">\r
-use OpenSRF::Utils::Cache;<co id="CO7-1"/>\r
-sub test_cache {\r
- my $self = shift;\r
- my $conn = shift;\r
- my $test_key = shift;\r
- my $cache = OpenSRF::Utils::Cache->new('global'); <co id="CO7-2"/>\r
- my $cache_key = "opensrf.simple-text.test_cache.$test_key"; <co id="CO7-3"/>\r
- my $result = $cache->get_cache($cache_key) || undef; <co id="CO7-4"/>\r
- if ($result) {\r
- $logger->info("Resolver found a cache hit");\r
- return $result;\r
- }\r
- sleep 10; <co id="CO7-5"/>\r
- my $cache_timeout = 300; <co id="CO7-6"/>\r
- $cache->put_cache($cache_key, "here", $cache_timeout); <co id="CO7-7"/>\r
- return "There was no cache hit.";\r
-}\r
-</programlisting>\r
- </para></formalpara>\r
- <calloutlist>\r
- <callout arearefs="CO7-1">\r
- <simpara>\r
- The OpenSRF::Utils::Cache module provides access to the built-in caching\r
- support in OpenSRF.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO7-2">\r
- <simpara>\r
- The constructor for the cache object accepts a single argument to define\r
- the cache type for the object. Each cache type can use a separate <literal>memcache</literal>\r
- server to keep the caches separated. Most Evergreen services use the <literal>global</literal>\r
- cache, while the <literal>anon</literal> cache is used for Web sessions.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO7-3">\r
- <simpara>\r
- The cache key is simply a string that uniquely identifies the value you\r
- want to store or retrieve. This line creates a cache key based on the OpenSRF\r
- method name and request input value.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO7-4">\r
- <simpara>\r
- The <literal>get_cache()</literal> method checks to see if the cache key already exists. If\r
- a matching key is found, the service immediately returns the stored value.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO7-5">\r
- <simpara>\r
- If the cache key does not exist, the code sleeps for 10 seconds to\r
- simulate a call to a slow remote Web service or an intensive process.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO7-6">\r
- <simpara>\r
- The <literal>$cache_timeout</literal> variable represents a value for the lifetime of the\r
- cache key in seconds.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO7-7">\r
- <simpara>\r
- After the code retrieves its value (or, in the case of this example,\r
- finishes sleeping), it creates the cache entry by calling the <literal>put_cache()</literal>\r
- method. The method accepts three arguments: the cache key, the value to be\r
- stored ("here"), and the timeout value in seconds to ensure that we do not\r
- return stale data on subsequent calls.\r
- </simpara>\r
- </callout>\r
- </calloutlist>\r
- </simplesect>\r
- <simplesect id="_initializing_the_service_and_its_children_child_labour">\r
- <title>Initializing the service and its children: child labour</title>\r
- <simpara>When an OpenSRF service is started, it looks for a procedure called\r
- <literal>initialize()</literal> to set up any global variables shared by all of the children of\r
- the service. The <literal>initialize()</literal> procedure is typically used to retrieve\r
- configuration settings from the <literal>opensrf.xml</literal> file.</simpara>\r
- <simpara>An OpenSRF service spawns one or more children to actually do the work\r
- requested by callers of the service. For every child process an OpenSRF service\r
- spawns, the child process clones the parent environment and then each child\r
- process runs the <literal>child_init()</literal> process (if any) defined in the OpenSRF service\r
- to initialize any child-specific settings.</simpara>\r
- <simpara>When the OpenSRF service kills a child process, it invokes the <literal>child_exit()</literal>\r
- procedure (if any) to clean up any resources associated with the child process.\r
- Similarly, when the OpenSRF service is stopped, it calls the <literal>DESTROY()</literal>\r
- procedure to clean up any remaining resources.</simpara>\r
- </simplesect>\r
- <simplesect id="_retrieving_configuration_settings">\r
- <title>Retrieving configuration settings</title>\r
- <simpara>The settings for OpenSRF services are maintained in the <literal>opensrf.xml</literal> XML\r
- configuration file. The structure of the XML document consists of a root\r
- element <literal><opensrf></literal> containing two child elements:</simpara>\r
- <itemizedlist>\r
- <listitem>\r
- <simpara>\r
- The <literal><default></literal> element contains an <literal><apps></literal> element describing all\r
- OpenSRF services running on this system — see <xref linkend="serviceRegistration"/> --, as\r
- well as any other arbitrary XML descriptions required for global configuration\r
- purposes. For example, Evergreen uses this section for email notification and\r
- inter-library patron privacy settings.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The <literal><hosts></literal> element contains one element per host that participates in\r
- this OpenSRF system. Each host element must include an <literal><activeapps></literal> element\r
- that lists all of the services to start on this host when the system starts\r
- up. Each host element can optionally override any of the default settings.\r
- </simpara>\r
- </listitem>\r
- </itemizedlist>\r
- <simpara>OpenSRF includes a service named <literal>opensrf.settings</literal> to provide distributed\r
- cached access to the configuration settings with a simple API:</simpara>\r
- <itemizedlist>\r
- <listitem>\r
- <simpara>\r
- <literal>opensrf.settings.default_config.get</literal> accepts zero arguments and returns\r
- the complete set of default settings as a JSON document.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- <literal>opensrf.settings.host_config.get</literal> accepts one argument (hostname) and\r
- returns the complete set of settings, as customized for that hostname, as a\r
- JSON document.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- <literal>opensrf.settings.xpath.get</literal> accepts one argument (an\r
- <ulink url="http://www.w3.org/TR/xpath/">XPath</ulink> expression) and returns the portion of\r
- the configuration file that matches the expression as a JSON document.\r
- </simpara>\r
- </listitem>\r
- </itemizedlist>\r
- <simpara>For example, to determine whether an Evergreen system uses the opt-in\r
- support for sharing patron information between libraries, you could either\r
- invoke the <literal>opensrf.settings.default_config.get</literal> method and parse the\r
- JSON document to determine the value, or invoke the <literal>opensrf.settings.xpath.get</literal>\r
- method with the XPath <literal>/opensrf/default/share/user/opt_in</literal> argument to\r
- retrieve the value directly.</simpara>\r
- <simpara>In practice, OpenSRF includes convenience libraries in all of its client\r
- language bindings to simplify access to configuration values. C offers\r
- osrfConfig.c, Perl offers <literal>OpenSRF::Utils::SettingsClient</literal>, Java offers\r
- <literal>org.opensrf.util.SettingsClient</literal>, and Python offers <literal>osrf.set</literal>. These\r
- libraries locally cache the configuration file to avoid network roundtrips for\r
- every request and enable the developer to request specific values without\r
- having to manually construct XPath expressions.</simpara>\r
- </simplesect>\r
- </section>\r
- <section id="_getting_under_the_covers_with_opensrf">\r
- <title>OpenSRF Communication Flows</title>\r
- <indexterm><primary>OpenSRF</primary><secondary>Communication Flows</secondary></indexterm>\r
- <simpara>Now that you have seen that it truly is easy to create an OpenSRF service, we\r
- can take a look at what is going on under the covers to make all of this work\r
- for you.</simpara>\r
- <simplesect id="_get_on_the_messaging_bus_safely">\r
- <title>Get on the messaging bus - safely</title>\r
- <simpara>One of the core innovations of OpenSRF was to use the Extensible Messaging and\r
- Presence Protocol (XMPP, more colloquially known as Jabber) as the messaging\r
- bus that ties OpenSRF services together across servers. XMPP is an "XML\r
- protocol for near-real-time messaging, presence, and request-response services"\r
- (<ulink url="http://www.ietf.org/rfc/rfc3920.txt">http://www.ietf.org/rfc/rfc3920.txt</ulink>) that OpenSRF relies on to handle most of\r
- the complexity of networked communications. OpenSRF requres an XMPP server\r
- that supports multiple domains such as <ulink url="http://www.ejabberd.im/">ejabberd</ulink>.\r
- Multiple domain support means that a single server can support XMPP virtual\r
- hosts with separate sets of users and access privileges per domain. By\r
- routing communications through separate public and private XMPP domains,\r
- OpenSRF services gain an additional layer of security.</simpara>\r
- <simpara>The <ulink url="http://evergreen-ils.org/dokuwiki/doku.php?id=opensrf:1.2:install">OpenSRF\r
- installation documentation</ulink> instructs you to create two separate hostnames\r
- (<literal>private.localhost</literal> and <literal>public.localhost</literal>) to use as XMPP domains. OpenSRF\r
- can control access to its services based on the domain of the client and\r
- whether a given service allows access from clients on the public domain. When\r
- you start OpenSRF, the first XMPP clients that connect to the XMPP server are\r
- the OpenSRF public and private <emphasis>routers</emphasis>. OpenSRF routers maintain a list of\r
- available services and connect clients to available services. When an OpenSRF\r
- service starts, it establishes a connection to the XMPP server and registers\r
- itself with the private router. The OpenSRF configuration contains a list of\r
- public OpenSRF services, each of which must also register with the public\r
- router.</simpara>\r
- </simplesect>\r
- <simplesect id="_opensrf_communication_flows_over_xmpp">\r
- <title>OpenSRF communication flows over XMPP</title>\r
- <indexterm><primary>XMPP</primary></indexterm>\r
- <simpara>In a minimal OpenSRF deployment, two XMPP users named "router" connect to the\r
- XMPP server, with one connected to the private XMPP domain and one connected to\r
- the public XMPP domain. Similarly, two XMPP users named "opensrf" connect to\r
- the XMPP server via the private and public XMPP domains. When an OpenSRF\r
- service is started, it uses the "opensrf" XMPP user to advertise its\r
- availability with the corresponding router on that XMPP domain; the XMPP server\r
- automatically assigns a Jabber ID (<emphasis>JID</emphasis>) based on the client hostname to each\r
- service’s listener process and each connected drone process waiting to carry\r
- out requests. When an OpenSRF router receives a request to invoke a method on a\r
- given service, it connects the requester to the next available listener in the\r
- list of registered listeners for that service.</simpara>\r
- <simpara>Services and clients connect to the XMPP server using a single set of XMPP\r
- client credentials (for example, <literal>opensrf@private.localhost</literal>), but use XMPP\r
- resource identifiers to differentiate themselves in the JID for each\r
- connection. For example, the JID for a copy of the <literal>opensrf.simple-text</literal>\r
- service with process ID <literal>6285</literal> that has connected to the <literal>private.localhost</literal>\r
- domain using the <literal>opensrf</literal> XMPP client credentials could be\r
- <literal>opensrf@private.localhost/opensrf.simple-text_drone_at_localhost_6285</literal>. By\r
- convention, the user name for OpenSRF clients is <literal>opensrf</literal>, and the user name\r
- for OpenSRF routers is <literal>router</literal>, so the XMPP server for OpenSRF will have four\r
- separate users registered:\r
- * <literal>opensrf@private.localhost</literal> is an OpenSRF client that connects with these\r
- credentials and which can access any OpenSRF service.\r
- * <literal>opensrf@public.localhost</literal> is an OpenSRF client that connects with these\r
- credentials and which can only access OpenSRF services that have registered\r
- with the public router.\r
- * <literal>router@private.localhost</literal> is the private OpenSRF router with which all\r
- services register.\r
- * <literal>router@public.localhost</literal> is the public OpenSRF router with which only\r
- services that must be publicly accessible register.</simpara>\r
- <simpara>All OpenSRF services automatically register themselves with the private XMPP\r
- domain, but only those services that register themselves with the public XMPP\r
- domain can be invoked from public OpenSRF clients. The OpenSRF client and\r
- router user names, passwords, and domain names, along with the list of services\r
- that should be public, are contained in the <literal>opensrf_core.xml</literal> configuration\r
- file.</simpara>\r
- </simplesect>\r
- <simplesect id="OpenSRFOverHTTP">\r
- <title>OpenSRF communication flows over HTTP</title>\r
- <indexterm><primary>HTTP</primary><secondary>translator</secondary></indexterm>\r
- <simpara>In some contexts, access to a full XMPP client is not a practical option. For\r
- example, while XMPP clients have been implemented in JavaScript, you might\r
- be concerned about browser compatibility and processing overhead - or you might\r
- want to issue OpenSRF requests from the command line with <literal>curl</literal>. Fortunately,\r
- any OpenSRF service registered with the public router is accessible via the\r
- OpenSRF HTTP Translator. The OpenSRF HTTP Translator implements the\r
- <ulink url="http://www.open-ils.org/dokuwiki/doku.php?id=opensrf_over_http">OpenSRF-over-HTTP\r
- proposed specification</ulink> as an Apache module that translates HTTP requests into\r
- OpenSRF requests and returns OpenSRF results as HTTP results to the initiating\r
- HTTP client.</simpara>\r
- <formalpara><title>Issuing an HTTP POST request to an OpenSRF method via the OpenSRF HTTP Translator</title><para>\r
-<programlisting language="bash" linenumbering="unnumbered">\r
-# curl request broken up over multiple lines for legibility\r
-curl -H "X-OpenSRF-service: opensrf.simple-text"<co id="CO8-1"/>\r
- --data 'osrf-msg=[ \<co id="CO8-2"/>\r
- {"__c":"osrfMessage","__p":{"threadTrace":0,"locale":"en-CA", <co id="CO8-3"/>\r
- "type":"REQUEST","payload": {"__c":"osrfMethod","__p": \r
- {"method":"opensrf.simple-text.reverse","params":["foobar"]} \r
- }} \r
- }]' \r
-http://localhost/osrf-http-translator <co id="CO8-4"/>\r
-</programlisting>\r
- </para></formalpara>\r
- <calloutlist>\r
- <callout arearefs="CO8-1">\r
- <simpara>\r
- The <literal>X-OpenSRF-service</literal> header identifies the OpenSRF service of interest.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO8-2">\r
- <simpara>\r
- The POST request consists of a single parameter, the <literal>osrf-msg</literal> value,\r
- which contains a JSON array.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO8-3">\r
- <simpara>\r
- The first object is an OpenSRF message (<literal>"__c":"osrfMessage"</literal>) with a set of\r
- parameters (<literal>"__p":{}</literal>).\r
- </simpara>\r
- <itemizedlist>\r
- <listitem>\r
- <simpara>\r
- The identifier for the request (<literal>"threadTrace":0</literal>); this value is echoed\r
- back in the result.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The message type (<literal>"type":"REQUEST"</literal>).\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The locale for the message; if the OpenSRF method is locale-sensitive, it\r
- can check the locale for each OpenSRF request and return different information\r
- depending on the locale.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The payload of the message (<literal>"payload":{}</literal>) containing the OpenSRF method\r
- request (<literal>"__c":"osrfMethod"</literal>) and its parameters (<literal>"__p:"{}</literal>).\r
- </simpara>\r
- <itemizedlist>\r
- <listitem>\r
- <simpara>\r
- The method name for the request (<literal>"method":"opensrf.simple-text.reverse"</literal>).\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- A set of JSON parameters to pass to the method (<literal>"params":["foobar"]</literal>); in\r
- this case, a single string <literal>"foobar"</literal>.\r
- </simpara>\r
- </listitem>\r
- </itemizedlist>\r
- </listitem>\r
- </itemizedlist>\r
- </callout>\r
- <callout arearefs="CO8-4">\r
- <simpara>\r
- The URL on which the OpenSRF HTTP translator is listening,\r
- <literal>/osrf-http-translator</literal> is the default location in the Apache example\r
- configuration files shipped with the OpenSRF source, but this is configurable.\r
- </simpara>\r
- </callout>\r
- </calloutlist>\r
- <formalpara><title>Results from an HTTP POST request to an OpenSRF method via the OpenSRF HTTP Translator</title><para>\r
-<programlisting language="bash" linenumbering="unnumbered">\r
-# HTTP response broken up over multiple lines for legibility\r
-[{"__c":"osrfMessage","__p": <co id="CO9-1"/>\r
- {"threadTrace":0, "payload": <co id="CO9-2"/>\r
- {"__c":"osrfResult","__p": <co id="CO9-3"/>\r
- {"status":"OK","content":"raboof","statusCode":200} <co id="CO9-4"/>\r
- },"type":"RESULT","locale":"en-CA" <co id="CO9-5"/>\r
- }\r
-},\r
-{"__c":"osrfMessage","__p": <co id="CO9-6"/>\r
- {"threadTrace":0,"payload": <co id="CO9-7"/>\r
- {"__c":"osrfConnectStatus","__p": <co id="CO9-8"/>\r
- {"status":"Request Complete","statusCode":205}<co id="CO9-9"/>\r
- },"type":"STATUS","locale":"en-CA" <co id="CO9-10"/>\r
- }\r
-}]\r
-</programlisting>\r
- </para></formalpara>\r
- <calloutlist>\r
- <callout arearefs="CO9-1">\r
- <simpara>\r
- The OpenSRF HTTP Translator returns an array of JSON objects in its\r
- response. Each object in the response is an OpenSRF message\r
- (<literal>"__c":"osrfMessage"</literal>) with a collection of response parameters (<literal>"__p":</literal>).\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO9-2">\r
- <simpara>\r
- The OpenSRF message identifier (<literal>"threadTrace":0</literal>) confirms that this\r
- message is in response to the request matching the same identifier.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO9-3">\r
- <simpara>\r
- The message includes a payload JSON object (<literal>"payload":</literal>) with an OpenSRF\r
- result for the request (<literal>"__c":"osrfResult"</literal>).\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO9-4">\r
- <simpara>\r
- The result includes a status indicator string (<literal>"status":"OK"</literal>), the content\r
- of the result response - in this case, a single string "raboof"\r
- (<literal>"content":"raboof"</literal>) - and an integer status code for the request\r
- (<literal>"statusCode":200</literal>).\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO9-5">\r
- <simpara>\r
- The message also includes the message type (<literal>"type":"RESULT"</literal>) and the\r
- message locale (<literal>"locale":"en-CA"</literal>).\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO9-6">\r
- <simpara>\r
- The second message in the set of results from the response.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO9-7">\r
- <simpara>\r
- Again, the message identifier confirms that this message is in response to\r
- a particular request.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO9-8">\r
- <simpara>\r
- The payload of the message denotes that this message is an\r
- OpenSRF connection status message (<literal>"__c":"osrfConnectStatus"</literal>), with some\r
- information about the particular OpenSRF connection that was used for this\r
- request.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO9-9">\r
- <simpara>\r
- The response parameters for an OpenSRF connection status message include a\r
- verbose status (<literal>"status":"Request Complete"</literal>) and an integer status code for\r
- the connection status (`"statusCode":205).\r
- </simpara>\r
- </callout>\r
- <callout arearefs="CO9-10">\r
- <simpara>\r
- The message also includes the message type (<literal>"type":"RESULT"</literal>) and the\r
- message locale (<literal>"locale":"en-CA"</literal>).\r
- </simpara>\r
- </callout>\r
- </calloutlist>\r
- <tip><simpara>Before adding a new public OpenSRF service, ensure that it does\r
- not introduce privilege escalation or unchecked access to data. For example,\r
- the Evergreen <literal>open-ils.cstore</literal> private service is an object-relational mapper\r
- that provides read and write access to the entire Evergreen database, so it\r
- would be catastrophic to expose that service publicly. In comparison, the\r
- Evergreen <literal>open-ils.pcrud</literal> public service offers the same functionality as\r
- <literal>open-ils.cstore</literal> to any connected HTTP client or OpenSRF client, but the\r
- additional authentication and authorization layer in <literal>open-ils.pcrud</literal> prevents\r
- unchecked access to Evergreen’s data.</simpara></tip>\r
- </simplesect>\r
- <simplesect id="_stateless_and_stateful_connections">\r
- <title>Stateless and stateful connections</title>\r
- <simpara>OpenSRF supports both <emphasis>stateless</emphasis> and <emphasis>stateful</emphasis> connections. When an OpenSRF\r
- client issues a <literal>REQUEST</literal> message in a <emphasis>stateless</emphasis> connection, the router\r
- forwards the request to the next available service and the service returns the\r
- result directly to the client.</simpara>\r
- \r
- <simpara>When an OpenSRF client issues a <literal>CONNECT</literal> message to create a <emphasis>stateful</emphasis> conection, the\r
- router returns the Jabber ID of the next available service to the client so\r
- that the client can issue one or more <literal>REQUEST</literal> message directly to that\r
- particular service and the service will return corresponding <literal>RESULT</literal> messages\r
- directly to the client. Until the client issues a <literal>DISCONNECT</literal> message, that\r
- particular service is only available to the requesting client. Stateful connections\r
- are useful for clients that need to make many requests from a particular service,\r
- as it avoids the intermediary step of contacting the router for each request, as\r
- well as for operations that require a controlled sequence of commands, such as a\r
- set of database INSERT, UPDATE, and DELETE statements within a transaction.</simpara>\r
- \r
- </simplesect>\r
- <simplesect id="_message_body_format">\r
- <title>Message body format</title>\r
- <simpara>OpenSRF was an early adopter of JavaScript Object Notation (JSON). While XMPP\r
- is an XML protocol, the Evergreen developers recognized that the compactness of\r
- the JSON format offered a significant reduction in bandwidth for the volume of\r
- messages that would be generated in an application of that size. In addition,\r
- the ability of languages such as JavaScript, Perl, and Python to generate\r
- native objects with minimal parsing offered an attractive advantage over\r
- invoking an XML parser for every message. Instead, the body of the XMPP message\r
- is a simple JSON structure. For a simple request, like the following example\r
- that simply reverses a string, it looks like a significant overhead: but we get\r
- the advantages of locale support and tracing the request from the requester\r
- through the listener and responder (drone).</simpara>\r
- <formalpara><title>A request for opensrf.simple-text.reverse("foobar"):</title><para>\r
-<programlisting language="xml" linenumbering="unnumbered">\r
-<message from='router@private.localhost/opensrf.simple-text'\r
- to='opensrf@private.localhost/opensrf.simple-text_listener_at_localhost_6275'\r
- router_from='opensrf@private.localhost/_karmic_126678.3719_6288'\r
- router_to='' router_class='' router_command='' osrf_xid=''\r
->\r
- <thread>1266781414.366573.12667814146288</thread>\r
- <body>\r
-[\r
- {"__c":"osrfMessage","__p":\r
- {"threadTrace":"1","locale":"en-US","type":"REQUEST","payload":\r
- {"__c":"osrfMethod","__p":\r
- {"method":"opensrf.simple-text.reverse","params":["foobar"]}\r
- }\r
- }\r
- }\r
-]\r
- </body>\r
-</message>\r
-</programlisting>\r
- </para></formalpara>\r
- <formalpara><title>A response from opensrf.simple-text.reverse("foobar")</title><para>\r
-<programlisting language="xml" linenumbering="unnumbered">\r
-<message from='opensrf@private.localhost/opensrf.simple-text_drone_at_localhost_6285'\r
- to='opensrf@private.localhost/_karmic_126678.3719_6288'\r
- router_command='' router_class='' osrf_xid=''\r
->\r
- <thread>1266781414.366573.12667814146288</thread>\r
- <body>\r
-[\r
- {"__c":"osrfMessage","__p":\r
- {"threadTrace":"1","payload":\r
- {"__c":"osrfResult","__p":\r
- {"status":"OK","content":"raboof","statusCode":200}\r
- } ,"type":"RESULT","locale":"en-US"}\r
- },\r
- {"__c":"osrfMessage","__p":\r
- {"threadTrace":"1","payload":\r
- {"__c":"osrfConnectStatus","__p":\r
- {"status":"Request Complete","statusCode":205}\r
- },"type":"STATUS","locale":"en-US"}\r
- }\r
-]\r
- </body>\r
-</message>\r
-</programlisting>\r
- </para></formalpara>\r
- <simpara>The content of the <literal><body></literal> element of the OpenSRF request and result should\r
- look familiar; they match the structure of the <link linkend="OpenSRFOverHTTP">OpenSRF over HTTP examples</link> that we previously dissected.</simpara>\r
- </simplesect>\r
- <simplesect id="_registering_opensrf_methods_in_depth">\r
- <title>Registering OpenSRF methods in depth</title>\r
- <simpara>Let’s explore the call to <literal>__PACKAGE__->register_method()</literal>; most of the members\r
- of the hash are optional, and for the sake of brevity we omitted them in the\r
- previous example. As we have seen in the results of the <link linkend="opensrfIntrospection">introspection call</link>, a\r
- verbose registration method call is recommended to better enable the internal\r
- documentation. Here is the complete set of members that you should pass to\r
- <literal>__PACKAGE__->register_method()</literal>:</simpara>\r
- <itemizedlist>\r
- <listitem>\r
- <simpara>\r
- The <literal>method</literal> member specifies the name of the procedure in this module that is being registered as an OpenSRF method.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The <literal>api_name</literal> member specifies the invocable name of the OpenSRF method; by convention, the OpenSRF service name is used as the prefix.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The optional <literal>api_level</literal> member can be used for versioning the methods to allow the use of a deprecated API, but in practical use is always 1.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The optional <literal>argc</literal> member specifies the minimal number of arguments that the method expects.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The optional <literal>stream</literal> member, if set to any value, specifies that the method supports returning multiple values from a single call to \r
- subsequent requests. OpenSRF automatically creates a corresponding method with ".atomic" appended to its name that returns the complete set of results in a \r
- single request. Streaming methods are useful if you are returning hundreds of records and want to act on the results as they return.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The optional <literal>signature</literal> member is a hash that describes the method’s purpose, arguments, and return value.\r
- </simpara>\r
- <itemizedlist>\r
- <listitem>\r
- <simpara>\r
- The <literal>desc</literal> member of the <literal>signature</literal> hash describes the method’s purpose.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The <literal>params</literal> member of the <literal>signature</literal> hash is an array of hashes in which each array element describes the corresponding method \r
- argument in order.\r
- </simpara>\r
- <itemizedlist>\r
- <listitem>\r
- <simpara>\r
- The <literal>name</literal> member of the argument hash specifies the name of the argument.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The <literal>desc</literal> member of the argument hash describes the argument’s purpose.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The <literal>type</literal> member of the argument hash specifies the data type of the argument: for example, string, integer, boolean, number, array, or hash.\r
- </simpara>\r
- </listitem>\r
- </itemizedlist>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The <literal>return</literal> member of the <literal>signature</literal> hash is a hash that describes the return value of the method.\r
- </simpara>\r
- <itemizedlist>\r
- <listitem>\r
- <simpara>\r
- The <literal>desc</literal> member of the <literal>return</literal> hash describes the return value.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The <literal>type</literal> member of the <literal>return</literal> hash specifies the data type of the return value: for example, string, integer, boolean, number, \r
- array, or hash.\r
- </simpara>\r
- </listitem>\r
- </itemizedlist>\r
- </listitem>\r
- </itemizedlist>\r
- </listitem>\r
- </itemizedlist>\r
- </simplesect>\r
- </section>\r
- <section id="_evergreen_specific_opensrf_services">\r
- <title>Evergreen-specific OpenSRF services</title>\r
- <simpara>Evergreen is currently the primary showcase for the use of OpenSRF as an\r
- application architecture. Evergreen 1.6.1 includes the following\r
- set of OpenSRF services:</simpara>\r
- <itemizedlist>\r
- <listitem>\r
- <simpara>\r
- The <systemitem class="service">open-ils.actor</systemitem> service supports common tasks for working with user\r
- accounts and libraries.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The <systemitem class="service">open-ils.auth</systemitem> service supports authentication of Evergreen users.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The <systemitem class="service">open-ils.booking</systemitem> service supports the management of reservations\r
- for bookable items.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The <systemitem class="service">open-ils.cat</systemitem> service supports common cataloging tasks, such as\r
- creating, modifying, and merging bibliographic and authority records.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The <systemitem class="service">open-ils.circ</systemitem> service supports circulation tasks such as checking\r
- out items and calculating due dates.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The <systemitem class="service">open-ils.collections</systemitem> service supports tasks that assist collections\r
- agencies in contacting users with outstanding fines above a certain\r
- threshold.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The <systemitem class="service">open-ils.cstore</systemitem> private service supports unrestricted access to\r
- Evergreen fieldmapper objects.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The <systemitem class="service">open-ils.ingest</systemitem> private service supports tasks for importing\r
- data such as bibliographic and authority records.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The <systemitem class="service">open-ils.pcrud</systemitem> service supports permission-based access to Evergreen\r
- fieldmapper objects.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The <systemitem class="service">open-ils.penalty</systemitem> penalty service supports the calculation of\r
- penalties for users, such as being blocked from further borrowing, for\r
- conditions such as having too many items checked out or too many unpaid\r
- fines.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The <systemitem class="service">open-ils.reporter</systemitem> service supports the creation and scheduling of\r
- reports.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The <systemitem class="service">open-ils.reporter-store</systemitem> private service supports access to Evergreen\r
- fieldmapper objects for the reporting service.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The <systemitem class="service">open-ils.search</systemitem> service supports searching across bibliographic\r
- records, authority records, serial records, Z39.50 sources, and ZIP codes.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The <systemitem class="service">open-ils.storage</systemitem> private service supports a deprecated method of\r
- providing access to Evergreen fieldmapper objects. Implemented in Perl,\r
- this service has largely been replaced by the much faster C-based\r
- <literal>open-ils.cstore</literal> service.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The <systemitem class="service">open-ils.supercat</systemitem> service supports transforms of MARC records into\r
- other formats, such as MODS, as well as providing Atom and RSS feeds and\r
- SRU access.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The <systemitem class="service">open-ils.trigger</systemitem> private service supports event-based triggers for\r
- actions such as overdue and holds available notification emails.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- The <systemitem class="service">open-ils.vandelay</systemitem> service supports the import and export of batches of\r
- bibliographic and authority records.\r
- </simpara>\r
- </listitem>\r
- </itemizedlist>\r
- <simpara>Of some interest is that the <systemitem class="service">open-ils.reporter-store</systemitem> and <systemitem class="service">open-ils.cstore</systemitem>\r
- services have identical implementations. Surfacing them as separate services\r
- enables a deployer of Evergreen to ensure that the reporting service does not\r
- interfere with the performance-critical <systemitem class="service">open-ils.cstore</systemitem> service. One can also\r
- direct the reporting service to a read-only database replica to, again, avoid\r
- interference with <systemitem class="service">open-ils.cstore</systemitem> which must write to the master database.</simpara>\r
- <simpara>There are only a few significant services that are not built on OpenSRF in\r
- Evergreen 1.6.0, such as the SIP and Z39.50 servers. These services implement\r
- different protocols and build on existing daemon architectures (Simple2ZOOM\r
- for Z39.50), but still rely on the other OpenSRF services to provide access\r
- to the Evergreen data. The non-OpenSRF services are reasonably self-contained\r
- and can be deployed on different servers to deliver the same sort of deployment\r
- flexibility as OpenSRF services, but have the disadvantage of not being\r
- integrated into the same configuration and control infrastructure as the\r
- OpenSRF services.</simpara>\r
- </section>\r
-</chapter>\r
projects / Evergreen-DocBook.git / blobdiff