X-Git-Url: http://sru.miketaylor.org.uk/?a=blobdiff_plain;f=doc%2Fbook.xml;h=08a3904a6c61cbae77ec9c88b8a36841e59212fa;hb=1e61b0aa05e2351e33d909f7503eaf936a2d9bb0;hp=13abe5ef088fc2b0431b56ccf6e766db106158dc;hpb=84364c07e4830831703c5bca5f900878753b6ac7;p=metaproxy-moved-to-github.git diff --git a/doc/book.xml b/doc/book.xml index 13abe5e..08a3904 100644 --- a/doc/book.xml +++ b/doc/book.xml @@ -1,4 +1,24 @@ - + + + + + + %common; + + + + +]> + + Metaproxy - User's Guide and Reference @@ -105,26 +125,60 @@ - - - - The Metaproxy Licence - - - No decision has yet been made on the terms under which - Metaproxy will be distributed. - - 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. - + + The Metaproxy License + + + + 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. + + + + + 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 info@indexdata.com + for clarification. + + + + + 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. + + + + + 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. + + + + + All rights to the software are reserved by Index Data except where + this license explicitly says otherwise. + + + - + Installation @@ -164,7 +218,7 @@ for more information. - We have succesfully used Metaproxy with Boost using the compilers + We have succesfully built Metaproxy using the compilers GCC version 4.0 and Microsoft Visual Studio 2003/2005. @@ -241,42 +295,82 @@
- Installation on Debian + Installation on Debian GNU/Linux - ### To be written + All dependencies for Metaproxy are available as + Debian + packages for the sarge (stable in 2005) and etch (testing in 2005) + distributions. - (Of course, since Debian is a Unix system, the instructions in the - previous section can be used.) + The procedures for Debian based systems, such as + Ubuntu is probably similar -
+ + There is currently no official Debian package for YAZ++. + And the Debian package for YAZ is probably too old. + Update the /etc/apt/sources.list + to include the Index Data repository. + See YAZ' Download Debian + for more information. + + + apt-get install libxslt1-dev + apt-get install libyazpp-dev + apt-get install libboost-dev + apt-get install libboost-thread-dev + apt-get install libboost-date-time-dev + apt-get install libboost-program-options-dev + apt-get install libboost-test-dev + + + With these packages installed, the usual configure + make + procedure can be used for Metaproxy as outlined in + . + +
Installation on Windows - Compilation of Metaproxy can be done using - Microsoft Visual Studio. - We know Version 2003 works. We expect Version 2005 to - work as well. + Metaproxy can be compiled with Microsoft + Visual Studio. + Version 2003 (C 7.1) and 2005 (C 8.0) is known to work.
Boost Get Boost from its home page. You also need Boost Jam (an alternative to make). - That's also available from this - home page. The files download are called something like: - boost_1_33-1.exe + That's also available from the Boost home page. + The files to be downloaded are called something like: + boost_1_33-1.exe and - boost-jam-3.1.12-1-ntx86.zip. - Unpack Boost Jam first. Put bjam.exe + boost-jam-3.1.12-1-ntx86.zip. + Unpack Boost Jam first. Put bjam.exe in your system path. Make a command prompt and ensure it can be found automatically. If not check the PATH. The Boost .exe is a self-extracting exe with complete source for Boost. Compile that source with Boost Jam (An alternative to Make). The compilation takes a while. - By default, the Boost build process puts the resulting + For Visual Studio 2003, use + + bjam "-sTOOLS=vc-7_1" + + Here vc-7_1 refers to a "Toolset" (compiler system). + For Visual Studio 2005, use + + bjam "-sTOOLS=vc-8_0" + + To install the libraries in a common place, use + + bjam "-sTOOLS=vc-7_1" install + + (or vc-8_0 for VS 2005). + + + By default, the Boost build process installs the resulting libraries + header files in \boost\lib, \boost\include. @@ -332,6 +426,58 @@ to point to the proper locations of Boost, Libxslt, Libxml2, zlib, iconv, yaz and yazpp. + + + DEBUG + + If set to 1, the software is + compiled with debugging libraries (code generation is + multi-threaded debug DLL). + If set to 0, the software is compiled with release libraries + (code generation is multi-threaded DLL). + + + + + BOOST + + + Boost install location + + + + + + BOOST_VERSION + + + Boost version (replace . with _). + + + + + + BOOST_TOOLSET + + + Boost toolset. + + + + + + LIBXSLT_DIR, + LIBXML2_DIR .. + + + Specify the locations of Libxslt, libiconv, libxml2 and + libxslt. + + + + + + After succesful compilation you'll find metaproxy.exe in the @@ -339,6 +485,7 @@
+
@@ -1091,6 +1238,27 @@ Z> be metasearched in this way: issues of resource usage and administrative complexity dictate the practical limits. + + 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 + <hideunavailable> + element inside the + multi filter: + + + + ]]> + + Under this regime, an error is reported to the client only if + all the databases in a multi-database search + are unavailable. + @@ -1128,15 +1296,18 @@ Z> >the HTTP 1.1 specification. - The role of the virt_db 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 + VAL_PROXY otherInfo are also annotated with the + same information. The role of the virt_db + filter is to rewrite this otherInfo packet dependent on the + virtual database that the client wants to search. 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 which - 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 @@ -1161,9 +1332,35 @@ Z> through it. - ### Describe the use of multiple VAL_PROXY - otherInfos, added by virt_db and used by - multi. + It is possible for a virt_db filter to contain + multiple + <target> + elements. What does this mean? Only that the filter will add + multiple VAL_PROXY 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 VAL_PROXY + otherInfo packets reaches a z3950_client + 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. + + + The multi filter comes to the rescue! This is + the only filter that knows how to deal with multiple + VAL_PROXY otherInfo packets, and it does so by + making multiple copies of the entire Search request: one for each + VAL_PROXY. 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 + VAL_PROXY otherInfo, they can be handled by the + z3950_client filter, which happily deals with + each one individually. When the results of the individual + searches come back up to the multi filter, it + merges them into a single Search response, which is what + eventually makes it back to the client. @@ -1173,7 +1370,7 @@ Z> - + @@ -1495,8 +1692,7 @@ Z> &manref; - - +