Fix splling and typos.

[working/Evergreen.git] / 1.6 / development / workshop.xml

<?xml version="1.0" encoding="UTF-8"?>\r
<chapter xml:id="developer_workshop" 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
\r
<chapterinfo>\r
    <title>Evergreen development</title>\r
    <date>February 2010</date>\r
    <author>\r
        <firstname>Dan</firstname>\r
        <surname>Scott</surname>\r
        <email>dscott@laurentian.ca</email>\r
    </author>\r
    <authorinitials>DS</authorinitials>\r
<revhistory><revision><revnumber>1.0</revnumber><date>February 2010</date><authorinitials>DS</authorinitials></revision></revhistory>\r
</chapterinfo>\r
<section id="_part_1_opensrf_applications">\r
<title>Part 1: OpenSRF applications</title>\r
<simpara>OpenSRF, pronounced "Open Surf", is the Open <emphasis role="strong">S</emphasis>ervice <emphasis role="strong">R</emphasis>equest\r
<emphasis role="strong">F</emphasis>ramework. It was designed as an architecture on which one could\r
easily build scalable applications.</simpara>\r
<section id="_introduction_to_opensrf">\r
<title>Introduction to OpenSRF</title>\r
<simpara>The framework is built on JSON-over-XMPP. XML can be used, but JSON\r
is much less verbose. XMPP is a standard messaging protocol that\r
has been used as the backbone of low-latency, high-volume\r
applications including instant messaging and Google Wave.</simpara>\r
<simpara>OpenSRF offers scalability via its clustering architecture; a service\r
that is a bottleneck can be moved onto its own server; or multiple\r
instances of the service can be run on many servers. Services can\r
themselves be clients of other services.</simpara>\r
<simpara>OpenSRF services listen at an XMPP address such as\r
"opensrf@private.localhost/open-ils.fielder_drone_at_localhost_7652".\r
The initial request from an OpenSRF client is directed to the\r
OpenSRF router, which determines whether the requested service is\r
accessible to the client (based on the public versus private domains),\r
and then connects the client to the service for any subsequent\r
communication that is required.</simpara>\r
<simpara>To significantly improve the speed at which request services can\r
respond to common requests, OpenSRF has integrated support for the\r
caching via the <literal>memcached</literal> daemon. For example, the contents of the\r
configuration files are cached by the <literal>opensrf.settings</literal> service when\r
that service starts, so that rather than having to parse the XML file\r
every time a service checks a configuration setting, the value can be\r
retrieved with much less overhead directly from the cache.</simpara>\r
<note><simpara>if you change a setting in one of those configuration files, you\r
must restart the <literal>opensrf.settings</literal> service to update its data. You must\r
then restart any of the services that make use of that setting to make\r
the change take effect.</simpara></note>\r
<simpara>Supports Perl, C, and Python as services and clients, and Java as a\r
client. JavaScript can access services via HTTP translator and\r
gateway. JSON library converts messages to/from native structures for\r
ease of development.</simpara>\r
</section>\r
<section id="_configuring_opensrf">\r
<title>Configuring OpenSRF</title>\r
<simpara>Walk through the configuration files, explaining <emphasis>why</emphasis> we put the values\r
into the files that we do:</simpara>\r
<itemizedlist>\r
<listitem>\r
<simpara>\r
opensrf_core.xml\r
</simpara>\r
<itemizedlist>\r
<listitem>\r
<simpara>\r
Distinguish between public and private services for security of Web-based applications.\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
Deprecated HTTP gateway versus OpenSRF-over-HTTP\r
</simpara>\r
</listitem>\r
</itemizedlist>\r
</listitem>\r
<listitem>\r
<simpara>\r
opensrf.xml\r
</simpara>\r
</listitem>\r
</itemizedlist>\r
<tip><simpara>In a clustered OpenSRF instance, these files are normally hosted on\r
a network share so that each member of the cluster can read them.</simpara></tip>\r
</section>\r
<section id="_starting_opensrf_services">\r
<title>Starting OpenSRF services</title>\r
<note><simpara>I won&#8217;t go through this during a live session. Perhaps I can cut this\r
out entirely&#8230;</simpara></note>\r
<simpara>Issue the following commands as the <literal>opensrf</literal> user. If you are running OpenSRF\r
on a single-server machine, you can use the <literal>-l</literal> flag to force the hostname\r
to be treated as <literal>localhost</literal>.</simpara>\r
<orderedlist numeration="arabic">\r
<listitem>\r
<simpara>\r
Start the OpenSRF router:\r
</simpara>\r
<screen>osrf_ctl.sh -a start_router</screen>\r
<important><simpara>The router must only run on a single machine in a given brick.</simpara></important>\r
</listitem>\r
<listitem>\r
<simpara>\r
Start all OpenSRF Perl services defined for this host:\r
</simpara>\r
<screen>osrf_ctl.sh -a start_perl</screen>\r
<tip><simpara>You can start an individual Perl service using:</simpara></tip>\r
<screen>opensrf-perl.pl -s &lt;service-name&gt; -a start -p &lt;PID-directory&gt;</screen>\r
</listitem>\r
<listitem>\r
<simpara>\r
Start all OpenSRF C services defined for this host:\r
</simpara>\r
<screen>osrf_ctl.sh -a start_c</screen>\r
</listitem>\r
</orderedlist>\r
</section>\r
<section id="_stopping_opensrf_services">\r
<title>Stopping OpenSRF services</title>\r
<simpara>Issue the following commands as the <literal>opensrf</literal> user. If you are running OpenSRF\r
on a single-server machine, you can use the <literal>-l</literal> flag to force the hostname\r
to be treated as <literal>localhost</literal>.</simpara>\r
<orderedlist numeration="arabic">\r
<listitem>\r
<simpara>\r
Stop the OpenSRF router:\r
</simpara>\r
<screen>osrf_ctl.sh -a stop_router</screen>\r
</listitem>\r
<listitem>\r
<simpara>\r
Stop all OpenSRF Perl services defined for this host:\r
</simpara>\r
<screen>osrf_ctl.sh -a stop_perl</screen>\r
<tip><simpara>You can stop an individual Perl service using:</simpara></tip>\r
<screen>opensrf-perl.pl -s &lt;service-name&gt; -a stop -p &lt;PID-directory&gt;</screen>\r
</listitem>\r
<listitem>\r
<simpara>\r
Stop all OpenSRF C services defined for this host:\r
</simpara>\r
<screen>osrf_ctl.sh -a stop_c</screen>\r
</listitem>\r
</orderedlist>\r
<important><simpara>PID files for OpenSRF services are stored and looked up\r
in <literal>/openils/var/run</literal> by default with <literal>osrf_ctl.sh</literal>, and in\r
<literal>/tmp/</literal> with <literal>opensrf-perl.pl</literal>.  For a clustered server instance\r
of Evergreen, you must store the PIDs on a directory that is local\r
to each server, or else one of your cluster servers may try\r
killing processes on itself that actually have PIDs on other servers.</simpara></important>\r
</section>\r
</section>\r
<section id="_examining_sample_code">\r
<title>Examining sample code</title>\r
<simpara>Show internal documentation for methods. Do some stupid srfsh tricks\r
(<literal>introspect</literal> for one) and show <literal>docgen.xsl</literal> in action.</simpara>\r
<section id="_srfsh_stupid_tricks">\r
<title>SRFSH stupid tricks</title>\r
<screen>srfsh# introspect open-ils.auth\r
... returns documentation for all methods registered for open-ils.auth\r
\r
srfsh# introspect open-ils.auth "open-ils.auth.authenticate"\r
... returns documentation for all methods with names beginning with\r
    "open-ils.auth.authenticate" registered for open-ils.auth\r
\r
srfsh# open open-ils.cstore\r
... begins a stateful connection with open-ils.cstore\r
srfsh# request open-ils.cstore open-ils.cstore.transaction.begin\r
... begins a transaction\r
srfsh# request open-ils.cstore open-ils.cstore.direct.config.language_map.delete \\r
   {"code": {"like":"a%"}}\r
... deletes all of the entries from config.language_map that have a\r
... code beginning with "e"\r
srfsh# request open-ils.cstore open-ils.cstore.transaction.rollback\r
... rolls back the transaction\r
srfsh# close open-ils.cstore\r
... closes the stateful connection with open-ils.cstore</screen>\r
</section>\r
<section id="_perl">\r
<title>Perl</title>\r
<section id="_services">\r
<title>Services</title>\r
<simpara>See <literal>OpenSRF/src/perl/lib/OpenSRF/UnixServer.pm</literal> to understand how the\r
optional methods for initializing and cleaning up OpenSRF services\r
are invoked:</simpara>\r
<itemizedlist>\r
<listitem>\r
<simpara>\r
<literal>initialize()</literal>\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
<literal>child_init()</literal>\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
<literal>child_exit()</literal>\r
</simpara>\r
</listitem>\r
</itemizedlist>\r
<simpara>Services are implemented as Perl functions. Each service needs to be registered with:</simpara>\r
<programlisting language="perl" linenumbering="unnumbered">__PACKAGE__-&gt;register_method(\r
  method =&gt; 'method name',                      # <co id="CO1-1"/>\r
  api_name =&gt; 'API name',                       # <co id="CO1-2"/>\r
  api_level =&gt; 1,                               # <co id="CO1-3"/>\r
  argc =&gt; # of args,                            # <co id="CO1-4"/>\r
  signature =&gt; {                                # <co id="CO1-5"/>\r
    desc =&gt; “Description”,\r
    params =&gt; [\r
      {\r
        name =&gt; 'parameter name',\r
        desc =&gt; 'parameter description',\r
        type =&gt; '(array|hash|number|string)'\r
      }\r
    ],\r
    return =&gt; {\r
      desc =&gt; 'Description of return value',\r
      type =&gt; '(array|hash|number|string)'\r
    }\r
  }\r
);</programlisting>\r
<calloutlist>\r
<callout arearefs="CO1-1">\r
<simpara>\r
The method name is the name of the Perl method that is called when a\r
client invokes the corresponding OpenSRF method.\r
</simpara>\r
</callout>\r
<callout arearefs="CO1-2">\r
<simpara>\r
The API name is the OpenSRF method name. By convention, each API\r
uses the OpenSRF service name for its root, and then appends one or more\r
levels of names to the OpenSRF service name, depending on the complexity\r
of the service and the number of methods exposed by a given service.\r
</simpara>\r
</callout>\r
<callout arearefs="CO1-3">\r
<simpara>\r
The API level is always <literal>1</literal>.\r
</simpara>\r
</callout>\r
<callout arearefs="CO1-4">\r
<simpara>\r
The number of arguments that can be passed to the OpenSRF method is\r
primarily for guidance purposes.\r
</simpara>\r
</callout>\r
<callout arearefs="CO1-5">\r
<simpara>\r
The signature is consumed by the various utilities (srfsh, docgen.xsl)\r
that generate documentation about the OpenSRF service.\r
</simpara>\r
</callout>\r
</calloutlist>\r
<simpara>Note that arguments are converted between native data structures and JSON\r
for us for free.</simpara>\r
</section>\r
<section id="_client_cheat_sheet">\r
<title>Client cheat sheet</title>\r
<simpara>This is the simplest possible OpenSRF client written in Perl:</simpara>\r
<programlisting language="perl" linenumbering="unnumbered"></programlisting>\r
<calloutlist>\r
<callout arearefs="">\r
<simpara>\r
The <literal>OpenSRF::System</literal> module gives our program access to the core OpenSRF\r
client functionality.\r
</simpara>\r
</callout>\r
<callout arearefs="">\r
<simpara>\r
The <literal>bootstrap_client()</literal> method reads the <literal>opensrf_core.xml</literal> file and sets\r
up communication with the OpenSRF router.\r
</simpara>\r
</callout>\r
<callout arearefs="">\r
<simpara>\r
The <literal>OpenSRF::Appsession-&gt;create()</literal> instance method asks the router if it\r
can connect to the named service. If the router determines that the service\r
is accessible (either the opensrf credentials are on the private domain, which\r
gives it access to all public and private services; or the service is on a\r
public domain, which is accessible to both public and private opensrf\r
credentials), it returns an OpenSRF session with a connection to the named service.\r
</simpara>\r
</callout>\r
<callout arearefs="">\r
<simpara>\r
The <literal>OpenSRF::Appsession-&gt;request()</literal> method invokes a method of the\r
associated service to return a request object.\r
</simpara>\r
</callout>\r
<callout arearefs="">\r
<simpara>\r
The method name that you want to invoke is the first argument to <literal>request()</literal>.\r
</simpara>\r
</callout>\r
<callout arearefs="">\r
<simpara>\r
The arguments to the method follow the method name.\r
</simpara>\r
</callout>\r
<callout arearefs="">\r
<simpara>\r
Invoking the <literal>gather()</literal> method on the returned request object returns a\r
single result.\r
</simpara>\r
<note><simpara>If the service is expected to return multiple results, you should loop\r
over it with <literal>recv()</literal> instead. But then, that wouldn&#8217;t be the simplest\r
possible client anymore would it?</simpara></note>\r
</callout>\r
<callout arearefs="">\r
<simpara>\r
The <literal>OpenSRF::Appsession-&gt;disconnect()</literal> instance method disconnects from\r
the service, enabling that child to go on and handle other requests.\r
</simpara>\r
</callout>\r
</calloutlist>\r
</section>\r
</section>\r
<section id="_javascript">\r
<title>JavaScript</title>\r
<simpara>Historically, JavaScript has had access to OpenSRF methods via the\r
OpenSRF HTTP gateway Apache module. You can still see this in heavy use\r
in the OPAC and staff client as of Evergreen 1.6, but the approach has been\r
deprecated as it has significant performance problems with large responses.\r
The successor for the OpenSRF gateway is the OpenSRF-over-HTTP translator\r
Apache module, which supports streaming responses for improved performance\r
and better support for the broad range of OpenSRF attributes.</simpara>\r
<section id="_invoking_methods_via_the_http_translator">\r
<title>Invoking methods via the HTTP Translator</title>\r
<simpara>The following example demonstrates the basic approach to invoking\r
OpenSRF methods via JavaScript. It uses just three OpenSRF JavaScript\r
libraries to simplify calls to the OpenSRF-over-HTTP translator,\r
which became available to developers as part of the OpenSRF 1.0 /\r
Evergreen 1.4 releases.</simpara>\r
<programlisting language="html" linenumbering="unnumbered"></programlisting>\r
<calloutlist>\r
<callout arearefs="">\r
<simpara>\r
opensrf.js defines most of the objects and methods required for a bare\r
JavaScript call to the OpenSRF HTTP translator.\r
</simpara>\r
</callout>\r
<callout arearefs="">\r
<simpara>\r
opensrf_xhr.js provides cross-browser XMLHttpRequest support for OpenSRF.\r
</simpara>\r
</callout>\r
<callout arearefs="">\r
<simpara>\r
JSON_v1.js converts the requests and responses between JavaScript and the\r
JSON format that the OpenSRF translator expects.\r
</simpara>\r
</callout>\r
<callout arearefs="">\r
<simpara>\r
Create a client session that connects to the <literal>open-ils.resolver</literal> service.\r
</simpara>\r
</callout>\r
<callout arearefs="">\r
<simpara>\r
Create a request object that identifies the target method and passes the\r
required method arguments.\r
</simpara>\r
</callout>\r
<callout arearefs="">\r
<simpara>\r
Define the function that will be called when the request is sent and\r
results are returned from the OpenSRF HTTP translator.\r
</simpara>\r
</callout>\r
<callout arearefs="">\r
<simpara>\r
Loop over the returned results using the <literal>recv()</literal> method.\r
</simpara>\r
</callout>\r
<callout arearefs="">\r
<simpara>\r
The content of each result is accessible via the content() method of\r
each returned result.\r
</simpara>\r
</callout>\r
<callout arearefs="">\r
<simpara>\r
<literal>open-ils.resolver.resolve_holdings</literal> returns a hash of values, so\r
invoking one of the hash keys (<literal>coverage</literal>) gives us access to that value.\r
</simpara>\r
</callout>\r
<callout arearefs="">\r
<simpara>\r
Actually send the request to the method; the function defined by\r
<literal>req.oncomplete</literal> is invoked as the results are returned.\r
</simpara>\r
</callout>\r
</calloutlist>\r
</section>\r
</section>\r
</section>\r
<section id="_exercise">\r
<title>Exercise</title>\r
<simpara>Build a new OpenSRF service.</simpara>\r
<section id="_perl_2">\r
<title>Perl</title>\r
<simpara>The challenge: implement a service that caches responses from some\r
other Web service (potentially cutting down on client-side latency\r
for something like OpenLibrary / Google Books / xISBN services, and\r
avoiding timeouts if the target service is not dependable). Our\r
example will be to build an SFX lookup service. This has the\r
additional advantage of enabling <literal>XmlHttpRequest</literal> from JavaScript by\r
hosting the services on the same domain.</simpara>\r
<simpara>Let&#8217;s start with the simplest possible implementation – a CGI script.</simpara>\r
<programlisting language="perl" linenumbering="unnumbered"></programlisting>\r
<simpara>Hopefully you can follow what this CGI script is doing. It works,\r
but it has all the disadvantages of CGI: the environment needs to\r
be built up on every request, and it doesn&#8217;t remember anything\r
from the previous times it was called, etc.</simpara>\r
<section id="_turning_the_cgi_script_into_an_opensrf_service">\r
<title>Turning the CGI script into an OpenSRF service</title>\r
<simpara>So now we want to turn this into an OpenSRF service.</simpara>\r
<orderedlist numeration="arabic">\r
<listitem>\r
<simpara>\r
Start by ripping out the CGI stuff, as we won&#8217;t need that any more.\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
To turn this into an OpenSRF service, we create a new\r
Perl module (<literal>OpenILS::Application::ResolverResolver</literal>). We no\r
longer have to convert results between Perl and JSON values, as\r
OpenSRF will handle that for us. We now have to register the\r
method with OpenSRF.\r
</simpara>\r
<programlisting language="perl" linenumbering="unnumbered"></programlisting>\r
</listitem>\r
<listitem>\r
<simpara>\r
Copy the file into the <literal>/openils/lib/perl5/OpenILS/Application/</literal> directory\r
so that OpenSRF can find it in the <literal>@INC</literal> search path.\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
Add the service to <literal>opensrf.xml</literal> so it gets started with the\r
other Perl services on our host of choice:\r
</simpara>\r
<programlisting language="xml" linenumbering="unnumbered">...\r
&lt;open-ils.resolver&gt;\r
  &lt;keepalive&gt;3&lt;/keepalive&gt;\r
  &lt;stateless&gt;1&lt;/stateless&gt;\r
  &lt;language&gt;perl&lt;/language&gt;\r
  &lt;implementation&gt;OpenILS::Application::ResolverResolver&lt;/implementation&gt;\r
  &lt;max_requests&gt;17&lt;/max_requests&gt;\r
  &lt;unix_config&gt;\r
    &lt;unix_sock&gt;open-ils.resolver_unix.sock&lt;/unix_sock&gt;\r
    &lt;unix_pid&gt;open-ils.resolver_unix.pid&lt;/unix_pid&gt;\r
    &lt;max_requests&gt;1000&lt;/max_requests&gt;\r
    &lt;unix_log&gt;open-ils.resolver_unix.log&lt;/unix_log&gt;\r
    &lt;min_children&gt;5&lt;/min_children&gt;\r
    &lt;max_children&gt;15&lt;/max_children&gt;\r
    &lt;min_spare_children&gt;3&lt;/min_spare_children&gt;\r
    &lt;max_spare_children&gt;5&lt;/max_spare_children&gt;\r
  &lt;/unix_config&gt;\r
  &lt;app_settings&gt;\r
    &lt;cache_timeout&gt;86400&lt;/cache_timeout&gt;\r
    &lt;default_url_base&gt;http://sfx.scholarsportal.info/laurentian&lt;/default_url_base&gt;\r
  &lt;/app_settings&gt;\r
&lt;/open-ils.resolver&gt;\r
...\r
&lt;!-- In the &lt;hosts&gt; section --&gt;\r
&lt;localhost&gt;\r
  ...\r
  &lt;appname&gt;open-ils.resolver&lt;/appname&gt;\r
&lt;/localhost&gt;</programlisting>\r
</listitem>\r
<listitem>\r
<simpara>\r
Add the service to <literal>opensrf_core.xml</literal> as a publicly exposed\r
service via the HTTP gateway and translator:\r
</simpara>\r
<programlisting language="xml" linenumbering="unnumbered">...\r
&lt;!-- In the public router section --&gt;\r
&lt;services&gt;\r
  ...\r
  &lt;service&gt;open-ils.resolver&lt;/service&gt;\r
&lt;/services&gt;\r
...\r
&lt;!-- In the public gateway section --&gt;\r
&lt;services&gt;\r
&lt;gateway&gt;\r
  ...\r
  &lt;services&gt;\r
    &lt;service&gt;open-ils.resolver&lt;/service&gt;\r
  &lt;/services&gt;\r
&lt;/gateway&gt;</programlisting>\r
</listitem>\r
<listitem>\r
<simpara>\r
Restart the OpenSRF Perl services to refresh the OpenSRF\r
settings and start the service..\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
Restart Apache to enable the gateway and translator to pick up\r
the new service.\r
</simpara>\r
</listitem>\r
</orderedlist>\r
</section>\r
<section id="_add_caching">\r
<title>Add caching</title>\r
<simpara>To really make this service useful, we can take advantage of OpenSRF&#8217;s\r
built-in support for caching via memcached. Keeping the values\r
returned by the resolver for 1 week is apparently good.</simpara>\r
<simpara>We will also take advantage of the <literal>opensrf.settings</literal> service that\r
holds the values defined in the <literal>opensrf.xml</literal> configuration file to\r
supply some of our default arguments.</simpara>\r
<formalpara><title>Caching OpenSRF Resolver Service</title><para>\r
<programlisting language="perl" linenumbering="unnumbered"></programlisting>\r
</para></formalpara>\r
</section>\r
<section id="_pulling_application_settings_from_literal_opensrf_xml_literal">\r
<title>Pulling application settings from <literal>opensrf.xml</literal></title>\r
<simpara>In case you missed it in the previous diff, we also started\r
pulling some application-specific settings from <literal>opensrf.xml</literal>\r
during the <literal>initialize()</literal> phase for the service.</simpara>\r
<simpara>In the following diff, we enable the service to pull the default URL from\r
<literal>opensrf.xml</literal> rather than hard-coding it into the OpenSRF service&#8230; because\r
that&#8217;s just the right thing to do.</simpara>\r
<programlisting language="perl" linenumbering="unnumbered">=== modified file 'ResolverResolver.pm'\r
--- ResolverResolver.pm    2009-10-22 21:00:15 +0000\r
+++ ResolverResolver.pm    2009-10-24 03:00:30 +0000\r
@@ -77,6 +77,7 @@\r
 my $prefix = "open-ils.resolver_"; # Prefix for caching values\r
 my $cache;\r
 my $cache_timeout;\r
+my $default_url_base;              # Default resolver location\r
\r
 our ($ua, $parser);\r
\r
@@ -86,6 +87,8 @@\r
     my $sclient = OpenSRF::Utils::SettingsClient-&gt;new();\r
     $cache_timeout = $sclient-&gt;config_value(\r
         "apps", "open-ils.resolver", "app_settings", "cache_timeout" ) || 300;\r
+    $default_url_base = $sclient-&gt;config_value(\r
+        "apps", "open-ils.resolver", "app_settings", "default_url_base");\r
 }\r
\r
 sub child_init {\r
@@ -102,14 +105,11 @@\r
     my $conn = shift;\r
     my $id_type = shift; # keep it simple for now, either 'issn' or 'isbn'\r
     my $id_value = shift; # the normalized ISSN or ISBN\r
+    my $url_base = shift || $default_url_base;\r
\r
     # We'll use this in our cache key\r
     my $method = "open-ils.resolver.resolve_holdings";\r
\r
-    # For now we'll pass the argument with a hard-coded default\r
-    # Should pull these specifics from the database as part of initialize()\r
-    my $url_base = shift || 'http://sfx.scholarsportal.info/laurentian';\r
-\r
     # Big ugly SFX OpenURL request\r
     my $url_args = '?url_ver=Z39.88-2004&amp;url_ctx_fmt=infofi/fmt:kev:mtx:ctx&amp;'\r
         . 'ctx_enc=UTF-8&amp;ctx_ver=Z39.88-2004&amp;rfr_id=info:sid/conifer&amp;'</programlisting>\r
<simpara>The <literal>opensrf.settings</literal> service caches the settings defined in <literal>opensrf.xml</literal>,\r
so if you change a setting in the configuration files and want that change\r
to take effect immediately, you have to:</simpara>\r
<orderedlist numeration="arabic">\r
<listitem>\r
<simpara>\r
Restart the <literal>opensrf.settings</literal> service to refresh the cached settings.\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
Restart the affected service to make the new settings take effect.\r
</simpara>\r
</listitem>\r
</orderedlist>\r
<simpara>Next step: add org_unit settings for resolver type and URL on a per-org_unit basis.\r
OrgUnit settings can be retrieved via\r
<literal>OpenILS::Application::AppUtils-&gt;ou_ancestor_setting_value($org_id, $setting_name)</literal>).</simpara>\r
<simpara>This is where we step beyond OpenSRF and start getting into the\r
Evergreen database schema (<literal>config.org_unit_setting</literal> table).</simpara>\r
</section>\r
</section>\r
<section id="_further_reading">\r
<title>Further reading</title>\r
<simpara>OpenSRF terminology: <ulink url="http://open-ils.org/dokuwiki/doku.php?id=osrf-devel:terms">http://open-ils.org/dokuwiki/doku.php?id=osrf-devel:terms</ulink></simpara>\r
</section>\r
</section>\r
<section id="_part_2_evergreen_applications">\r
<title>Part 2: Evergreen applications</title>\r
<section id="_authentication">\r
<title>Authentication</title>\r
<simpara>Although many services offer methods that can be invoked without\r
authentication, some methods require authentication in Evergreen.\r
Evergreen&#8217;s authentication framework returns an <emphasis>authentication token</emphasis>\r
when a user has successfully logged in to represent that user\r
session. You can then pass the authentication token to various\r
methods to ensure, for example, that the requesting user has permission\r
to access the circulation information attached to a particular account,\r
or has been granted the necessary permissions at a particular library\r
to perform the action that they are requesting.</simpara>\r
<simpara>Authentication in Evergreen is performed with the assistance of the\r
<literal>open-ils.auth</literal> service, which has been written in C for performance\r
reasons because it is invoked so frequently. A successful authentication\r
request requires two steps:</simpara>\r
<orderedlist numeration="arabic">\r
<listitem>\r
<simpara>\r
Retrieve an authentication seed value by invoking the\r
<literal>open-ils.auth.authenticate.init</literal> method, passing the user name as\r
the only argument. As long as the user name contains no spaces, the\r
method returns a seed value calculated by the MD5 checksum of\r
a string composed of the concatenation of the time() system call,\r
process ID, and user name.\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
Retrieve an authentication token by invoking the\r
<literal>open-ils.auth.authenticate.complete</literal> method, passing\r
a JSON hash composed of a minimum of the following arguments\r
(where <emphasis>seed</emphasis> represents the value returned by the\r
<literal>open-ils.auth.authenticate.init</literal> method):\r
</simpara>\r
<programlisting language="java" linenumbering="unnumbered">{\r
    "username": username, // or "barcode": barcode,\r
    "password": md5sum(seed + md5sum(password)),\r
}</programlisting>\r
</listitem>\r
</orderedlist>\r
<simpara><literal>open-ils.auth.authenticate.complete</literal> also accepts the following\r
additional arguments:</simpara>\r
<itemizedlist>\r
<listitem>\r
<simpara>\r
<literal>type</literal>: one of "staff" (default), "opac", or "temp"\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
<literal>org</literal>: the numeric ID of the org_unit where the login is active\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
<literal>workstation</literal>: the registered workstation name\r
</simpara>\r
</listitem>\r
</itemizedlist>\r
<section id="_authentication_in_perl">\r
<title>Authentication in Perl</title>\r
<simpara>The following example is taken directly from <literal>OpenILS::WWW::Proxy</literal>:</simpara>\r
<programlisting language="perl" linenumbering="unnumbered">sub oils_login {\r
    my( $username, $password, $type ) = @_;\r
\r
    $type |= "staff";\r
    my $nametype = 'username';\r
    $nametype = 'barcode' if ($username =~ /^\d+$/o);\r
\r
    my $seed = OpenSRF::AppSession\r
        -&gt;create("open-ils.auth")\r
        -&gt;request( 'open-ils.auth.authenticate.init', $username )\r
        -&gt;gather(1);\r
\r
    return undef unless $seed;\r
\r
    my $response = OpenSRF::AppSession\r
        -&gt;create("open-ils.auth")\r
        -&gt;request( 'open-ils.auth.authenticate.complete', {\r
        $nametype =&gt; $username,\r
            password =&gt; md5_hex($seed . md5_hex($password)),\r
            type =&gt; $type\r
        })\r
        -&gt;gather(1);\r
\r
    return undef unless $response;\r
\r
    return $response-&gt;{payload}-&gt;{authtoken};\r
}</programlisting>\r
</section>\r
<section id="_authentication_in_javascript">\r
<title>Authentication in JavaScript</title>\r
<simpara>The following example provides a minimal implementation of the authentication\r
method in JavaScript. For a more complete implementation, you would\r
differentiate between user names and barcodes, potentially accept the\r
org_unit and workstation name for more granular permissions, and provide\r
exception handling.</simpara>\r
<programlisting language="html" linenumbering="unnumbered"></programlisting>\r
<calloutlist>\r
<callout arearefs="">\r
<simpara>\r
opensrf.js defines most of the objects and methods required for a bare\r
JavaScript call to the OpenSRF HTTP translator.\r
</simpara>\r
</callout>\r
<callout arearefs="">\r
<simpara>\r
opensrf_xhr.js provides cross-browser XMLHttpRequest support for OpenSRF.\r
</simpara>\r
</callout>\r
<callout arearefs="">\r
<simpara>\r
JSON_v1.js converts the requests and responses between JavaScript and the\r
JSON format that the OpenSRF translator expects.\r
</simpara>\r
</callout>\r
<callout arearefs="">\r
<simpara>\r
md5.js provides the implementation of the md5sum algorithm in the\r
<literal>hex_md5</literal> function\r
</simpara>\r
</callout>\r
<callout arearefs="">\r
<simpara>\r
Create a client session that connects to the <literal>open-ils.auth</literal> service.\r
</simpara>\r
</callout>\r
<callout arearefs="">\r
<simpara>\r
Create a request object that invokes the <literal>open-ils.auth.authenticate.init</literal>\r
method, providing the user name as the salt.\r
</simpara>\r
</callout>\r
<callout arearefs="">\r
<simpara>\r
Set the <literal>timeout</literal> property on the request object to make it a\r
synchronous call.\r
</simpara>\r
</callout>\r
<callout arearefs="">\r
<simpara>\r
Send the request. The method returns a seed value which is assigned to\r
the <literal>seed</literal> variable.\r
</simpara>\r
</callout>\r
<callout arearefs="">\r
<simpara>\r
Create the hash of parameters that will be sent in the request to the\r
<literal>open-ils.auth.authenticate.complete</literal> method, including the password and\r
authentication type.\r
</simpara>\r
</callout>\r
<callout arearefs="">\r
<simpara>\r
Assume that the credentials being sent are based on the user name rather\r
than the barcode. The Perl implementation tests the value of the user name\r
variable to determine whether it contains a digit; if it does contain a\r
digit, then it is considered a barcode rather than a user name. Ensure that\r
your implementations are consistent!\r
</simpara>\r
</callout>\r
<callout arearefs="">\r
<simpara>\r
Create a request object that invokes the\r
<literal>open-ils.auth.authenticate.complete</literal> method, passing the entire hash of\r
parameters. Once again, set the <literal>timeout</literal> parameter to make the request\r
synchronous.\r
</simpara>\r
</callout>\r
<callout arearefs="">\r
<simpara>\r
Assign the <literal>authtoken</literal> attribute of the returned payload to the\r
<literal>authtoken</literal> variable.\r
</simpara>\r
</callout>\r
</calloutlist>\r
</section>\r
</section>\r
</section>\r
<section id="_evergreen_data_models_and_access">\r
<title>Evergreen data models and access</title>\r
<section id="_database_schema">\r
<title>Database schema</title>\r
<simpara>The database schema is tied pretty tightly to PostgreSQL. Although PostgreSQL\r
adheres closely to ANSI SQL standards, the use of schemas, SQL functions\r
implemented in both plpgsql and plperl, and PostgreSQL&#8217;s native full-text\r
search would make it&#8230; challenging&#8230; to port to other database platforms.</simpara>\r
<simpara>A few common PostgreSQL interfaces for poking around the schema and\r
manipulating data are:</simpara>\r
<itemizedlist>\r
<listitem>\r
<simpara>\r
psql (the command line client)\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
pgadminIII (a GUI client).\r
</simpara>\r
</listitem>\r
</itemizedlist>\r
<simpara>Or you can read through the source files in Open-ILS/src/sql/Pg.</simpara>\r
<simpara>Let&#8217;s take a quick tour through the schemas, pointing out some highlights\r
and some key interdependencies:</simpara>\r
<itemizedlist>\r
<listitem>\r
<simpara>\r
actor.org_unit &#8594; asset.copy_location\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
actor.usr &#8594; actor.card\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
biblio.record_entry &#8594; asset.call_number &#8594; asset.copy\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
config.metabib_field &#8594; metabib.*_field_entry\r
</simpara>\r
</listitem>\r
</itemizedlist>\r
</section>\r
<section id="_database_access_methods">\r
<title>Database access methods</title>\r
<simpara>You could use direct access to the database via Perl DBI, JDBC, etc,\r
but Evergreen offers several database CRUD services for\r
creating / retrieving / updating / deleting data. These avoid tying\r
you too tightly to the current database schema and they funnel database\r
access through the same mechanism, rather than tying up connections\r
with other interfaces.</simpara>\r
</section>\r
<section id="_evergreen_interface_definition_language_idl">\r
<title>Evergreen Interface Definition Language (IDL)</title>\r
<simpara>Defines properties and required permissions for Evergreen classes.\r
To reduce network overhead, a given object is identified via a\r
class-hint and serialized as a JSON array of properties (no named properties).</simpara>\r
<simpara>As of 1.6, fields will be serialized in the order in which they appear\r
in the IDL definition file, and the is_new / is_changed / is_deleted\r
properties are automatically added. This has greatly reduced the size of\r
the <literal>fm_IDL.xml</literal> file and makes DRY people happier :)</simpara>\r
<itemizedlist>\r
<listitem>\r
<simpara>\r
&#8230; oils_persist:readonly tells us, if true, that the data lives in the database, but is pulled from the SELECT statement defined in the &lt;oils_persist:source_definition&gt; child element\r
</simpara>\r
</listitem>\r
</itemizedlist>\r
<section id="_idl_basic_example_config_language_map">\r
<title>IDL basic example (config.language_map)</title>\r
<programlisting language="xml" linenumbering="unnumbered">&lt;class id="clm" controller="open-ils.cstore open-ils.pcrud"\r
        oils_obj:fieldmapper="config::language_map"\r
        oils_persist:tablename="config.language_map"\r
        reporter:label="Language Map" oils_persist:field_safe="true"&gt;      # <co id="CO5-1"/> <co id="CO5-2"/> <co id="CO5-3"/> <co id="CO5-4"/>\r
    &lt;fields oils_persist:primary="code" oils_persist:sequence=""&gt;          # <co id="CO5-5"/>\r
        &lt;field reporter:label="Language Code" name="code"\r
            reporter:selector="value" reporter:datatype="text"/&gt;           # <co id="CO5-6"/>\r
        &lt;field reporter:label="Language" name="value"\r
            reporter:datatype="text" oils_persist:i18n="true"/&gt;            # <co id="CO5-7"/>\r
    &lt;/fields&gt;\r
    &lt;links/&gt;\r
    &lt;permacrud xmlns="http://open-ils.org/spec/opensrf/IDL/permacrud/v1"&gt;  # <co id="CO5-8"/>\r
        &lt;actions&gt;\r
            &lt;create global_required="true" permission="CREATE_MARC_CODE"&gt;  # <co id="CO5-9"/>\r
            &lt;retrieve global_required="true"\r
                permission="CREATE_MARC_CODE UPDATE_MARC_CODE DELETE_MARC_CODE"&gt;\r
            &lt;update global_required="true" permission="UPDATE_MARC_CODE"&gt;\r
            &lt;delete global_required="true" permission="DELETE_MARC_CODE"&gt;\r
        &lt;/actions&gt;\r
    &lt;/permacrud&gt;\r
&lt;/class&gt;</programlisting>\r
<calloutlist>\r
<callout arearefs="CO5-1">\r
<simpara>\r
The <literal>class</literal> element defines the attributes and permissions for classes,\r
and relationships between classes.\r
</simpara>\r
<itemizedlist>\r
<listitem>\r
<simpara>\r
The <literal>id</literal> attribute on the <literal>class</literal> element defines the class hint that is\r
used everywhere in Evergreen.\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
The <literal>controller</literal> attribute defines the OpenSRF\r
services that provide access to the data for the class objects.\r
</simpara>\r
</listitem>\r
</itemizedlist>\r
</callout>\r
<callout arearefs="CO5-2">\r
<simpara>\r
The <literal>oils_obj::fieldmapper</literal> attribute defines the name of the class that\r
is generated by <literal>OpenILS::Utils::Fieldmapper</literal>.\r
</simpara>\r
</callout>\r
<callout arearefs="CO5-3">\r
<simpara>\r
The <literal>oils_persist:tablename</literal> attribute defines the name of the table\r
that contains the data for the class objects.\r
</simpara>\r
</callout>\r
<callout arearefs="CO5-4">\r
<simpara>\r
The reporter interface uses <literal>reporter:label</literal> attribute values in\r
the source list to provide meaningful class and attribute names. The\r
<literal>open-ils.fielder</literal> service generates a set of methods that provide direct\r
access to the classes for which <literal>oils_persist:field_safe</literal> is <literal>true</literal>. For\r
example,\r
</simpara>\r
<screen>srfsh# request open-ils.fielder open-ils.fielder.clm.atomic \\r
    {"query":{"code":{"=":"eng"}}}\r
\r
Received Data: [\r
  {\r
    "value":"English",\r
    "code":"eng"\r
  }\r
]</screen>\r
</callout>\r
<callout arearefs="CO5-5">\r
<simpara>\r
The <literal>fields</literal> element defines the list of fields for the class.\r
</simpara>\r
<itemizedlist>\r
<listitem>\r
<simpara>\r
The <literal>oils_persist:primary</literal> attribute defines the column that acts as\r
the primary key for the table.\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
The <literal>oils_persist:sequence</literal> attribute holds the name of the database\r
sequence.\r
</simpara>\r
</listitem>\r
</itemizedlist>\r
</callout>\r
<callout arearefs="CO5-6">\r
<simpara>\r
Each <literal>field</literal> element defines one property of the class.\r
</simpara>\r
<itemizedlist>\r
<listitem>\r
<simpara>\r
The <literal>name</literal> attribute defines the getter/setter method name for the field.\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
The <literal>reporter:label</literal> attribute defines the attribute name as used in\r
the reporter interface.\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
The <literal>reporter:selector</literal> attribute defines the field used in the reporter\r
filter interface to provide a selectable list. This gives the user a more\r
meaningful access point than the raw numeric ID or abstract code.\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
The <literal>reporter:datatype</literal> attribute defines the type of data held by\r
this property for the purposes of the reporter.\r
</simpara>\r
</listitem>\r
</itemizedlist>\r
</callout>\r
<callout arearefs="CO5-7">\r
<simpara>\r
The <literal>oils_persist:i18n</literal> attribute, when <literal>true</literal>, means that\r
translated values for the field&#8217;s contents may be accessible in\r
different locales.\r
</simpara>\r
</callout>\r
<callout arearefs="CO5-8">\r
<simpara>\r
The <literal>permacrud</literal> element defines the permissions (if any) required\r
to <emphasis role="strong">c</emphasis>reate, <emphasis role="strong">r</emphasis>etrieve, <emphasis role="strong">u</emphasis>pdate, and <emphasis role="strong">d</emphasis>elete data for this\r
class. <literal>open-ils.permacrud</literal> must be defined as a controller for the class\r
for the permissions to be applied.\r
</simpara>\r
</callout>\r
<callout arearefs="CO5-9">\r
<simpara>\r
Each action requires one or more <literal>permission</literal> values that the\r
user must possess to perform the action.\r
</simpara>\r
<itemizedlist>\r
<listitem>\r
<simpara>\r
If the <literal>global_required</literal> attribute is <literal>true</literal>, then the user must\r
have been granted that permission globally (depth = 0) to perform\r
the action.\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
The <literal>context_field</literal> attribute denotes the <literal>&lt;field&gt;</literal> that identifies\r
the org_unit at which the user must have the pertinent permission.\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
An action element may contain a <literal>&lt;context_field&gt;</literal> element that\r
defines the linked class (identified by the <literal>link</literal> attribute) and\r
the field in the linked class that identifies the org_unit where\r
the permission must be held.\r
</simpara>\r
<itemizedlist>\r
<listitem>\r
<simpara>\r
If the <literal>&lt;context_field&gt;</literal> element contains a <literal>jump</literal> attribute,\r
then it defines a link to a link to a class with a field identifying\r
the org_unit where the permission must be held.\r
</simpara>\r
</listitem>\r
</itemizedlist>\r
</listitem>\r
</itemizedlist>\r
</callout>\r
</calloutlist>\r
</section>\r
<section id="_reporter_data_types_and_their_possible_values">\r
<title>Reporter data types and their possible values</title>\r
<itemizedlist>\r
<listitem>\r
<simpara>\r
<literal>bool</literal>: Boolean <literal>true</literal> or <literal>false</literal>\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
<literal>id</literal>: ID of the row in the database\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
<literal>int</literal>: integer value\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
<literal>interval</literal>: PostgreSQL time interval\r
</simpara>\r
</listitem>\r
\r
<listitem>\r
<simpara>\r
<literal>link</literal>: link to another class, as defined in the <literal>&lt;links&gt;</literal>\r
element of the class definition\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
<literal>money</literal>: currency amount\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
<literal>org_unit</literal>: list of org_units\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
<literal>text</literal>: text value\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
<literal>timestamp</literal>: PostgreSQL timestamp\r
</simpara>\r
</listitem>\r
</itemizedlist>\r
</section>\r
<section id="_idl_example_with_linked_fields_actor_workstation">\r
<title>IDL example with linked fields (actor.workstation)</title>\r
<simpara>Just as tables often include columns with foreign keys that point\r
to values stored in the column of a different table, IDL classes\r
can contain fields that link to fields in other classes. The <literal>&lt;links&gt;</literal>\r
element defines which fields link to fields in other classes, and\r
the nature of the relationship:</simpara>\r
<programlisting language="xml" linenumbering="unnumbered">&lt;class id="aws" controller="open-ils.cstore"\r
        oils_obj:fieldmapper="actor::workstation"\r
        oils_persist:tablename="actor.workstation"\r
        reporter:label="Workstation"&gt;\r
    &lt;fields oils_persist:primary="id"\r
            oils_persist:sequence="actor.workstation_id_seq"&gt;\r
        &lt;field reporter:label="Workstation ID" name="id"\r
                reporter:datatype="id"/&gt;\r
        &lt;field reporter:label="Workstation Name" name="name"\r
                reporter:datatype="text"/&gt;\r
        &lt;field reporter:label="Owning Library" name="owning_lib"\r
                reporter:datatype="org_unit"/&gt;\r
        &lt;field reporter:label="Circulations" name="circulations"\r
                oils_persist:virtual="true" reporter:datatype="link"/&gt;     # <co id="CO6-1"/>\r
    &lt;/fields&gt;\r
    &lt;links&gt;                                                                # <co id="CO6-2"/>\r
        &lt;link field="owning_lib" reltype="has_a" key="id"\r
                map="" class="aou"/&gt;                                       # <co id="CO6-3"/>\r
        &lt;link field="circulations" reltype="has_many" key="workstation"\r
                map="" class="circ"/&gt;\r
        &lt;link field="circulation_checkins" reltype="has_many"\r
                key="checkin_workstation" map="" class="circ"/&gt;\r
    &lt;/links&gt;\r
&lt;/class&gt;</programlisting>\r
<calloutlist>\r
<callout arearefs="CO6-1">\r
<simpara>\r
This field includes an <literal>oils_persist:virtual</literal> attribute with the value of\r
<literal>true</literal>, meaning that the linked class <literal>circ</literal> is a virtual class.\r
</simpara>\r
</callout>\r
<callout arearefs="CO6-2">\r
<simpara>\r
The <literal>&lt;links&gt;</literal> element contains 0 or more <literal>&lt;link&gt;</literal> elements.\r
</simpara>\r
</callout>\r
<callout arearefs="CO6-3">\r
<simpara>\r
Each <literal>&lt;link&gt;</literal> element defines the field (<literal>field</literal>) that links to a different\r
class (<literal>class</literal>), the relationship (<literal>rel_type</literal>) between this field and the target\r
field (<literal>key</literal>). If the field in this class links to a virtual class, the (<literal>map</literal>)\r
attribute defines the field in the target class that returns a list of matching\r
objects for each object in this class.\r
</simpara>\r
</callout>\r
</calloutlist>\r
</section>\r
</section>\r
<section id="_literal_open_ils_cstore_literal_data_access_interfaces">\r
<title><literal>open-ils.cstore</literal> data access interfaces</title>\r
<simpara>For each class documented in the IDL, the <literal>open-ils.cstore</literal> service\r
automatically generates a set of data access methods, based on the\r
<literal>oils_persist:tablename</literal> class attribute.</simpara>\r
<simpara>For example, for the class hint <literal>clm</literal>, cstore generates the following\r
methods with the <literal>config.language_map</literal> qualifer:</simpara>\r
<itemizedlist>\r
<listitem>\r
<simpara>\r
<literal>open-ils.cstore.direct.config.language_map.id_list {"code" { "like": "e%" } }</literal>\r
</simpara>\r
<simpara>Retrieves a list composed only of the IDs that match the query.</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
<literal>open-ils.cstore.direct.config.language_map.retrieve "eng"</literal>\r
</simpara>\r
<simpara>Retrieves the object that matches a specific ID.</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
<literal>open-ils.cstore.direct.config.language_map.search {"code" : "eng"}</literal>\r
</simpara>\r
<simpara>Retrieves a list of objects that match the query.</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
<literal>open-ils.cstore.direct.config.language_map.create &lt;_object_&gt;</literal>\r
</simpara>\r
<simpara>Creates a new object from the passed in object.</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
<literal>open-ils.cstore.direct.config.language_map.update &lt;_object_&gt;</literal>\r
</simpara>\r
<simpara>Updates the object that has been passed in.</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
<literal>open-ils.cstore.direct.config.language_map.delete "eng"</literal>\r
</simpara>\r
<simpara>Deletes the object that matches the query.</simpara>\r
</listitem>\r
</itemizedlist>\r
</section>\r
<section id="_open_ils_pcrud_data_access_interfaces">\r
<title>open-ils.pcrud data access interfaces</title>\r
<simpara>For each class documented in the IDL, the <literal>open-ils.pcrud</literal> service\r
automatically generates a set of data access methods, based on the\r
<literal>oils_persist:tablename</literal> class attribute.</simpara>\r
<simpara>For example, for the class hint <literal>clm</literal>, <literal>open-ils.pcrud</literal> generates the following\r
methods that parallel the <literal>open-ils.cstore</literal> interface:</simpara>\r
<itemizedlist>\r
<listitem>\r
<simpara>\r
<literal>open-ils.pcrud.id_list.clm &lt;_authtoken_&gt;, { "code": { "like": "e%" } }</literal>\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
<literal>open-ils.pcrud.retrieve.clm &lt;_authtoken_&gt;, "eng"</literal>\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
<literal>open-ils.pcrud.search.clm &lt;_authtoken_&gt;, { "code": "eng" }</literal>\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
<literal>open-ils.pcrud.create.clm &lt;_authtoken_&gt;, &lt;_object_&gt;</literal>\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
<literal>open-ils.pcrud.update.clm &lt;_authtoken_&gt;, &lt;_object_&gt;</literal>\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
<literal>open-ils.pcrud.delete.clm &lt;_authtoken_&gt;, "eng"</literal>\r
</simpara>\r
</listitem>\r
</itemizedlist>\r
</section>\r
<section id="_transaction_and_savepoint_control">\r
<title>Transaction and savepoint control</title>\r
<simpara>Both <literal>open-ils.cstore</literal> and <literal>open-ils.pcrud</literal> enable you to control database transactions\r
to ensure that a set of operations either all succeed, or all fail,\r
atomically:</simpara>\r
<itemizedlist>\r
<listitem>\r
<simpara>\r
<literal>open-ils.cstore.transaction.begin</literal>\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
<literal>open-ils.cstore.transaction.commit</literal>\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
<literal>open-ils.cstore.transaction.rollback</literal>\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
<literal>open-ils.pcrud.transaction.begin</literal>\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
<literal>open-ils.pcrud.transaction.commit</literal>\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
<literal>open-ils.pcrud.transaction.rollback</literal>\r
</simpara>\r
</listitem>\r
</itemizedlist>\r
<simpara>At a more granular level, <literal>open-ils.cstore</literal> and <literal>open-ils.pcrud</literal> enable you to set database\r
savepoints to ensure that a set of operations either all succeed, or all\r
fail, atomically, within a given transaction:</simpara>\r
<itemizedlist>\r
<listitem>\r
<simpara>\r
<literal>open-ils.cstore.savepoint.begin</literal>\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
<literal>open-ils.cstore.savepoint.commit</literal>\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
<literal>open-ils.cstore.savepoint.rollback</literal>\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
<literal>open-ils.pcrud.savepoint.begin</literal>\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
<literal>open-ils.pcrud.savepoint.commit</literal>\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
<literal>open-ils.pcrud.savepoint.rollback</literal>\r
</simpara>\r
</listitem>\r
</itemizedlist>\r
<simpara>Transactions and savepoints must be performed within a stateful\r
connection to the <literal>open-ils.cstore</literal> and <literal>open-ils.pcrud</literal> services.\r
In <literal>srfsh</literal>, you can open a stateful connection using the <literal>open</literal>\r
command, and then close the stateful connection using the <literal>close</literal>\r
command - for example:</simpara>\r
<screen>srfsh# open open-ils.cstore\r
... perform various transaction-related work\r
srfsh# close open-ils.cstore</screen>\r
<section id="_json_queries">\r
<title>JSON Queries</title>\r
<simpara>Beyond simply retrieving objects by their ID using the <literal>\*.retrieve</literal>\r
methods, you can issue queries against the <literal>\*.delete</literal> and <literal>\*.search</literal>\r
methods using JSON to filter results with simple or complex search\r
conditions.</simpara>\r
<simpara>For example, to generate a list of barcodes that are held in a\r
copy location that allows holds and is visible in the OPAC:</simpara>\r
<programlisting language="sh" linenumbering="unnumbered">srfsh# request open-ils.cstore open-ils.cstore.json_query      #\ <co id="CO7-1"/>\r
    {"select": {"acp":["barcode"], "acpl":["name"]},           #\ <co id="CO7-2"/>\r
     "from":   {"acp":"acpl"},                                 #\ <co id="CO7-3"/>\r
     "where":  [                                               #\ <co id="CO7-4"/>\r
         {"+acpl": "holdable"},                                #\ <co id="CO7-5"/>\r
         {"+acpl": "opac_visible"}                             #\ <co id="CO7-6"/>\r
     ]}\r
\r
Received Data: {\r
  "barcode":"BARCODE1",\r
  "name":"Stacks"\r
}\r
\r
Received Data: {\r
  "barcode":"BARCODE2",\r
  "name":"Stacks"\r
}</programlisting>\r
<calloutlist>\r
<callout arearefs="CO7-1">\r
<simpara>\r
Invoke the <literal>json_query</literal> service.\r
</simpara>\r
</callout>\r
<callout arearefs="CO7-2">\r
<simpara>\r
Select the <literal>barcode</literal> field from the <literal>acp</literal> class and the <literal>name</literal>\r
field from the <literal>acpl</literal> class.\r
</simpara>\r
</callout>\r
<callout arearefs="CO7-3">\r
<simpara>\r
Join the <literal>acp</literal> class to the <literal>acpl</literal> class based on the linked field\r
defined in the IDL.\r
</simpara>\r
</callout>\r
<callout arearefs="CO7-4">\r
<simpara>\r
Add a <literal>where</literal> clause to filter the results. We have more than one\r
condition beginning with the same key, so we wrap the conditions inside\r
an array.\r
</simpara>\r
</callout>\r
<callout arearefs="CO7-5">\r
<simpara>\r
The first condition tests whether the boolean value of the <literal>holdable</literal>\r
field on the <literal>acpl</literal> class is true.\r
</simpara>\r
</callout>\r
<callout arearefs="CO7-6">\r
<simpara>\r
The second condition tests whether the boolean value of the\r
<literal>opac_visible</literal> field on the <literal>acpl</literal> class is true.\r
</simpara>\r
</callout>\r
</calloutlist>\r
<simpara>For thorough coverage of the breadth of support offered by JSON\r
query syntax, see <ulink url="http://open-ils.org/dokuwiki/doku.php?id=documentation:technical:jsontutorial">JSON Queries: A Tutorial</ulink>.</simpara>\r
</section>\r
<section id="_fleshing_linked_objects">\r
<title>Fleshing linked objects</title>\r
<simpara>A simplistic approach to retrieving a set of objects that are linked to\r
an object that you are retrieving - for example, a set of call numbers\r
linked to the barcodes that a given user has borrowed - would be to:\r
  1. Retrieve the list of circulation objects (<literal>circ</literal> class)\r
for a given user (<literal>usr</literal> class).\r
  2. For each circulation object, look up the target copy (<literal>target_copy</literal>\r
field, linked to the <literal>acp</literal> class).\r
  3. For each copy, look up the call number for that copy (<literal>call_number</literal>\r
field, linked to the <literal>acn</literal> class).</simpara>\r
<simpara>However, this would result in potentially hundreds of round-trip\r
queries from the client to the server. Even with low-latency connections,\r
the network overhead would be considerable. So, built into the <literal>open-ils.cstore</literal> and\r
<literal>open-ils.pcrud</literal> access methods is the ability to <emphasis>flesh</emphasis> linked fields -\r
that is, rather than return an identifier to a given linked field,\r
the method can return the entire object as part of the initial response.</simpara>\r
<simpara>Most of the interfaces that return class instances from the IDL offer the\r
ability to flesh returned fields. For example, the\r
<literal>open-ils.cstore.direct.\*.retrieve</literal> methods allow you to specify a\r
JSON structure defining the fields you wish to flesh in the returned object.</simpara>\r
<formalpara><title>Fleshing fields in objects returned by <literal>open-ils.cstore</literal></title><para>\r
<programlisting language="sh" linenumbering="unnumbered">srfsh# request open-ils.cstore open-ils.cstore.direct.asset.copy.retrieve 1, \\r
    {\r
        "flesh": 1,                                                       #\ <co id="CO8-1"/>\r
        "flesh_fields": {                                                 #\ <co id="CO8-2"/>\r
            "acp": ["location"]\r
        }\r
    }</programlisting>\r
</para></formalpara>\r
<calloutlist>\r
<callout arearefs="CO8-1">\r
<simpara>\r
The <literal>flesh</literal> argument is the depth at which objects should be fleshed.\r
For example, to flesh out a field that links to another object that includes\r
a field that links to another object, you would specify a depth of 2.\r
</simpara>\r
</callout>\r
<callout arearefs="CO8-2">\r
<simpara>\r
The <literal>flesh_fields</literal> argument contains a list of objects with the fields\r
to flesh for each object.\r
</simpara>\r
</callout>\r
</calloutlist>\r
<simpara>Let&#8217;s flesh things a little deeper. In addition to the copy location,\r
let&#8217;s also flesh the call number attached to the copy, and then flesh\r
the bibliographic record attached to the call number.</simpara>\r
<formalpara><title>Fleshing fields in fields of objects returned by <literal>open-ils.cstore</literal></title><para>\r
<programlisting language="java" linenumbering="unnumbered">request open-ils.cstore open-ils.cstore.direct.asset.copy.retrieve 1, \\r
    {\r
        "flesh": 2,\r
        "flesh_fields": {\r
            "acp": ["location", "call_number"],\r
            "acn": ["record"]\r
         }\r
    }</programlisting>\r
</para></formalpara>\r
</section>\r
</section>\r
<section id="_adding_an_idl_entry_for_resolverresolver">\r
<title>Adding an IDL entry for ResolverResolver</title>\r
<simpara>Most OpenSRF methods in Evergreen define their object interface in the\r
IDL. Without an entry in the IDL, the prospective caller of a given\r
method is forced to either call the method and inspect the returned\r
contents, or read the source to work out the structure of the JSON\r
payload. At this stage of the tutorial, we have not defined an entry\r
in the IDL to represent the object returned by the\r
<literal>open-ils.resolver.resolve_holdings</literal> method. It is time to complete\r
that task.</simpara>\r
<simpara>The <literal>open-ils.resolver</literal> service is unlike many of the other classes\r
defined in the IDL because its data is not stored in the Evergreen\r
database. Instead, the data is requested from an external Web service\r
and only temporarily cached in <literal>memcached</literal>. Fortunately, the IDL\r
enables us to represent this kind of class by setting the\r
<literal>oils_persist:virtual</literal> class attribute to <literal>true</literal>.</simpara>\r
<simpara>So, let&#8217;s add an entry to the IDL for the <literal>open-ils.resolver.resolve_holdings</literal>\r
service:</simpara>\r
<programlisting language="xml" linenumbering="unnumbered"></programlisting>\r
<simpara>And let&#8217;s make <literal>ResolverResolver.pm</literal> return an array composed of our new\r
<literal>rhr</literal> classes rather than raw JSON objects:</simpara>\r
<programlisting language="perl" linenumbering="unnumbered"></programlisting>\r
<simpara>Once we add the new entry to the IDL and copy the revised <literal>ResolverResolver.pm</literal>\r
Perl module to <literal>/openils/lib/perl5/OpenILS/Application/</literal>, we need to:</simpara>\r
<orderedlist numeration="arabic">\r
<listitem>\r
<simpara>\r
Copy the updated IDL to both the <literal>/openils/conf/</literal> and\r
<literal>/openils/var/web/reports/</literal> directories. The Dojo approach to\r
parsing the IDL uses the IDL stored in the reports directory.\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
Restart the Perl services to make the new IDL visible to the services\r
and refresh the <literal>open-ils.resolver</literal> implementation\r
</simpara>\r
</listitem>\r
<listitem>\r
<simpara>\r
Rerun <literal>/openils/bin/autogen.sh</literal> to regenerate the JavaScript versions\r
of the IDL required by the HTTP translator and gateway.\r
</simpara>\r
</listitem>\r
</orderedlist>\r
<simpara>We also need to adjust our JavaScript client to use the nifty new\r
objects that <literal>open-ils.resolver.resolve_holdings</literal> now returns.\r
The best approach is to use the support in Evergreen&#8217;s Dojo extensions\r
to generate the JavaScript classes directly from the IDL XML file.</simpara>\r
<formalpara><title>Accessing classes defined in the IDL via Fieldmapper</title><para>\r
<programlisting language="html" linenumbering="unnumbered"></programlisting>\r
</para></formalpara>\r
<calloutlist>\r
<callout arearefs="">\r
<simpara>\r
Load the Dojo core.\r
</simpara>\r
</callout>\r
<callout arearefs="">\r
<simpara>\r
<literal>fieldmapper.AutoIDL</literal> reads <literal>/openils/var/reports/fm_IDL.xml</literal> to\r
generate a list of class properties.\r
</simpara>\r
</callout>\r
<callout arearefs="">\r
<simpara>\r
<literal>fieldmapper.dojoData</literal> seems to provide a store for Evergreen data\r
accessed via Dojo.\r
</simpara>\r
</callout>\r
<callout arearefs="">\r
<simpara>\r
<literal>fieldmapper.Fieldmapper</literal> converts the list of class properties into\r
actual classes.\r
</simpara>\r
</callout>\r
<callout arearefs="">\r
<simpara>\r
<literal>fieldmapper.standardRequest</literal> invokes an OpenSRF method and returns\r
an array of objects.\r
</simpara>\r
</callout>\r
<callout arearefs="">\r
<simpara>\r
The first argument to <literal>fieldmapper.standardRequest</literal> is an array\r
containing the OpenSRF service name and method name.\r
</simpara>\r
</callout>\r
<callout arearefs="">\r
<simpara>\r
The second argument to <literal>fieldmapper.standardRequest</literal> is an array\r
containing the arguments to pass to the OpenSRF method.\r
</simpara>\r
</callout>\r
<callout arearefs="">\r
<simpara>\r
As Fieldmapper has instantiated the returned objects based on their\r
class hints, we can invoke getter/setter methods on the objects.\r
</simpara>\r
</callout>\r
</calloutlist>\r
</section>\r
</section>\r
<section id="_license">\r
<title>License</title>\r
<simpara>This work is licensed under a <ulink url="http://creativecommons.org/licenses/by-sa/2.5/ca/">Creative Commons Attribution-Share Alike 2.5 Canada License</ulink>.</simpara>\r
</section>\r
</chapter>\r