[RFA/JDWP] Event basics

[Keith Seitz <keiths at redhat dot com>]

Hi,

Okay, while I'm waiting on more difficult patches to be reviewed (more)
and approved, I thought I would toss out some easier ones.

This is the beginning of the package gnu.classpath.jdwp.event and
event.filter. These two base classes (okay, one of them is an interface)
lay the foundation for event notifications in the VM.

Events are requested by the debugger. All event notifications from the
VM to the back-end are supplied by event-specific classes. The Event
class in the patch is a base class for common event-related functions.

The debugger may specify that it is to be notified of certain events in
a specific thread, in a specific class, or any number of other criteria.

In the back-end, I have implemented this as filtering. So there are
filters for Threads, Classes, and so on. The interface IEventFilter
describes the basic operations of all filters.

Comments/questions/concerns?
Keith

ChangeLog
2005-06-22  Keith Seitz  <keiths@redhat.com>

	* gnu/classpath/jdwp/event/Event.java: New file.
	* gnu/classpath/jdwp/event/filters/IEventFilter.java: New file.

Index: gnu/classpath/jdwp/event/filters/IEventFilter.java
--- /dev/null
+++ gnu/classpath/jdwp/event/filters/IEventFilter.java
@@ -0,0 +1,65 @@
+/* IEventFilter.java -- an interface for event filters
+   Copyright (C) 2005 Free Software Foundation
+
+This file is part of GNU Classpath.
+
+GNU Classpath is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2, or (at your option)
+any later version.
+
+GNU Classpath is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with GNU Classpath; see the file COPYING.  If not, write to the
+Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+02111-1307 USA.
+
+Linking this library statically or dynamically with other modules is
+making a combined work based on this library.  Thus, the terms and
+conditions of the GNU General Public License cover the whole
+combination.
+
+As a special exception, the copyright holders of this library give you
+permission to link this library with independent modules to produce an
+executable, regardless of the license terms of these independent
+modules, and to copy and distribute the resulting executable under
+terms of your choice, provided that you also meet, for each linked
+terms of your choice, provided that you also meet, for each linked
+independent module, the terms and conditions of the license of that
+module.  An independent module is a module which is not derived from
+or based on this library.  If you modify this library, you may extend
+this exception to your version of the library, but you are not
+obligated to do so.  If you do not wish to do so, delete this
+exception statement from your version. */
+
+
+package gnu.classpath.jdwp.event.filters;
+
+import gnu.classpath.jdwp.event.Event;
+
+/**
+ * An interface for event filters. The debugger registers an event
+ * filter for a given event when it is interested in receiving
+ * notifications about that event from the VM.
+ *
+ * <p>Filters are attached to {@link gnu.classpath.jdwp.event.EventRequest}s
+ * in order to allow the debugger to specify that an event should be sent
+ * only when the filters for the event request all match.
+ *
+ * <p>No filters means "send all notifications".
+ *
+ * @author Keith Seitz  (keiths@redhat.com)
+ */
+public interface IEventFilter
+{
+  /**
+   * Does the given event match the filter?
+   *
+   * @param event  the <code>Event</code> to scrutinize
+   */
+  public boolean matches (Event event);
+}
Index: gnu/classpath/jdwp/event/Event.java
--- /dev/null
+++ gnu/classpath/jdwp/event/Event.java
@@ -0,0 +1,129 @@
+/* Event.java -- a base class for all event types
+   Copyright (C) 2005 Free Software Foundation
+
+This file is part of GNU Classpath.
+
+GNU Classpath is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2, or (at your option)
+any later version.
+
+GNU Classpath is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with GNU Classpath; see the file COPYING.  If not, write to the
+Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+02111-1307 USA.
+
+Linking this library statically or dynamically with other modules is
+making a combined work based on this library.  Thus, the terms and
+conditions of the GNU General Public License cover the whole
+combination.
+
+As a special exception, the copyright holders of this library give you
+permission to link this library with independent modules to produce an
+executable, regardless of the license terms of these independent
+modules, and to copy and distribute the resulting executable under
+terms of your choice, provided that you also meet, for each linked
+terms of your choice, provided that you also meet, for each linked
+independent module, the terms and conditions of the license of that
+module.  An independent module is a module which is not derived from
+or based on this library.  If you modify this library, you may extend
+this exception to your version of the library, but you are not
+obligated to do so.  If you do not wish to do so, delete this
+exception statement from your version. */
+
+
+package gnu.classpath.jdwp.event;
+
+import gnu.classpath.jdwp.JdwpConstants;
+import gnu.classpath.jdwp.transport.JdwpCommandPacket;
+import gnu.classpath.jdwp.transport.JdwpPacket;
+
+import java.io.ByteArrayOutputStream;
+import java.io.DataOutputStream;
+import java.io.IOException;
+
+/**
+ * This class is a base class for all VM->debugger event
+ * notifications.
+ *
+ * @author Keith Seitz  (keiths@redhat.com)
+ */
+public abstract class Event
+{
+  // The kind of event represented by this event
+  private byte _eventKind;
+
+  /**
+   * Constructs an <code>Event</code> of the given kind
+   *
+   * @param kind  the type of event
+   */
+  public Event (byte kind)
+  {
+    _eventKind = kind;
+  }
+
+  /**
+   * Returns the event type of this event
+   *
+   * @returns  the event kind
+   */
+  public byte getEventKind ()
+  {
+    return _eventKind;
+  }
+
+  /**
+   * Abstract function used by implementing classes to fill in the
+   * event-specific data. Note that request ID is automatically added
+   * by this class (since it appears in all event notifications).
+   *
+   * @param outStream  the stream to which to write data
+   */
+  protected abstract void _writeData (DataOutputStream outStream)
+    throws IOException;
+
+  /**
+   * Returns the filtering parameters for this event. For example,
+   * most events may be filtered by thread, so one of the parameters
+   * returned should be a <code>Thread</code>.
+   */
+  public abstract Object[] getParameters ();
+
+  /**
+   * Converts this event into to a JDWP packet
+   *
+   * @param  requestId  the request id that wanted this event (or 0)
+   * @returns a <code>JdwpPacket</code> of the events or <code>null</code>
+   */
+  public JdwpPacket toPacket (int requestId, byte suspendPolicy)
+  {
+    JdwpPacket pkt;
+    try
+      {
+	ByteArrayOutputStream data = new ByteArrayOutputStream ();
+	DataOutputStream outStream = new DataOutputStream (data);
+
+	outStream.writeByte (suspendPolicy);
+	outStream.writeInt (1);
+	outStream.writeByte (_eventKind);
+	outStream.writeInt (requestId);
+	_writeData (outStream);
+
+	pkt = new JdwpCommandPacket (JdwpConstants.CommandSet.Event.value,
+				     JdwpConstants.CommandSet.Event.Composite);
+	pkt.setData (data.toByteArray ());
+      }
+    catch (IOException ioe)
+      {
+	pkt = null;
+      }
+
+    return pkt;
+  }
+}