The amazing refactor forteen hundred billion: eliminated "locations",

portals will by dynamically created, combined display/runtime/editable
scenes into one, enhanced support for modifying scenes and distributing
updates to the clients, various other small stuff that should not be
sweated.


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

src/java/com/threerings/whirled/data/AuxModel.java

@@ -0,0 +1,18 @@
+//
+// $Id: AuxModel.java,v 1.1 2003/02/12 07:23:31 mdb Exp $
+
+package com.threerings.whirled.data;
+
+import com.threerings.io.Streamable;
+
+/**
+ * An interface that must be implemented by auxiliary scene models.
+ */
+public interface AuxModel extends Streamable, Cloneable
+{
+    /**
+     * Creates a clone of this auxiliary model.
+     */
+    public Object clone ()
+        throws CloneNotSupportedException;
+}

src/java/com/threerings/whirled/data/Scene.java

@@ -0,0 +1,57 @@
+//
+// $Id: Scene.java,v 1.8 2003/02/12 07:23:31 mdb Exp $
+
+package com.threerings.whirled.data;
+
+import com.threerings.crowd.data.PlaceConfig;
+
+/**
+ * This interface makes available basic scene information. At this basic
+ * level, not much information is available, but extensions to this
+ * interface begin to create a more comprehensive picture of a scene in a
+ * system built from the Whirled services.
+ */
+public interface Scene
+{
+    /**
+     * Returns the unique identifier for this scene.
+     */
+    public int getId ();
+
+    /**
+     * Returns the human readable name of this scene.
+     */
+    public String getName ();
+
+    /**
+     * Returns the version number of this scene.
+     */
+    public int getVersion ();
+
+    /**
+     * Returns the place config that can be used to determine which place
+     * controller instance should be used to display this scene as well as
+     * to obtain runtime configuration information.
+     */
+    public PlaceConfig getPlaceConfig ();
+
+    /**
+     * Sets this scene's unique identifier.
+     */
+    public void setId (int sceneId);
+
+    /**
+     * Sets the human readable name of this scene.
+     */
+    public void setName (String name);
+
+    /**
+     * Sets this scene's version number.
+     */
+    public void setVersion (int version);
+
+    /**
+     * Returns the scene model from which this scene was created.
+     */
+    public SceneModel getSceneModel ();
+}

src/java/com/threerings/whirled/data/SceneImpl.java

@@ -0,0 +1,94 @@
+//
+// $Id: SceneImpl.java,v 1.1 2003/02/12 07:23:31 mdb Exp $
+
+package com.threerings.whirled.data;
+
+import com.threerings.crowd.data.PlaceConfig;
+import com.threerings.whirled.data.SceneModel;
+
+/**
+ * An implementation of the {@link Scene} interface.
+ */
+public class SceneImpl implements Scene
+{
+    /**
+     * Creates an instance that will obtain data from the supplied scene
+     * model and place config.
+     */
+    public SceneImpl (SceneModel model, PlaceConfig config)
+    {
+        _model = model;
+        _config = config;
+    }
+
+    /**
+     * Instantiates a blank scene implementation. No place config will be
+     * associated with this scene.
+     */
+    public SceneImpl ()
+    {
+        _model = SceneModel.blankSceneModel();
+    }
+
+    // documentation inherited
+    public int getId ()
+    {
+        return _model.sceneId;
+    }
+
+    // documentation inherited
+    public String getName ()
+    {
+        return _model.name;
+    }
+
+    // documentation inherited
+    public int getVersion ()
+    {
+        return _model.version;
+    }
+
+    // documentation inherited
+    public PlaceConfig getPlaceConfig ()
+    {
+        return _config;
+    }
+
+    // documentation inherited from interface
+    public void setId (int sceneId)
+    {
+        _model.sceneId = sceneId;
+    }
+
+    // documentation inherited from interface
+    public void setName (String name)
+    {
+        _model.name = name;
+    }
+
+    // documentation inherited from interface
+    public void setVersion (int version)
+    {
+        _model.version = version;
+    }
+
+    // documentation inherited from interface
+    public SceneModel getSceneModel ()
+    {
+        return _model;
+    }
+
+    /**
+     * Generates a string representation of this instance.
+     */
+    public String toString ()
+    {
+        return "[model=" + _model + ", config=" + _config + "]";
+    }
+
+    /** A reference to our scene model. */
+    protected SceneModel _model;
+
+    /** A reference to our place configuration. */
+    protected PlaceConfig _config;
+}

src/java/com/threerings/whirled/data/SceneMarshaller.java

@@ -1,5 +1,5 @@
 //
-// $Id: SceneMarshaller.java,v 1.2 2002/08/20 19:38:15 mdb Exp $
+// $Id: SceneMarshaller.java,v 1.3 2003/02/12 07:23:31 mdb Exp $
 
 package com.threerings.whirled.data;
 
@@ -10,6 +10,7 @@ import com.threerings.presents.dobj.InvocationResponseEvent;
 import com.threerings.whirled.client.SceneService;
 import com.threerings.whirled.client.SceneService.SceneMoveListener;
 import com.threerings.whirled.data.SceneModel;
+import com.threerings.whirled.data.SceneUpdate;
 
 /**
  * Provides the implementation of the {@link SceneService} interface
@@ -17,10 +18,6 @@ import com.threerings.whirled.data.SceneModel;
  * on the server. Also provides an implementation of the response listener
  * interfaces that marshall the response arguments and deliver them back
  * to the requesting client.
- *
- * <p> Generated from <code>
- * $Id: SceneMarshaller.java,v 1.2 2002/08/20 19:38:15 mdb Exp $
- * </code>
  */
 public class SceneMarshaller extends InvocationMarshaller
     implements SceneService
@@ -41,15 +38,27 @@ public class SceneMarshaller extends InvocationMarshaller
                                new Object[] { new Integer(arg1), arg2 }));
         }
 
-        /** The method id used to dispatch {@link #moveSucceededPlusUpdate}
+        /** The method id used to dispatch {@link #moveSucceededWithUpdates}
          * responses. */
-        public static final int MOVE_SUCCEEDED_PLUS_UPDATE = 2;
+        public static final int MOVE_SUCCEEDED_WITH_UPDATES = 2;
 
         // documentation inherited from interface
-        public void moveSucceededPlusUpdate (int arg1, PlaceConfig arg2, SceneModel arg3)
+        public void moveSucceededWithUpdates (int arg1, PlaceConfig arg2, SceneUpdate[] arg3)
         {
             omgr.postEvent(new InvocationResponseEvent(
-                               callerOid, requestId, MOVE_SUCCEEDED_PLUS_UPDATE,
+                               callerOid, requestId, MOVE_SUCCEEDED_WITH_UPDATES,
+                               new Object[] { new Integer(arg1), arg2, arg3 }));
+        }
+
+        /** The method id used to dispatch {@link #moveSucceededWithScene}
+         * responses. */
+        public static final int MOVE_SUCCEEDED_WITH_SCENE = 3;
+
+        // documentation inherited from interface
+        public void moveSucceededWithScene (int arg1, PlaceConfig arg2, SceneModel arg3)
+        {
+            omgr.postEvent(new InvocationResponseEvent(
+                               callerOid, requestId, MOVE_SUCCEEDED_WITH_SCENE,
                                new Object[] { new Integer(arg1), arg2, arg3 }));
         }
 
@@ -62,8 +71,13 @@ public class SceneMarshaller extends InvocationMarshaller
                     ((Integer)args[0]).intValue(), (PlaceConfig)args[1]);
                 return;
 
-            case MOVE_SUCCEEDED_PLUS_UPDATE:
-                ((SceneMoveListener)listener).moveSucceededPlusUpdate(
+            case MOVE_SUCCEEDED_WITH_UPDATES:
+                ((SceneMoveListener)listener).moveSucceededWithUpdates(
+                    ((Integer)args[0]).intValue(), (PlaceConfig)args[1], (SceneUpdate[])args[2]);
+                return;
+
+            case MOVE_SUCCEEDED_WITH_SCENE:
+                ((SceneMoveListener)listener).moveSucceededWithScene(
                     ((Integer)args[0]).intValue(), (PlaceConfig)args[1], (SceneModel)args[2]);
                 return;
 
@@ -86,5 +100,5 @@ public class SceneMarshaller extends InvocationMarshaller
         });
     }
 
-    // Class file generated on 12:33:06 08/20/02.
+    // Generated on 14:44:07 02/08/03.
 }

src/java/com/threerings/whirled/data/SceneModel.java

@@ -1,18 +1,16 @@
 //
-// $Id: SceneModel.java,v 1.8 2002/07/23 05:54:52 mdb Exp $
+// $Id: SceneModel.java,v 1.9 2003/02/12 07:23:31 mdb Exp $
 
 package com.threerings.whirled.data;
 
-import com.samskivert.util.StringUtil;
+import com.samskivert.util.ArrayUtil;
 
 import com.threerings.io.SimpleStreamableObject;
 
 /**
  * The scene model is the bare bones representation of the data for a
  * scene in the Whirled system. From the scene model, one would create an
- * instance of {@link com.threerings.whirled.server.RuntimeScene}, {@link
- * com.threerings.whirled.client.DisplayScene} or {@link
- * com.threerings.whirled.tools.EditableScene}.
+ * instance of {@link Scene}.
  *
  * <p> The scene model is what is loaded from the scene repositories and
  * what is transmitted over the wire when communicating scenes from the
@@ -25,7 +23,7 @@ public class SceneModel extends SimpleStreamableObject
     public int sceneId;
 
     /** The human readable name of this scene. */
-    public String sceneName;
+    public String name;
 
     /** The version number of this scene. Versions are incremented
      * whenever modifications are made to a scene so that clients can
@@ -33,18 +31,15 @@ public class SceneModel extends SimpleStreamableObject
      * scene. */
     public int version;
 
-    /** The scene ids of the scenes that neighbor this scene. A neighbor
-     * is a scene that can be entered from this scene. */
-    public int[] neighborIds;
+    /** Auxiliary scene model information. */
+    public AuxModel[] auxModels = new AuxModel[0];
 
     /**
-     * Generates a string representation of this scene model.
+     * Adds the specified auxiliary model to this scene model.
      */
-    public String toString ()
+    public void addAuxModel (AuxModel auxModel)
     {
-        StringBuffer buf = new StringBuffer("[");
-        toString(buf);
-        return buf.append("]").toString();
+        auxModels = (AuxModel[])ArrayUtil.append(auxModels, auxModel);
     }
 
     // documentation inherited
@@ -52,22 +47,13 @@ public class SceneModel extends SimpleStreamableObject
         throws CloneNotSupportedException
     {
         SceneModel model = (SceneModel)super.clone();
-        model.neighborIds = (int[])neighborIds.clone();
+        model.auxModels = new AuxModel[auxModels.length];
+        for (int ii = 0; ii < auxModels.length; ii++) {
+            model.auxModels[ii] = (AuxModel)auxModels[ii].clone();
+        }
         return model;
     }
 
-    /**
-     * Derived classes override this to tack their <code>toString</code>
-     * data on to the string buffer.
-     */
-    protected void toString (StringBuffer buf)
-    {
-        buf.append("sceneId=").append(sceneId);
-        buf.append(", name=").append(sceneName);
-        buf.append(", version=").append(version);
-        buf.append(", neighborIds=").append(StringUtil.toString(neighborIds));
-    }
-
     /**
      * Creates and returns a blank scene model.
      */
@@ -84,8 +70,7 @@ public class SceneModel extends SimpleStreamableObject
     protected static void populateBlankSceneModel (SceneModel model)
     {
         model.sceneId = -1;
-        model.sceneName = "<blank>";
+        model.name = "<blank>";
         model.version = 0;
-        model.neighborIds = new int[0];
     }
 }

src/java/com/threerings/whirled/data/SceneUpdate.java

@@ -0,0 +1,114 @@
+//
+// $Id: SceneUpdate.java,v 1.1 2003/02/12 07:23:31 mdb Exp $
+
+package com.threerings.whirled.data;
+
+import com.threerings.io.Streamable;
+
+import com.threerings.whirled.Log;
+
+/**
+ * Used to encapsulate updates to scenes in such a manner that updates can
+ * be stored persistently and sent to clients to update their own local
+ * copies of scenes.
+ */
+public abstract class SceneUpdate
+    implements Streamable, Cloneable
+{
+    /**
+     * Creates a scene update that will operate on a scene with the
+     * specified target scene and version number.
+     *
+     * @param targetId the id of the scene on which we are to operate.
+     * @param targetVersion the version of the scene on which we are to
+     * operate.
+     */
+    public SceneUpdate (int targetId, int targetVersion)
+    {
+        _targetId = targetId;
+        _targetVersion = targetVersion;
+    }
+
+    /**
+     * Returns the scene id for which this update is appropriate.
+     */
+    public int getSceneId ()
+    {
+        return _targetId;
+    }
+
+    /**
+     * Returns the scene version for which this update is appropriate.
+     */
+    public int getSceneVersion ()
+    {
+        return _targetVersion;
+    }
+
+    /**
+     * Called to ensure that the scene is in the appropriate state prior
+     * to applying the update.
+     *
+     * @exception IllegalStateException thrown if the update cannot be
+     * applied to the scene because it is not in a valid state
+     * (appropriate previous updates were not applied, it's the wrong kind
+     * of scene, etc.).
+     */
+    public void validate (SceneModel model)
+        throws IllegalStateException
+    {
+        if (model.sceneId != _targetId) {
+            String errmsg = "Wrong target scene, expected id " +
+                _targetId + " got id " + model.sceneId;
+            throw new IllegalStateException(errmsg);
+        }
+        if (model.version != _targetVersion) {
+            String errmsg = "Target scene not proper version, expected " +
+                _targetVersion + " got " + model.version;
+            throw new IllegalStateException(errmsg);
+        }
+    }
+
+    /**
+     * Applies this update to the specified scene model. Derived classes
+     * will want to override this method and apply updates of their own,
+     * being sure to call <code>super.applyToScene</code>.
+     */
+    public void apply (SceneModel model)
+    {
+        // increment the version; disallowing integer overflow
+        model.version = Math.max(_targetVersion + 1, model.version);
+
+        // sanity check for the amazing two billion updates
+        if (model.version == _targetVersion) {
+            Log.warning("Egads! This scene has been updated two billion " +
+                        "times [model=" + model + ", update=" + this + "].");
+        }
+    }
+
+    /**
+     * Generates a string representation of this instance.
+     */
+    public String toString ()
+    {
+        StringBuffer buf = new StringBuffer("[");
+        toString(buf);
+        return buf.append("]").toString();
+    }
+
+    /**
+     * An extensible mechanism for generating a string representation of
+     * this instance.
+     */
+    protected void toString (StringBuffer buf)
+    {
+        buf.append("sceneId=").append(_targetId);
+        buf.append(", version=").append(_targetVersion);
+    }
+
+    /** The version number of the scene on which we operate. */
+    protected int _targetId;
+
+    /** The version number of the scene on which we operate. */
+    protected int _targetVersion;
+}