Widened added setTargetOid().

git-svn-id: svn+ssh://src.earth.threerings.net/narya/trunk@4528 542714f4-19e9-0310-aa3c-eee0fc999fb1

src/java/com/threerings/presents/dobj/DEvent.java

@@ -24,10 +24,9 @@ package com.threerings.presents.dobj;
 import com.threerings.io.Streamable;
 
 /**
- * A distributed object event is dispatched whenever any modification is
+ * A distributed object event is dispatched whenever any modification is made to a distributed
- * made to a distributed object. It can also be dispatched purely for
+ * object. It can also be dispatched purely for notification purposes, without making any
- * notification purposes, without making any modifications to the object
+ * modifications to the object that defines the delivery group (the object's subscribers).
- * that defines the delivery group (the object's subscribers).
  */
 public abstract class DEvent implements Streamable
 {
@@ -39,8 +38,7 @@ public abstract class DEvent implements Streamable
     }
 
     /**
-     * Constructs a new distributed object event that pertains to the
+     * Constructs a new distributed object event that pertains to the specified distributed object.
-     * specified distributed object.
      */
     public DEvent (int targetOid)
     {
@@ -56,10 +54,9 @@ public abstract class DEvent implements Streamable
     }
 
     /**
-     * Some events are used only internally on the server and need not be
+     * Some events are used only internally on the server and need not be broadcast to subscribers,
-     * broadcast to subscribers, proxy or otherwise. Such events can
+     * proxy or otherwise. Such events can return true here and short-circuit the normal proxy
-     * return true here and short-circuit the normal proxy event dispatch
+     * event dispatch mechanism.
-     * mechanism.
      */
     public boolean isPrivate ()
     {
@@ -67,27 +64,24 @@ public abstract class DEvent implements Streamable
     }
 
     /**
-     * Applies the attribute modifications represented by this event to
+     * Applies the attribute modifications represented by this event to the specified target
-     * the specified target object. This is called by the distributed
+     * object. This is called by the distributed object manager in the course of dispatching events
-     * object manager in the course of dispatching events and should not
+     * and should not be called directly.
-     * be called directly.
      *
-     * @exception ObjectAccessException thrown if there is any problem
+     * @exception ObjectAccessException thrown if there is any problem applying the event to the
-     * applying the event to the object (invalid attribute, etc.).
+     * object (invalid attribute, etc.).
      *
-     * @return true if the object manager should go on to notify the
+     * @return true if the object manager should go on to notify the object's subscribers of this
-     * object's subscribers of this event, false if the event should be
+     * event, false if the event should be treated silently and the subscribers should not be
-     * treated silently and the subscribers should not be notified.
+     * notified.
      */
     public abstract boolean applyToObject (DObject target)
         throws ObjectAccessException;
 
     /**
-     * Returns the object id of the client that generated this event. If
+     * Returns the object id of the client that generated this event. If the event was generated by
-     * the event was generated by the server, the value returned will be
+     * the server, the value returned will be -1. This is not valid on the client, it will return
-     * -1. This is not valid on the client, it will return -1 for all
+     * -1 for all events there (it is primarily provided to allow for event-level access control).
-     * events there (it is primarily provided to allow for event-level
-     * access control).
      */
     public int getSourceOid ()
     {
@@ -95,9 +89,18 @@ public abstract class DEvent implements Streamable
     }
 
     /**
-     * Do not call this method. Sets the source oid of the client that
+     * Do not call this method. Sets the oid of the object on which this event operates. It is only
-     * generated this event. It is automatically called by the client
+     * used when rewriting events during object proxying.
-     * management code when a client forwards an event to the server.
+     */
+    public void setTargetOid (int targetOid)
+    {
+        _toid = targetOid;
+    }
+
+    /**
+     * Do not call this method. Sets the source oid of the client that generated this event. It is
+     * automatically called by the client management code when a client forwards an event to the
+     * server.
      */
     public void setSourceOid (int sourceOid)
     {
@@ -105,11 +108,9 @@ public abstract class DEvent implements Streamable
     }
 
     /**
-     * Events with associated listener interfaces should implement this
+     * Events with associated listener interfaces should implement this function and notify the
-     * function and notify the supplied listener if it implements their
+     * supplied listener if it implements their event listening interface. For example, the {@link
-     * event listening interface. For example, the {@link
+     * AttributeChangedEvent} will notify listeners that implement {@link AttributeChangeListener}.
-     * AttributeChangedEvent} will notify listeners that implement {@link
-     * AttributeChangeListener}.
      */
     protected void notifyListener (Object listener)
     {
@@ -129,9 +130,9 @@ public abstract class DEvent implements Streamable
     }
 
     /**
-     * This should be overridden by derived classes (which should be sure
+     * This should be overridden by derived classes (which should be sure to call
-     * to call <code>super.toString()</code>) to append the derived class
+     * <code>super.toString()</code>) to append the derived class specific event information to the
-     * specific event information to the string buffer.
+     * string buffer.
      */
     protected void toString (StringBuilder buf)
     {
@@ -145,12 +146,12 @@ public abstract class DEvent implements Streamable
     /** The oid of the client that generated this event. */
     protected transient int _soid = -1;
 
-    /** Used to differentiate between null meaning we haven't initialized
+    /** Used to differentiate between null meaning we haven't initialized our old value and null
-     * our old value and null being the actual old value. */
+     * being the actual old value. */
     protected static final Object UNSET_OLD_VALUE = new Object();
 
-    /** Used to differentiate between null meaning we haven't initialized
+    /** Used to differentiate between null meaning we haven't initialized our old entry and null
-     * our old entry and null being the actual old entry. */
+     * being the actual old entry. */
     protected static final DSet.Entry UNSET_OLD_ENTRY = new DSet.Entry() {
         public Comparable getKey () {
             return null;