From 465748e588f2e12d9670b62a7d07cc75d59ca827 Mon Sep 17 00:00:00 2001
From: Adam Dickmeiss <adam@indexdata.dk>
Date: Tue, 20 Apr 2004 23:49:48 +0000
Subject: [PATCH] More examples

---
 doc/reference.xml |  139 ++++++++++++++++++++++++++++++++++++++++++++++++++++-
 doc/using.xml     |  109 ++++++++++++++++++++++++++++++++++++-----
 etc/config.xml    |    8 +--
 3 files changed, 239 insertions(+), 17 deletions(-)

diff --git a/doc/reference.xml b/doc/reference.xml
index 2bd922d..aeeefa1 100644
--- a/doc/reference.xml
+++ b/doc/reference.xml
@@ -17,7 +17,7 @@
    </para>
   </section>
   <section id="proxy-target">
-   <title>Specifying the Backend Server</title>
+   <title>Choosing the Backend Server</title>
    <para>
     When the proxy receives a Z39.50 Initialize Request from a Z39.50
     client, it determines the backend server by the following rules:
@@ -57,6 +57,30 @@
      </listitem>
     </orderedlist>
    </para>
+   <para>
+    If the proxy receives an SRW/SRU request, the following rules are used.
+    <orderedlist>
+     <listitem>
+      <para>If default target has Explain information with a
+       <literal>database</literal> that matches the path of the
+	HTTP request of SRW/SRU that backend server is used for
+       SRW/SRU operation.
+       </para>
+     </listitem>
+     <listitem>
+      <para>
+       Otherwise the service will return HTTP 404 (Not found).
+      </para>
+     </listitem>
+    </orderedlist>
+   </para>
+   <note>
+    <para>
+     We know it is stupid to only check for explain in default target.
+     It means that it is only possible to offer one SRW/SRU server.
+     We expect to improve that in the next version of the YAZ proxy.
+    </para>
+   </note>
   </section>
   <section id="proxy-keepalive">
    <title>Keep-alive Facility</title>
@@ -104,6 +128,10 @@
     <ulink url="http://xmlsoft.org/XSLT/">libXSLT</ulink> support in
     order for the config file facility to be enabled.
    </para>
+   <para>
+    See <xref linkend="yazproxy-schema"/> for an XML schema
+    for the configuration.
+   </para>
    <tip>
     <para>To check for a config file to be well-formed, the yazproxy may
      be invoked without specifying a listening port, i.e.
@@ -649,7 +677,114 @@
     <literal>characterInfo</literal> of the <literal>information</literal>
      choice.
    </para>
-   </section>
+  </section>
+  <section id="yazproxy-schema">
+   <title>YAZ Proxy Configuration Schema</title>
+   <para>
+    Here an XML Schema for the YAZ proxy configuration file. 
+    The schema, <filename>yazproxy.xsd</filename> is located in sub
+    directory <filename>etc</filename> of the distribution.
+   </para>
+   <screen><![CDATA[
+    <?xml version="1.0"?>
+<!-- XML Schema for YAZ proxy config file.
+    $Id: reference.xml,v 1.3 2004-04-20 23:49:48 adam Exp $
+-->
+<xs:schema
+  xmlns:xs="http://www.w3.org/2001/XMLSchema"
+  xmlns:exp="http://explain.z3950.org/dtd/2.0/"
+  xmlns="http://indexdata.dk/yazproxy/schema/0.8/"
+  targetNamespace="http://indexdata.dk/yazproxy/schema/0.8/"
+  >
+ <xs:import namespace="http://explain.z3950.org/dtd/2.0/" 
+      schemaLocation="zeerex-2.0.xsd"/>
+ <xs:element name="proxy">
+  <xs:complexType>
+   <xs:sequence>
+    <xs:element ref="target" minOccurs="0" maxOccurs="unbounded"/>
+    <xs:element ref="max-clients" minOccurs="0"/>
+    <xs:element ref="log" minOccurs="0"/>
+   </xs:sequence>
+  </xs:complexType>
+ </xs:element>
+
+ <xs:element name="target">
+  <xs:complexType>
+   <xs:sequence>
+     <xs:element ref="url" minOccurs="0" maxOccurs="unbounded"/>
+     <xs:element ref="target-timeout" minOccurs="0"/>
+     <xs:element ref="client-timeout" minOccurs="0"/>
+     <xs:element ref="keepalive" minOccurs="0"/>
+     <xs:element ref="limit" minOccurs="0"/>
+     <xs:element ref="attribute" minOccurs="0" maxOccurs="unbounded"/>
+     <xs:element ref="syntax" minOccurs="0" maxOccurs="unbounded"/>
+     <xs:element ref="preinit" minOccurs="0"/>
+     <xs:element name="exp:explain" minOccurs="0"/>
+     <xs:element ref="cql2rpn" minOccurs="0"/>
+   </xs:sequence>
+   <xs:attribute name="default" type="xs:string" use="optional"/>
+   <xs:attribute name="name" type="xs:string"/>
+  </xs:complexType>
+ </xs:element>
+
+ <xs:element name="url" type="xs:string"/>
+ <xs:element name="target-timeout" type="xs:integer"/>
+ <xs:element name="client-timeout" type="xs:integer"/>
+ <xs:element name="bandwidth" type="xs:integer"/>
+ <xs:element name="pdu" type="xs:integer"/>
+ <xs:element name="retrieve" type="xs:integer"/>
+ <xs:element name="preinit" type="xs:integer"/>
+ <xs:element name="cql2rpn" type="xs:string"/>
+
+ <xs:element name="keepalive">
+  <xs:complexType>
+   <xs:sequence>
+    <xs:element ref="bandwidth" minOccurs="0"/>
+    <xs:element ref="pdu" minOccurs="0"/>
+   </xs:sequence>
+  </xs:complexType>
+ </xs:element>
+ <xs:element name="limit">
+  <xs:complexType>
+   <xs:sequence>
+    <xs:element ref="bandwidth" minOccurs="0"/>
+    <xs:element ref="pdu" minOccurs="0"/>
+    <xs:element ref="retrieve" minOccurs="0"/>
+   </xs:sequence>
+  </xs:complexType>
+ </xs:element>
+ 
+ <xs:element name="attribute">
+  <xs:complexType>
+   <xs:attribute name="type" type="xs:string"/>
+   <xs:attribute name="value" type="xs:string"/>
+   <xs:attribute name="error" type="xs:integer"/>
+  </xs:complexType>
+ </xs:element>
+
+ <xs:element name="syntax">
+  <xs:complexType>
+   <xs:sequence>
+    <xs:element name="title" type="xs:string" minOccurs="0"/>
+    <xs:element name="name" type="xs:string" minOccurs="0"
+                                             maxOccurs="unbounded"/>
+   </xs:sequence>
+   <xs:attribute name="error" type="xs:string" minOccurs="0"/>
+   <xs:attribute name="type" type="xs:string" minOccurs="0"/>
+   <xs:attribute name="marcxml" type="xs:string" minOccurs="0"/>
+   <xs:attribute name="identifier" type="xs:string" minOccurs="0"/>
+   <xs:attribute name="stylesheet" type="xs:string" minOccurs="0"/>
+  </xs:complexType>
+ </xs:element>
+
+ <xs:element name="max-clients" type="xs:integer"/>
+ <xs:element name="log" type="xs:string"/>
+
+</xs:schema>
+
+]]>
+   </screen>
+  </section>
  </chapter>
 
  <!-- Keep this comment at the end of the file
diff --git a/doc/using.xml b/doc/using.xml
index d6ed178..0eaeb58 100644
--- a/doc/using.xml
+++ b/doc/using.xml
@@ -5,12 +5,6 @@
    This chapter includes a few examples.
   </para>
   <para>
-   -- All config directives --
-   -- SRW/SRU ..
-   -- Example config
-   -- Mention XSLT conversion
-  </para>
-  <para>
    The YAZ Proxy is useful for debugging SRW/SRU/Z39.50 software, logging
    APDUs, redirecting Z39.50 packages through firewalls, etc.
    Furthermore, it offers facilities that often
@@ -127,20 +121,113 @@
    </screen>
   </example>
 
-  <example id="example-firewall">
-   <title>Exposing a Z39.50 server behind a firewall</title>
+  <example id="first-config">
+   <title>Using a configuration file</title>
+   <para>
+    In <xref linkend="example-apdu-logging"/> the default backend server
+    was specified by a command line option. The same proxy behavior can
+    be achieved by creating a configuration with the following contents:
+    <screen><![CDATA[
+     <?xml version="1.0"?>
+     <proxy xmlns="http://indexdata.dk/yazproxy/schema/0.8/">
+       <target name="foo" default="1">
+         <url>foo.bar.com:18398</url>
+         <log>client-apdu</log>
+       </target>
+       <target name="*">
+       </target>
+     </proxy>
+]]>
+    </screen>
+   </para>
    <para>
-    ..
+    The proxy is started with
+    <screen><![CDATA[
+     yazproxy -c config.xml @:9000
+]]>
+    </screen>
+   </para>
+   <para>
+    The last target section is used for all servers except foo.
+    Had the the last section been omitted, then
+    <emphasis>only</emphasis> foo could be reached via the proxy.
    </para>
   </example>
   
   <example id="example-srw-service">
    <title>Offering SRW/SRU/Z39.50 service</title>
    <para>
-    ..
+    In order to offer SRW/SRU service we must be specify sufficient
+    information to allow the proxy to convert from SRW/SRU to Z39.50.
+    This involves CQL to Type-1 (also called RPN/PQF), since most
+    Z39.50 servers do not support CQL. The conversion
+    is specified by the <literal>cql2rpn</literal> element.
+   </para>
+   <para>
+    We must also ensure that the
+    server can return at least one kind of XML record (Dublin-Core
+    recommended). 
+   </para>
+   <para>
+    An explain record for the SRW/SRU service must also be created.
+   </para>
+   <para>
+    The following is a relatively simple configuration file for 
+    such a service. This service lives on <literal>indexdata.dk</literal>,
+    port 9000. The database is <literal>gils</literal>. The
+    backend server is also <literal>indexdata.dk</literal> (port 210) as
+    given by <literal>url</literal>.
+   </para>
+   <para>
+    The server may return USMARC/MARC21 (Z39.50/SRW/SRU) and
+    MARCXML (SRW/SRU only) as specified by the
+    <link linkend="proxy-config-syntax">syntax</link> elements.
+   </para>
+    <screen><![CDATA[
+<?xml version="1.0"?>
+<!-- $Id: using.xml,v 1.3 2004-04-20 23:49:48 adam Exp $ -->
+<proxy xmlns="http://indexdata.dk/yazproxy/schema/0.8/">
+  <target name="bagel">
+    <url>indexdata.dk</url>
+    <target-timeout>240</target-timeout>
+    <client-timeout>180</client-timeout>
+    <attribute type="1" value="1-11,13-1016"/>
+    <attribute type="1" value="*" error="114"/>
+    <syntax type="usmarc"/>
+    <syntax type="none"/>
+    <syntax type="xml" marcxml="1"
+      identifier="info:srw/schema/1/marcxml-v1.1" >
+      <name>marcxml</name>
+    </syntax>
+    <syntax type="*" error="238"/>
+    <preinit>0</preinit>
+    <explain xmlns="http://explain.z3950.org/dtd/2.0/">
+       <serverInfo>
+       <host>indexdata.dk</host>
+       <port>9000</port>
+       <database>gils</database>
+       </serverInfo>
+    </explain>
+    <cql2rpn>pqf.properties</cql2rpn>
+  </target>
+</proxy>
+]]>
+    </screen>
+   <para>
+    The conversion from CQL to RPN is specified by the
+    <link linkend="proxy-config-cql2rpn">cql2rpn</link> element.
+    <filename>pqf.properties</filename>.
+    A complete BATH/DC conversion file
+    <filename>pqf.properties</filename> is
+    part of yazproxy in sub direcory <filename>etc</filename>.
+   </para>
+   <para>
+    Explain information is embedded in the configuration file. 
+    Note that in this example,only a few mandatory
+    explain elements are specified. A well-behaving server should describe
+    index sets, indexes, record schemas as well.
    </para>
   </example>
-
  </chapter>
 
  <!-- Keep this comment at the end of the file
diff --git a/etc/config.xml b/etc/config.xml
index fdc229e..f304734 100644
--- a/etc/config.xml
+++ b/etc/config.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
-<!-- $Id: config.xml,v 1.2 2004-04-19 13:42:52 adam Exp $ -->
+<!-- $Id: config.xml,v 1.3 2004-04-20 23:49:49 adam Exp $ -->
 <proxy xmlns="http://indexdata.dk/yazproxy/schema/0.8/">
-  <target name="bagel">
+  <target name="bagel" default="1">
     <url>indexdata.dk</url>
     <target-timeout>240</target-timeout>
     <client-timeout>180</client-timeout>
@@ -14,7 +14,7 @@
       <pdu>50</pdu>
       <retrieve>100</retrieve>
     </limit>
-    <attribute type="1" value="1-11,13-1010"/>
+    <attribute type="1" value="1-11,13-1016"/>
     <attribute type="1" value="*" error="114"/>
     <syntax type="opac"/>
     <syntax type="usmarc"/>
@@ -31,7 +31,7 @@
     </explain>
     <cql2rpn>pqf.properties</cql2rpn>
   </target>
-  <target default="1" name="localhost">
+  <target name="localhost">
     <url>localhost:9999</url>
     <target-timeout>300</target-timeout>
     <client-timeout>180</client-timeout>
-- 
1.7.10.4