Sophie: jiapi-manual-0.4.0-8.mga7 noarch

jiapi-manual-0.4.0-8.mga7.noarch.rpm

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<body>

<a href="user_guide.html">[index]</a><br>
<a href="framework.html">[prev]</a>

<h1>3. Jiapi Events</h1>

This chapter explains the Jiapi event API. The event API is designed to 
get runtime events from an instrumented class. As an API, it is similar to 
core Java event model. From Jiapi framework's point of view the event API 
is just an application implemented on top of it. As such, it is a useful 
example and useful for those applications which need some basic information 
from a running application.

<p>
To utilize the events, application developer implements a listener interface 
and registers it to an event producer. Current implementation provides
a notification mechanism for following events:

<ul>
  <li><b>Method events</b>
  <li><b>Field access events</b>
  <li><b>Exception events</b>
</ul>

<h2>3.1 Method events</h2>

An application component which is interested about method related events
can implement a <code>alt.jiapi.event.MethodListener</code> interface.
The interface provides callback methods to get notification when
a method is entered or when a method exits:

<pre>
public interface MethodListener extends JiapiListener {
    /**
     * Called when a method is entered. 
     * @param event a MethodEvent describing which method triggered
     *        this event
     */
    public void methodEntered(MethodEvent event);

    /**
     * Called just before method is exiting.
     * @param event a MethodEvent describing which method triggered
     *        this event
     */
    public void methodExited(MethodEvent event);
}
</pre>

<h2>3.2 Field access events</h2>

Field access events are notified for classes which implement
a <code>alt.jiapi.event.FieldListener</code> interface.

<pre>
public interface FieldListener extends JiapiListener {
    /**
     * Called just before a field is changed.
     */
    public void fieldChanging(FieldEvent fe);

    /**
     * Called after a field has been set.
     */
    public void fieldSet(FieldEvent fe);

    /**
     * Called when someone is getting a field.
     */
    public void fieldGet(FieldEvent fe);
}
</pre>


<h2>3.3 Exception events</h2>

Exception related events are notified for classes which implement
a <code>alt.jiapi.event.ExceptionListener</code> interface.


<h2>3.4 Example 1</h2>

This example implements <code>MethodListener</code> interface,
registers itself to a <code>MethodEventProducer</code> and
launches a test class which is instrumented to fire method events.

<pre>
       1 package samples.example1;
       2 
       3 import alt.jiapi.InstrumentationContext;
       4 import alt.jiapi.InstrumentationDescriptor;
       5 import alt.jiapi.event.MethodEvent;
       6 import alt.jiapi.event.MethodEventProducer;
       7 import alt.jiapi.event.MethodListener;
       8 import alt.jiapi.util.Bootstrapper;
       9 
      10 public class Example1 implements MethodListener {
      11     public static void main(String args[]) throws Exception {
      12         new Example1();
      13     }
      14 
      15     public Example1() throws Exception {
      16         // Configure:
      17         InstrumentationContext ctx = new InstrumentationContext();
      18         InstrumentationDescriptor id = new InstrumentationDescriptor();
      19         id.addInclusionRule("test.*");
      20         ctx.addInstrumentationDescriptor(id);
      21 
      22         // Use event API:
      23         MethodEventProducer eventProducer = new MethodEventProducer(id);
      24         eventProducer.addMethodListener(this);
      25 
      26         // Launch:
      27         Bootstrapper.launch("test.Foo", null, ctx, 
      28                             getClass().getClassLoader());
      29     }
      30 
      31     public void methodEntered(MethodEvent event) {
      32         System.out.println("Method " + event.getClassName() + "." +
      33                            event.getMethodName() + " entered.");
      34     }
      35 
      36     public void methodExited(MethodEvent event) {
      37         System.out.println("Method " + event.getClassName() + "." +
      38                            event.getMethodName() + " exited.");
      39     }
      40 }

</pre>

The example is a <code>MethodListener</code>, it implements the required
callback methods <code>methodEntered</code> and <code>methodExited</code>.
In constructor the example configures itself, registers itself to
a <code>MethodEventProducer</code> and launches Jiapi in a just-in-time
bytecode weaving mode.

<p>
Lines 17-20 configures the context for the instrumentation. The context 
is configured so that all the classes whose fully qualified name matches 
<code>test.*</code> will be included in instrumentation.

<p>
In lines 23 and 24 a <code>MethodEventProducer</code> is created and
a listener is registered.

<p>
Lines 27 and 28 are used to launch a class <code>test.Foo</code> with
a given <code>InstrumentationContext</code>. 
<code>alt.jiapi.util.Bootstrapper</code> is a utility which loads the
given class with <code>alt.jiapi.util.InstrumentingClassLoader</code> and
calls loaded class' main method. <code>InstrumentingClassLoader</code>
first forms an in-memory representation for the class, triggers the
instrumentation process for it and then loads the modified class
into a Java virtual machine.

<p>
To run the example1 put jiapi.jar and all the required third-party
libraries (these are listed in README) to your CLASSPATH and then
bootstrap it:<br>
<code>
java alt.jiapi.util.Bootstrapper samples.example1.Example1
</code>
or more shortly:<br>
<code>
jiapi.sh samples.example1.Example1
</code>

<p>
You should see console prints when a methods are entered and exited.

<p>
Source code for the example can be found from src/samples/example1/.

<p>
<a href="framework.html">[prev]</a>
</body>
</html>