Add documentation about fake substitute library.

diff --git a/org.glite.lb.client/doc/README-fake b/org.glite.lb.client/doc/README-fake
new file mode 100644 (file)
index 0000000..e2593ae
--- /dev/null
+++ b/org.glite.lb.client/doc/README-fake
@@ -0,0 +1,132 @@
+Fake library
+------------
+
+Fake library is a substitute library designed for usage in unit tests of
+programs which use L&B. The library implements a subset of L&B client API.
+Implemented functions are dummy in the sense that they do not produce any
+sideefect and they do not require any running services.
+
+Main purpose of the library is WMS unit testing, so it should contain all L&B
+function calls used in WMS.
+
+List of implemented functions:
+
+  1) consumer API
+
+     edg_wll_QueryEvents
+     edg_wll_QueryListener
+     edg_wll_JobLog
+     edg_wll_QuerySequenceCode
+
+  2) producer API
+
+     edg_wll_Log*     (functions for logging all event types)
+     edg_wll_LogEvent
+     edg_wll_LogEventSync
+     edg_wll_LogEventProxy
+     edg_wll_LogFlush
+     edg_wll_LogFlushAll
+     edg_wll_SetLoggingJob
+     edg_wll_SetLoggingJobProxy
+     edg_wll_RegisterJobSync
+     edg_wll_RegisterJob
+     edg_wll_RegisterSubjob
+     edg_wll_RegisterSubjobs
+     edg_wll_ChangeACL
+
+
+Function calls always try to return some meaningful data. However, for testing
+purposes a fine control on the returned value is usually required (e.g. to 
+cover both success and failure of the called function). Therefore the library
+enables to set function error codes and/or adjust returned data. This is done
+via callbacks. Callbacks are activated right before function end when all
+pre-set data are available. 
+
+Callbacks must be registered before using the library call. It is possible to
+have only one registered callback for each registration type at once (see
+below). Callback registration is global, it IS NOT thread safe. Otherwise
+the library is thread safe in the same way as standard L&B library -- 
+functions may be called by multiple threads simultaneously provided that
+more threads do not operate on a single L&B context at the same time.
+
+The following code fragments represent an example of unit test of a function
+calling e.g. edg_wll_LogMatch()
+
+#include "glite/lb/producer_fake.h"
+
+int fail_EAGAIN_callback(edg_wll_Context ctx)
+{
+       return edg_wll_SetError(ctx,EAGAIN,"failure reason");
+}
+
+unit_test()
+{
+       /* sucessfull logging, edg_wll_LogMatch() called from
+        * tested_function() returns OK */
+
+       tested_function();
+       /* check results here */
+
+       /* failing with EAGAIN */
+       edg_wll_RegisterTestLogging(fail_EAGAIN_callback);
+       tested_function();
+       /* check results here */
+}
+
+The consumer API (QueryEvents, QueryListener) fake implementations
+prepare some result set which is returned to the caller. The callback
+function may also adjust this set for particular purposes of the unit test.
+
+List of the callbacks and registering functions:
+
+  1) cosumer API
+
+       typedef int (edg_wll_QueryEvents_cb_f)
+               (edg_wll_Context context, edg_wll_Event **events);
+       typedef int (edg_wll_QueryListener_cb_f)
+               (edg_wll_Context context, char **host, uint16_t *port);
+
+       int edg_wll_RegisterTestQueryEvents(edg_wll_QueryEvents_cb_f *cb);
+       int edg_wll_RegisterTestQueryListener(edg_wll_QueryListener_cb_f *cb);
+
+  2) producer API
+
+       typedef int (edg_wll_Logging_cb_f)(edg_wll_Context context);
+
+       int edg_wll_RegisterTestLogging(edg_wll_Logging_cb_f *cb);
+       int edg_wll_RegisterTestLoggingProxy(edg_wll_Logging_cb_f *cb);
+
+
+It possible to unregister registered callbacks using following functions:
+
+       void edg_wll_UnregisterTestQueryEvents();
+       void edg_wll_UnregisterTestQueryListener();
+       void edg_wll_UnregisterTestLogging();
+       void edg_wll_UnregisterTestLoggingProxy();
+
+
+Library name is libglite_lb_client_fake_gcc32dbg[pthr].so. It is built
+in the org.glite.lb.client module, staged (so that it is available
+for WMS unit tests run during the build process) but currenlty 
+neither installed nor included in RPM.
+
+Unit test programs should linked with this library instead of the original
+libglite_lb_client_gcc32dbg[pthr].so. You can find examples of fake library
+usage in org.glite.lb.client. The Makefile target 'fake' builds these examples.
+There is no ant equivalent, hence the following procedure is required:
+
+    cd org.glite.lb.client
+    ant init
+    cd build
+    make fake
+
+
+* TODO (MATOUCI): v examples/ musi byt jednak priklady, ktere se linkuji s normalni
+* knihovnou a funguji plnohodnotne dle ocekavani, a navic neco jako
+* fake_job_log, ktery bude prikladem unittestu (opravdu s pouzitim cppUnitu
+* atd.) nejake funkce z jinak opravdoveho job_log (asi bude treba ji
+* pro tyto ucely vytahnout z main()u).
+
+In the example examples/job_log.c is showed how to use callbacks and their
+registration. Examples examples/job_reg.c and src/logevent.c are original L&B
+examples which are just linked with the fake library too.