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