-<!-- $Id: introduction.xml,v 1.9 2003-02-21 00:24:26 adam Exp $ -->
<chapter id="introduction"><title>Introduction</title>
<para>
&yaz; is a C/C++ library for information retrieval applications
- using the Z39.50/SRW protocols for information retrieval.
+ using the Z39.50/SRU/SOLR protocols for information retrieval.
</para>
-
+
<para>
Properties of &yaz;:
<itemizedlist>
<listitem><para>
- Fast operation. The C based BER encoders/decoders as well
- as the server component of &yaz; is very fast.
- </para></listitem>
- <listitem><para>
Complete
- <ulink url="http://www.loc.gov/z3950/agency/">Z39.50</ulink>
- version 3 support. All newer extensions
- including Z39.50-2000 have been incorporated.
+ <ulink url="&url.z39.50;">Z39.50</ulink> version 3 support.
+ Amendments and Z39.50-2002 revision is supported.
</para></listitem>
<listitem><para>
Supports
- <ulink url="http://www.loc.gov/z3950/agency/zing/srw/">SRW</ulink>
- version 1.0 (over HTTP and HTTPS).
+ <ulink url="&url.sru;">SRU GET/POST/SOAP</ulink>
+ version 1.2 (over HTTP and HTTPS).
</para></listitem>
<listitem><para>
Includes BER encoders/decoders for the
- <ulink url="http://www.nlc-bnc.ca/iso/ill/">ISO ILL</ulink>
+ <ulink url="&url.ill;">ISO ILL</ulink>
protocol.
</para></listitem>
<listitem><para>
+ Supports
+ <ulink url="&url.solr;">SOLR</ulink> Web Service version 1.4.x (client side only)
+ </para></listitem>
+ <listitem><para>
Supports the following transports: BER over TCP/IP
- (<ulink url="http://www.faqs.org/rfcs/rfc1729.html">RFC1729</ulink>),
+ (<ulink url="&url.ber.over.tcpip;">RFC1729</ulink>),
BER over unix local socket, and
- <ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616.html">HTTP
- 1.1</ulink>.
+ <ulink url="&url.http.1.1;">HTTP 1.1</ulink>.
</para></listitem>
<listitem><para>
Secure Socket Layer support using
- <ulink url="http://www.openssl.org/">OpenSSL</ulink>.
+ <ulink url="&url.gnutls;">GNU TLS</ulink> or
+ <ulink url="&url.openssl;">OpenSSL</ulink>.
If enabled, &yaz; uses HTTPS transport (for SOAP) or
"Secure BER" (for Z39.50).
</para></listitem>
<listitem><para>
Offers
- <ulink url="http://zoom.z3950.org/">ZOOM</ulink>
- C API implementing both Z39.50 and SRW.
+ <ulink url="&url.zoom;">ZOOM</ulink> C API implementing
+ Z39.50, SRU and SOLR Web Service.
</para></listitem>
<listitem><para>
The &yaz; library offers a set of useful utilities
related to the protocols, such as MARC (ISO2709) parser,
CCL (ISO8777) parser,
- <ulink url="http://www.loc.gov/z3950/agency/zing/cql/">CQL</ulink>
+ <ulink url="&url.cql;">CQL</ulink>
parser, memory management routines, character set conversion.
</para></listitem>
<listitem><para>
on Windows using Microsoft Visual C++.
</para></listitem>
<listitem><para>
+ Fast operation. The C based BER encoders/decoders as well
+ as the server component of &yaz; is very fast.
+ </para></listitem>
+ <listitem><para>
Liberal license that allows for commercial use of &yaz;.
</para></listitem>
</itemizedlist>
</listitem>
<listitem>
- <para>
+ <para>
<xref linkend="zoom"/> describes the ZOOM API of &yaz;.
- This is definitely worth a read if you wish to develop a Z39.50/SRW
- client.
- </para>
+ This is definitely worth a read if you wish to develop a Z39.50/SRU
+ client.
+ </para>
</listitem>
-
+
<listitem>
<para>
- <xref linkend="zoom"/> describes the generic frontend server
- and explains how to develop server Z39.50/SRW applications for &yaz;.
- Obviously worth reading if you're to develop a server.
+ <xref linkend="server"/> describes the generic frontend server
+ and explains how to develop server Z39.50/SRU applications for &yaz;.
+ Obviously worth reading if you're to develop a server.
</para>
</listitem>
<listitem>
<para>
- <xref linkend="client"/> describes how to use the &yaz; Z39.50
+ <xref linkend="yaz-client"/> describes how to use the &yaz; Z39.50
client. If you're developer and wish to test your server
or a server from another party, you might find this chapter
useful.
<para>
<xref linkend="asn"/> documents the most commonly used Z39.50
C data structures offered by the &yaz; API. Client
- developers using ZOOM you do not need reading this.
- For the remaining client developers (not using ZOOM),
- reading this chapter is a must.
- Z39.50 server implementors should read this, unless you're
- developing a simple server (or SRW only).
+ developers using ZOOM and non-Z39.50 implementors may skip this.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <xref linkend="soap"/> describes how SRU and SOAP is used
+ in &yaz;. Only if you're developing SRU applications
+ this section is a must.
</para>
</listitem>
<para>
<xref linkend="tools"/> contains sections for the various
tools offered by &yaz;. Scan through the material quickly
- and see what's relevant to you! SRW implementors
- might find the <link linkend="tools.cql">CQL</link> section
+ and see what's relevant to you! SRU implementors
+ might find the <link linkend="cql">CQL</link> section
particularly useful.
</para>
</listitem>
<para>
<xref linkend="odr"/> goes through the details of the
ODR module which is the work horse that encodes and decodes
- BER packages. Implementors using ZOOM only do not need reading this.
+ BER packages. Implementors using ZOOM only, do <emphasis>not</emphasis>
+ need reading this.
Most other Z39.50 implementors only need to read the first two
- sections <link linkend="odr.introduction">Introduction</link>,
- <link linkend="odr.use">Using ODR</link>.
+ sections (<xref linkend="odr.introduction"/> and
+ <xref linkend="odr.use"/>).
</para>
</listitem>
<sect1 id="introduction.api"><title>The API</title>
<para>
- The <ulink url="http://www.indexdata.dk/yaz/">&yaz;</ulink>
+ The <ulink url="&url.yaz;">&yaz;</ulink>
toolkit offers several different levels of access to the
- <ulink url="http://www.loc.gov/z3950/agency/">ISO23950/Z39.50</ulink>,
- <ulink url="http://www.nlc-bnc.ca/iso/ill/">ILL</ulink> and
- SRW protocols.
+ <ulink url="&url.z39.50;">ISO23950/Z39.50</ulink>,
+ <ulink url="&url.ill;">ILL</ulink> and
+ <ulink url="&url.sru;">SRU</ulink>
+ protocols.
The level that you need to use depends on your requirements, and
the role (server or client) that you want to implement.
If you're developing a client application you should consider the
<link linkend="zoom">ZOOM</link> API.
- It is, by far, the easiest way to develop clients in C.
+ It is, by far, the easiest way to develop clients in C.
Server implementers should consider the
<link linkend="server">generic frontend server</link>.
None of those high-level APIs support the whole protocol, but
- they do include most facilities used in existing Z39.50
- applications.
+ they do include most facilities used in existing Z39.50 applications.
</para>
<para>
If you're using 'exotic' functionality (meaning anything not included in
you're going to develop an ILL application you'll have to learn the lower
level APIs of &yaz;.
</para>
- <para>
- The basic low level modules, which are independent of the role
- (client or server), consist of three primary interfaces:
-
+ <para>
+ The YAZ toolkit modules is shown in figure <xref linkend="yaz.layer"/>.
+ </para>
+ <figure id="yaz.layer">
+ <title>YAZ layers</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="apilayer.png" format="PNG"/>
+ </imageobject>
+ <imageobject>
+ <imagedata fileref="apilayer.eps" format="EPS"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>
+ There are four layers.
<itemizedlist>
- <listitem><para>&asn;, which provides a C representation of the Z39.50
- protocol packages (PDUs).
- </para></listitem>
- <listitem><para>&odr;, which encodes and decodes the packages according
- to the BER specification.
- </para></listitem>
- <listitem><para>&comstack;, which exchanges the encoded packages with
- a peer process over a network.
- </para></listitem>
+ <listitem>
+ <para>A client or server application (or both).
+ This layer includes ZOOM and the generic frontend server.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The second layer provides a C represenation of the
+ protocol units (packages) for Z39.50 ASN.1, ILL ASN.1,
+ SRU.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The third layer encodes and decodes protocol data units to
+ simple packages (buffer with certain length). The &odr; module
+ encodes and decodes BER whereas the HTTP modules encodes and
+ decodes HTTP ruquests/responses.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The lowest layer is &comstack; which exchanges the encoded packages
+ with a peer process over a network.
+ </para>
+ </listitem>
</itemizedlist>
-
+ </para>
+ <para>
The &asn; module represents the ASN.1 definition of
the Z39.50 protocol. It establishes a set of type and
structure definitions, with one structure for each of the top-level
<para>
If you are using the premade definitions of the &asn; module, and you
are not adding new protocol of your own, the only parts of &odr; that you
- need to worry about are documented in section
- <link linkend="odr-use">Using ODR</link>.
+ need to worry about are documented in
+ <xref linkend="odr.use"/>.
</para>
</note>
create a connection endpoint, you need to specify what transport to
use (TCP/IP, SSL or UNIX sockets).
For the remainder of the connection's lifetime, you don't have
- to worry about the underlying transport protocol at all - the &comstack;
+ to worry about the underlying transport protocol at all - the &comstack;
will ensure that the correct mechanism is used.
</para>
<para>
</para>
<para>
The reason that the &yaz; service-level API is a conglomerate of the
- APIs from three different submodules is twofold. First, we wanted to allow
+ APIs from three different submodules is twofold. First, we wanted to allow
the user a choice of different options for each major task. For instance,
if you don't like the protocol API provided by &odr;/&asn;, you
can use SNACC or BERUtils instead, and still have the benefits of the