Do some clean up of development files. Adjust converting script to
[working/Evergreen.git] / 1.6 / development / datamodelsandaccess.xml
index da7c40b..a887ab3 100644 (file)
@@ -9,25 +9,25 @@
        </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\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
+               <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&#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
+               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).\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 Open-ILS/src/sql/Pg.</simpara>\r
+               <simpara>Or you can read through the source files in <filename class="directoy">Open-ILS/src/sql/Pg</filename>.</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
                </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">&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="dmCO5-1"/> <co id="dmCO5-2"/> <co id="dmCO5-3"/> <co id="dmCO5-4"/>\r
-                           &lt;fields oils_persist:primary="code" oils_persist:sequence=""&gt;  <co id="dmCO5-5"/>\r
-                               &lt;field reporter:label="Language Code" name="code"\r
-                                   reporter:selector="value" reporter:datatype="text"/&gt; <co id="dmCO5-6"/>\r
-                               &lt;field reporter:label="Language" name="value"\r
-                                   reporter:datatype="text" oils_persist:i18n="true"/&gt; <co id="dmCO5-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="dmCO5-8"/>\r
-                               &lt;actions&gt;\r
-                                   &lt;create global_required="true" permission="CREATE_MARC_CODE"&gt; <co id="dmCO5-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
+<programlisting language="xml" linenumbering="unnumbered">\r
+&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="dmCO5-1"/> <co id="dmCO5-2"/> <co id="dmCO5-3"/> <co id="dmCO5-4"/>\r
+    &lt;fields oils_persist:primary="code" oils_persist:sequence=""&gt;  <co id="dmCO5-5"/>\r
+       &lt;field reporter:label="Language Code" name="code"\r
+           reporter:selector="value" reporter:datatype="text"/&gt; <co id="dmCO5-6"/>\r
+       &lt;field reporter:label="Language" name="value"\r
+           reporter:datatype="text" oils_persist:i18n="true"/&gt; <co id="dmCO5-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="dmCO5-8"/>\r
+       &lt;actions&gt;\r
+           &lt;create global_required="true" permission="CREATE_MARC_CODE"&gt; <co id="dmCO5-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;\r
+</programlisting>\r
                        <calloutlist>\r
                        <callout arearefs="dmCO5-1">\r
                        <simpara>\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
+<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
-                       ]</screen>\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
                        <callout arearefs="dmCO5-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
+                       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
                        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="dmCO6-1"/>\r
-                           &lt;/fields&gt;\r
-                           &lt;links&gt;  <co id="dmCO6-2"/>\r
-                               &lt;link field="owning_lib" reltype="has_a" key="id"\r
-                                       map="" class="aou"/&gt;  <co id="dmCO6-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
+<programlisting language="xml" linenumbering="unnumbered">\r
+&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="dmCO6-1"/>\r
+    &lt;/fields&gt;\r
+    &lt;links&gt;  <co id="dmCO6-2"/>\r
+       &lt;link field="owning_lib" reltype="has_a" key="id"\r
+               map="" class="aou"/&gt;  <co id="dmCO6-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;\r
+</programlisting>\r
                        <calloutlist>\r
                        <callout arearefs="dmCO6-1">\r
                        <simpara>\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="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
+<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
+Received Data: {\r
+  "barcode":"BARCODE1",\r
+  "name":"Stacks"\r
+}\r
 \r
-                       Received Data: {\r
-                         "barcode":"BARCODE2",\r
-                         "name":"Stacks"\r
-                       }</programlisting>\r
+Received Data: {\r
+  "barcode":"BARCODE2",\r
+  "name":"Stacks"\r
+}\r
+</programlisting>\r
                        <calloutlist>\r
                        <callout arearefs="dmCO7-1">\r
                        <simpara>\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="dmCO8-1"/>\r
-                               "flesh_fields": {   <co id="dmCO8-2"/>\r
-                                   "acp": ["location"]\r
-                               }\r
-                           }</programlisting>\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
                        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
+<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
                </listitem>\r
                <listitem>\r
                <simpara>\r
-               Rerun <literal>/openils/bin/autogen.sh</literal> to regenerate the JavaScript versions\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\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&#8217;s Dojo extensions\r
+               The best approach is to use the support in Evergreen&#8217;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
                </callout>\r
                <callout arearefs="">\r
                <simpara>\r
-               <literal>fieldmapper.AutoIDL</literal> reads <literal>/openils/var/reports/fm_IDL.xml</literal> to\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