Much work on generalizing the notion of message "transport" and

allowing the use of annotations to customize transport for 
DObject fields and service/receiver methods.


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

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

@@ -21,14 +21,12 @@
 
 package com.threerings.presents.net;
 
-import com.threerings.io.SimpleStreamableObject;
-
 /**
  * This class encapsulates a message in the distributed object protocol
  * that flows from the server to the client. Downstream messages include
  * object subscription, event forwarding and session management.
  */
-public abstract class DownstreamMessage extends SimpleStreamableObject
+public abstract class DownstreamMessage extends Message
 {
     /**
      * The message id of the upstream message with which this downstream
@@ -37,12 +35,6 @@ public abstract class DownstreamMessage extends SimpleStreamableObject
      */
     public short messageId = -1;
 
-    /**
-     * When sending, this acts as a hint that the message may be transmitted as a datagram.
-     * When receiving, it indicates that the message was received as a datagram.
-     */
-    public transient boolean datagram;
-
     /**
      * Generates a string representation of this instance.
      */

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

@@ -46,6 +46,19 @@ public class EventNotification extends DownstreamMessage
         return _event;
     }
 
+    @Override // documentation inherited
+    public void setTransport (Transport transport)
+    {
+        // the event handles the transport
+        _event.setTransport(transport);
+    }
+
+    @Override // documentation inherited
+    public Transport getTransport ()
+    {
+        return _event.getTransport();
+    }
+
     public String toString ()
     {
         return "[type=EVT, evt=" + _event + "]";

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

@@ -49,6 +49,19 @@ public class ForwardEventRequest extends UpstreamMessage
         return _event;
     }
 
+    @Override // documentation inherited
+    public void setTransport (Transport transport)
+    {
+        // the event handles the transport
+        _event.setTransport(transport);
+    }
+
+    @Override // documentation inherited
+    public Transport getTransport ()
+    {
+        return _event.getTransport();
+    }
+
     public String toString ()
     {
         return "[type=FWD, evt=" + _event + "]";

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

@@ -0,0 +1,50 @@
+//
+// $Id: DownstreamMessage.java 5090 2008-05-13 21:12:39Z andrzej $
+//
+// Narya library - tools for developing networked games
+// Copyright (C) 2002-2007 Three Rings Design, Inc., All Rights Reserved
+// http://www.threerings.net/code/narya/
+//
+// This library is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License as published
+// by the Free Software Foundation; either version 2.1 of the License, or
+// (at your option) any later version.
+//
+// This library 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
+// Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+package com.threerings.presents.net;
+
+import com.threerings.io.SimpleStreamableObject;
+
+/**
+ * The superclass of {@link UpstreamMessage} and {@link DownstreamMessage}.
+ */
+public abstract class Message extends SimpleStreamableObject
+{
+    /**
+     * Sets the message transport parameters.  For messages received over the network, these
+     * describe the mode of transport over which the message was received.  When sending messages,
+     * they act as a hint as to the type of transport desired.  Calling this method may have no
+     * effect, depending on whether non-default modes of transport are supported for this message
+     * type.
+     */
+    public void setTransport (Transport transport)
+    {
+        // no-op by default
+    }
+
+    /**
+     * Returns the message transport parameters.
+     */
+    public Transport getTransport ()
+    {
+        return Transport.DEFAULT;
+    }
+}

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

@@ -41,6 +41,14 @@ public class PingRequest extends UpstreamMessage
         super();
     }
 
+    /**
+     * Creates a new ping request using the specified transport.
+     */
+    public PingRequest (Transport transport)
+    {
+        _transport = transport;
+    }
+
     /**
      * Returns a timestamp that was obtained when this packet was encoded
      * by the low-level networking code.
@@ -85,9 +93,21 @@ public class PingRequest extends UpstreamMessage
         in.defaultReadObject();
     }
 
+    @Override // documentation inherited
+    public void setTransport (Transport transport)
+    {
+        _transport = transport;
+    }
+
+    @Override // documentation inherited
+    public Transport getTransport ()
+    {
+        return _transport;
+    }
+
     public String toString ()
     {
-        return "[type=PING, msgid=" + messageId + "]";
+        return "[type=PING, msgid=" + messageId + ", transport=" + _transport + "]";
     }
 
     /** A time stamp obtained when we serialize this object. */
@@ -97,4 +117,7 @@ public class PingRequest extends UpstreamMessage
      * is to get a timestamp as close as possible to when the packet was
      * received on the network). */
     protected transient long _unpackStamp;
+
+    /** The transport parameters. */
+    protected transient Transport _transport = Transport.DEFAULT;
 }

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

@@ -42,11 +42,12 @@ public class PongResponse extends DownstreamMessage
      * Constructs a pong response which will use the supplied ping time to
      * establish the end-to-end processing delay introduced by the server.
      */
-    public PongResponse (long pingStamp)
+    public PongResponse (long pingStamp, Transport transport)
     {
         // save this for when we are serialized in preparation for
         // delivery over the network
         _pingStamp = pingStamp;
+        _transport = transport;
     }
 
     /**
@@ -112,9 +113,21 @@ public class PongResponse extends DownstreamMessage
         in.defaultReadObject();
     }
 
+    @Override // documentation inherited
+    public void setTransport (Transport transport)
+    {
+        _transport = transport;
+    }
+
+    @Override // documentation inherited
+    public Transport getTransport ()
+    {
+        return _transport;
+    }
+
     public String toString ()
     {
-        return "[type=PONG, msgid=" + messageId + "]";
+        return "[type=PONG, msgid=" + messageId + ", transport=" + _transport + "]";
     }
 
     /** The ping unpack stamp provided at construct time to this pong
@@ -135,4 +148,7 @@ public class PongResponse extends DownstreamMessage
      * is to get a timestamp as close as possible to when the packet was
      * received on the network). */
     protected transient long _unpackStamp;
+
+    /** The transport parameters. */
+    protected transient Transport _transport = Transport.DEFAULT;
 }

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

@@ -0,0 +1,256 @@
+//
+// $Id$
+//
+// Narya library - tools for developing networked games
+// Copyright (C) 2002-2008 Three Rings Design, Inc., All Rights Reserved
+// http://www.threerings.net/code/narya/
+//
+// This library is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License as published
+// by the Free Software Foundation; either version 2.1 of the License, or
+// (at your option) any later version.
+//
+// This library 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
+// Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+package com.threerings.presents.net;
+
+import java.util.EnumMap;
+
+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
+ * priority, etc.
+ */
+public class Transport
+{
+    /**
+     * The available types of transport.
+     */
+    public enum Type
+    {
+        /**
+         * Messages are neither guaranteed to arrive nor, if they do arrive, to arrive in order
+         * and without duplicates.  Functionally identical to UDP.
+         */
+        UNRELIABLE_UNORDERED(false, false) {
+            public Type combine (Type other) {
+                return other; // we defer to all
+            }
+        },
+
+        /**
+         * Messages are not guaranteed to arrive, but if they do arrive, then they will arrive in
+         * order and without duplicates.  In other words, out-of-order packets will be dropped.
+         */
+        UNRELIABLE_ORDERED(false, true) {
+            public Type combine (Type other) {
+                return other.isReliable() ? RELIABLE_ORDERED : this;
+            }
+        },
+
+        /**
+         * Messages are guaranteed to arrive eventually, but they are not guaranteed to arrive in
+         * order.
+         */
+        RELIABLE_UNORDERED(true, false) {
+            public Type combine (Type other) {
+                return other.isOrdered() ? RELIABLE_ORDERED : this;
+            }
+        },
+
+        /**
+         * Messages are guaranteed to arrive, and will arrive in the order in which they are sent.
+         * Functionally identical to TCP.
+         */
+        RELIABLE_ORDERED(true, true) {
+            public Type combine (Type other) {
+                return this; // we override all
+            }
+        };
+
+        /**
+         * Checks whether this transport type guarantees that messages will be delivered.
+         */
+        public boolean isReliable ()
+        {
+            return _reliable;
+        }
+
+        /**
+         * Checks whether this transport type guarantees that messages will be received in the
+         * order in which they were sent, if they are received at all.
+         */
+        public boolean isOrdered ()
+        {
+            return _ordered;
+        }
+
+        /**
+         * Returns a transport type that combines the requirements of this type with those of the
+         * specified other type.
+         */
+        public abstract Type combine (Type other);
+
+        Type (boolean reliable, boolean ordered)
+        {
+            _reliable = reliable;
+            _ordered = ordered;
+        }
+
+        protected boolean _reliable, _ordered;
+    }
+
+    /** The unreliable/unordered mode of transport. */
+    public static final Transport UNRELIABLE_UNORDERED = getInstance(Type.UNRELIABLE_UNORDERED);
+
+    /** The unreliable/ordered mode on the default channel. */
+    public static final Transport UNRELIABLE_ORDERED = getInstance(Type.UNRELIABLE_ORDERED, 0);
+
+    /** The reliable/unordered mode. */
+    public static final Transport RELIABLE_UNORDERED = getInstance(Type.RELIABLE_UNORDERED);
+
+    /** The reliable/ordered mode on the default channel. */
+    public static final Transport RELIABLE_ORDERED = getInstance(Type.RELIABLE_ORDERED, 0);
+
+    /** The default mode of transport. */
+    public static final Transport DEFAULT = RELIABLE_ORDERED;
+
+    /**
+     * Returns the shared instance with the specified parameters.
+     */
+    public static Transport getInstance (Type type)
+    {
+        return getInstance(type, 0);
+    }
+
+    /**
+     * Returns the shared instance with the specified parameters.
+     */
+    public static Transport getInstance (Type type, int channel)
+    {
+        // were there more parameters in transport objects, it would be better to have a single map
+        // of instances and use Transport objects as keys (as in examples of the flyweight
+        // pattern).  however, doing it this way avoids the need to create a new object on lookup
+        if (_unordered == null) {
+            _unordered = new EnumMap<Type, Transport>(Type.class);
+            _ordered = new EnumMap<Type, HashIntMap<Transport>>(Type.class);
+        }
+
+        // for unordered transport, we map on the type alone
+        if (!type.isOrdered()) {
+            Transport instance = _unordered.get(type);
+            if (instance == null) {
+                _unordered.put(type, instance = new Transport(type));
+            }
+            return instance;
+        }
+
+        // for ordered transport, we map on the type and channel
+        HashIntMap<Transport> instances = _ordered.get(type);
+        if (instances == null) {
+            _ordered.put(type, instances = new HashIntMap<Transport>());
+        }
+        Transport instance = instances.get(channel);
+        if (instance == null) {
+            instances.put(channel, instance = new Transport(type, channel));
+        }
+        return instance;
+    }
+
+    /**
+     * Returns the type of transport.
+     */
+    public Type getType ()
+    {
+        return _type;
+    }
+
+    /**
+     * Returns the transport channel.
+     */
+    public int getChannel ()
+    {
+        return _channel;
+    }
+
+    /**
+     * Checks whether this transport guarantees that messages will be delivered.
+     */
+    public boolean isReliable ()
+    {
+        return _type.isReliable();
+    }
+
+    /**
+     * Checks whether this transport guarantees that messages will be received in the order in
+     * which they were sent, if they are received at all.
+     */
+    public boolean isOrdered ()
+    {
+        return _type.isOrdered();
+    }
+
+    /**
+     * Returns a transport that satisfies the requirements of this and the specified other
+     * transport.
+     */
+    public Transport combine (Transport other)
+    {
+        // if the channels are different, we fall back to the default channel
+        return getInstance(
+            _type.combine(other._type),
+            (_channel == other._channel) ? _channel : 0);
+    }
+
+    @Override // documentation inherited
+    public int hashCode ()
+    {
+        return 31*_type.hashCode() + _channel;
+    }
+
+    @Override // documentation inherited
+    public boolean equals (Object other)
+    {
+        Transport otrans;
+        return other instanceof Transport && (otrans = (Transport)other)._type == _type &&
+            otrans._channel == _channel;
+    }
+
+    @Override // documentation inherited
+    public String toString ()
+    {
+        return "[type=" + _type + ", channel=" + _channel + "]";
+    }
+
+    protected Transport (Type type)
+    {
+        this(type, 0);
+    }
+
+    protected Transport (Type type, int channel)
+    {
+        _type = type;
+        _channel = channel;
+    }
+
+    /** The type of transport. */
+    protected Type _type;
+
+    /** The transport channel. */
+    protected int _channel;
+
+    /** Unordered instances mapped by type. */
+    protected static EnumMap<Type, Transport> _unordered;
+
+    /** Ordered instances mapped by type and channel. */
+    protected static EnumMap<Type, HashIntMap<Transport>> _ordered;
+}

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

@@ -21,14 +21,12 @@
 
 package com.threerings.presents.net;
 
-import com.threerings.io.SimpleStreamableObject;
-
 /**
  * This class encapsulates a message in the distributed object protocol
  * that flows from the client to the server.  Upstream messages include
  * object subscription, event forwarding and session management.
  */
-public abstract class UpstreamMessage extends SimpleStreamableObject
+public abstract class UpstreamMessage extends Message
 {
     /**
      * This is a unique (within the context of a reasonable period of
@@ -41,12 +39,6 @@ public abstract class UpstreamMessage extends SimpleStreamableObject
     /** A timestamp indicating when this upstream message was received. */
     public transient long received;
 
-    /**
-     * When sending, this acts as a hint that the message may be transmitted as a datagram.
-     * When receiving, it indicates that the message was received as a datagram.
-     */
-    public transient boolean datagram;
-
     /**
      * Each upstream message derived class must provide a zero argument
      * constructor so that it can be unserialized when read from the