adderet extra doc info on bounce filter
[metaproxy-moved-to-github.git] / doc / book.xml
index 406e7bf..ce1b5b6 100644 (file)
      -->
      <!NOTATION PDF SYSTEM "PDF">
 ]>
-<!-- $Id: book.xml,v 1.37 2006-09-07 10:00:43 adam Exp $ -->
+<!-- $Id: book.xml,v 1.38 2006-09-08 14:12:28 marc Exp $ -->
 <book id="metaproxy">
  <bookinfo>
   <title>Metaproxy - User's Guide and Reference</title>
   <author>
-   <firstname>Mike</firstname><surname>Taylor</surname>
-  </author>
-  <author>
    <firstname>Adam</firstname><surname>Dickmeiss</surname>
   </author>
   <author>
    <firstname>Marc</firstname><surname>Cromme</surname>
   </author>
+  <author>
+   <firstname>Mike</firstname><surname>Taylor</surname>
+  </author>
   <copyright>
    <year>2006</year>
    <holder>Index Data ApS</holder>
     as part of Metaproxy, and others may be provided by third parties
     and dynamically loaded.  They all conform to the same simple API
     of essentially two methods: <function>configure()</function> is
-    called at startup time, and is passed a DOM tree representing that
+    called at startup time, and is passed an XML DOM tree representing that
     part of the configuration file that pertains to this filter
     instance: it is expected to walk that tree extracting relevant
     information; and <function>process()</function> is called every
     others are sinks: they consume packages and return a result
     (<literal>z3950_client</literal>,
     <literal>backend_test</literal>,
+    <literal>bounce</literal>,
     <literal>http_file</literal>);
     the others are true filters, that read, process and pass on the
     packages they are fed
@@ -712,7 +713,7 @@ Figure out what additional information we need in:
     <title><literal>backend_test</literal>
     (mp::filter::Backend_test)</title>
     <para>
-     A sink that provides dummy responses in the manner of the
+     A partial sink that provides dummy responses in the manner of the
      <literal>yaz-ztest</literal> Z39.50 server.  This is useful only
      for testing.  Seriously, you don't need this.  Pretend you didn't
      even read this section.
@@ -720,6 +721,24 @@ Figure out what additional information we need in:
    </section>
    
    <section>
+    <title><literal>bounce</literal>
+    (mp::filter::Bounce)</title>
+    <para>
+     A sink that swallows <emphasis>all packages</emphasis>, 
+     and returns them almost unprocessed.
+     It never sends any package of any type further down the row, but
+     sets Z39.50 packages to Z_Close, and HTTP_Request packages to
+     HTTP_Response err code 400 packages, and adds a suitable bounce
+     message. 
+     The bounce filter is usually added at end of each filter chain
+     config.xml to prevent infinite hanging of for example HTTP
+     requests packages when only the Z39.50 client partial sink 
+     filter is found in the
+     route.  
+    </para>
+   </section>
+   
+   <section>
     <title><literal>frontend_net</literal>
      (mp::filter::FrontendNet)</title>
     <para>
@@ -734,8 +753,12 @@ Figure out what additional information we need in:
     <title><literal>http_file</literal>
      (mp::filter::HttpFile)</title>
     <para>
-     A sink that returns the contents of files from the local
-     filesystem in response to HTTP requests.  (Yes, Virginia, this
+     A partial sink which swallows only HTTP_Request packages, and 
+     returns the contents of files from the local
+     filesystem in response to HTTP requests.  
+     It lets Z39.50 packages and all other forthcoming package types
+     pass untouched. 
+     (Yes, Virginia, this
      does mean that Metaproxy is also a Web-server in its spare time.  So
      far it does not contain either an email-reader or a Lisp
      interpreter, but that day is surely coming.)
@@ -747,7 +770,8 @@ Figure out what additional information we need in:
      (mp::filter::Log)</title>
     <para>
      Writes logging information to standard output, and passes on
-     the package unchanged.
+     the package unchanged. A log file name can be specified, as well
+     as multiple different logging formats.
    </para>
    </section>
    
@@ -825,13 +849,16 @@ Figure out what additional information we need in:
     <title><literal>z3950_client</literal>
      (mp::filter::Z3950Client)</title>
     <para>
-     Performs Z39.50 searching and retrieval by proxying the
+     A partial sink which swallows only Z39.50 packages.
+     It performs Z39.50 searching and retrieval by proxying the
      packages that are passed to it.  Init requests are sent to the
      address specified in the <literal>VAL_PROXY</literal> otherInfo
      attached to the request: this may have been specified by client,
      or generated by a <literal>virt_db</literal> filter earlier in
      the route.  Subsequent requests are sent to the same address,
      which is remembered at Init time in a Session object.
+     HTTP_Request packages and all other forthcoming package types
+     are passed untouched. 
     </para>
   </section>
   </section>
@@ -1000,7 +1027,7 @@ Figure out what additional information we need in:
    <para>
     The following is a small, but complete, Metaproxy configuration
     file (included in the distribution as
-    <literal>metaproxy/etc/config0.xml</literal>).
+    <literal>metaproxy/etc/config1.xml</literal>).
     This file defines a very simple configuration that simply proxies
     to whatever back-end server the client requests, but logs each
     request and response.  This can be useful for debugging complex
@@ -1021,13 +1048,14 @@ Figure out what additional information we need in:
       <filter refid="frontend"/>
       <filter type="log"/>
       <filter refid="backend"/>
+      <filter type="bounce"/>
     </route>
   </routes>
 </yp2>
 ]]></screen>
    <para>
     It works by defining a single route, called
-    <literal>start</literal>, which consists of a sequence of three
+    <literal>start</literal>, which consists of a sequence of four
     filters.  The first and last of these are included by reference:
     their <literal>&lt;filter&gt;</literal> elements have
     <literal>refid</literal> attributes that refer to filters defined
@@ -1035,16 +1063,23 @@ Figure out what additional information we need in:
     middle filter is included inline in the route.
    </para>
    <para>
-    The three filters in the route are as follows: first, a
+    The four filters in the route are as follows: first, a
     <literal>frontend_net</literal> filter accepts Z39.50 requests
     from any host on port 9000; then these requests are passed through
     a <literal>log</literal> filter that emits a message for each
     request; they are then fed into a <literal>z3950_client</literal>
-    filter, which forwards the requests to the client-specified
-    back-end Z39.509 server.  When the response arrives, it is handed
+    filter, which forwards all Z39.50 requests to the client-specified
+    back-end Z39.509 server. Those Z39.50 packages are returned by the
+    <literal>z3950_client</literal> filter, with the response data
+    filled by the external Z39.50 server targeted.
+    All non-Z39.50 packages are passed through to the
+    <literal>bounce</literal> filter, which defitely bounces
+    everything, including fish, bananas, cold pyjamas,
+    mutton, beef and trout packages.
+    When the response arrives, it is handed
     back to the <literal>log</literal> filter, which emits another
-    message; and then to the front-end filter, which returns the
-    response to the client.
+    message; and then to the <literal>frontend_net</literal> filter, 
+    which returns the response to the client.
    </para>
   </section>
  </chapter>
@@ -1166,6 +1201,7 @@ Figure out what additional information we need in:
       <filter type="z3950_client">
         <timeout>30</timeout>
       </filter>
+      <filter type="bounce"/>
     </route>
   </routes>
 </yp2>]]></screen>
@@ -1518,7 +1554,7 @@ Z>
     <para>
      The virtual base class of all filters.  The filter API is, on the
      surface at least, extremely simple: two methods.
-     <literal>configure()</literal> is passed a DOM tree representing
+     <literal>configure()</literal> is passed an XML DOM tree representing
      that part of the configuration file that pertains to this filter
      instance, and is expected to walk that tree extracting relevant
      information.  And <literal>process()</literal> processes a