From 4e876b7359785f69806459e19fcaa8aea37fc15d Mon Sep 17 00:00:00 2001 From: Adam Dickmeiss Date: Thu, 16 Mar 2006 12:03:38 +0000 Subject: [PATCH] Configure and build docbook doc as part of make. The documentation has been split in two: metaproxy.xml(.in) + book.xml. It's rather painful to edit .in files too often. The documentation now refers to Metaproxy rather than yp2. --- Makefile.am | 2 +- configure.ac | 12 +- doc/Makefile.am | 35 +-- doc/book.xml | 781 +++++++++++++++++++++++++++++++++++++++++++++++++ doc/html.dsl.in | 26 ++ doc/metaproxy.xml.in | 25 ++ doc/print.dsl.in | 21 ++ doc/yp2.xml.in | 788 -------------------------------------------------- doc/yp2html.dsl.in | 26 -- doc/yp2php.dsl.in | 98 ------- doc/yp2print.dsl.in | 21 -- 11 files changed, 873 insertions(+), 962 deletions(-) create mode 100644 doc/book.xml create mode 100644 doc/html.dsl.in create mode 100644 doc/metaproxy.xml.in create mode 100644 doc/print.dsl.in delete mode 100644 doc/yp2.xml.in delete mode 100644 doc/yp2html.dsl.in delete mode 100644 doc/yp2php.dsl.in delete mode 100644 doc/yp2print.dsl.in diff --git a/Makefile.am b/Makefile.am index f300b57..18da25b 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,4 +1,4 @@ -SUBDIRS = src +SUBDIRS = src doc ACLOCAL_AMFLAGS = -I m4 diff --git a/configure.ac b/configure.ac index babf624..c4816b8 100644 --- a/configure.ac +++ b/configure.ac @@ -49,11 +49,6 @@ AC_CHECK_LIB(boost_program_options, main, [],[ AC_MSG_ERROR([Install libboost-program-options-dev (or similar)]) ]) -AC_CHECK_LIB(boost_regex, main, [],[ - AC_MSG_NOTICE([boost regex library not found.]) - AC_MSG_ERROR([Install libboost-regex-dev (or similar)]) -]) - AC_CHECK_HEADER(boost/test/auto_unit_test.hpp,,[ AC_MSG_NOTICE([boost test unit header not found.]) AC_MSG_ERROR([Install libboost-test-dev (or similar)]) @@ -85,7 +80,7 @@ YAZPP_INIT(threads,1.0) if test -z "$YAZPPLIB"; then AC_MSG_ERROR([YAZ++ development libraries missing]) fi -##YAZ_DOC +YAZ_DOC ## libxslt checks AC_SUBST(XSLT_LIBS) @@ -138,6 +133,11 @@ AC_CONFIG_FILES([ Makefile src/Makefile src/Jamfile + doc/Makefile + doc/metaproxy.xml + doc/print.dsl + doc/html.dsl + doc/tkl.xsl ]) AC_OUTPUT diff --git a/doc/Makefile.am b/doc/Makefile.am index 82bb4e9..f3c1057 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,47 +1,38 @@ -## $Id: Makefile.am,v 1.1 2006-02-02 18:22:47 mike Exp $ +## $Id: Makefile.am,v 1.2 2006-03-16 12:03:39 adam Exp $ docdir=$(datadir)/doc/@PACKAGE@ -SUPPORTFILES = \ - yp2html.dsl \ - yp2php.dsl \ - yp2print.dsl \ - tkl.xsl \ - xml.dcl - -XMLFILES = yp2.xml.in - -HTMLFILES = yp2.html +SUPPORTFILES = html.dsl print.dsl tkl.xsl xml.dcl +XMLFILES = metaproxy.xml.in book.xml +MAINXML = metaproxy.xml +HTMLFILES = metaproxy.html PNGFILES= EPSFILES= REFFILES= -doc_DATA = $(HTMLFILES) yp2.pdf $(PNGFILES) +doc_DATA = $(HTMLFILES) metaproxy.pdf $(PNGFILES) man_MANS = $(MANFILES) EXTRA_DIST = $(XMLFILES) $(SUPPORTFILES) $(REFFILES) \ $(doc_DATA) $(EPSFILES) $(man_MANS) $(REFFILES) $(HTMLFILES): $(XMLFILES) - jade -E14 -D $(srcdir) -d yp2html.dsl -t sgml $(srcdir)/xml.dcl yp2.xml - -yp2.php: $(XMLFILES) - jade -E14 -D $(srcdir) -d yp2php.dsl -t sgml $(srcdir)/xml.dcl yp2.xml + jade -E14 -D $(srcdir) -d html.dsl -t sgml $(srcdir)/xml.dcl $(MAINXML) -yp2.pdf: $(XMLFILES) +metaproxy.pdf: $(XMLFILES) for i in $(PNGFILES); do \ if test ! -f $$i; then ln -s $(srcdir)/$$i .; fi; \ done - jade -E14 -D $(srcdir) -d yp2print.dsl -t tex $(srcdir)/xml.dcl yp2.xml - pdfjadetex yp2.tex >/dev/null - pdfjadetex yp2.tex >/dev/null - pdfjadetex yp2.tex >/dev/null + jade -E14 -D $(srcdir) -d print.dsl -t tex $(srcdir)/xml.dcl $(MAINXML) + pdfjadetex metaproxy.tex >/dev/null + pdfjadetex metaproxy.tex >/dev/null + pdfjadetex metaproxy.tex >/dev/null index.tkl: $(XMLFILES) tkl.xsl - xsltproc tkl.xsl yp2.xml + xsltproc tkl.xsl $(MAINXML) clean-data-hook: rm -f [0-9]* *.bak diff --git a/doc/book.xml b/doc/book.xml new file mode 100644 index 0000000..03032af --- /dev/null +++ b/doc/book.xml @@ -0,0 +1,781 @@ + + + Metaproxy - User's Guide and Reference + + MikeTaylor + + + 2006 + Index Data + + + + ### + Metaproxy is ... in need of description :-) + + + + + + + + Introduction + + +
+ Overview + + Metaproxy + is .. + + + ### We should probably consider saying a little more by way of + introduction. + +
+ + + + + + Filters + + +
+ Introductory notes + + It's useful to think of Metaproxy as an interpreter providing a small + number of primitives and operations, but operating on a very + complex data type, namely the ``package''. + + + A package represents a Z39.50 or SRW/U request (whether for Init, + Search, Scan, etc.) together with information about where it came + from. Packages are created by front-end filters such as + frontend_net (see below), which reads them from + the network; other front-end filters are possible. They then pass + along a route consisting of a sequence of filters, each of which + transforms the package and may also have side-effects such as + generating logging. Eventually, the route will yield a response, + which is sent back to the origin. + + + There are many kinds of filter: some that are defined statically + as part of Metaproxy, and other that may be provided by third parties + and dynamically loaded. They all conform to the same simple API + of essentially two methods: configure() is + called at startup time, and is passed a 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 process() is called every + time the filter has to processes a package. + + + While all filters provide the same API, there are different modes + of functionality. Some filters are sources: they create + packages + (frontend_net); + others are sinks: they consume packages and return a result + (z3950_client, + backend_test, + http_file); + the others are true filters, that read, process and pass on the + packages they are fed + (auth_simple, + log, + multi, + session_shared, + template, + virt_db). + +
+ + +
+ Individual filters + + The filters are here named by the string that is used as the + type attribute of a + <filter> element in the configuration + file to request them, with the name of the class that implements + them in parentheses. + + +
+ <literal>auth_simple</literal> + (mp::filter::AuthSimple) + + Simple authentication and authorisation. The configuration + specifies the name of a file that is the user register, which + lists username:password + pairs, one per line, colon separated. When a session begins, it + is rejected unless username and passsword are supplied, and match + a pair in the register. + + + ### discuss authorisation phase + +
+ +
+ <literal>backend_test</literal> + (mp::filter::Backend_test) + + A sink that provides dummy responses in the manner of the + yaz-ztest Z39.50 server. This is useful only + for testing. + +
+ +
+ <literal>frontend_net</literal> + (mp::filter::FrontendNet) + + A source that accepts Z39.50 and SRW connections from a port + specified in the configuration, reads protocol units, and + feeds them into the next filter, eventually returning the + result to the origin. + +
+ +
+ <literal>http_file</literal> + (mp::filter::HttpFile) + + A sink that returns the contents of files from the local + filesystem in response to HTTP requests. (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.) + +
+ +
+ <literal>log</literal> + (mp::filter::Log) + + Writes logging information to standard output, and passes on + the package unchanged. + +
+ +
+ <literal>multi</literal> + (mp::filter::Multi) + + Performs multicast searching. See the extended discussion of + multi-database searching below. + +
+ +
+ <literal>session_shared</literal> + (mp::filter::SessionShared) + + When this is finished, it will implement global sharing of + result sets (i.e. between threads and therefore between + clients), but it's not yet done. + +
+ +
+ <literal>template</literal> + (mp::filter::Template) + + Does nothing at all, merely passing the packet on. (Maybe it + should be called nop or + passthrough?) This exists not to be used, but + to be copied - to become the skeleton of new filters as they are + written. + +
+ +
+ <literal>virt_db</literal> + (mp::filter::Virt_db) + + Performs virtual database selection. See the extended discussion + of virtual databases below. + +
+ +
+ <literal>z3950_client</literal> + (mp::filter::Z3950Client) + + 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 VAL_PROXY otherInfo + attached to the request: this may have been specified by client, + or generated by a virt_db filter earlier in + the route. Subsequent requests are sent to the same address, + which is remembered at Init time in a Session object. + +
+
+ + +
+ Future directions + + Some other filters that do not yet exist, but which would be + useful, are briefly described. These may be added in future + releases. + + + + + frontend_cli (source) + + + Command-line interface for generating requests. + + + + + srw2z3950 (filter) + + + Translate SRW requests into Z39.50 requests. + + + + + srw_client (sink) + + + SRW searching and retrieval. + + + + + sru_client (sink) + + + SRU searching and retrieval. + + + + + opensearch_client (sink) + + + A9 OpenSearch searching and retrieval. + + + + +
+ + + + + + Configuration: the Metaproxy configuration file format + + +
+ Introductory notes + + If Metaproxy is an interpreter providing operations on packages, then + its configuration file can be thought of as a program for that + interpreter. Configuration is by means of a single file, the name + of which is supplied as the sole command-line argument to the + yp2 program. + + + The configuration files are written in XML. (But that's just an + implementation detail - they could just as well have been written + in YAML or Lisp-like S-expressions, or in a custom syntax.) + + + Since XML has been chosen, an XML schema, + config.xsd, is provided for validating + configuration files. This file is supplied in the + etc directory of the Metaproxy distribution. It + can be used by (among other tools) the xmllint + program supplied as part of the libxml2 + distribution: + + + xmllint --noout --schema etc/config.xsd my-config-file.xml + + + (A recent version of libxml2 is required, as + support for XML Schemas is a relatively recent addition.) + +
+ +
+ Overview of XML structure + + All elements and attributes are in the namespace + . + This is most easily achieved by setting the default namespace on + the top-level element, as here: + + + <yp2 xmlns="http://indexdata.dk/yp2/config/1"> + + + The top-level element is <yp2>. This contains a + <start> element, a <filters> element and a + <routes> element, in that order. <filters> is + optional; the other two are mandatory. All three are + non-repeatable. + + + The <start> element is empty, but carries a + route attribute, whose value is the name of + route at which to start running - analogouse to the name of the + start production in a formal grammar. + + + If present, <filters> contains zero or more <filter> + elements; filters carry a type attribute and + contain various elements that provide suitable configuration for + filters of that type. The filter-specific elements are described + below. Filters defined in this part of the file must carry an + id attribute so that they can be referenced + from elsewhere. + + + <routes> contains one or more <route> elements, each + of which must carry an id element. One of the + routes must have the ID value that was specified as the start + route in the <start> element's route + attribute. Each route contains zero or more <filter> + elements. These are of two types. They may be empty, but carry a + refid attribute whose value is the same as the + id of a filter previously defined in the + <filters> section. Alternatively, a route within a filter + may omit the refid attribute, but contain + configuration elements similar to those used for filters defined + in the <filters> section. + +
+ + +
+ Filter configuration + + All <filter> elements have in common that they must carry a + type attribute whose value is one of the + supported ones, listed in the schema file and discussed below. In + additional, <filters>s occurring the <filters> section + must have an id attribute, and those occurring + within a route must have either a refid + attribute referencing a previously defined filter or contain its + own configuration information. + + + In general, each filter recognises different configuration + elements within its element, as each filter has different + functionality. These are as follows: + + +
+ <literal>auth_simple</literal> + + <filter type="auth_simple"> + <userRegister>../etc/example.simple-auth</userRegister> + </filter> + +
+ +
+ <literal>backend_test</literal> + + <filter type="backend_test"/> + +
+ +
+ <literal>frontend_net</literal> + + <filter type="frontend_net"> + <threads>10</threads> + <port>@:9000</port> + </filter> + +
+ +
+ <literal>http_file</literal> + + <filter type="http_file"> + <mimetypes>/etc/mime.types</mimetypes> + <area> + <documentroot>.</documentroot> + <prefix>/etc</prefix> + </area> + </filter> + +
+ +
+ <literal>log</literal> + + <filter type="log"> + <message>B</message> + </filter> + +
+ +
+ <literal>multi</literal> + + <filter type="multi"/> + +
+ +
+ <literal>session_shared</literal> + + <filter type="session_shared"> + ### Not yet defined + </filter> + +
+ +
+ <literal>template</literal> + + <filter type="template"/> + +
+ +
+ <literal>virt_db</literal> + + <filter type="virt_db"> + <virtual> + <database>loc</database> + <target>z3950.loc.gov:7090/voyager</target> + </virtual> + <virtual> + <database>idgils</database> + <target>indexdata.dk/gils</target> + </virtual> + </filter> + +
+ +
+ <literal>z3950_client</literal> + + <filter type="z3950_client"> + <timeout>30</timeout> + </filter> + +
+
+ + + + + + Virtual database as multi-database searching + + +
+ Introductory notes + + Two of Metaproxy's filters are concerned with multiple-database + operations. Of these, virt_db can work alone + to control the routing of searches to one of a number of servers, + while multi can work with the output of + virt_db to perform multicast searching, merging + the results into a unified result-set. The interaction between + these two filters is necessarily complex, reflecting the real + complexity of multicast searching in a protocol such as Z39.50 + that separates initialisation from searching, with the database to + search known only during the latter operation. + + + ### Much, much more to say! + +
+ + + + + + Classes in the Metaproxy source code + + +
+ Introductory notes + + Stop! Do not read this! + You won't enjoy it at all. + + + This chapter contains documentation of the Metaproxy source code, and is + of interest only to maintainers and developers. If you need to + change Metaproxy's behaviour or write a new filter, then you will most + likely find this chapter helpful. Otherwise it's a waste of your + good time. Seriously: go and watch a film or something. + This is Spinal Tap is particularly good. + + + Still here? OK, let's continue. + + + In general, classes seem to be named big-endianly, so that + FactoryFilter is not a filter that filters + factories, but a factory that produces filters; and + FactoryStatic is a factory for the statically + registered filters (as opposed to those that are dynamically + loaded). + +
+ +
+ Individual classes + + The classes making up the Metaproxy application are here listed by + class-name, with the names of the source files that define them in + parentheses. + + +
+ <literal>mp::FactoryFilter</literal> + (<filename>factory_filter.cpp</filename>) + + A factory class that exists primarily to provide the + create() method, which takes the name of a + filter class as its argument and returns a new filter of that + type. To enable this, the factory must first be populated by + calling add_creator() for static filters (this + is done by the FactoryStatic class, see below) + and add_creator_dyn() for filters loaded + dynamically. + +
+ +
+ <literal>mp::FactoryStatic</literal> + (<filename>factory_static.cpp</filename>) + + A subclass of FactoryFilter which is + responsible for registering all the statically defined filter + types. It does this by knowing about all those filters' + structures, which are listed in its constructor. Merely + instantiating this class registers all the static classes. It is + for the benefit of this class that struct + yp2_filter_struct exists, and that all the filter + classes provide a static object of that type. + +
+ +
+ <literal>mp::filter::Base</literal> + (<filename>filter.cpp</filename>) + + The virtual base class of all filters. The filter API is, on the + surface at least, extremely simple: two methods. + configure() is passed a 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 process() processes a + package (see below). That surface simplicitly is a bit + misleading, as process() needs to know a lot + about the Package class in order to do + anything useful. + +
+ +
+ <literal>mp::filter::AuthSimple</literal>, + <literal>Backend_test</literal>, etc. + (<filename>filter_auth_simple.cpp</filename>, + <filename>filter_backend_test.cpp</filename>, etc.) + + Individual filters. Each of these is implemented by a header and + a source file, named filter_*.hpp and + filter_*.cpp respectively. All the header + files should be pretty much identical, in that they declare the + class, including a private Rep class and a + member pointer to it, and the two public methods. The only extra + information in any filter header is additional private types and + members (which should really all be in the Rep + anyway) and private methods (which should also remain known only + to the source file, but C++'s brain-damaged design requires this + dirty laundry to be exhibited in public. Thanks, Bjarne!) + + + The source file for each filter needs to supply: + + + + + A definition of the private Rep class. + + + + + Some boilerplate constructors and destructors. + + + + + A configure() method that uses the + appropriate XML fragment. + + + + + Most important, the process() method that + does all the actual work. + + + +
+ +
+ <literal>mp::Package</literal> + (<filename>package.cpp</filename>) + + Represents a package on its way through the series of filters + that make up a route. This is essentially a Z39.50 or SRU APDU + together with information about where it came from, which is + modified as it passes through the various filters. + +
+ +
+ <literal>mp::Pipe</literal> + (<filename>pipe.cpp</filename>) + + This class provides a compatibility layer so that we have an IPC + mechanism that works the same under Unix and Windows. It's not + particularly exciting. + +
+ +
+ <literal>mp::RouterChain</literal> + (<filename>router_chain.cpp</filename>) + + ### + +
+ +
+ <literal>mp::RouterFleXML</literal> + (<filename>router_flexml.cpp</filename>) + + ### + +
+ +
+ <literal>mp::Session</literal> + (<filename>session.cpp</filename>) + + ### + +
+ +
+ <literal>mp::ThreadPoolSocketObserver</literal> + (<filename>thread_pool_observer.cpp</filename>) + + ### + +
+ +
+ <literal>mp::util</literal> + (<filename>util.cpp</filename>) + + A namespace of various small utility functions and classes, + collected together for convenience. Most importantly, includes + the mp::util::odr class, a wrapper for YAZ's + ODR facilities. + +
+ +
+ <literal>mp::xml</literal> + (<filename>xmlutil.cpp</filename>) + + A namespace of various XML utility functions and classes, + collected together for convenience. + +
+
+ + +
+ Other Source Files + + In addition to the Metaproxy source files that define the classes + described above, there are a few additional files which are + briefly described here: + + + + metaproxy_prog.cpp + + + The main function of the yp2 program. + + + + + ex_router_flexml.cpp + + + Identical to metaproxy_prog.cpp: it's not clear why. + + + + + test_*.cpp + + + Unit-tests for various modules. + + + + + + ### Still to be described: + ex_filter_frontend_net.cpp, + filter_dl.cpp, + plainfile.cpp, + tstdl.cpp. + + + + + + -- + + + + + + + + +
+ + + diff --git a/doc/html.dsl.in b/doc/html.dsl.in new file mode 100644 index 0000000..54610f4 --- /dev/null +++ b/doc/html.dsl.in @@ -0,0 +1,26 @@ + +]> + + + + + +(define %use-id-as-filename% #t) +(define %output-dir% "html") +(define %html-ext% ".html") +(define %shade-verbatim% #t) + + + + + + + diff --git a/doc/metaproxy.xml.in b/doc/metaproxy.xml.in new file mode 100644 index 0000000..9880590 --- /dev/null +++ b/doc/metaproxy.xml.in @@ -0,0 +1,25 @@ + + + + +]> + + + &book; + + diff --git a/doc/print.dsl.in b/doc/print.dsl.in new file mode 100644 index 0000000..bd5814d --- /dev/null +++ b/doc/print.dsl.in @@ -0,0 +1,21 @@ + +]> + + + + + + + + + + + diff --git a/doc/yp2.xml.in b/doc/yp2.xml.in deleted file mode 100644 index e23efe5..0000000 --- a/doc/yp2.xml.in +++ /dev/null @@ -1,788 +0,0 @@ - - -]> - - - - YP2 - User's Guide and Reference - - MikeTaylor - - - 2006 - Index Data - - - - ### - YP2 is ... in need of description :-) - - - - - - - - Introduction - - -
- Overview - - YP2 - is extremely cool. - - - ### We should probably consider saying a little more by way of - introduction. - -
- - - - - - Filters - - -
- Introductory notes - - It's useful to think of YP2 as an interpreter providing a small - number of primitives and operations, but operating on a very - complex data type, namely the ``package''. - - - A package represents a Z39.50 or SRW/U request (whether for Init, - Search, Scan, etc.) together with information about where it came - from. Packages are created by front-end filters such as - frontend_net (see below), which reads them from - the network; other front-end filters are possible. They then pass - along a route consisting of a sequence of filters, each of which - transforms the package and may also have side-effects such as - generating logging. Eventually, the route will yield a response, - which is sent back to the origin. - - - There are many kinds of filter: some that are defined statically - as part of YP2, and other that may be provided by third parties - and dynamically loaded. They all conform to the same simple API - of essentially two methods: configure() is - called at startup time, and is passed a 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 process() is called every - time the filter has to processes a package. - - - While all filters provide the same API, there are different modes - of functionality. Some filters are sources: they create - packages - (frontend_net); - others are sinks: they consume packages and return a result - (z3950_client, - backend_test, - http_file); - the others are true filters, that read, process and pass on the - packages they are fed - (auth_simple, - log, - multi, - session_shared, - template, - virt_db). - -
- - -
- Individual filters - - The filters are here named by the string that is used as the - type attribute of a - <filter> element in the configuration - file to request them, with the name of the class that implements - them in parentheses. - - -
- <literal>auth_simple</literal> - (yp2::filter::AuthSimple) - - Simple authentication and authorisation. The configuration - specifies the name of a file that is the user register, which - lists username:password - pairs, one per line, colon separated. When a session begins, it - is rejected unless username and passsword are supplied, and match - a pair in the register. - - - ### discuss authorisation phase - -
- -
- <literal>backend_test</literal> - (yp2::filter::Backend_test) - - A sink that provides dummy responses in the manner of the - yaz-ztest Z39.50 server. This is useful only - for testing. - -
- -
- <literal>frontend_net</literal> - (yp2::filter::FrontendNet) - - A source that accepts Z39.50 and SRW connections from a port - specified in the configuration, reads protocol units, and - feeds them into the next filter, eventually returning the - result to the origin. - -
- -
- <literal>http_file</literal> - (yp2::filter::HttpFile) - - A sink that returns the contents of files from the local - filesystem in response to HTTP requests. (Yes, Virginia, this - does mean that YP2 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.) - -
- -
- <literal>log</literal> - (yp2::filter::Log) - - Writes logging information to standard output, and passes on - the package unchanged. - -
- -
- <literal>multi</literal> - (yp2::filter::Multi) - - Performs multicast searching. See the extended discussion of - multi-database searching below. - -
- -
- <literal>session_shared</literal> - (yp2::filter::SessionShared) - - When this is finished, it will implement global sharing of - result sets (i.e. between threads and therefore between - clients), but it's not yet done. - -
- -
- <literal>template</literal> - (yp2::filter::Template) - - Does nothing at all, merely passing the packet on. (Maybe it - should be called nop or - passthrough?) This exists not to be used, but - to be copied - to become the skeleton of new filters as they are - written. - -
- -
- <literal>virt_db</literal> - (yp2::filter::Virt_db) - - Performs virtual database selection. See the extended discussion - of virtual databases below. - -
- -
- <literal>z3950_client</literal> - (yp2::filter::Z3950Client) - - 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 VAL_PROXY otherInfo - attached to the request: this may have been specified by client, - or generated by a virt_db filter earlier in - the route. Subsequent requests are sent to the same address, - which is remembered at Init time in a Session object. - -
-
- - -
- Future directions - - Some other filters that do not yet exist, but which would be - useful, are briefly described. These may be added in future - releases. - - - - - frontend_cli (source) - - - Command-line interface for generating requests. - - - - - srw2z3950 (filter) - - - Translate SRW requests into Z39.50 requests. - - - - - srw_client (sink) - - - SRW searching and retrieval. - - - - - sru_client (sink) - - - SRU searching and retrieval. - - - - - opensearch_client (sink) - - - A9 OpenSearch searching and retrieval. - - - - -
- - - - - - Configuration: the YP2 configuration file format - - -
- Introductory notes - - If YP2 is an interpreter providing operations on packages, then - its configuration file can be thought of as a program for that - interpreter. Configuration is by means of a single file, the name - of which is supplied as the sole command-line argument to the - yp2 program. - - - The configuration files are written in XML. (But that's just an - implementation detail - they could just as well have been written - in YAML or Lisp-like S-expressions, or in a custom syntax.) - - - Since XML has been chosen, an XML schema, - config.xsd, is provided for validating - configuration files. This file is supplied in the - etc directory of the YP2 distribution. It - can be used by (among other tools) the xmllint - program supplied as part of the libxml2 - distribution: - - - xmllint --noout --schema etc/config.xsd my-config-file.xml - - - (A recent version of libxml2 is required, as - support for XML Schemas is a relatively recent addition.) - -
- -
- Overview of XML structure - - All elements and attributes are in the namespace - . - This is most easily achieved by setting the default namespace on - the top-level element, as here: - - - <yp2 xmlns="http://indexdata.dk/yp2/config/1"> - - - The top-level element is <yp2>. This contains a - <start> element, a <filters> element and a - <routes> element, in that order. <filters> is - optional; the other two are mandatory. All three are - non-repeatable. - - - The <start> element is empty, but carries a - route attribute, whose value is the name of - route at which to start running - analogouse to the name of the - start production in a formal grammar. - - - If present, <filters> contains zero or more <filter> - elements; filters carry a type attribute and - contain various elements that provide suitable configuration for - filters of that type. The filter-specific elements are described - below. Filters defined in this part of the file must carry an - id attribute so that they can be referenced - from elsewhere. - - - <routes> contains one or more <route> elements, each - of which must carry an id element. One of the - routes must have the ID value that was specified as the start - route in the <start> element's route - attribute. Each route contains zero or more <filter> - elements. These are of two types. They may be empty, but carry a - refid attribute whose value is the same as the - id of a filter previously defined in the - <filters> section. Alternatively, a route within a filter - may omit the refid attribute, but contain - configuration elements similar to those used for filters defined - in the <filters> section. - -
- - -
- Filter configuration - - All <filter> elements have in common that they must carry a - type attribute whose value is one of the - supported ones, listed in the schema file and discussed below. In - additional, <filters>s occurring the <filters> section - must have an id attribute, and those occurring - within a route must have either a refid - attribute referencing a previously defined filter or contain its - own configuration information. - - - In general, each filter recognises different configuration - elements within its element, as each filter has different - functionality. These are as follows: - - -
- <literal>auth_simple</literal> - - <filter type="auth_simple"> - <userRegister>../etc/example.simple-auth</userRegister> - </filter> - -
- -
- <literal>backend_test</literal> - - <filter type="backend_test"/> - -
- -
- <literal>frontend_net</literal> - - <filter type="frontend_net"> - <threads>10</threads> - <port>@:9000</port> - </filter> - -
- -
- <literal>http_file</literal> - - <filter type="http_file"> - <mimetypes>/etc/mime.types</mimetypes> - <area> - <documentroot>.</documentroot> - <prefix>/etc</prefix> - </area> - </filter> - -
- -
- <literal>log</literal> - - <filter type="log"> - <message>B</message> - </filter> - -
- -
- <literal>multi</literal> - - <filter type="multi"/> - -
- -
- <literal>session_shared</literal> - - <filter type="session_shared"> - ### Not yet defined - </filter> - -
- -
- <literal>template</literal> - - <filter type="template"/> - -
- -
- <literal>virt_db</literal> - - <filter type="virt_db"> - <virtual> - <database>loc</database> - <target>z3950.loc.gov:7090/voyager</target> - </virtual> - <virtual> - <database>idgils</database> - <target>indexdata.dk/gils</target> - </virtual> - </filter> - -
- -
- <literal>z3950_client</literal> - - <filter type="z3950_client"> - <timeout>30</timeout> - </filter> - -
-
- - - - - - Virtual database as multi-database searching - - -
- Introductory notes - - Two of YP2's filters are concerned with multiple-database - operations. Of these, virt_db can work alone - to control the routing of searches to one of a number of servers, - while multi can work with the output of - virt_db to perform multicast searching, merging - the results into a unified result-set. The interaction between - these two filters is necessarily complex, reflecting the real - complexity of multicast searching in a protocol such as Z39.50 - that separates initialisation from searching, with the database to - search known only during the latter operation. - - - ### Much, much more to say! - -
- - - - - - Classes in the YP2 source code - - -
- Introductory notes - - Stop! Do not read this! - You won't enjoy it at all. - - - This chapter contains documentation of the YP2 source code, and is - of interest only to maintainers and developers. If you need to - change YP2's behaviour or write a new filter, then you will most - likely find this chapter helpful. Otherwise it's a waste of your - good time. Seriously: go and watch a film or something. - This is Spinal Tap is particularly good. - - - Still here? OK, let's continue. - - - In general, classes seem to be named big-endianly, so that - FactoryFilter is not a filter that filters - factories, but a factory that produces filters; and - FactoryStatic is a factory for the statically - registered filters (as opposed to those that are dynamically - loaded). - -
- -
- Individual classes - - The classes making up the YP2 application are here listed by - class-name, with the names of the source files that define them in - parentheses. - - -
- <literal>yp::FactoryFilter</literal> - (<filename>factory_filter.cpp</filename>) - - A factory class that exists primarily to provide the - create() method, which takes the name of a - filter class as its argument and returns a new filter of that - type. To enable this, the factory must first be populated by - calling add_creator() for static filters (this - is done by the FactoryStatic class, see below) - and add_creator_dyn() for filters loaded - dynamically. - -
- -
- <literal>yp2::FactoryStatic</literal> - (<filename>factory_static.cpp</filename>) - - A subclass of FactoryFilter which is - responsible for registering all the statically defined filter - types. It does this by knowing about all those filters' - structures, which are listed in its constructor. Merely - instantiating this class registers all the static classes. It is - for the benefit of this class that struct - yp2_filter_struct exists, and that all the filter - classes provide a static object of that type. - -
- -
- <literal>yp2::filter::Base</literal> - (<filename>filter.cpp</filename>) - - The virtual base class of all filters. The filter API is, on the - surface at least, extremely simple: two methods. - configure() is passed a 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 process() processes a - package (see below). That surface simplicitly is a bit - misleading, as process() needs to know a lot - about the Package class in order to do - anything useful. - -
- -
- <literal>yp2::filter::AuthSimple</literal>, - <literal>Backend_test</literal>, etc. - (<filename>filter_auth_simple.cpp</filename>, - <filename>filter_backend_test.cpp</filename>, etc.) - - Individual filters. Each of these is implemented by a header and - a source file, named filter_*.hpp and - filter_*.cpp respectively. All the header - files should be pretty much identical, in that they declare the - class, including a private Rep class and a - member pointer to it, and the two public methods. The only extra - information in any filter header is additional private types and - members (which should really all be in the Rep - anyway) and private methods (which should also remain known only - to the source file, but C++'s brain-damaged design requires this - dirty laundry to be exhibited in public. Thanks, Bjarne!) - - - The source file for each filter needs to supply: - - - - - A definition of the private Rep class. - - - - - Some boilerplate constructors and destructors. - - - - - A configure() method that uses the - appropriate XML fragment. - - - - - Most important, the process() method that - does all the actual work. - - - -
- -
- <literal>yp2::Package</literal> - (<filename>package.cpp</filename>) - - Represents a package on its way through the series of filters - that make up a route. This is essentially a Z39.50 or SRU APDU - together with information about where it came from, which is - modified as it passes through the various filters. - -
- -
- <literal>yp2::Pipe</literal> - (<filename>pipe.cpp</filename>) - - This class provides a compatibility layer so that we have an IPC - mechanism that works the same under Unix and Windows. It's not - particularly exciting. - -
- -
- <literal>yp2::RouterChain</literal> - (<filename>router_chain.cpp</filename>) - - ### - -
- -
- <literal>yp2::RouterFleXML</literal> - (<filename>router_flexml.cpp</filename>) - - ### - -
- -
- <literal>yp2::Session</literal> - (<filename>session.cpp</filename>) - - ### - -
- -
- <literal>yp2::ThreadPoolSocketObserver</literal> - (<filename>thread_pool_observer.cpp</filename>) - - ### - -
- -
- <literal>yp2::util</literal> - (<filename>util.cpp</filename>) - - A namespace of various small utility functions and classes, - collected together for convenience. Most importantly, includes - the yp2::util::odr class, a wrapper for YAZ's - ODR facilities. - -
- -
- <literal>yp2::xml</literal> - (<filename>xmlutil.cpp</filename>) - - A namespace of various XML utility functions and classes, - collected together for convenience. - -
-
- - -
- Other Source Files - - In addition to the YP2 source files that define the classes - described above, there are a few additional files which are - briefly described here: - - - - yp2_prog.cpp - - - The main function of the yp2 program. - - - - - ex_router_flexml.cpp - - - Identical to yp2_prog.cpp: it's not clear why. - - - - - test_*.cpp - - - Unit-tests for various modules. - - - - - - ### Still to be described: - ex_filter_frontend_net.cpp, - filter_dl.cpp, - plainfile.cpp, - tstdl.cpp. - - - - - - -- - - - - - - - - -
- - - - diff --git a/doc/yp2html.dsl.in b/doc/yp2html.dsl.in deleted file mode 100644 index 06df7c6..0000000 --- a/doc/yp2html.dsl.in +++ /dev/null @@ -1,26 +0,0 @@ - -]> - - - - - -(define %use-id-as-filename% #t) -(define %output-dir% "html") -(define %html-ext% ".html") -(define %shade-verbatim% #t) - - - - - - - diff --git a/doc/yp2php.dsl.in b/doc/yp2php.dsl.in deleted file mode 100644 index f50e336..0000000 --- a/doc/yp2php.dsl.in +++ /dev/null @@ -1,98 +0,0 @@ - -]> - - - - - -(define %use-id-as-filename% #t) -(define %output-dir% "php") -(define %html-ext% ".php") -(define %shade-verbatim% #t) - -(define newline "\U-000D") - -(define (html-document title-sosofo body-sosofo) - (let* (;; Let's look these up once, so that we can avoid calculating - ;; them over and over again. - (prev (prev-chunk-element)) - (next (next-chunk-element)) - (prevm (prev-major-component-chunk-element)) - (nextm (next-major-component-chunk-element)) - (navlist (list prev next prevm nextm)) - - ;; Let's make it possible to control the output even in the - ;; nochunks case. Note: in the nochunks case, (chunk?) will - ;; return #t for only the root element. - (make-entity? (and (or (not nochunks) rootchunk) - (chunk?))) - - (make-head? (or make-entity? - (and nochunks - (node-list=? (current-node) - (sgml-root-element))))) - (doc-sosofo - (if make-head? - (make sequence - (make formatting-instruction data: - (string-append "<" "?php " - newline - "require \"../../id_common.inc\";" - newline - "id_header(\"" - ) - ) - title-sosofo - (make formatting-instruction data: - (string-append "\");" - newline - "?" ">" - ) - ) - (header-navigation (current-node) navlist) - body-sosofo - (footer-navigation (current-node) navlist) - (make formatting-instruction data: - (string-append "<" "?php id_footer() ?>") - ) - ) - body-sosofo - ) - ) - ) - (if make-entity? - (make entity - system-id: (html-entity-file (html-file)) - (if %html-pubid% - (make document-type - name: "HTML" - public-id: %html-pubid%) - (empty-sosofo)) - doc-sosofo) - (if (node-list=? (current-node) (sgml-root-element)) - (make sequence - (if %html-pubid% - (make document-type - name: "HTML" - public-id: %html-pubid%) - (empty-sosofo)) - doc-sosofo) - doc-sosofo) - ) - ) - ) - - - - - - - diff --git a/doc/yp2print.dsl.in b/doc/yp2print.dsl.in deleted file mode 100644 index 50ee6dc..0000000 --- a/doc/yp2print.dsl.in +++ /dev/null @@ -1,21 +0,0 @@ - -]> - - - - - - - - - - - -- 1.7.10.4