--- a/Query.st	Sat Oct 04 10:42:47 2008 +0200
+++ b/Query.st	Sat Oct 04 10:47:38 2008 +0200
@@ -9,7 +9,6 @@
  other person.  No title to or ownership of the software is
  hereby transferred.
 "
-
 "{ Package: 'stx:libbasic' }"
 
 Notification subclass:#Query
@@ -48,11 +47,62 @@
         Query does not add/refine any functionality from its superclass.
         It exists for the more descriptive class name only.
 
+    Queries are like exceptions, except that they are not accepted
+    by handlers for ordinary exceptions.
+    I.e. a handler for a normal exception will not handle a query. 
+    Thus, these bypass all normal exception handlers.
+
+    However, if unhandled, no error is raised, instead it is simply ignored
+    and nil is returned from the raise
+    (as opposed to normal exceptions, which raise an unhandled exception error).
+    Queries are also ignored, if a handler exists, but rejects.
+
+    The main use of Queries is to implement an upQuery, which works even 
+    if intermediate errorSignal handlers are present. 
+
+    Code deep down in the calling hierarchy can post such an up-Query to ask
+    for some information or to pass some information upward. 
+
+    For example, the activityNotification mechanism is built on top of this:
+    everyone can send such a notification which is either handled by someone
+    up in the hierarchy (to show it in the windows info area) or simply
+    ignored.
+
+    Using Queries for this (instead of regular Signals) helps in documenting
+    the intended usage of those signals.
+
+    Another use of queries is to provide additional information to
+    deeply nested methods, which is only required in the uncommon case;
+    or if another parameter is required by some method, which was not planned
+    for in the beginning, and you do not want to hand this value (via an
+    additional argument) through all intermediate levels.
+
+    A highly elegant solution to this problem is to provide a handler somewhere
+    at the top of the calling hierarchy, and raise an upQuery from whereever
+    that value is required.
+    A concrete application can be found in the windowGroup-lastEvent
+    queries. If anyone is interested in the windowEvent which was responible for 
+    being invoked, all he needs to do is to raise the lastEventQuerySignal, 
+    which returns that event.
+    No intermediate methods are required to know anything about that.
+    Another example is found in the way Metaclass asks for the nameSpace
+    when new classes are to be installed. A Browser may simply answer such
+    a query and provide a namespace (no need to pass that information down
+    the calling chain).
+
+    A final note (to C++ and Java fans):
+        such upQueries are only possible, if the exception handling mechanism
+        does not automatically unwind the stack for the handler invokation.
+        Since the handler must be able to proceed the execution and return
+        a value to the raiser ....
+        ... another demonstration of why ST's exception mechanisms are superior.
+
     [author:]
         Claus Gittinger
 
     [see also:]
-        Warning Signal QuerySignal
+        Notification Warning Signal QuerySignal
+        (``Exception handling and signals'': programming/exceptions.html)
 "
 !
 
@@ -214,7 +264,7 @@
 !Query class methodsFor:'documentation'!
 
 version
-    ^ '$Header: /cvs/stx/stx/libbasic/Query.st,v 1.11 2005-01-20 12:26:18 stefan Exp $'
+    ^ '$Header: /cvs/stx/stx/libbasic/Query.st,v 1.12 2008-10-04 08:47:38 cg Exp $'
 ! !
 
 Query initialize!