Comment briefly outlining P2P changes.

[metaproxy-moved-to-github.git] / doc / book.xml

diff --git a/doc/book.xml b/doc/book.xml
index d3437a8..be53892 100644 (file)
--- a/doc/book.xml
+++ b/doc/book.xml
@@ -1,4 +1,24 @@
-<!-- $Id: book.xml,v 1.28 2006-04-30 07:07:12 adam Exp $ -->
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN"
+    "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd" 
+[
+     <!ENTITY local SYSTEM "local.ent">
+     <!ENTITY manref SYSTEM "manref.xml">
+     <!ENTITY progref SYSTEM "progref.xml">
+     <!ENTITY % common SYSTEM "common/common.ent">
+     %common;
+     <!-- Next line allows imagedata/@format="PDF" and is taken from 
+         http://lists.oasis-open.org/archives/docbook/200303/msg00163.html
+     -->
+     <!ENTITY % local.notation.class "| PDF">
+     <!-- Next line is necessary for some XML parsers, for reasons I
+          don't understand.  I got this from
+         http://lists.oasis-open.org/archives/docbook/200303/msg00180.html
+     -->
+     <!NOTATION PDF SYSTEM "PDF">
+]>
+<!-- $Id: book.xml,v 1.36 2006-09-07 09:42:53 mike Exp $ -->
+<book id="metaproxy">

  <bookinfo>
   <title>Metaproxy - User's Guide and Reference</title>
   <author>
  <bookinfo>
   <title>Metaproxy - User's Guide and Reference</title>
   <author>

@@ -32,10 +52,10 @@
     using the filter API.
    </simpara>
    <simpara>
     using the filter API.
    </simpara>
    <simpara>

-    The terms under which Metaproxy will be distributed have yet to be
-    established, but it will not necessarily be open source; so users
-    should not at this stage redistribute the code without explicit
-    written permission from the copyright holders, Index Data ApS.
+    Metaproxy is <emphasis>not</emphasis> open-source software, but
+    may be freely downloaded, unpacked, inspected, built and run for
+    evaluation purposes.  Deployment requires a separate, commercial,
+    license.

    </simpara>
    <simpara>
     <inlinemediaobject>
    </simpara>
    <simpara>
     <inlinemediaobject>

@@ -90,7 +110,7 @@
    functionality.
   </para>
   <para>
    functionality.
   </para>
   <para>

-   This manual will briefly describe Metaproxy's licensing situation
+   This manual will describe how to install Metaproxy

    before giving an overview of its architecture, then discussing the
    key concept of a filter in some depth and giving an overview of
    the various filter types, then discussing the configuration file
    before giving an overview of its architecture, then discussing the
    key concept of a filter in some depth and giving an overview of
    the various filter types, then discussing the configuration file

@@ -105,26 +125,60 @@
   </para>
  </chapter>
 
   </para>
  </chapter>
 

-
-
- <chapter id="licence">
-  <title>The Metaproxy Licence</title>
-  <para>
-   <emphasis role="strong">
-    No decision has yet been made on the terms under which
-    Metaproxy will be distributed.
-   </emphasis>
-   It is possible that, unlike
-   other Index Data products, metaproxy may not be released under a
-   free-software licence such as the GNU GPL.  Until a decision is
-   made and a public statement made, then, and unless it has been
-   delivered to you other specific terms, please treat Metaproxy as
-   though it were proprietary software.
-   The code should not be redistributed without explicit
-   written permission from the copyright holders, Index Data ApS.
-  </para>
+ <chapter id="license">
+  <title>The Metaproxy License</title>
+  <orderedlist numeration="arabic">
+   <listitem>
+    <para>
+     You are allowed to download this software for evaluation purposes.
+     You can unpack it, build it, run it, see how it works and how it fits
+     your needs, all at zero cost.
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     You may NOT deploy the software.  For the purposes of this license,
+     deployment means running it for any purpose other than evaluation,
+     whether or not you or anyone else makes a profit from doing so.  If
+     you wish to deploy the software, you must first contact Index Data and
+     arrange to purchase a DEPLOYMENT LICENCE.  If you are unsure
+     whether or not your proposed use of the software constitutes
+     deployment, email us at <literal>info@indexdata.com</literal>
+     for clarification.
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     You may modify your copy of the software (fix bugs, add features)
+     if you need to.  We encourage you to send your changes back to us for
+     integration into the master copy, but you are not obliged to do so.  You
+      may NOT pass your changes on to any other party.
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     There is NO WARRANTY for this software, to the extent permitted by
+     applicable law.  We provide the software ``as is'' without warranty of
+     any kind, either expressed or implied, including, but not limited to, the
+     implied warranties of MERCHANTABILITY and FITNESS FOR A
+     PARTICULAR PURPOSE.  The entire risk as to the quality and
+     performance of the software is with you.  Should the software prove
+     defective, you assume the cost of all necessary servicing, repair or
+     correction.  In no event unless required by applicable law will we be
+     liable to you for damages, arising out of the use of the software,
+     including but not limited to loss of data or data being rendered
+     inaccurate.
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     All rights to the software are reserved by Index Data except where
+     this license explicitly says otherwise.
+    </para>
+   </listitem>
+  </orderedlist>

  </chapter>
  </chapter>

-
+ 

  <chapter id="installation">
   <title>Installation</title>
   <para>
  <chapter id="installation">
   <title>Installation</title>
   <para>

@@ -501,7 +555,7 @@
       The word ``filter'' is sometimes used rather loosely, in two
       different ways: it may be used to mean a particular
       <emphasis>type</emphasis> of filter, as when we speak of ``the
       The word ``filter'' is sometimes used rather loosely, in two
       different ways: it may be used to mean a particular
       <emphasis>type</emphasis> of filter, as when we speak of ``the

-      auth_simplefilter'' or ``the multi filter''; or it may be used
+      auth_simple filter'' or ``the multi filter''; or it may be used

       to be a specific <emphasis>instance</emphasis> of a filter
       within a Metaproxy configuration.  For example, a single
       configuration will often contain multiple instances of the
       to be a specific <emphasis>instance</emphasis> of a filter
       within a Metaproxy configuration.  For example, a single
       configuration will often contain multiple instances of the

@@ -609,6 +663,29 @@
     The filters are here listed in alphabetical order:
    </para>
    
     The filters are here listed in alphabetical order:
    </para>
    

+<!--
+
+### New filters:
+
+New virt_db-alike that does inteligent peer choice, explain merging,
+adds FD&N to explain.  Keeps init responses (like "virt_db Classic"),
+makes routing choices based on local explain knowledge.  Ref IDDI
+paper.
+
+Filter to convert Explain Classic to ZeeRex.
+
+CQL2PQF (which needs augmented ZeeRex) - MARC for Talis.
+
+SRU2Z39.50 (ditto).
+
+Figure out what additional information we need in:
+       ZeeRex (check against D3.1)
+       Init request (e.g. loop detection)
+       Query package (e.g. number of hops)
+       Query response (e.g. record source)
+
+-->
+

    <section>
     <title><literal>auth_simple</literal>
      (mp::filter::AuthSimple)</title>
    <section>
     <title><literal>auth_simple</literal>
      (mp::filter::AuthSimple)</title>

@@ -1184,6 +1261,27 @@ Z>
     be metasearched in this way: issues of resource usage and
     administrative complexity dictate the practical limits.
    </para>
     be metasearched in this way: issues of resource usage and
     administrative complexity dictate the practical limits.
    </para>

+   <para>
+    What happens when one of the databases doesn't respond?  By default,
+    the entire multi-database search fails, and the appropriate
+    diagnostic is returned to the client.  This is usually appropriate
+    during development, when technicians need maximum information, but
+    can be inconvenient in deployment, when users typically don't want
+    to be bothered with problems of this kind and prefer just to get
+    the records from the databases that are available.  To obtain this
+    latter behaviour add an empty
+    <literal>&lt;hideunavailable&gt;</literal>
+    element inside the
+    <literal>multi</literal> filter:
+   </para>
+   <screen><![CDATA[      <filter type="multi">
+        <hideunavailable/>
+      </filter>]]></screen>
+   <para>
+    Under this regime, an error is reported to the client only if
+    <emphasis>all</emphasis> the databases in a multi-database search
+    are unavailable.
+   </para>

   </section>
 
 
   </section>
 
 

@@ -1221,15 +1319,18 @@ Z>
           >the HTTP 1.1 specification</ulink>.
    </para>
    <para>
           >the HTTP 1.1 specification</ulink>.
    </para>
    <para>

-    The role of the <literal>virt_db</literal> filter is to rewrite
-    this otherInfo packet dependent on the virtual database that the
-    client wants to search.  
+    Within Metaproxy, Search requests that are part of the same
+    session as an Init request that carries a
+    <literal>VAL_PROXY</literal> otherInfo are also annotated with the
+    same information.  The role of the <literal>virt_db</literal>
+    filter is to rewrite this otherInfo packet dependent on the
+    virtual database that the client wants to search.

    </para>
    <para>
     When Metaproxy receives a Z39.50 Init request from a client, it
     doesn't immediately forward that request to the back-end server.
     Why not?  Because it doesn't know <emphasis>which</emphasis>
    </para>
    <para>
     When Metaproxy receives a Z39.50 Init request from a client, it
     doesn't immediately forward that request to the back-end server.
     Why not?  Because it doesn't know <emphasis>which</emphasis>

-    back-end server to forward it to until the client sends a search
+    back-end server to forward it to until the client sends a Search

     request that specifies the database that it wants to search in.
     Instead, it just treasures the Init request up in its heart; and,
     later, the first time the client does a search on one of the
     request that specifies the database that it wants to search in.
     Instead, it just treasures the Init request up in its heart; and,
     later, the first time the client does a search on one of the

@@ -1254,9 +1355,35 @@ Z>
     through it.
    </para>
    <para>
     through it.
    </para>
    <para>

-    ### Describe the use of multiple <literal>VAL_PROXY</literal>
-    otherInfos, added by <literal>virt_db</literal> and used by
-    <literal>multi</literal>.
+    It is possible for a <literal>virt_db</literal> filter to contain
+    multiple
+    <literal>&lt;target&gt;</literal>
+    elements.  What does this mean?  Only that the filter will add
+    multiple <literal>VAL_PROXY</literal> otherInfo packets to the
+    Search requests that pass through it.  That's because the virtual
+    DB filter is dumb, and does exactly what it's told - no more, no
+    less.
+    If a Search request with multiple <literal>VAL_PROXY</literal>
+    otherInfo packets reaches a <literal>z3950_client</literal>
+    filter, this is an error.  That filter doesn't know how to deal
+    with multiple targets, so it will either just pick one and search
+    in it, or (better) fail with an error message.
+   </para>
+   <para>
+    The <literal>multi</literal> filter comes to the rescue!  This is
+    the only filter that knows how to deal with multiple
+    <literal>VAL_PROXY</literal> otherInfo packets, and it does so by
+    making multiple copies of the entire Search request: one for each
+    <literal>VAL_PROXY</literal>.  Each of these new copies is then
+    passed down through the remaining filters in the route.  (The
+    copies are handled in parallel though the
+    spawning of new threads.)  Since the copies each have only one
+    <literal>VAL_PROXY</literal> otherInfo, they can be handled by the
+    <literal>z3950_client</literal> filter, which happily deals with
+    each one individually.  When the results of the individual
+    searches come back up to the <literal>multi</literal> filter, it
+    merges them into a single Search response, which is what
+    eventually makes it back to the client.

    </para>
   </section>
 
    </para>
   </section>
 

@@ -1588,8 +1715,7 @@ Z>
    &manref;
   </section>
  </chapter>
    &manref;
   </section>
  </chapter>

-
-
+</book>

 
  <!-- Keep this comment at the end of the file
  Local variables:
 
  <!-- Keep this comment at the end of the file
  Local variables:

@@ -1600,7 +1726,7 @@ Z>
  sgml-always-quote-attributes:t
  sgml-indent-step:1
  sgml-indent-data:t
  sgml-always-quote-attributes:t
  sgml-indent-step:1
  sgml-indent-data:t

- sgml-parent-document: "main.xml"
+ sgml-parent-document: nil

  sgml-local-catalogs: nil
  sgml-namecase-general:t
  End:
  sgml-local-catalogs: nil
  sgml-namecase-general:t
  End: