Widening.

git-svn-id: svn+ssh://src.earth.threerings.net/vilya/trunk@320 c613c5cb-e716-0410-b11b-feb51c14d237

src/java/com/threerings/whirled/server/SceneManager.java

@@ -35,16 +35,15 @@ import com.threerings.whirled.server.WhirledServer;
 import com.threerings.whirled.util.UpdateList;
 
 /**
- * The scene manager extends the place manager and takes care of basic
+ * The scene manager extends the place manager and takes care of basic scene services. Presently
- * scene services. Presently that is little more than registering the
+ * that is little more than registering the scene manager with the scene registry so that the
- * scene manager with the scene registry so that the manager can be looked
+ * manager can be looked up by scene id in addition to place object id.
- * up by scene id in addition to place object id.
  */
 public class SceneManager extends PlaceManager
 {
     /**
-     * Returns the scene object (not the scene distributed object) being
+     * Returns the scene object (not the scene distributed object) being managed by this scene
-     * managed by this scene manager.
+     * manager.
      */
     public Scene getScene ()
     {
@@ -60,25 +59,21 @@ public class SceneManager extends PlaceManager
     }
 
     /**
-     * Called by the scene registry once the scene manager has been
+     * Called by the scene registry once the scene manager has been created (and initialized), but
-     * created (and initialized), but before it is started up.
+     * before it is started up.
      */
-    protected void setSceneData (Scene scene, UpdateList updates,
+    protected void setSceneData (Scene scene, UpdateList updates, SceneRegistry screg)
-                                 SceneRegistry screg)
     {
         _scene = scene;
         _screg = screg;
         _updates = updates;
 
-        // make sure the list and our version of the scene are in
+        // make sure the list and our version of the scene are in accordance
-        // accordance
         if (!_updates.validate(scene.getVersion())) {
-            Log.warning("Provided with invalid updates; flushing " +
+            Log.warning("Provided with invalid updates; flushing [where=" + where() +
-                        "[where=" + where() +
+                        ", sceneId=" + scene.getId() + ", version=" + scene.getVersion() + "].");
-                        ", sceneId=" + scene.getId() + "].");
+            // clear out the update list as it will not allow us to bring clients up to date with
-            // clear out the update list as it will not allow us to bring
+            // our current scene version; instead they'll have to download the whole thing
-            // clients up to date with our current scene version; instead
-            // they'll have to download the whole thing
             _updates = new UpdateList();
         }
 
@@ -87,26 +82,24 @@ public class SceneManager extends PlaceManager
     }
 
     /**
-     * A method that can be overridden by derived classes to perform
+     * A method that can be overridden by derived classes to perform initialization processing
-     * initialization processing after we receive our scene information
+     * after we receive our scene information but before we're started up (and hence registered as
-     * but before we're started up (and hence registered as an active
+     * an active place).
-     * place).
      */
     protected void gotSceneData ()
     {
     }
 
     /**
-     * We're fully ready to go, so now we register ourselves with the
+     * We're fully ready to go, so now we register ourselves with the scene registry which will
-     * scene registry which will make us available to the clients and
+     * make us available to the clients and system at large.
-     * system at large.
      */
     protected void didStartup ()
     {
         super.didStartup();
 
-        // Wait until us and all of our subclasses have completely finished
+        // Wait until us and all of our subclasses have completely finished running didStartup
-        // running didStartup prior to registering the scene as being ready.
+        // prior to registering the scene as being ready.
         PresentsServer.omgr.postRunnable(new Runnable() {
             public void run () {
                 _screg.sceneManagerDidStart(SceneManager.this);
@@ -126,18 +119,15 @@ public class SceneManager extends PlaceManager
     }
 
     /**
-     * When a modification is made to a scene, the scene manager should
+     * When a modification is made to a scene, the scene manager should create a SceneUpdate
-     * create a SceneUpdate instance and pass it to this method which will
+     * instance and pass it to this method which will update the in-memory scene, and apply and
-     * update the in-memory scene, and apply and record the update in the
+     * record the update in the scene repository.
-     * scene repository.
      *
-     * <p> This update will be stored persistently and provided (along
+     * <p> This update will be stored persistently and provided (along with any other accumulated
-     * with any other accumulated updates) to clients that later request
+     * updates) to clients that later request to enter the scene with an old version of the scene
-     * to enter the scene with an old version of the scene data. Updates
+     * data. Updates are not stored forever, but a sizable number of recent updates are stored so
-     * are not stored forever, but a sizable number of recent updates are
+     * that moderately current clients can apply incremental patches to their scenes rather than
-     * stored so that moderately current clients can apply incremental
+     * redownloading entire scenes when they change.
-     * patches to their scenes rather than redownloading entire scenes
-     * when they change.
      */
     protected void recordUpdate (final SceneUpdate update)
     {
@@ -168,8 +158,7 @@ public class SceneManager extends PlaceManager
     // documentation inherited
     public String where ()
     {
-        return _scene.getName() + " (" + super.where() + ":" +
+        return _scene.getName() + " (" + super.where() + ":" + _scene.getId() + ")";
-            _scene.getId() + ")";
     }
 
     // documentation inherited
@@ -179,16 +168,16 @@ public class SceneManager extends PlaceManager
         buf.append(", scene=").append(_scene);
     }
 
-    /** A reference to our scene implementation which provides a
+    /** A reference to our scene implementation which provides a meaningful interpretation of the
-     * meaningful interpretation of the data in the scene model. */
+     * data in the scene model. */
     protected Scene _scene;
 
-    /** A list of the updates tracked for this scene. These will be used
+    /** A list of the updates tracked for this scene. These will be used to attempt to bring
-     * to attempt to bring clients up to date efficiently if they request
+     * clients up to date efficiently if they request to enter our scene with old scene model
-     * to enter our scene with old scene model data. */
+     * data. */
     protected UpdateList _updates;
 
-    /** A reference to the scene registry so that we can call back to it
+    /** A reference to the scene registry so that we can call back to it when we're fully
-     * when we're fully initialized. */
+     * initialized. */
     protected SceneRegistry _screg;
 }