X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Fintroduction.xml;h=dd93b10c54046af9d02a7b014896c10b95f131f6;hp=aecfe6702708aba32dbf6e19c19112664dfc3a2c;hb=4466c3fb3ec5053427237ca4523ed4ed9f7e9425;hpb=add5a2db6b4360b1b448ad09f991a3977eb1220d diff --git a/doc/introduction.xml b/doc/introduction.xml index aecfe67..dd93b10 100644 --- a/doc/introduction.xml +++ b/doc/introduction.xml @@ -1,57 +1,56 @@ - Introduction &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. Properties of &yaz;: - Fast operation. The C based BER encoders/decoders as well - as the server component of &yaz; is very fast. + Complete + Z39.50 version 3 support. + Amendments and Z39.50-2002 revision is supported. - Complete - Z39.50 - version 3 support. All newer extensions - including Z39.50-2000 have been incorporated. + Supports + SRU GET/POST/SOAP + version 1.1, 1.2 and 2.0 (over HTTP and HTTPS). - Supports - SRW - version 1.0 (over HTTP and HTTPS). + Includes BER encoders/decoders for the + ISO ILL + protocol. - Includes BER encoders/decoders for the - ISO ILL - protocol. + Supports + Solr Web Service version 1.4.x + (client side only) Supports the following transports: BER over TCP/IP - (RFC1729), - BER over unix local socket, and - HTTP - 1.1. + (RFC1729), + BER over unix local socket, and + HTTP 1.1. Secure Socket Layer support using - OpenSSL. + GNU TLS or + OpenSSL. If enabled, &yaz; uses HTTPS transport (for SOAP) or "Secure BER" (for Z39.50). - Offers - ZOOM - C API implementing both Z39.50 and SRW. + Offers + ZOOM C API implementing + Z39.50, SRU and Solr Web Service. The &yaz; library offers a set of useful utilities related to the protocols, such as MARC (ISO2709) parser, - CCL (ISO8777) parser, - CQL + CCL (ISO8777) parser, + CQL parser, memory management routines, character set conversion. @@ -59,6 +58,10 @@ on Windows using Microsoft Visual C++. + Fast operation. The C based BER encoders/decoders as well + as the server component of &yaz; is very fast. + + Liberal license that allows for commercial use of &yaz;. @@ -72,7 +75,7 @@ - contains installation + contains installation instructions for &yaz;. You don't need reading this if you expect to download &yaz; binaries. However, the chapter contains information about how @@ -82,24 +85,24 @@ - + describes the ZOOM API of &yaz;. - This is definitely worth a read if you wish to develop a Z39.50/SRW - client. - + This is definitely worth a read if you wish to develop a Z39.50/SRU + client. + - 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. + 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. - describes how to use the &yaz; Z39.50 + 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. @@ -116,8 +119,8 @@ - describes how SRW and SOAP is used - in &yaz;. Only if you're developing SOAP/SRW applications + describes how SRU and SOAP is used + in &yaz;. Only if you're developing SRU applications this section is a must. @@ -126,8 +129,8 @@ 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 CQL section + and see what's relevant to you! SRU implementors + might find the CQL section particularly useful. @@ -136,10 +139,11 @@ 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 not + need reading this. Most other Z39.50 implementors only need to read the first two - sections Introduction, - Using ODR. + sections ( and + ). @@ -155,23 +159,23 @@ The API - + - The &yaz; + The &yaz; toolkit offers several different levels of access to the - ISO23950/Z39.50, - ILL and - SRW protocols. + ISO23950/Z39.50, + ILL and + SRU + 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 ZOOM API. - It is, by far, the easiest way to develop clients in C. - Server implementers should consider the + It is, by far, the easiest way to develop clients in C. + Server implementers should consider the generic frontend server. 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. If you're using 'exotic' functionality (meaning anything not included in @@ -179,22 +183,52 @@ you're going to develop an ILL application you'll have to learn the lower level APIs of &yaz;. - - The basic low level modules, which are independent of the role - (client or server), consist of three primary interfaces: - + + The YAZ toolkit modules is shown in figure . + +
+ YAZ layers + + + + + + + + +
+ + There are four layers. - &asn;, which provides a C representation of the Z39.50 - protocol packages (PDUs). - - &odr;, which encodes and decodes the packages according - to the BER specification. - - &comstack;, which exchanges the encoded packages with - a peer process over a network. - + + A client or server application (or both). + This layer includes ZOOM and the generic frontend server. + + + + + The second layer provides a C represenation of the + protocol units (packages) for Z39.50 ASN.1, ILL ASN.1, + SRU. + + + + + 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. + + + + + The lowest layer is &comstack; which exchanges the encoded packages + with a peer process over a network. + + - + + 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 @@ -218,7 +252,7 @@ The &asn; library also provides functions (which are, in turn, defined using &odr; primitives) for encoding and decoding data values. Their general form is - + int z_xxx ODR o @@ -229,16 +263,16 @@ (note the lower-case "z" in the function name) - + 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 - Using ODR. + need to worry about are documented in + . - + When you have created a BER-encoded buffer, you can use the &comstack; subsystem to transmit (or receive) data over the network. The &comstack; @@ -248,7 +282,7 @@ 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. @@ -259,7 +293,7 @@ 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