X-Git-Url: http://git.indexdata.com/?p=yazpp-moved-to-github.git;a=blobdiff_plain;f=doc%2Fproxy.xml;h=9d04a650f4a208b1a509da61f4c6732cc21a356c;hp=cf76fe6459be62fc7811f8936026e655461d61df;hb=5554ddf9c4d9670aaaa8f8b9ce6def1dadff3c96;hpb=a03eabd5ecf775dc8ba57186fc906b4b698772ed diff --git a/doc/proxy.xml b/doc/proxy.xml index cf76fe6..9d04a65 100644 --- a/doc/proxy.xml +++ b/doc/proxy.xml @@ -130,7 +130,9 @@ If the InitializeRequest PDU from the - client includes an otherInfo element with OID + client includes an + otherInfo + element with OID 1.2.840.10003.10.1000.81.1, then the contents of that element specify the target to be used, in the usual YAZ address format (typically @@ -155,33 +157,36 @@
- Keep-alive Facility for Stateless Clients + Keep-alive Facility - Stateless clients such as web gateways may generate a cookie for a Z39.50 - session which is sent to the proxy as part of PDUs. - In this case, the proxy will keep alive its Z39.50 session - to the backend target even when the connection from the client - to the proxy is closed. When the client contacts the - proxy again, and re-issues the same cookie, the proxy reuses the - Z39.50 connection with the backend target. + The keep-alive is a facility where the proxy keeps the connection to the + backend - even if the client closes the connection to the proxy. - There is no - guarantee that the Z39.50 connection to the backend - target is kept forever: the proxy will shut it down after certain - idle time. - - So in effect, the connection from the client's - point of view should be considered stateless, and the keep-alive - facility should be treated only as a performance booster. + If a new or another client connects to the proxy again and requests the + same backend it will be reassigned to this backend. In this case, the + proxy sends an initialize response directly to the client and an + initialize handshake with the backend is omitted. - Cookies may be passed in an otherInfo element - with OID 1.2.840.10003.10.1000.81.2. + When a client reconnects, query and record caching works better, if the + proxy assigns it to the same backend as before. And the result set + (if any) is re-used. To achive this, Index Data defined a session + cookie which identifies the backend session. + + + The cookie is defined by the client and is sent as part of the + Initialize Request and passed in an + otherInfo + element with OID 1.2.840.10003.10.1000.81.2. + + + Clients that do not send a cookie as part of the initialize request + may still better performance, since the init handshake is saved.
-
+
Query Caching Simple stateless clients often send identical Z39.50 searches @@ -196,21 +201,44 @@ backend target, so that if an identical query is received next, it is turned into Present Requests rather than new Search Requests. - + + + In a future we release will will probably allows for + an arbitrary-sized cache for targets supporting named result sets. + + - This optimization should work for any Z39.50 client and/or - target. The target does not have to support named result sets. + You can enable/disable query caching using option -o. - +
+ + +
+ Record Caching + + As an option, the proxy may also cache result set records for the + last search. + The proxy takes into account the Record Syntax and CompSpec. + The CompSpec includes simple element set names as well. +
-
+
+ Query Validation + + +
+ +
+ Record Syntax Validation + + +
+ +
Other Optimizations - - We've had some plans to support caching of result set records, + + We've had some plans to support global caching of result set records, but this has not yet been implemented.
@@ -220,143 +248,37 @@ - - yaz-proxy - 8 - - - yaz-proxy - The YAZ toolkit's transparent Z39.50 proxy - - - - yaz-proxy - -a filename - -c num - -v level - -t target - -u auth - -o level - host:port - - - - DESCRIPTION - - The proxy runs stand-alone (not from - inetd). The - host:port - argument specifies host address to listen to, and the port to - listen on. Use the host @ - to listen for connections coming from any address. - - - OPTIONS - - -a filename - - Specifies the name of a file to which to write a log of the - APDUs (protocol packets) that pass through the proxy. The - special filename - may be used to indicate - standard output. - - - -c num - - Specifies the maximum number of connections to be cached - [default 50]. - - - -v level - - Sets the logging level. level is - a comma-separated list of members of the set - {fatal,debug,warn,log,malloc,all,none}. - - - -t target - - Specifies the default backend target to use when a client - connects that does not explicitly specify a target in its - initRequest. - - - -u auth - - Specifies authentication info to be sent to the backend target. - This is useful if you happen to have an internal target that - requires authentication, or if the client software does not allow - you to set it. - - - -o level - - Sets level for optimization. Use zero to disable; non-zero - to enable. Handling for this is not fully implemented; - we will probably use a bit mask to enable/disable specific - features. - - - - - - EXAMPLES - - The following command starts the proxy, listening on port - 9000, with its default backend target set to the Library of - Congress bibliographic server: - - - $ yaz-proxy -t z3950.loc.gov:7090 @:9000 - - - The LOC target is sometimes very slow. You can connect to - it using yaz-client as follows: - - - $ yaz-client localhost:9000/voyager - Connecting...Ok. - Sent initrequest. - Connection accepted by target. - ID : 34 - Name : Voyager LMS - Z39.50 Server - Version: 1.13 - Options: search present - Elapsed: 7.131197 - Z> f computer - Sent searchRequest. - Received SearchResponse. - Search was a success. - Number of hits: 10000 - records returned: 0 - Elapsed: 6.695174 - Z> f computer - Sent searchRequest. - Received SearchResponse. - Search was a success. - Number of hits: 10000 - records returned: 0 - Elapsed: 0.001417 - - - In this test, the second search was more than 4000 times faster - than the first, because the proxy cached the result of the first - search and noticed that the second was the same. - - - The YAZ command-line client, - yaz-client, - allows you to set the backend target in - the initRequest using the - -p option. For example, to connect to - Index Data's target you could use: - - - yaz-client -p indexdata.dk localhost:9000/gils - - + &yaz-proxy-ref;
+
OtherInformation Encoding + + The proxy uses the OtherInformation definition to carry + information about the target address and cookie. + + + OtherInformation ::= [201] IMPLICIT SEQUENCE OF SEQUENCE{ + category [1] IMPLICIT InfoCategory OPTIONAL, + information CHOICE{ + characterInfo [2] IMPLICIT InternationalString, + binaryInfo [3] IMPLICIT OCTET STRING, + externallyDefinedInfo [4] IMPLICIT EXTERNAL, + oid [5] IMPLICIT OBJECT IDENTIFIER}} +-- + InfoCategory ::= SEQUENCE{ + categoryTypeId [1] IMPLICIT OBJECT IDENTIFIER OPTIONAL, + categoryValue [2] IMPLICIT INTEGER} + + + The categoryTypeId is either + OID 1.2.840.10003.10.1000.81.1, 1.2.840.10003.10.1000.81.2 + for proxy target and proxy cookie respectively. The + integer element category is set to 0. + The value proxy and cookie is stored in element + characterInfo of the information + choice. + +