+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>\r
-<chapter xml:id="data_models_and_access" 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>Evergreen Data Models and Access</title>\r
- </chapterinfo>\r
- <abstract id="DM_abstract">\r
- <simpara>This chapter was taken from Dan Scott's <emphasis>Developer Workshop</emphasis>, February 2010.</simpara>\r
- </abstract>\r
- <section id="exploring_database_schema">\r
- <title>Exploring the Database Schema</title>\r
- <simpara>The database schema is tied pretty tightly to PostgreSQL. Although PostgreSQL<indexterm><primary>databases</primary><secondary>PostgreSQL</secondary></indexterm>\r
- adheres closely to ANSI SQL standards, the use of schemas, SQL functions<indexterm><primary>ANSI</primary></indexterm>\r
- implemented in both <systemitem>plpgsql</systemitem> and <systemitem>plperl</systemitem>, and PostgreSQL’s native full-text\r
- search would make it… challenging… 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)<indexterm><primary>databases</primary><secondary>PostgreSQL</secondary><tertiery>psql</tertiery></indexterm>\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- pgadminIII (a GUI client).<indexterm><primary>databases</primary><secondary>PostgreSQL</secondary><tertiery>pgadminIII</tertiery></indexterm>\r
- </simpara>\r
- </listitem>\r
- </itemizedlist>\r
- <simpara>Or you can read through the source files in <filename class="directoy">Open-ILS/src/sql/Pg</filename>.</simpara>\r
- <simpara>Let’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 → asset.copy_location\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- actor.usr → actor.card\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- biblio.record_entry → asset.call_number → asset.copy\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- config.metabib_field → metabib.*_field_entry\r
- </simpara>\r
- </listitem>\r
- </itemizedlist>\r
- This documentation also contains an Appendix for the Evergreen <xref linkend="databaseschema"/>. \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
- <indexterm><primary>Evergreen Interface Definition Language (IDL)</primary></indexterm>\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
- … oils_persist:readonly tells us, if true, that the data lives in the database, but is pulled from the SELECT statement defined in the <oils_persist:source_definition> \r
- child element\r
- </simpara>\r
- </listitem>\r
- </itemizedlist>\r
- <simplesect id="_idl_basic_example_config_language_map">\r
- <title>IDL basic example (config.language_map)</title>\r
-<programlisting language="xml" linenumbering="unnumbered">\r
-<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"> <co id="dmCO5-1"/> <co id="dmCO5-2"/> <co id="dmCO5-3"/> <co id="dmCO5-4"/>\r
- <fields oils_persist:primary="code" oils_persist:sequence=""> <co id="dmCO5-5"/>\r
- <field reporter:label="Language Code" name="code"\r
- reporter:selector="value" reporter:datatype="text"/> <co id="dmCO5-6"/>\r
- <field reporter:label="Language" name="value"\r
- reporter:datatype="text" oils_persist:i18n="true"/> <co id="dmCO5-7"/>\r
- </fields>\r
- <links/>\r
- <permacrud xmlns="http://open-ils.org/spec/opensrf/IDL/permacrud/v1"> <co id="dmCO5-8"/>\r
- <actions>\r
- <create global_required="true" permission="CREATE_MARC_CODE"> <co id="dmCO5-9"/>\r
- <retrieve global_required="true"\r
- permission="CREATE_MARC_CODE UPDATE_MARC_CODE DELETE_MARC_CODE">\r
- <update global_required="true" permission="UPDATE_MARC_CODE">\r
- <delete global_required="true" permission="DELETE_MARC_CODE">\r
- </actions>\r
- </permacrud>\r
-</class>\r
-</programlisting>\r
- <calloutlist>\r
- <callout arearefs="dmCO5-1">\r
- <simpara>\r
- The <literal>class</literal> element defines the attributes and permissions for classes,\r
- and relationships between classes.\r
- </simpara>\r
- <indexterm><primary>Evergreen Interface Definition Language (IDL)</primary><secondary>class element</secondary></indexterm>\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="dmCO5-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="dmCO5-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="dmCO5-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>\r
-<userinput>\r
-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
-]\r
-</userinput>\r
-</screen>\r
- </callout>\r
- <callout arearefs="dmCO5-5">\r
- <simpara>\r
- The <literal>fields</literal> element defines the list of fields for the class.\r
- </simpara>\r
- <indexterm><primary>Evergreen Interface Definition Language (IDL)</primary><secondary>fields element</secondary></indexterm>\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="dmCO5-6">\r
- <simpara>\r
- Each <literal>field</literal> element defines one property of the class.\r
- </simpara>\r
- <indexterm><primary>Evergreen Interface Definition Language (IDL)</primary><secondary>field element</secondary></indexterm>\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="dmCO5-7">\r
- <simpara>\r
- The <literal>oils_persist:i18n</literal> attribute, when <literal>true</literal>, means that\r
- translated values for the field’s contents may be accessible in\r
- different locales.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="dmCO5-8">\r
- <simpara>\r
- <indexterm><primary>Evergreen Interface Definition Language (IDL)</primary><secondary>permacrud element</secondary></indexterm>\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, \r
- 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
- \r
- </callout>\r
- <callout arearefs="dmCO5-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><field></literal> that identifies\r
- the org_unit at which the user must have the pertinent permission.\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <indexterm><primary>Evergreen Interface Definition Language (IDL)</primary><secondary>action element</secondary></indexterm>\r
- <simpara>\r
- An action element may contain a <literal><context_field></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
- <indexterm><primary>Evergreen Interface Definition Language (IDL)</primary><secondary>context_field element</secondary></indexterm>\r
- <simpara>\r
- If the <literal><context_field></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
- </simplesect>\r
- <simplesect 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
- <listitem>\r
- <simpara>\r
- <literal>link</literal>: link to another class, as defined in the <literal><links></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
- </simplesect>\r
- <simplesect 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><links></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">\r
-<class id="aws" controller="open-ils.cstore"\r
- oils_obj:fieldmapper="actor::workstation"\r
- oils_persist:tablename="actor.workstation"\r
- reporter:label="Workstation">\r
- <fields oils_persist:primary="id"\r
- oils_persist:sequence="actor.workstation_id_seq">\r
- <field reporter:label="Workstation ID" name="id"\r
- reporter:datatype="id"/>\r
- <field reporter:label="Workstation Name" name="name"\r
- reporter:datatype="text"/>\r
- <field reporter:label="Owning Library" name="owning_lib"\r
- reporter:datatype="org_unit"/>\r
- <field reporter:label="Circulations" name="circulations"\r
- oils_persist:virtual="true" reporter:datatype="link"/> <co id="dmCO6-1"/>\r
- </fields>\r
- <links> <co id="dmCO6-2"/>\r
- <link field="owning_lib" reltype="has_a" key="id"\r
- map="" class="aou"/> <co id="dmCO6-3"/>\r
- <link field="circulations" reltype="has_many" key="workstation"\r
- map="" class="circ"/>\r
- <link field="circulation_checkins" reltype="has_many"\r
- key="checkin_workstation" map="" class="circ"/>\r
- </links>\r
-</class>\r
-</programlisting>\r
- <calloutlist>\r
- <callout arearefs="dmCO6-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="dmCO6-2">\r
- <simpara>\r
- The <literal><links></literal> element contains 0 or more <literal><link></literal> elements.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="dmCO6-3">\r
- <simpara>\r
- Each <literal><link></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
- </simplesect>\r
- </section>\r
- <section id="open_ils_cstore_literal_data_access_interfaces">\r
- <title><literal>open-ils.cstore</literal> data access interfaces</title>\r
- <indexterm><primary>cstore</primary></indexterm>\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 <_object_></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 <_object_></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
- <indexterm><primary>pcrud</primary></indexterm>\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 <_authtoken_>, { "code": { "like": "e%" } }</literal>\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- <literal>open-ils.pcrud.retrieve.clm <_authtoken_>, "eng"</literal>\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- <literal>open-ils.pcrud.search.clm <_authtoken_>, { "code": "eng" }</literal>\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- <literal>open-ils.pcrud.create.clm <_authtoken_>, <_object_></literal>\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- <literal>open-ils.pcrud.update.clm <_authtoken_>, <_object_></literal>\r
- </simpara>\r
- </listitem>\r
- <listitem>\r
- <simpara>\r
- <literal>open-ils.pcrud.delete.clm <_authtoken_>, "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
- <simplesect id="_json_queries">\r
- <title>JSON Queries</title>\r
- <indexterm><primary>JSON</primary></indexterm>\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">\r
-srfsh# request open-ils.cstore open-ils.cstore.json_query <co id="dmCO7-1"/>\r
- {"select": {"acp":["barcode"], "acpl":["name"]}, <co id="dmCO7-2"/>\r
- "from": {"acp":"acpl"}, <co id="dmCO7-3"/>\r
- "where": [ <co id="dmCO7-4"/>\r
- {"+acpl": "holdable"}, <co id="dmCO7-5"/>\r
- {"+acpl": "opac_visible"} <co id="dmCO7-6"/>\r
- ]}\r
-\r
-Received Data: {\r
- "barcode":"BARCODE1",\r
- "name":"Stacks"\r
-}\r
-\r
-Received Data: {\r
- "barcode":"BARCODE2",\r
- "name":"Stacks"\r
-}\r
-</programlisting>\r
- <calloutlist>\r
- <callout arearefs="dmCO7-1">\r
- <simpara>\r
- Invoke the <literal>json_query</literal> service.\r
- </simpara>\r
- </callout>\r
- <callout arearefs="dmCO7-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="dmCO7-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="dmCO7-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="dmCO7-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="dmCO7-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
- </simplesect>\r
- <simplesect 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">\r
-srfsh# request open-ils.cstore open-ils.cstore.direct.asset.copy.retrieve 1, \\r
- {\r
- "flesh": 1, <co id="dmCO8-1"/>\r
- "flesh_fields": { <co id="dmCO8-2"/>\r
- "acp": ["location"]\r
- }\r
- }\r
-</programlisting>\r
- </para></formalpara>\r
- <calloutlist>\r
- <callout arearefs="dmCO8-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="dmCO8-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’s flesh things a little deeper. In addition to the copy location,\r
- let’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">\r
-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
- }\r
-</programlisting>\r
- </para></formalpara>\r
- </simplesect>\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’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’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 <filename>/openils/bin/autogen.sh</filename> to regenerate the JavaScript versions<indexterm><primary>autogen</primary></indexterm>\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<indexterm><primary>JavaScript</primary></indexterm>\r
- objects that <literal>open-ils.resolver.resolve_holdings</literal> now returns.\r
- The best approach is to use the support in Evergreen’s Dojo extensions<indexterm><primary>Dojo toolkit</primary></indexterm>\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 <filename>/openils/var/reports/fm_IDL.xml</filename> 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
- \r
-</chapter>\r
projects / Evergreen-DocBook.git / blobdiff