doc/recordmodel-domxml.xml

   1  <chapter id="record-model-domxml">
   2   <title>&acro.dom; &acro.xml; Record Model and Filter Module</title>
   3
   4   <para>
   5    The record model described in this chapter applies to the fundamental,
   6    structured &acro.xml;
   7    record type <literal>&acro.dom;</literal>, introduced in
   8    <xref linkend="componentmodulesdom"/>. The &acro.dom; &acro.xml; record model
   9    is experimental, and its inner workings might change in future
  10    releases of the &zebra; Information Server.
  11   </para>
  12
  13
  14
  15   <section id="record-model-domxml-filter">
  16    <title>&acro.dom; Record Filter Architecture</title>
  17
  18    <para>
  19     The &acro.dom; &acro.xml; filter uses a standard &acro.dom; &acro.xml; structure as
  20     internal data model, and can therefore parse, index, and display
  21     any &acro.xml; document type. It is well suited to work on
  22     standardized &acro.xml;-based formats such as Dublin Core, MODS, METS,
  23     MARCXML, OAI-PMH, RSS, and performs equally  well on any other
  24     non-standard &acro.xml; format.
  25    </para>
  26    <para>
  27     A parser for binary &acro.marc; records based on the ISO2709 library
  28     standard is provided, it transforms these to the internal
  29     &acro.marcxml; &acro.dom; representation. Other binary document parsers
  30     are planned to follow.
  31    </para>
  32
  33    <para>
  34     The &acro.dom; filter architecture consists of four
  35     different pipelines, each being a chain of arbitrarily many successive
  36     &acro.xslt; transformations of the internal &acro.dom; &acro.xml;
  37     representations of documents.
  38    </para>
  39
  40    <figure id="record-model-domxml-architecture-fig">
  41     <title>&acro.dom; &acro.xml; filter architecture</title>
  42     <mediaobject>
  43      <imageobject>
  44       <imagedata fileref="domfilter.pdf" format="PDF" scale="50"/>
  45      </imageobject>
  46      <imageobject>
  47       <imagedata fileref="domfilter.png" format="PNG"/>
  48      </imageobject>
  49      <textobject>
  50       <!-- Fall back if none of the images can be used -->
  51       <phrase>
  52        [Here there should be a diagram showing the &acro.dom; &acro.xml;
  53        filter architecture, but is seems that your
  54        tool chain has not been able to include the diagram in this
  55        document.]
  56       </phrase>
  57      </textobject>
  58     </mediaobject>
  59    </figure>
  60
  61
  62    <table id="record-model-domxml-architecture-table" frame="top">
  63     <title>&acro.dom; &acro.xml; filter pipelines overview</title>
  64     <tgroup cols="5">
  65      <thead>
  66       <row>
  67        <entry>Name</entry>
  68        <entry>When</entry>
  69        <entry>Description</entry>
  70        <entry>Input</entry>
  71        <entry>Output</entry>
  72       </row>
  73      </thead>
  74
  75      <tbody>
  76       <row>
  77        <entry><literal>input</literal></entry>
  78        <entry>first</entry>
  79        <entry>input parsing and initial
  80         transformations to common &acro.xml; format</entry>
  81        <entry>Input raw &acro.xml; record buffers, &acro.xml;  streams and
  82         binary &acro.marc; buffers</entry>
  83        <entry>Common &acro.xml; &acro.dom;</entry>
  84       </row>
  85       <row>
  86        <entry><literal>extract</literal></entry>
  87        <entry>second</entry>
  88        <entry>indexing term extraction
  89         transformations</entry>
  90        <entry>Common &acro.xml; &acro.dom;</entry>
  91        <entry>Indexing &acro.xml; &acro.dom;</entry>
  92       </row>
  93       <row>
  94        <entry><literal>store</literal></entry>
  95        <entry>second</entry>
  96        <entry> transformations before internal document
  97         storage</entry>
  98        <entry>Common &acro.xml; &acro.dom;</entry>
  99        <entry>Storage &acro.xml; &acro.dom;</entry>
 100       </row>
 101       <row>
 102        <entry><literal>retrieve</literal></entry>
 103        <entry>third</entry>
 104        <entry>multiple document retrieve transformations from
 105         storage to different output
 106         formats are possible</entry>
 107        <entry>Storage &acro.xml; &acro.dom;</entry>
 108        <entry>Output &acro.xml; syntax in requested formats</entry>
 109       </row>
 110      </tbody>
 111     </tgroup>
 112    </table>
 113
 114    <para>
 115     The &acro.dom; &acro.xml; filter pipelines use &acro.xslt; (and if  supported on
 116     your platform, even &acro.exslt;), it brings thus full &acro.xpath;
 117     support to the indexing, storage and display rules of not only
 118     &acro.xml; documents, but also binary &acro.marc; records.
 119    </para>
 120   </section>
 121
 122
 123   <section id="record-model-domxml-pipeline">
 124    <title>&acro.dom; &acro.xml; filter pipeline configuration</title>
 125
 126    <para>
 127     The experimental, loadable  &acro.dom; &acro.xml;/&acro.xslt; filter module
 128     <literal>mod-dom.so</literal>
 129     is invoked by the <filename>zebra.cfg</filename> configuration statement
 130     <screen>
 131      recordtype.xml: dom.db/filter_dom_conf.xml
 132     </screen>
 133     In this example the &acro.dom; &acro.xml; filter is configured to work
 134     on all data files with suffix
 135     <filename>*.xml</filename>, where the configuration file is found in the
 136     path <filename>db/filter_dom_conf.xml</filename>.
 137    </para>
 138
 139    <para>The &acro.dom; &acro.xslt; filter configuration file must be
 140     valid &acro.xml;. It might look like this:
 141     <screen>
 142      <![CDATA[
 143      <?xml version="1.0" encoding="UTF8"?>
 144      <dom xmlns="http://indexdata.com/zebra-2.0">
 145      <input>
 146      <xmlreader level="1"/>
 147      <!-- <marc inputcharset="marc-8"/> -->
 148     </input>
 149      <extract>
 150      <xslt stylesheet="common2index.xsl"/>
 151     </extract>
 152      <store>
 153      <xslt stylesheet="common2store.xsl"/>
 154     </store>
 155      <retrieve name="dc">
 156      <xslt stylesheet="store2dc.xsl"/>
 157     </retrieve>
 158      <retrieve name="mods">
 159      <xslt stylesheet="store2mods.xsl"/>
 160     </retrieve>
 161     </dom>
 162      ]]>
 163     </screen>
 164    </para>
 165    <para>
 166     The root &acro.xml; element <literal>&lt;dom&gt;</literal> and all other &acro.dom;
 167     &acro.xml; filter elements are residing in the namespace
 168     <literal>xmlns="http://indexdata.com/zebra-2.0"</literal>.
 169    </para>
 170    <para>
 171     All pipeline definition elements - i.e. the
 172     <literal>&lt;input&gt;</literal>,
 173     <literal>&lt;extract&gt;</literal>,
 174     <literal>&lt;store&gt;</literal>, and
 175     <literal>&lt;retrieve&gt;</literal> elements - are optional.
 176     Missing pipeline definitions are just interpreted
 177     do-nothing identity pipelines.
 178    </para>
 179    <para>
 180     All pipeline definition elements may contain zero or more
 181     <literal><![CDATA[<xslt stylesheet="path/file.xsl"/>]]></literal>
 182     &acro.xslt; transformation instructions, which are performed
 183     sequentially from top to bottom.
 184     The paths in the <literal>stylesheet</literal> attributes
 185     are relative to zebras working directory, or absolute to the file
 186     system root.
 187    </para>
 188
 189
 190    <section id="record-model-domxml-pipeline-input">
 191     <title>Input pipeline</title>
 192     <para>
 193      The <literal>&lt;input&gt;</literal> pipeline definition element
 194      may contain either one &acro.xml; Reader definition
 195      <literal><![CDATA[<xmlreader level="1"/>]]></literal>, used to split
 196      an &acro.xml; collection input stream into individual &acro.xml; &acro.dom;
 197      documents at the prescribed element level,
 198      or one &acro.marc; binary
 199      parsing instruction
 200      <literal><![CDATA[<marc inputcharset="marc-8"/>]]></literal>, which defines
 201      a conversion to &acro.marcxml; format &acro.dom; trees. The allowed values
 202      of the <literal>inputcharset</literal> attribute depend on your
 203      local <productname>iconv</productname> set-up.
 204     </para>
 205     <para>
 206      Both input parsers deliver individual &acro.dom; &acro.xml; documents to the
 207      following chain of zero or more
 208      <literal><![CDATA[<xslt stylesheet="path/file.xsl"/>]]></literal>
 209      &acro.xslt; transformations. At the end of this pipeline, the documents
 210      are in the common format, used to feed both the
 211      <literal>&lt;extract&gt;</literal> and
 212      <literal>&lt;store&gt;</literal> pipelines.
 213     </para>
 214    </section>
 215
 216    <section id="record-model-domxml-pipeline-extract">
 217     <title>Extract pipeline</title>
 218     <para>
 219      The <literal>&lt;extract&gt;</literal> pipeline takes documents
 220      from any common &acro.dom; &acro.xml; format to the &zebra; specific
 221      indexing &acro.dom; &acro.xml; format.
 222      It may consist of zero ore more
 223      <literal><![CDATA[<xslt stylesheet="path/file.xsl"/>]]></literal>
 224      &acro.xslt; transformations, and the outcome is handled to the
 225      &zebra; core to drive the process of building the inverted
 226      indexes. See
 227      <xref linkend="record-model-domxml-canonical-index"/> for
 228      details.
 229     </para>
 230    </section>
 231
 232    <section id="record-model-domxml-pipeline-store">
 233     <title>Store pipeline</title>
 234     The <literal>&lt;store&gt;</literal> pipeline takes documents
 235     from any common &acro.dom;  &acro.xml; format to the &zebra; specific
 236     storage &acro.dom;  &acro.xml; format.
 237     It may consist of zero ore more
 238     <literal><![CDATA[<xslt stylesheet="path/file.xsl"/>]]></literal>
 239     &acro.xslt; transformations, and the outcome is handled to the
 240     &zebra; core for deposition into the internal storage system.
 241    </section>
 242
 243    <section id="record-model-domxml-pipeline-retrieve">
 244     <title>Retrieve pipeline</title>
 245     <para>
 246      Finally, there may be one or more
 247      <literal>&lt;retrieve&gt;</literal> pipeline definitions, each
 248      of them again consisting of zero or more
 249      <literal><![CDATA[<xslt stylesheet="path/file.xsl"/>]]></literal>
 250      &acro.xslt; transformations. These are used for document
 251      presentation after search, and take the internal storage &acro.dom;
 252      &acro.xml; to the requested output formats during record present
 253      requests.
 254     </para>
 255     <para>
 256      The  possible multiple
 257      <literal>&lt;retrieve&gt;</literal> pipeline definitions
 258      are distinguished by their unique <literal>name</literal>
 259      attributes, these are the literal <literal>schema</literal> or
 260      <literal>element set</literal> names used in
 261      <ulink url="http://www.loc.gov/standards/sru/srw/">&acro.srw;</ulink>,
 262      <ulink url="&url.sru;">&acro.sru;</ulink> and
 263      &acro.z3950; protocol queries.
 264     </para>
 265    </section>
 266
 267
 268    <section id="record-model-domxml-canonical-index">
 269     <title>Canonical Indexing Format</title>
 270
 271     <para>
 272      &acro.dom; &acro.xml; indexing comes in two flavors: pure
 273      processing-instruction governed plain &acro.xml; documents, and - very
 274      similar to the Alvis filter indexing format - &acro.xml; documents
 275      containing &acro.xml; <literal>&lt;record&gt;</literal> and
 276      <literal>&lt;index&gt;</literal> instructions from the magic
 277      namespace <literal>xmlns:z="http://indexdata.com/zebra-2.0"</literal>.
 278     </para>
 279
 280     <section id="record-model-domxml-canonical-index-pi">
 281      <title>Processing-instruction governed indexing format</title>
 282
 283      <para>The output of the processing instruction driven
 284       indexing &acro.xslt; stylesheets must contain
 285       processing instructions named
 286       <literal>zebra-2.0</literal>.
 287       The output of the &acro.xslt; indexing transformation is then
 288       parsed using &acro.dom; methods, and the contained instructions are
 289       performed on the <emphasis>elements and their
 290        subtrees directly following the processing instructions</emphasis>.
 291      </para>
 292      <para>
 293       For example, the output of the command
 294       <screen>
 295        xsltproc dom-index-pi.xsl marc-one.xml
 296       </screen>
 297       might look like this:
 298       <screen>
 299        <![CDATA[
 300        <?xml version="1.0" encoding="UTF-8"?>
 301        <?zebra-2.0 record id=11224466 rank=42?>
 302        <record>
 303        <?zebra-2.0 index control:0?>
 304        <control>11224466</control>
 305        <?zebra-2.0 index any:w title:w title:p title:s?>
 306        <title>How to program a computer</title>
 307       </record>
 308        ]]>
 309       </screen>
 310      </para>
 311     </section>
 312
 313     <section id="record-model-domxml-canonical-index-element">
 314      <title>Magic element governed indexing format</title>
 315
 316      <para>The output of the indexing &acro.xslt; stylesheets must contain
 317       certain elements in the magic
 318       <literal>xmlns:z="http://indexdata.com/zebra-2.0"</literal>
 319       namespace. The output of the &acro.xslt; indexing transformation is then
 320       parsed using &acro.dom; methods, and the contained instructions are
 321       performed on the <emphasis>magic elements and their
 322        subtrees</emphasis>.
 323      </para>
 324      <para>
 325       For example, the output of the command
 326       <screen>
 327        xsltproc dom-index-element.xsl marc-one.xml
 328       </screen>
 329       might look like this:
 330       <screen>
 331        <![CDATA[
 332        <?xml version="1.0" encoding="UTF-8"?>
 333        <z:record xmlns:z="http://indexdata.com/zebra-2.0"
 334        z:id="11224466" z:rank="42">
 335        <z:index name="control:0">11224466</z:index>
 336        <z:index name="any:w title:w title:p title:s">
 337        How to program a computer</z:index>
 338       </z:record>
 339        ]]>
 340       </screen>
 341      </para>
 342     </section>
 343
 344
 345     <section id="record-model-domxml-canonical-index-semantics">
 346      <title>Semantics of the indexing formats</title>
 347
 348      <para>
 349       Both indexing formats are defined with equal semantics and
 350       behavior in mind:
 351       <itemizedlist>
 352        <listitem>
 353         <para>&zebra; specific instructions are either
 354          processing instructions named
 355          <literal>zebra-2.0</literal> or
 356          elements contained in the namespace
 357          <literal>xmlns:z="http://indexdata.com/zebra-2.0"</literal>.
 358         </para>
 359        </listitem>
 360        <listitem>
 361         <para>There must be exactly one <literal>record</literal>
 362          instruction, which sets the scope for the following,
 363          possibly nested <literal>index</literal> instructions.
 364         </para>
 365        </listitem>
 366        <listitem>
 367         <para>
 368          The unique <literal>record</literal> instruction
 369          may have additional attributes <literal>id</literal>,
 370          <literal>rank</literal> and <literal>type</literal>.
 371          Attribute <literal>id</literal> is the value of the opaque ID
 372          and may be any string not containing the whitespace character
 373          <literal>' '</literal>.
 374          The <literal>rank</literal> attribute value must be a
 375          non-negative integer. See
 376          <xref linkend="administration-ranking"/> .
 377          The <literal>type</literal> attribute specifies how the record
 378          is to be treated. The following values may be given for
 379          <literal>type</literal>:
 380          <variablelist>
 381           <varlistentry>
 382            <term><literal>insert</literal></term>
 383            <listitem>
 384             <para>
 385              The record is inserted. If the record already exists, it is
 386              skipped (i.e. not replaced).
 387             </para>
 388            </listitem>
 389           </varlistentry>
 390           <varlistentry>
 391            <term><literal>replace</literal></term>
 392            <listitem>
 393             <para>
 394              The record is replaced. If the record does not already exist,
 395              it is skipped (i.e. not inserted).
 396             </para>
 397            </listitem>
 398           </varlistentry>
 399           <varlistentry>
 400            <term><literal>delete</literal></term>
 401            <listitem>
 402             <para>
 403              The record is deleted. If the record does not already exist,
 404              a warning issued and rest of records are skipped in
 405              from the input stream.
 406             </para>
 407            </listitem>
 408           </varlistentry>
 409           <varlistentry>
 410            <term><literal>update</literal></term>
 411            <listitem>
 412             <para>
 413              The record is inserted or replaced depending on whether the
 414              record exists or not. This is the default behavior but may
 415              be effectively changed by "outside" the scope of the DOM
 416              filter by zebraidx commands or extended services updates.
 417             </para>
 418            </listitem>
 419           </varlistentry>
 420           <varlistentry>
 421            <term><literal>adelete</literal></term>
 422            <listitem>
 423             <para>
 424              The record is deleted. If the record does not already exist,
 425              it is skipped (i.e. nothing is deleted).
 426             </para>
 427             <note>
 428              <para>
 429               Requires version 2.0.54 or later.
 430              </para>
 431             </note>
 432            </listitem>
 433           </varlistentry>
 434          </variablelist>
 435          Note that the value of <literal>type</literal> is only used to
 436          determine the action if and only if the Zebra indexer is running
 437          in "update" mode (i.e zebraidx update) or if the specialUpdate
 438          action of the
 439          <link linkend="administration-extended-services-z3950">Extended
 440           Service Update</link> is used.
 441          For this reason a specialUpdate may end up deleting records!
 442         </para>
 443        </listitem>
 444        <listitem>
 445         <para> Multiple and possible nested <literal>index</literal>
 446          instructions must contain at least one
 447          <literal>indexname:indextype</literal>
 448          pair, and may contain multiple such pairs separated by the
 449          whitespace character  <literal>' '</literal>. In each index
 450          pair, the name and the type of the index is separated by a
 451          colon character <literal>':'</literal>.
 452         </para>
 453        </listitem>
 454        <listitem>
 455         <para>
 456          Any index name consisting of ASCII letters, and following the
 457          standard &zebra; rules will do, see
 458          <xref linkend="querymodel-pqf-apt-mapping-accesspoint"/>.
 459         </para>
 460        </listitem>
 461        <listitem>
 462         <para>
 463          Index types are restricted to the values defined in
 464          the standard configuration
 465          file <filename>default.idx</filename>, see
 466          <xref linkend="querymodel-bib1"/> and
 467          <xref linkend="fields-and-charsets"/> for details.
 468         </para>
 469        </listitem>
 470        <listitem>
 471         <para>
 472          &acro.dom; input documents which are not resulting in both one
 473          unique valid
 474          <literal>record</literal> instruction and one or more valid
 475          <literal>index</literal> instructions can not be searched and
 476          found. Therefore,
 477          invalid document processing is aborted, and any content of
 478          the <literal>&lt;extract&gt;</literal> and
 479          <literal>&lt;store&gt;</literal> pipelines is discarded.
 480          A warning is issued in the logs.
 481         </para>
 482        </listitem>
 483       </itemizedlist>
 484      </para>
 485
 486      <para>The examples work as follows:
 487       From the original &acro.xml; file
 488       <literal>marc-one.xml</literal> (or from the &acro.xml; record &acro.dom; of the
 489       same form coming from an <literal>&lt;input&gt;</literal>
 490       pipeline),
 491       the indexing
 492       pipeline <literal>&lt;extract&gt;</literal>
 493       produces an indexing &acro.xml; record, which is defined by
 494       the <literal>record</literal> instruction
 495       &zebra; uses the content of
 496       <literal>z:id="11224466"</literal>
 497       or
 498       <literal>id=11224466</literal>
 499       as internal
 500       record ID, and - in case static ranking is set - the content of
 501       <literal>rank=42</literal>
 502       or
 503       <literal>z:rank="42"</literal>
 504       as static rank.
 505      </para>
 506
 507
 508      <para>In these examples, the following literal indexes are constructed:
 509       <screen>
 510        any:w
 511        control:0
 512        title:w
 513        title:p
 514        title:s
 515       </screen>
 516       where the indexing type is defined after the
 517       literal <literal>':'</literal> character.
 518       Any value from the standard configuration
 519       file <filename>default.idx</filename> will do.
 520       Finally, any
 521       <literal>text()</literal> node content recursively contained
 522       inside the <literal>&lt;z:index&gt;</literal> element, or any
 523       element following a <literal>index</literal> processing instruction,
 524       will be filtered through the
 525       appropriate char map for character normalization, and will be
 526       inserted in the named indexes.
 527      </para>
 528      <para>
 529       Finally, this example configuration can be queried using &acro.pqf;
 530       queries, either transported by &acro.z3950;, (here using a yaz-client)
 531       <screen>
 532        <![CDATA[
 533        Z> open localhost:9999
 534        Z> elem dc
 535        Z> form xml
 536        Z>
 537        Z> find @attr 1=control @attr 4=3 11224466
 538        Z> scan @attr 1=control @attr 4=3 ""
 539        Z>
 540        Z> find @attr 1=title program
 541        Z> scan @attr 1=title ""
 542        Z>
 543        Z> find @attr 1=title @attr 4=2 "How to program a computer"
 544        Z> scan @attr 1=title @attr 4=2 ""
 545        ]]>
 546       </screen>
 547       or the proprietary
 548       extensions <literal>x-pquery</literal> and
 549       <literal>x-pScanClause</literal> to
 550       &acro.sru;, and &acro.srw;
 551       <screen>
 552        <![CDATA[
 553        http://localhost:9999/?version=1.1&operation=searchRetrieve&x-pquery=@attr 1=title program
 554        http://localhost:9999/?version=1.1&operation=scan&x-pScanClause=@attr 1=title ""
 555        ]]>
 556       </screen>
 557       See <xref linkend="zebrasrv-sru"/> for more information on &acro.sru;/&acro.srw;
 558       configuration, and <xref linkend="gfs-config"/> or the &yaz;
 559       <ulink url="&url.yaz.cql;">&acro.cql; section</ulink>
 560       for the details or the &yaz; frontend server.
 561      </para>
 562      <para>
 563       Notice that there are no <filename>*.abs</filename>,
 564       <filename>*.est</filename>, <filename>*.map</filename>, or other &acro.grs1;
 565       filter configuration files involves in this process, and that the
 566       literal index names are used during search and retrieval.
 567      </para>
 568      <para>
 569       In case that we want to support the usual
 570       <literal>bib-1</literal> &acro.z3950; numeric access points, it is a
 571       good idea to choose string index names defined in the default
 572       configuration file <filename>tab/bib1.att</filename>, see
 573       <xref linkend="attset-files"/>
 574      </para>
 575
 576     </section>
 577
 578    </section>
 579   </section>
 580
 581
 582   <section id="record-model-domxml-conf">
 583    <title>&acro.dom; Record Model Configuration</title>
 584
 585
 586    <section id="record-model-domxml-index">
 587     <title>&acro.dom; Indexing Configuration</title>
 588     <para>
 589      As mentioned above, there can be only one indexing pipeline,
 590      and configuration of the indexing process is a synonym
 591      of writing an &acro.xslt; stylesheet which produces &acro.xml; output containing the
 592      magic processing instructions or elements discussed in
 593      <xref linkend="record-model-domxml-canonical-index"/>.
 594      Obviously, there are million of different ways to accomplish this
 595      task, and some comments and code snippets are in order to
 596      enlighten the wary.
 597     </para>
 598     <para>
 599      Stylesheets can be written in the <emphasis>pull</emphasis> or
 600      the <emphasis>push</emphasis> style: <emphasis>pull</emphasis>
 601      means that the output &acro.xml; structure is taken as starting point of
 602      the internal structure of the &acro.xslt; stylesheet, and portions of
 603      the input &acro.xml; are <emphasis>pulled</emphasis> out and inserted
 604      into the right spots of the output &acro.xml; structure.
 605      On the other
 606      side, <emphasis>push</emphasis> &acro.xslt; stylesheets are recursively
 607      calling their template definitions, a process which is commanded
 608      by the input &acro.xml; structure, and is triggered to produce
 609      some output &acro.xml;
 610      whenever some special conditions in the input stylesheets are
 611      met. The <emphasis>pull</emphasis> type is well-suited for input
 612      &acro.xml; with strong and well-defined structure and semantics, like the
 613      following &acro.oai; indexing example, whereas the
 614      <emphasis>push</emphasis> type might be the only possible way to
 615      sort out deeply recursive input &acro.xml; formats.
 616     </para>
 617     <para>
 618      A <emphasis>pull</emphasis> stylesheet example used to index
 619      &acro.oai; harvested records could use some of the following template
 620      definitions:
 621      <screen>
 622       <![CDATA[
 623       <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
 624       xmlns:z="http://indexdata.com/zebra-2.0"
 625       xmlns:oai="http://www.openarchives.org/&acro.oai;/2.0/"
 626       xmlns:oai_dc="http://www.openarchives.org/&acro.oai;/2.0/oai_dc/"
 627       xmlns:dc="http://purl.org/dc/elements/1.1/"
 628       version="1.0">
 629
 630       <!-- Example pull and magic element style Zebra indexing -->
 631       <xsl:output indent="yes" method="xml" version="1.0" encoding="UTF-8"/>
 632
 633       <!-- disable all default text node output -->
 634       <xsl:template match="text()"/>
 635
 636       <!-- disable all default recursive element node transversal -->
 637       <xsl:template match="node()"/>
 638
 639       <!-- match only on oai xml record root -->
 640       <xsl:template match="/">
 641       <z:record z:id="{normalize-space(oai:record/oai:header/oai:identifier)}">
 642       <!-- you may use z:rank="{some XSLT; function here}" -->
 643
 644       <!-- explicetly calling defined templates -->
 645       <xsl:apply-templates/>
 646      </z:record>
 647      </xsl:template>
 648
 649       <!-- OAI indexing templates -->
 650       <xsl:template match="oai:record/oai:header/oai:identifier">
 651       <z:index name="oai_identifier:0">
 652       <xsl:value-of select="."/>
 653      </z:index>
 654      </xsl:template>
 655
 656       <!-- etc, etc -->
 657
 658       <!-- DC specific indexing templates -->
 659       <xsl:template match="oai:record/oai:metadata/oai_dc:dc/dc:title">
 660       <z:index name="dc_any:w dc_title:w dc_title:p dc_title:s ">
 661       <xsl:value-of select="."/>
 662      </z:index>
 663      </xsl:template>
 664
 665       <!-- etc, etc -->
 666
 667      </xsl:stylesheet>
 668       ]]>
 669      </screen>
 670     </para>
 671    </section>
 672
 673
 674    <section id="record-model-domxml-index-marc">
 675     <title>&acro.dom; Indexing &acro.marcxml;</title>
 676     <para>
 677      The &acro.dom; filter allows indexing of both binary &acro.marc; records
 678      and &acro.marcxml; records, depending on its configuration.
 679      A typical &acro.marcxml; record might look like this:
 680      <screen>
 681       <![CDATA[
 682       <record xmlns="http://www.loc.gov/MARC21/slim">
 683       <rank>42</rank>
 684       <leader>00366nam  22001698a 4500</leader>
 685       <controlfield tag="001">   11224466   </controlfield>
 686       <controlfield tag="003">DLC  </controlfield>
 687       <controlfield tag="005">00000000000000.0  </controlfield>
 688       <controlfield tag="008">910710c19910701nju           00010 eng    </controlfield>
 689       <datafield tag="010" ind1=" " ind2=" ">
 690       <subfield code="a">   11224466 </subfield>
 691      </datafield>
 692       <datafield tag="040" ind1=" " ind2=" ">
 693       <subfield code="a">DLC</subfield>
 694       <subfield code="c">DLC</subfield>
 695      </datafield>
 696       <datafield tag="050" ind1="0" ind2="0">
 697       <subfield code="a">123-xyz</subfield>
 698      </datafield>
 699       <datafield tag="100" ind1="1" ind2="0">
 700       <subfield code="a">Jack Collins</subfield>
 701      </datafield>
 702       <datafield tag="245" ind1="1" ind2="0">
 703       <subfield code="a">How to program a computer</subfield>
 704      </datafield>
 705       <datafield tag="260" ind1="1" ind2=" ">
 706       <subfield code="a">Penguin</subfield>
 707      </datafield>
 708       <datafield tag="263" ind1=" " ind2=" ">
 709       <subfield code="a">8710</subfield>
 710      </datafield>
 711       <datafield tag="300" ind1=" " ind2=" ">
 712       <subfield code="a">p. cm.</subfield>
 713      </datafield>
 714      </record>
 715       ]]>
 716      </screen>
 717     </para>
 718
 719     <para>
 720      It is easily possible to make string manipulation in the &acro.dom;
 721      filter. For example, if you want to drop some leading articles
 722      in the indexing of sort fields, you might want to pick out the
 723      &acro.marcxml; indicator attributes to chop of leading substrings. If
 724      the above &acro.xml; example would have an indicator
 725      <literal>ind2="8"</literal> in the title field
 726      <literal>245</literal>, i.e.
 727      <screen>
 728       <![CDATA[
 729       <datafield tag="245" ind1="1" ind2="8">
 730       <subfield code="a">How to program a computer</subfield>
 731      </datafield>
 732       ]]>
 733      </screen>
 734      one could write a template taking into account this information
 735      to chop the first <literal>8</literal> characters from the
 736      sorting index <literal>title:s</literal> like this:
 737      <screen>
 738       <![CDATA[
 739       <xsl:template match="m:datafield[@tag='245']">
 740       <xsl:variable name="chop">
 741       <xsl:choose>
 742       <xsl:when test="not(number(@ind2))">0</xsl:when>
 743       <xsl:otherwise><xsl:value-of select="number(@ind2)"/></xsl:otherwise>
 744      </xsl:choose>
 745      </xsl:variable>
 746
 747       <z:index name="title:w title:p any:w">
 748       <xsl:value-of select="m:subfield[@code='a']"/>
 749      </z:index>
 750
 751       <z:index name="title:s">
 752       <xsl:value-of select="substring(m:subfield[@code='a'], $chop)"/>
 753      </z:index>
 754
 755      </xsl:template>
 756       ]]>
 757      </screen>
 758      The output of the above &acro.marcxml; and &acro.xslt; excerpt would then be:
 759      <screen>
 760       <![CDATA[
 761       <z:index name="title:w title:p any:w">How to program a computer</z:index>
 762       <z:index name="title:s">program a computer</z:index>
 763       ]]>
 764      </screen>
 765      and the record would be sorted in the title index under 'P', not 'H'.
 766     </para>
 767    </section>
 768
 769
 770    <section id="record-model-domxml-index-wizzard">
 771     <title>&acro.dom; Indexing Wizardry</title>
 772     <para>
 773      The names and types of the indexes can be defined in the
 774      indexing &acro.xslt; stylesheet <emphasis>dynamically according to
 775       content in the original &acro.xml; records</emphasis>, which has
 776      opportunities for great power and wizardry as well as grande
 777      disaster.
 778     </para>
 779     <para>
 780      The following excerpt of a <emphasis>push</emphasis> stylesheet
 781      <emphasis>might</emphasis>
 782      be a good idea according to your strict control of the &acro.xml;
 783      input format (due to rigorous checking against well-defined and
 784      tight RelaxNG or &acro.xml; Schema's, for example):
 785      <screen>
 786       <![CDATA[
 787       <xsl:template name="element-name-indexes">
 788       <z:index name="{name()}:w">
 789       <xsl:value-of select="'1'"/>
 790      </z:index>
 791      </xsl:template>
 792       ]]>
 793      </screen>
 794      This template creates indexes which have the name of the working
 795      node of any input  &acro.xml; file, and assigns a '1' to the index.
 796      The example query
 797      <literal>find @attr 1=xyz 1</literal>
 798      finds all files which contain at least one
 799      <literal>xyz</literal> &acro.xml; element. In case you can not control
 800      which element names the input files contain, you might ask for
 801      disaster and bad karma using this technique.
 802     </para>
 803     <para>
 804      One variation over the theme <emphasis>dynamically created
 805       indexes</emphasis> will definitely be unwise:
 806      <screen>
 807       <![CDATA[
 808       <!-- match on oai xml record root -->
 809       <xsl:template match="/">
 810       <z:record>
 811
 812       <!-- create dynamic index name from input content -->
 813       <xsl:variable name="dynamic_content">
 814       <xsl:value-of select="oai:record/oai:header/oai:identifier"/>
 815      </xsl:variable>
 816
 817       <!-- create zillions of indexes with unknown names -->
 818       <z:index name="{$dynamic_content}:w">
 819       <xsl:value-of select="oai:record/oai:metadata/oai_dc:dc"/>
 820      </z:index>
 821      </z:record>
 822
 823      </xsl:template>
 824       ]]>
 825      </screen>
 826      Don't be tempted to play too smart tricks with the power of
 827      &acro.xslt;, the above example will create zillions of
 828      indexes with unpredictable names, resulting in severe &zebra;
 829      index pollution..
 830     </para>
 831    </section>
 832
 833    <section id="record-model-domxml-debug">
 834     <title>Debuggig &acro.dom; Filter Configurations</title>
 835     <para>
 836      It can be very hard to debug a &acro.dom; filter setup due to the many
 837      successive &acro.marc; syntax translations, &acro.xml; stream splitting and
 838      &acro.xslt; transformations involved. As an aid, you have always the
 839      power of the <literal>-s</literal> command line switch to the
 840      <literal>zebraidz</literal> indexing command at your hand:
 841      <screen>
 842       zebraidx -s -c zebra.cfg update some_record_stream.xml
 843      </screen>
 844      This command line simulates indexing and dumps a lot of debug
 845      information in the logs, telling exactly which transformations
 846      have been applied, how the documents look like after each
 847      transformation, and which record ids and terms are send to the indexer.
 848     </para>
 849    </section>
 850
 851    <!--
 852    <section id="record-model-domxml-elementset">
 853    <title>&acro.dom; Exchange Formats</title>
 854    <para>
 855    An exchange format can be anything which can be the outcome of an
 856    &acro.xslt; transformation, as far as the stylesheet is registered in
 857    the main &acro.dom; &acro.xslt; filter configuration file, see
 858    <xref linkend="record-model-domxml-filter"/>.
 859    In principle anything that can be expressed in  &acro.xml;, HTML, and
 860    TEXT can be the output of a <literal>schema</literal> or
 861    <literal>element set</literal> directive during search, as long as
 862    the information comes from the
 863    <emphasis>original input record &acro.xml; &acro.dom; tree</emphasis>
 864    (and not the transformed and <emphasis>indexed</emphasis> &acro.xml;!!).
 865   </para>
 866    <para>
 867    In addition, internal administrative information from the &zebra;
 868    indexer can be accessed during record retrieval. The following
 869    example is a summary of the possibilities:
 870    <screen>
 871    <![CDATA[
 872    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
 873    xmlns:z="http://indexdata.com/zebra-2.0"
 874    version="1.0">
 875
 876    <!- - register internal zebra parameters - ->
 877    <xsl:param name="id" select="''"/>
 878    <xsl:param name="filename" select="''"/>
 879    <xsl:param name="score" select="''"/>
 880    <xsl:param name="schema" select="''"/>
 881
 882    <xsl:output indent="yes" method="xml" version="1.0" encoding="UTF-8"/>
 883
 884    <!- - use then for display of internal information - ->
 885    <xsl:template match="/">
 886    <z:zebra>
 887    <id><xsl:value-of select="$id"/></id>
 888    <filename><xsl:value-of select="$filename"/></filename>
 889    <score><xsl:value-of select="$score"/></score>
 890    <schema><xsl:value-of select="$schema"/></schema>
 891   </z:zebra>
 892   </xsl:template>
 893
 894   </xsl:stylesheet>
 895    ]]>
 896   </screen>
 897   </para>
 898
 899   </section>
 900    -->
 901
 902    <!--
 903    <section id="record-model-domxml-example">
 904    <title>&acro.dom; Filter &acro.oai; Indexing Example</title>
 905    <para>
 906    The source code tarball contains a working &acro.dom; filter example in
 907    the directory <filename>examples/dom-oai/</filename>, which
 908    should get you started.
 909   </para>
 910    <para>
 911    More example data can be harvested from any &acro.oai; compliant server,
 912    see details at the  &acro.oai;
 913    <ulink url="http://www.openarchives.org/">
 914    http://www.openarchives.org/</ulink> web site, and the community
 915    links at
 916    <ulink url="http://www.openarchives.org/community/index.html">
 917    http://www.openarchives.org/community/index.html</ulink>.
 918    There is a  tutorial
 919    found at
 920    <ulink url="http://www.oaforum.org/tutorial/">
 921    http://www.oaforum.org/tutorial/</ulink>.
 922   </para>
 923   </section>
 924    -->
 925
 926   </section>
 927
 928
 929  </chapter>
 930
 931
 932
 933  <!-- Keep this comment at the end of the file
 934  Local variables:
 935  mode: sgml
 936  sgml-omittag:t
 937  sgml-shorttag:t
 938  sgml-minimize-attributes:nil
 939  sgml-always-quote-attributes:t
 940  sgml-indent-step:1
 941  sgml-indent-data:t
 942  sgml-parent-document: "idzebra.xml"
 943  sgml-local-catalogs: nil
 944  sgml-namecase-general:t
 945  End:
 946  -->