doc/book.xml

   1 <?xml version="1.0" standalone="no"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
   3     "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
   4 [
   5      <!ENTITY % local SYSTEM "local.ent">
   6      %local;
   7      <!ENTITY manref SYSTEM "manref.xml">
   8      <!ENTITY gpl2 SYSTEM "gpl-2.0.xml">
   9      <!ENTITY % idcommon SYSTEM "common/common.ent">
  10      %idcommon;
  11 ]>
  12 <book>
  13  <bookinfo>
  14   <title>MP-SPARQL - User's Guide and Reference</title>
  15   <authorgroup>
  16    <author>
  17     <firstname>Adam</firstname><surname>Dickmeiss</surname>
  18    </author>
  19    <author>
  20     <firstname>Heikki</firstname><surname>Levanto</surname>
  21    </author>
  22    <author>
  23     <firstname>Jakub</firstname><surname>Skoczen</surname>
  24    </author>
  25   </authorgroup>
  26   <releaseinfo>&version;</releaseinfo>
  27   <copyright>
  28    <year>2014-2015</year>
  29    <holder>Index Data</holder>
  30   </copyright>
  31   <abstract>
  32    <simpara>
  33     This manual is part of MP-SPARQL version &version;.
  34     </simpara>
  35    <simpara>
  36     MP-XQuery is a Metaproxy module that converts Type-1/RPN Queries
  37     to SPARQL.
  38    </simpara>
  39    <simpara>
  40     MP-SPARQL is covered by the GNU General Public License version 2.
  41    </simpara>
  42    <simpara>
  43     <inlinemediaobject>
  44      <imageobject>
  45       <imagedata fileref="common/id.png" format="PNG"/>
  46      </imageobject>
  47      <imageobject>
  48       <imagedata fileref="common/id.eps" format="EPS"/>
  49      </imageobject>
  50     </inlinemediaobject>
  51    </simpara>
  52   </abstract>
  53  </bookinfo>
  54  <chapter id="introduction">
  55   <title>Introduction</title>
  56   <para>
  57    MP-SPARQL is a <ulink url="&url.metaproxy;">Metaproxy</ulink> module
  58    that converts Type-1/RPN queries to <ulink url="http://www.w3.org/TR/rdf-sparql-query/">SPARQL</ulink>.
  59   </para>
  60  </chapter>
  61  <chapter id="installation">
  62   <title>Installation</title>
  63   <para>
  64    MP-SPARQL is available as packages for CentOS/RHEL and most
  65    recent Ubuntu/Debian versions. For other systems, the module must be build
  66    from source.
  67   </para>
  68   <sect1 id="installation.packages">
  69    <title>Installing packages</title>
  70    <para>
  71     You need to enable the relevant software repositories.
  72     For setting up refer to one of:
  73     <ulink
  74         url="http://ftp.indexdata.dk/pub/mp-sparql/redhat/centos/5.5/README">CentOS 5</ulink>,
  75     <ulink
  76         url="http://ftp.indexdata.dk/pub/mp-sparql/redhat/centos/6/README">CentOS 6</ulink>
  77     ,
  78     <ulink
  79         url="http://ftp.indexdata.dk/pub/mp-sparql/redhat/centos/7/README">CentOS 7</ulink>
  80     ,
  81     <ulink
  82         url="http://ftp.indexdata.dk/pub/mp-sparql/ubuntu/README">Ubuntu</ulink>
  83     and
  84     <ulink
  85         url="http://ftp.indexdata.dk/pub/mp-sparql/debian/README">Debian</ulink>
  86    </para>
  87    <para>
  88     The package is called <literal>mp-sparql</literal> on RHEL/Debian systems.
  89     Install that package and you are ready to use filter "sparql" in your
  90     setup.
  91    </para>
  92    <para>
  93     mp-sparql depends on a number of packages created by Index Data and
  94     system-provided ones, such as Libxml2. For external software Zorba, no
  95     system package exist so Index Data has packaged that separately. This
  96     package is called <literal>idzorba</literal>. All these dependences should
  97     be automatically installed when the Index Data software repository is
  98     set up.
  99    </para>
 100   </sect1>
 101   <sect1 id="installation.source">
 102    <title>Installing from source</title>
 103    <para>
 104     To build from source, you need metaproxy development
 105     packages. Metaproxy can be installed as follows:
 106     <screen>
 107      ./configure
 108      make
 109      sudo make install
 110     </screen>
 111     Refer to the Metaproxy documentation for requirements and options.
 112    </para>
 113    <para>
 114     We are now ready to build the MP-SPARQL module with:
 115     <screen>
 116      cd mp-sparql-version
 117      make MP_CONFIG=/usr/local/bin/mp-config
 118     </screen>
 119     Adjust <literal>MP_CONFIG</literal> value
 120     above for the correct location of installed
 121     Metaproxy's mp-config. <literal>MP_CONFIG</literal> can be omitted
 122     if Metaproxy was installed in the system <filename>PATH</filename>.
 123    </para>
 124    <para>
 125     You can now install the <filename>metaproxy_filter_sparql.so</filename>
 126     in a directory searched by Metaproxy daemon.
 127     Specifically, that's the directories
 128     given by the <literal>dlpath</literal> configuration.
 129    </para>
 130    <para>
 131     If dlpath includes <filename>/usr/lib/metaproxy6/modules</filename>,
 132     the module can be installed with:
 133     <screen>
 134      cp src/metaproxy_filter_sparql.so /usr/lib/metaproxy6/modules
 135     </screen>
 136    </para>
 137    <note>
 138     <para>
 139      For RHEL/CentOS systems on 64-bit architectures, the correct paths is:
 140      <filename>/usr/lib64/metaproxy6/modules</filename>.
 141     </para>
 142    </note>
 143   </sect1>
 144   <sect1 id="configuration">
 145    <title>Configuration</title>
 146    <para>
 147     If you have installed mp-sparql as a package or have executed
 148     <literal>make install</literal> from source, sample configuration
 149     can be found in <filename>/usr/share/mp-sparql/bibframe</filename> or
 150     <filename>/usr/local/share/mp-sparql/bibframe</filename>. In the
 151     the following /usr/share prefix assumed. Adjust accordingly.
 152     The directory contains these files:
 153     <variablelist>
 154      <varlistentry>
 155       <term><filename>triplestore.xml</filename></term>
 156       <listitem>
 157        <para>
 158         A mature PQF to SPARQL configuration illustrating a lot of the
 159         configuration facilities that are described in the manual
 160         page of <xref linkend="sparql"/>.
 161        </para>
 162       </listitem>
 163      </varlistentry>
 164      <varlistentry>
 165       <term><filename>config-sparql.xml</filename></term>
 166       <listitem>
 167        <para>
 168         A full metaproxy configuration file that includes
 169         <filename>triplestore.xml</filename> cofiguration for the
 170         mp-sparql filter, enables SRU and CQL to PQF conversion.
 171        </para>
 172       </listitem>
 173      </varlistentry>
 174      <varlistentry>
 175       <term><filename>filter-sparql.xml</filename></term>
 176       <listitem>
 177        <para>
 178         A partial metaproxy configuration suitable to be enabled in
 179         <filename>/etc/metaproxy/filters-enabled</filename>.
 180         This includes <filename>triplestore.xml</filename> as well.
 181        </para>
 182       </listitem>
 183      </varlistentry>
 184     </variablelist>
 185    </para>
 186    <para>
 187     If you want to use the package layout and modular configuration we
 188     suggest you use filter-sparql.xml and perform something along the lines of:
 189     <screen>
 190      cp /usr/share/mp-sparql/bibframe/filter-sparql.xml /etc/metaproxy/filters-available
 191      cp /usr/share/mp-sparql/bibframe/triplestore.xml /etc/metaproxy
 192      vi /etc/metaproxy/triplestore.xml
 193      ln -s ../filters-available/filter-sparql.xml /etc/metaproxy/filters-enabled
 194      service metaproxy restart
 195     </screen>
 196     A copy of triplestore.xml is made. Adjust the
 197     <literal>&lt;defaults uri=.. </literal> value to the URI of your
 198     triplestore.
 199    </para>
 200    <para>
 201     If you want to create your own top-level configuration, you can copy
 202     <filename>config-sparql.xml</filename> to any location you like and
 203     run metaproxy with that. Something like this:
 204     <screen>
 205      mkdir /etc/myconfig
 206      cp /usr/share/mp-sparql/bibframe/* /etc/myconfig
 207      sudo vi /etc/myconfig/triplestore.xml
 208      metaproxy -c /etc/myconfig/config-sparql.xml
 209     </screen>
 210     Again, a copy of triplestore.xml is made. Adjust the
 211     <literal>&lt;defaults uri=.. </literal> value to the URI of your
 212     triplestore.
 213    </para>
 214    <note>
 215     <para>
 216      Do not edit files in <filename>/usr/share/mp-sparql/bibframe</filename>.
 217      They are only samples and will be overwritten by a package update.
 218      Instead copy the files away from there if you need to modify them.
 219     </para>
 220    </note>
 221   </sect1>
 222   <sect1 id="using">
 223    <title>Using the service</title>
 224    <para>
 225     Either way, unless you have adjusted the metaproxy configuration,
 226     Metaproxy can be reached on port 9000. Example using yaz-client and
 227     PQF/Type-1:
 228     <screen><![CDATA[
 229 adam@tuna:~$ yaz-client localhost:9000/work
 230 Connecting...OK.
 231 Sent initrequest.
 232 Connection accepted by v3 target.
 233 ID     : 81
 234 Name   : sparql
 235 Version: 1.9.0/5.14.6 87faebe8ef5cab8f6df86f387e8b919b7b9897a8
 236 Options: search present namedResultSets
 237 Elapsed: 0.000961
 238 Z> f @attr 1=bf.anytitle water
 239 Sent searchRequest.
 240 Received SearchResponse.
 241 Search was a success.
 242 Number of hits: 1, setno 1
 243 records returned: 0
 244 Elapsed: 0.279441
 245 Z> s
 246 Sent presentRequest (1+1).
 247 Records: 1
 248 [work]Record type: XML
 249 <?xml version="1.0" encoding="utf-8" ?>
 250 <rdf:RDF
 251         xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
 252         xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
 253         xmlns:ns2="http://bibframe.org/vocab/" >
 254   <rdf:Description rdf:about="http://bibframe.org/resources/sample-lc-2/15513351">
 255   ...
 256   </rdf:Description>
 257 </rdf:RDF>nextResultSetPosition = 0
 258 Elapsed: 0.256142
 259 ]]></screen>
 260    </para>
 261    <para>
 262    Example using SRU:
 263    <ulink url="http://localhost:9000/work?query=bf.anytitle%3Dwater&amp;maximumRecords=1"/>
 264    </para>
 265   </sect1>
 266  </chapter>
 267  <reference id="reference">
 268   <title>Reference</title>
 269    <partintro id="reference-introduction">
 270     <para>
 271      The material in this chapter is drawn directly from the individual
 272      manual entries.
 273     </para>
 274    </partintro>
 275    &manref;
 276  </reference>
 277
 278  <appendix id="license">
 279   <title>License</title>
 280   <para>
 281    Copyright (C) 2014-2015 Index Data
 282   </para>
 283
 284   <para>
 285    Metaproxy is free software; you can redistribute it and/or modify it under
 286    the terms of the GNU General Public License as published by the Free
 287    Software Foundation; either version 2, or (at your option) any later
 288    version.
 289    </para>
 290
 291   <para>
 292    Metaproxy is distributed in the hope that it will be useful, but WITHOUT ANY
 293    WARRANTY; without even the implied warranty of MERCHANTABILITY or
 294    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 295    for more details.
 296   </para>
 297
 298   <para>
 299    You should have received a copy of the GNU General Public License
 300    along with Metaproxy; see the file LICENSE.  If not, write to the
 301    Free Software Foundation,
 302    51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 303   </para>
 304
 305  </appendix>
 306
 307  &gpl2;
 308 </book>
 309
 310 <!-- Keep this comment at the end of the file
 311 Local variables:
 312 mode: nxml
 313 nxml-child-indent: 1
 314 End:
 315 -->