doc/introduction.xml

   1  <chapter id="introduction"><title>Introduction</title>
   2
   3   <para>
   4    &yaz; is a C/C++ library for information retrieval applications
   5    using the Z39.50/SRU/Solr protocols for information retrieval.
   6   </para>
   7
   8   <para>
   9    Properties of &yaz;:
  10    <itemizedlist>
  11     <listitem><para>
  12       Complete
  13       <ulink url="&url.z39.50;">Z39.50</ulink> version 3 support.
  14       Amendments and Z39.50-2002 revision is supported.
  15      </para></listitem>
  16     <listitem><para>
  17       Supports
  18       <ulink url="&url.sru;">SRU GET/POST/SOAP</ulink>
  19       version 1.1, 1.2 and 2.0 (over HTTP and HTTPS).
  20      </para></listitem>
  21     <listitem><para>
  22       Includes BER encoders/decoders for the
  23       <ulink url="&url.ill;">ISO ILL</ulink>
  24       protocol.
  25      </para></listitem>
  26     <listitem><para>
  27       Supports
  28       <ulink url="&url.solr;">Solr</ulink> Web Service version 1.4.x
  29       (client side only)
  30      </para></listitem>
  31     <listitem><para>
  32       Supports the following transports: BER over TCP/IP
  33       (<ulink url="&url.ber.over.tcpip;">RFC1729</ulink>),
  34       BER over unix local socket, and
  35       <ulink url="&url.http.1.1;">HTTP 1.1</ulink>.
  36      </para></listitem>
  37     <listitem><para>
  38       Secure Socket Layer support using
  39       <ulink url="&url.gnutls;">GNU TLS</ulink> or
  40       <ulink url="&url.openssl;">OpenSSL</ulink>.
  41       If enabled, &yaz; uses HTTPS transport (for SOAP) or
  42       "Secure BER" (for Z39.50).
  43      </para></listitem>
  44     <listitem><para>
  45       Offers
  46       <ulink url="&url.zoom;">ZOOM</ulink> C API implementing
  47       Z39.50, SRU and Solr Web Service.
  48      </para></listitem>
  49     <listitem><para>
  50       The &yaz; library offers a set of useful utilities
  51       related to the protocols, such as MARC (ISO2709) parser,
  52       CCL (ISO8777) parser,
  53       <ulink url="&url.cql;">CQL</ulink>
  54       parser, memory management routines, character set conversion.
  55      </para></listitem>
  56     <listitem><para>
  57       Portable code. &yaz; compiles out-of-the box on most Unixes and
  58       on Windows using Microsoft Visual C++.
  59      </para></listitem>
  60     <listitem><para>
  61       Fast operation. The C based BER encoders/decoders as well
  62       as the server component of &yaz; is very fast.
  63      </para></listitem>
  64     <listitem><para>
  65       Liberal license that allows for commercial use of &yaz;.
  66      </para></listitem>
  67    </itemizedlist>
  68   </para>
  69
  70   <sect1 id="introduction.reading"><title>Reading this Manual</title>
  71    <para>Most implementors only need to read a fraction of the
  72     material in thie manual, so a quick walkthrough of the chapters
  73     is in order.
  74    </para>
  75    <itemizedlist>
  76     <listitem>
  77      <para>
  78       <xref linkend="installation"/> contains installation
  79       instructions for &yaz;. You don't need reading this
  80       if you expect to download &yaz; binaries.
  81       However, the chapter contains information about how
  82       to make <emphasis>your</emphasis> application link
  83       with &yaz;.
  84      </para>
  85     </listitem>
  86
  87     <listitem>
  88      <para>
  89       <xref linkend="zoom"/> describes the ZOOM API of &yaz;.
  90       This is definitely worth a read if you wish to develop a Z39.50/SRU
  91       client.
  92      </para>
  93     </listitem>
  94
  95     <listitem>
  96      <para>
  97       <xref linkend="server"/> describes the generic frontend server
  98       and explains how to develop server Z39.50/SRU applications for &yaz;.
  99       Obviously worth reading if you're to develop a server.
 100     </para>
 101     </listitem>
 102
 103     <listitem>
 104      <para>
 105       <xref linkend="yaz-client"/> describes how to use the &yaz; Z39.50
 106       client. If you're developer and wish to test your server
 107       or a server from another party, you might find this chapter
 108       useful.
 109     </para>
 110     </listitem>
 111
 112     <listitem>
 113      <para>
 114       <xref linkend="asn"/> documents the most commonly used Z39.50
 115       C data structures offered by the &yaz; API. Client
 116       developers using ZOOM and non-Z39.50 implementors may skip this.
 117      </para>
 118     </listitem>
 119
 120     <listitem>
 121      <para>
 122       <xref linkend="soap"/> describes how SRU and SOAP is used
 123       in &yaz;. Only if you're developing SRU applications
 124       this section is a must.
 125      </para>
 126     </listitem>
 127
 128     <listitem>
 129      <para>
 130       <xref linkend="tools"/> contains sections for the various
 131       tools offered by &yaz;. Scan through the material quickly
 132       and see what's relevant to you! SRU implementors
 133       might find the <link linkend="cql">CQL</link> section
 134       particularly useful.
 135      </para>
 136     </listitem>
 137
 138     <listitem>
 139      <para>
 140       <xref linkend="odr"/> goes through the details of the
 141       ODR module which is the work horse that encodes and decodes
 142       BER packages. Implementors using ZOOM only, do <emphasis>not</emphasis>
 143       need reading this.
 144       Most other Z39.50 implementors only need to read the first two
 145       sections (<xref linkend="odr.introduction"/> and
 146       <xref linkend="odr.use"/>).
 147      </para>
 148     </listitem>
 149
 150     <listitem>
 151      <para>
 152       <xref linkend="comstack"/> describes the network layer module
 153       COMSTACK. Implementors using ZOOM or the generic frontend server
 154       may skip this. Others, presumably, handling client/server
 155      communication on their own should read this.
 156      </para>
 157     </listitem>
 158
 159    </itemizedlist>
 160   </sect1>
 161   <sect1 id="introduction.api"><title>The API</title>
 162
 163    <para>
 164     The <ulink url="&url.yaz;">&yaz;</ulink>
 165     toolkit offers several different levels of access to the
 166     <ulink url="&url.z39.50;">ISO23950/Z39.50</ulink>,
 167     <ulink url="&url.ill;">ILL</ulink> and
 168     <ulink url="&url.sru;">SRU</ulink>
 169     protocols.
 170     The level that you need to use depends on your requirements, and
 171     the role (server or client) that you want to implement.
 172     If you're developing a client application you should consider the
 173     <link linkend="zoom">ZOOM</link> API.
 174     It is, by far, the easiest way to develop clients in C.
 175     Server implementers should consider the
 176     <link linkend="server">generic frontend server</link>.
 177     None of those high-level APIs support the whole protocol, but
 178     they do include most facilities used in existing Z39.50 applications.
 179    </para>
 180    <para>
 181     If you're using 'exotic' functionality (meaning anything not included in
 182     the high-level APIs), developing non-standard extensions to Z39.50 or
 183     you're going to develop an ILL application you'll have to learn the lower
 184     level APIs of &yaz;.
 185    </para>
 186    <para>
 187     The YAZ toolkit modules is shown in figure <xref linkend="yaz.layer"/>.
 188    </para>
 189    <figure id="yaz.layer">
 190     <title>YAZ layers</title>
 191     <mediaobject>
 192      <imageobject>
 193       <imagedata fileref="apilayer.png" format="PNG"/>
 194      </imageobject>
 195      <imageobject>
 196       <imagedata fileref="apilayer.eps" format="EPS"/>
 197      </imageobject>
 198     </mediaobject>
 199    </figure>
 200    <para>
 201     There are four layers.
 202     <itemizedlist>
 203      <listitem>
 204       <para>A client or server application (or both).
 205        This layer includes ZOOM and the generic frontend server.
 206       </para>
 207      </listitem>
 208      <listitem>
 209       <para>
 210        The second layer provides a C represenation of the
 211        protocol units (packages) for Z39.50 ASN.1, ILL ASN.1,
 212        SRU.
 213       </para>
 214      </listitem>
 215      <listitem>
 216       <para>
 217        The third layer encodes and decodes protocol data units to
 218        simple packages (buffer with certain length). The &odr; module
 219        encodes and decodes BER whereas the HTTP modules encodes and
 220        decodes HTTP ruquests/responses.
 221       </para>
 222      </listitem>
 223      <listitem>
 224       <para>
 225        The lowest layer is &comstack; which exchanges the encoded packages
 226        with a peer process over a network.
 227       </para>
 228      </listitem>
 229     </itemizedlist>
 230    </para>
 231    <para>
 232     The &asn; module represents the ASN.1 definition of
 233     the Z39.50 protocol. It establishes a set of type and
 234     structure definitions, with one structure for each of the top-level
 235     PDUs, and one structure or type for each of the contained ASN.1 types.
 236     For primitive types, or other types that are defined by the ASN.1
 237     standard itself (such as the EXTERNAL type), the C representation is
 238     provided by the &odr; (Open Data Representation) subsystem.
 239   </para>
 240    <para>
 241      &odr; is a basic mechanism for representing an
 242     ASN.1 type in the C programming language, and for implementing BER
 243     encoders and decoders for values of that type. The types defined in
 244     the &asn; module generally have the prefix <literal>Z_</literal>, and
 245     a suffix corresponding to the name of the type in the ASN.1
 246     specification of the protocol (generally Z39.50-1995). In the case of
 247     base types (those originating in the ASN.1 standard itself), the prefix
 248     <literal>Odr_</literal> is sometimes seen. Either way, look for
 249     the actual definition in either <filename>z-core.h</filename> (for the types
 250     from the protocol), <filename>odr.h</filename> (for the primitive ASN.1
 251     types).
 252     The &asn; library also provides functions (which are, in turn,
 253     defined using &odr; primitives) for encoding and decoding data values.
 254     Their general form is
 255
 256     <funcsynopsis>
 257      <funcprototype><funcdef>int <function>z_<replaceable>xxx</replaceable></function></funcdef>
 258       <paramdef>ODR <parameter>o</parameter></paramdef>
 259       <paramdef>Z_<replaceable>xxx</replaceable> **<parameter>p</parameter></paramdef>
 260       <paramdef>int <parameter>optional</parameter></paramdef>
 261       <paramdef>const char *<parameter>name</parameter></paramdef>
 262      </funcprototype>
 263     </funcsynopsis>
 264     (note the lower-case &quot;z&quot; in the function name)
 265    </para>
 266
 267    <note>
 268     <para>
 269      If you are using the premade definitions of the &asn; module, and you
 270      are not adding new protocol of your own, the only parts of &odr; that you
 271      need to worry about are documented in
 272      <xref linkend="odr.use"/>.
 273     </para>
 274    </note>
 275
 276   <para>
 277     When you have created a BER-encoded buffer, you can use the &comstack;
 278     subsystem to transmit (or receive) data over the network. The &comstack;
 279     module provides simple functions for establishing a connection
 280     (passively or actively, depending on the role of your application),
 281     and for exchanging BER-encoded PDUs over that connection. When you
 282     create a connection endpoint, you need to specify what transport to
 283     use (TCP/IP, SSL or UNIX sockets).
 284     For the remainder of the connection's lifetime, you don't have
 285     to worry about the underlying transport protocol at all - the &comstack;
 286     will ensure that the correct mechanism is used.
 287    </para>
 288    <para>
 289     We call the combined interfaces to &odr;, &asn;, and &comstack; the service
 290     level API. It's the API that most closely models the Z39.50
 291    service/protocol definition, and it provides unlimited access to all
 292     fields and facilities of the protocol definitions.
 293    </para>
 294    <para>
 295     The reason that the &yaz; service-level API is a conglomerate of the
 296     APIs from three different submodules is twofold. First, we wanted to allow
 297     the user a choice of different options for each major task. For instance,
 298     if you don't like the protocol API provided by &odr;/&asn;, you
 299     can use SNACC or BERUtils instead, and still have the benefits of the
 300     transparent transport approach of the &comstack; module. Secondly,
 301     we realize that you may have to fit the toolkit into an existing
 302     event-processing structure, in a way that is incompatible with
 303     the &comstack; interface or some other part of &yaz;.
 304    </para>
 305   </sect1>
 306  </chapter>
 307
 308  <!-- Keep this comment at the end of the file
 309  Local variables:
 310  mode: sgml
 311  sgml-omittag:t
 312  sgml-shorttag:t
 313  sgml-minimize-attributes:nil
 314  sgml-always-quote-attributes:t
 315  sgml-indent-step:1
 316  sgml-indent-data:t
 317  sgml-parent-document:"yaz.xml"
 318  sgml-local-catalogs: nil
 319  sgml-namecase-general:t
 320  End:
 321  -->