Styley stylopolis.

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

src/java/com/threerings/presents/client/ClientDObjectMgr.java

@@ -35,8 +35,25 @@ import com.samskivert.util.StringUtil;
 import com.samskivert.util.IntMap;
 import com.samskivert.util.Interval;
 
-import com.threerings.presents.dobj.*;
+import com.threerings.presents.dobj.CompoundEvent;
-import com.threerings.presents.net.*;
+import com.threerings.presents.dobj.DEvent;
+import com.threerings.presents.dobj.DObject;
+import com.threerings.presents.dobj.DObjectManager;
+import com.threerings.presents.dobj.ObjectAccessException;
+import com.threerings.presents.dobj.ObjectDestroyedEvent;
+import com.threerings.presents.dobj.Subscriber;
+
+import com.threerings.presents.net.BootstrapData;
+import com.threerings.presents.net.BootstrapNotification;
+import com.threerings.presents.net.DownstreamMessage;
+import com.threerings.presents.net.EventNotification;
+import com.threerings.presents.net.FailureResponse;
+import com.threerings.presents.net.ForwardEventRequest;
+import com.threerings.presents.net.ObjectResponse;
+import com.threerings.presents.net.PongResponse;
+import com.threerings.presents.net.SubscribeRequest;
+import com.threerings.presents.net.UnsubscribeRequest;
+import com.threerings.presents.net.UnsubscribeResponse;
 
 import static com.threerings.presents.Log.log;
 

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

@@ -28,7 +28,6 @@ import java.util.ConcurrentModificationException;
 import java.util.Iterator;
 
 import com.samskivert.util.ArrayUtil;
-import com.samskivert.util.StringUtil;
 
 import com.threerings.io.ObjectInputStream;
 import com.threerings.io.ObjectOutputStream;
@@ -49,6 +48,8 @@ import static com.threerings.presents.Log.log;
  * case of entry removal, only the key for the entry to be removed will be transmitted with the
  * removal event to save network bandwidth. Lastly, the object returned by {@link Entry#getKey}
  * must be a {@link Streamable} type.
+ *
+ * @param <E> the type of entry stored in this set.
  */
 public class DSet<E extends DSet.Entry>
     implements Iterable<E>, Streamable, Cloneable
@@ -197,10 +198,8 @@ public class DSet<E extends DSet.Entry>
     public Iterator<E> iterator ()
     {
         // the crazy sanity checks
-        if (_size < 0 ||_size > _entries.length ||
+        if (_size < 0 || _size > _entries.length || (_size > 0 && _entries[_size-1] == null)) {
-            (_size > 0 && _entries[_size-1] == null)) {
+            log.warning("DSet in a bad way", "size", _size, "entries", _entries);
-            log.warning("DSet in a bad way [size=" + _size +
-                        ", entries=" + StringUtil.toString(_entries) + "].");
             Thread.dumpStack();
         }
 
@@ -221,9 +220,8 @@ public class DSet<E extends DSet.Entry>
                     throw new ConcurrentModificationException();
                 }
                 if (_ssize != _size) {
-                    log.warning("Size changed during iteration [ssize=" + _ssize +
+                    log.warning("Size changed during iteration", "ssize", _ssize, "nsize", _size,
-                                ", nsize=" + _size +
+                                "entries", _entries);
-                                ", entsries=" + StringUtil.toString(_entries) + "].");
                     Thread.dumpStack();
                 }
             }
@@ -460,6 +458,7 @@ public class DSet<E extends DSet.Entry>
         }
     }
 
+    /** Used to search for keys. */
     protected static class KeyWrapper implements DSet.Entry
     {
         public KeyWrapper (Comparable key) {

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

@@ -29,6 +29,9 @@ import com.samskivert.util.StringUtil;
  * posted to the dobjmgr.
  *
  * @see DObjectManager#postEvent
+ *
+ * @param <T> the type of entry being handled by this event. This must match the type on the set
+ * that generated this event.
  */
 public class EntryAddedEvent<T extends DSet.Entry> extends NamedEvent
 {

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

@@ -29,6 +29,9 @@ import static com.threerings.presents.Log.log;
  * posted to the dobjmgr.
  *
  * @see DObjectManager#postEvent
+ *
+ * @param <T> the type of entry being handled by this event. This must match the type on the set
+ * that generated this event.
  */
 public class EntryRemovedEvent<T extends DSet.Entry> extends NamedEvent
 {

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

@@ -32,6 +32,9 @@ import static com.threerings.presents.Log.log;
  * constructed to request the update of an entry and posted to the dobjmgr.
  *
  * @see DObjectManager#postEvent
+ *
+ * @param <T> the type of entry being handled by this event. This must match the type on the set
+ * that generated this event.
  */
 public class EntryUpdatedEvent<T extends DSet.Entry> extends NamedEvent
 {

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

@@ -28,6 +28,9 @@ package com.threerings.presents.dobj;
  * <p> <b>NOTE:</b> This adapter will receive <em>all</em> Entry events from a DObject it's
  * listening to, so it should check that the event's name matches the field it's interested in
  * before acting on the event.
+ *
+ * @param <T> the type of entry being handled by this listener. This must match the type on the set
+ * that generates the events.
  */
 public class SetAdapter<T extends DSet.Entry> implements SetListener<T>
 {

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

@@ -30,6 +30,9 @@ package com.threerings.presents.dobj;
  * before acting on the event.
  *
  * @see DObject#addListener
+ *
+ * @param <T> the type of entry being handled by this listener. This must match the type on the set
+ * that generates the events.
  */
 public interface SetListener<T extends DSet.Entry> extends ChangeListener
 {

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

@@ -37,6 +37,8 @@ package com.threerings.presents.dobj;
  * @see AttributeChangeListener
  * @see SetListener
  * @see OidListListener
+ *
+ * @param <T> the type object being subscribed to.
  */
 public interface Subscriber<T extends DObject>
 {

src/java/com/threerings/presents/net/EventNotification.java

@@ -23,6 +23,9 @@ package com.threerings.presents.net;
 
 import com.threerings.presents.dobj.DEvent;
 
+/**
+ * Contains an event forwarded from the server.
+ */
 public class EventNotification extends DownstreamMessage
 {
     /**

src/java/com/threerings/presents/net/FailureResponse.java

@@ -21,6 +21,9 @@
 
 package com.threerings.presents.net;
 
+/**
+ * Communicates failure to subscribe to an object.
+ */
 public class FailureResponse extends DownstreamMessage
 {
     /**

src/java/com/threerings/presents/net/ForwardEventRequest.java

@@ -23,6 +23,9 @@ package com.threerings.presents.net;
 
 import com.threerings.presents.dobj.DEvent;
 
+/**
+ * Forwards an event to the server for dispatch.
+ */
 public class ForwardEventRequest extends UpstreamMessage
 {
     /**

src/java/com/threerings/presents/net/LogoffRequest.java

@@ -21,6 +21,9 @@
 
 package com.threerings.presents.net;
 
+/**
+ * Requests to end our session with the server.
+ */
 public class LogoffRequest extends UpstreamMessage
 {
     /**

src/java/com/threerings/presents/net/ObjectResponse.java

@@ -23,6 +23,11 @@ package com.threerings.presents.net;
 
 import com.threerings.presents.dobj.DObject;
 
+/**
+ * Contains a distributed object to which the client has subscribed.
+ *
+ * @param <T> the type of object delivered by the response.
+ */
 public class ObjectResponse<T extends DObject>
     extends DownstreamMessage
 {

src/java/com/threerings/presents/net/PingRequest.java

@@ -26,11 +26,13 @@ import java.io.IOException;
 import com.threerings.io.ObjectInputStream;
 import com.threerings.io.ObjectOutputStream;
 
+/**
+ * Let's the server know we're still alive.
+ */
 public class PingRequest extends UpstreamMessage
 {
-    /** The number of milliseconds of idle upstream that are allowed to
+    /** The number of milliseconds of idle upstream that are allowed to elapse before the client
-     * elapse before the client sends a ping message to the server to let
+     * sends a ping message to the server to let it know that we're still alive. */
-     * it know that we're still alive. */
     public static final long PING_INTERVAL = 60 * 1000L;
 
     /**
@@ -50,8 +52,8 @@ public class PingRequest extends UpstreamMessage
     }
 
     /**
-     * Returns a timestamp that was obtained when this packet was encoded
+     * Returns a timestamp that was obtained when this packet was encoded by the low-level
-     * by the low-level networking code.
+     * networking code.
      */
     public long getPackStamp ()
     {
@@ -59,8 +61,8 @@ public class PingRequest extends UpstreamMessage
     }
 
     /**
-     * Returns a timestamp that was obtained when this packet was decoded
+     * Returns a timestamp that was obtained when this packet was decoded by the low-level
-     * by the low-level networking code.
+     * networking code.
      */
     public long getUnpackStamp ()
     {
@@ -73,8 +75,8 @@ public class PingRequest extends UpstreamMessage
     public void writeObject (ObjectOutputStream out)
         throws IOException
     {
-        // grab a timestamp noting when we were encoded into a raw buffer
+        // grab a timestamp noting when we were encoded into a raw buffer for delivery over the
-        // for delivery over the network
+        // network
         _packStamp = System.currentTimeMillis();
 
         out.defaultWriteObject();
@@ -86,8 +88,8 @@ public class PingRequest extends UpstreamMessage
     public void readObject (ObjectInputStream in)
         throws IOException, ClassNotFoundException
     {
-        // grab a timestamp noting when we were decoded from a raw buffer
+        // grab a timestamp noting when we were decoded from a raw buffer after being received over
-        // after being received over the network
+        // the network
         _unpackStamp = System.currentTimeMillis();
 
         in.defaultReadObject();
@@ -114,9 +116,8 @@ public class PingRequest extends UpstreamMessage
     /** A time stamp obtained when we serialize this object. */
     protected transient long _packStamp;
 
-    /** A time stamp obtained when we unserialize this object (the intent
+    /** A time stamp obtained when we unserialize this object (the intent is to get a timestamp as
-     * is to get a timestamp as close as possible to when the packet was
+     * close as possible to when the packet was received on the network). */
-     * received on the network). */
     protected transient long _unpackStamp;
 
     /** The transport parameters. */

src/java/com/threerings/presents/net/PongResponse.java

@@ -28,6 +28,10 @@ import com.threerings.io.ObjectOutputStream;
 
 import static com.threerings.presents.Log.log;
 
+/**
+ * Let's the client know the server heard its ping (and that the server and connection are still
+ * alive).
+ */
 public class PongResponse extends DownstreamMessage
 {
     /**
@@ -39,20 +43,19 @@ public class PongResponse extends DownstreamMessage
     }
 
     /**
-     * Constructs a pong response which will use the supplied ping time to
+     * Constructs a pong response which will use the supplied ping time to establish the end-to-end
-     * establish the end-to-end processing delay introduced by the server.
+     * processing delay introduced by the server.
      */
     public PongResponse (long pingStamp, Transport transport)
     {
-        // save this for when we are serialized in preparation for
+        // save this for when we are serialized in preparation for delivery over the network
-        // delivery over the network
         _pingStamp = pingStamp;
         _transport = transport;
     }
 
     /**
-     * Returns the time at which this packet was packed for delivery in
+     * Returns the time at which this packet was packed for delivery in the time frame of the
-     * the time frame of the server that sent the packet.
+     * server that sent the packet.
      */
     public long getPackStamp ()
     {
@@ -60,9 +63,9 @@ public class PongResponse extends DownstreamMessage
     }
 
     /**
-     * Returns the number of milliseconds that elapsed between the time
+     * Returns the number of milliseconds that elapsed between the time that the ping which
-     * that the ping which instigated this pong was read from the network
+     * instigated this pong was read from the network and the time that this pong was written to
-     * and the time that this pong was written to the network.
+     * the network.
      */
     public int getProcessDelay ()
     {
@@ -70,8 +73,8 @@ public class PongResponse extends DownstreamMessage
     }
 
     /**
-     * Returns a timestamp that was obtained when this packet was decoded
+     * Returns a timestamp that was obtained when this packet was decoded by the low-level
-     * by the low-level networking code.
+     * networking code.
      */
     public long getUnpackStamp ()
     {
@@ -87,8 +90,7 @@ public class PongResponse extends DownstreamMessage
         // make a note of the time at which we were packed
         _packStamp = System.currentTimeMillis();
 
-        // the time spent between unpacking the ping and packing the pong
+        // the time spent between unpacking the ping and packing the pong is the processing delay
-        // is the processing delay
         if (_pingStamp == 0L) {
             log.warning("Pong response written that was not constructed " +
                         "with a valid ping stamp [rsp=" + this + "].");
@@ -106,8 +108,8 @@ public class PongResponse extends DownstreamMessage
     public void readObject (ObjectInputStream in)
         throws IOException, ClassNotFoundException
     {
-        // grab a timestamp noting when we were decoded from a raw buffer
+        // grab a timestamp noting when we were decoded from a raw buffer after being received over
-        // after being received over the network
+        // the network
         _unpackStamp = System.currentTimeMillis();
 
         in.defaultReadObject();
@@ -131,23 +133,19 @@ public class PongResponse extends DownstreamMessage
         return "[type=PONG, msgid=" + messageId + ", transport=" + _transport + "]";
     }
 
-    /** The ping unpack stamp provided at construct time to this pong
+    /** The ping unpack stamp provided at construct time to this pong response; only valid on the
-     * response; only valid on the sending process, not the receiving
+     * sending process, not the receiving process. */
-     * process. */
     protected transient long _pingStamp;
 
-    /** The timestamp obtained immediately before this packet was sent out
+    /** The timestamp obtained immediately before this packet was sent out over the network. */
-     * over the network. */
     protected long _packStamp;
 
-    /** The delay in milliseconds between the time that the ping request
+    /** The delay in milliseconds between the time that the ping request was read from the network
-     * was read from the network and the time the pong response was
+     * and the time the pong response was written to the network. */
-     * written to the network. */
     protected int _processDelay;
 
-    /** A time stamp obtained when we unserialize this object (the intent
+    /** A time stamp obtained when we unserialize this object (the intent is to get a timestamp as
-     * is to get a timestamp as close as possible to when the packet was
+     * close as possible to when the packet was received on the network). */
-     * received on the network). */
     protected transient long _unpackStamp;
 
     /** The transport parameters. */

src/java/com/threerings/presents/net/SubscribeRequest.java

@@ -21,6 +21,9 @@
 
 package com.threerings.presents.net;
 
+/**
+ * Requests to subscribe to a particular distributed object.
+ */
 public class SubscribeRequest extends UpstreamMessage
 {
     /**

src/java/com/threerings/presents/net/Transport.java

@@ -25,8 +25,8 @@ import com.samskivert.util.HashIntMap;
 
 /**
  * Message transport parameters.  These include the type of transport and the channel (used to
- * define independent streams for ordered transport), and may eventually include message
+ * define independent streams for ordered transport), and may eventually include message priority,
- * priority, etc.
+ * etc.
  */
 public class Transport
 {

src/java/com/threerings/presents/net/UnsubscribeRequest.java

@@ -21,6 +21,9 @@
 
 package com.threerings.presents.net;
 
+/**
+ * Requests to end a subscription to a particular distributed object.
+ */
 public class UnsubscribeRequest extends UpstreamMessage
 {
     /**

src/java/com/threerings/presents/net/UsernamePasswordCreds.java

@@ -23,6 +23,9 @@ package com.threerings.presents.net;
 
 import com.threerings.util.Name;
 
+/**
+ * Extends the basic credentials with a password.
+ */
 public class UsernamePasswordCreds extends Credentials
 {
     /**

src/java/com/threerings/presents/peer/server/PeerManager.java

@@ -1211,7 +1211,8 @@ public abstract class PeerManager
     protected ArrayIntSet _suboids = new ArrayIntSet();
 
     /** Contains a mapping of proxied objects to subscriber instances. */
-    protected Map<Tuple<String,Integer>,Tuple<Subscriber<?>,DObject>> _proxies = Maps.newHashMap();
+    protected Map<Tuple<String, Integer>, Tuple<Subscriber<?>, DObject>> _proxies =
+        Maps.newHashMap();
 
     /** Our stale cache observers. */
     protected Map<String, ObserverList<StaleCacheObserver>> _cacheobs = Maps.newHashMap();

src/java/com/threerings/presents/server/ClientManager.java

@@ -42,7 +42,10 @@ import com.threerings.presents.data.ClientObject;
 import com.threerings.presents.net.AuthRequest;
 import com.threerings.presents.net.AuthResponse;
 import com.threerings.presents.net.Credentials;
-import com.threerings.presents.server.net.*;
+import com.threerings.presents.server.net.AuthingConnection;
+import com.threerings.presents.server.net.Connection;
+import com.threerings.presents.server.net.ConnectionManager;
+import com.threerings.presents.server.net.ConnectionObserver;
 
 import static com.threerings.presents.Log.log;
 
@@ -323,7 +326,7 @@ public class ClientManager
     }
 
     /**
-     * Renames a currently connected client from <code>oldname</code> to <code>newname</code>
+     * Renames a currently connected client from <code>oldname</code> to <code>newname</code>.
      *
      * @return true if the client was found and renamed.
      */