Return-Path: <rael@zopyra.com>
Mailing-List: contact commons-dev-help@jakarta.apache.org; run by ezmlm
Delivered-To: mailing list commons-dev@jakarta.apache.org
Received: (qmail 85331 invoked from network); 16 Sep 2003 14:51:01 -0000
Received: from unknown (HELO zopyra.com) (65.68.225.25)
  by daedalus.apache.org with SMTP; 16 Sep 2003 14:51:01 -0000
Received: (from rael@localhost)
	by zopyra.com (8.11.6/8.11.6) id h8GErhx27571;
	Tue, 16 Sep 2003 09:53:43 -0500
From: Bill Lear <rael@zopyra.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit
Message-ID: <16231.9199.494522.86755@lisa.zopyra.com>
Date: Tue, 16 Sep 2003 09:53:35 -0500
To: commons-dev@jakarta.apache.org
Subject: [HiveMind] Suggestion for Bootstrap documentation addition
X-Mailer: VM 6.97 under Emacs 21.1.1
X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N

I've just added my first interceptor.  Neat stuff.  I suggest we add
a section to the example (Bootstrap) to show how to do this and
how to configure the log4j properties (this was a bit confusing
for me).

Here is a sketch:

Debugging the Example Using a Logging Interceptor

Logging interceptors can be used to print out method invocation,
including parameters passed and results returned.  Adding a logging
interceptor to a service is easy: add an interceptor clause to your
HiveMind module, and set the log4j debug property on this interceptor
to print out the information when the application is run.

So, for our example, first add a logging interceptor to the HiveMind
module:

<?xml version="1.0"?>

<module id="hivemind.examples" version="1.0.0">
    <service id="Adder" interface="hivemind.examples.Adder">
        <create-instance class="hivemind.examples.impl.AdderImpl2"/>

        <interceptor service-id="hivemind.LoggingInterceptor"/>
    </service>
</module>

This interceptor will use the ID of the service within which it is
operating, in this case 'hivemind.examples.Adder'.

Next, set the debug level in the log4j.properties file by
catenating 'log4j.category.' with the service id:

log4j.category.hivemind.examples.Adder=debug

The complete log4j file now looks something like this:

log4j.rootCategory=WARN, A1
log4j.appender.A1=org.apache.log4j.ConsoleAppender
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=%r %c{1} [%p] %m%n
log4j.category.hivemind.examples.Adder=debug

Now type in 'ant run' from the top-level directory and you should see
the interceptor at work, printing out parameter values on entry, and
the result upon exit:

% ant run
     ...
     [java] 0 Adder [DEBUG] BEGIN add(11, 23)
     [java] 5 Adder [DEBUG] END add() [34]
     ...

You can also get rough execution times for the methods by setting
the pattern for the layout to include millisecond time values:

log4j.appender.A1.layout.ConversionPattern=<%p %d{ISO8601} %c{1}> %m%n

% ant run
     ...
     [java] <DEBUG 2003-09-16 09:46:02,034 Adder> BEGIN add(11, 23)
     [java] <DEBUG 2003-09-16 09:46:02,054 Adder> END add() [34]
     ...

This shows that the Adder add method took about 20 milliseconds to
run.  [Q: is this time at all accurate?  Does it include any
interceptor overhead, or is it mostly the method invocation?].

In any case, just a suggestion.

Next, I'm going to work on understanding extensions to services.
Not sure I like the terms, "extension" or "extension-point".
Configuring seems much less involved than extending, and HiveMind
extensions seem to be all about configuring.  Since I don't fully
understand it, though, once I get through the doc and work through
a few examples, I may change my view.


Bill