Mmm... comments and updates.

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

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

@@ -1,5 +1,5 @@
 //
-// $Id: DObject.java,v 1.5 2001/06/01 05:01:52 mdb Exp $
+// $Id: DObject.java,v 1.6 2001/06/01 05:17:16 mdb Exp $
 
 package com.threerings.cocktail.cher.dobj;
 
@@ -79,9 +79,10 @@ public class DObject
      *
      * @see DObjectManager.createObject
      */
-    public DObject (int oid)
+    public DObject (int oid, DObjectManager manager)
     {
         _oid = oid;
+        _mgr = manager;
         _subscribers = new ArrayList();
     }
 
@@ -126,5 +127,6 @@ public class DObject
     }
 
     protected int _oid;
+    protected DObjectManager _mgr;
     protected ArrayList _subscribers;
 }

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

@@ -1,5 +1,5 @@
 //
-// $Id: DObjectManager.java,v 1.1 2001/06/01 05:01:52 mdb Exp $
+// $Id: DObjectManager.java,v 1.2 2001/06/01 05:17:16 mdb Exp $
 
 package com.threerings.cocktail.cher.dobj;
 
@@ -14,9 +14,57 @@ package com.threerings.cocktail.cher.dobj;
  */
 public interface DObjectManager
 {
-    public void createObject (Class dclass, Subscriber sub);
+    /**
+     * Creates a distributed object instance of the supplied class and
+     * notifies the specified subscriber when it becomes available. This
+     * is the proper mechanism for constructing a new distributed object
+     * as it is the only way in which it can be properly registered with
+     * the dobj system.
+     *
+     * @param dclass The class object of the derived class of
+     * <code>DObject</code> (or <code>DObject.class</code> itself) that
+     * should be instantiated.
+     * @param target The subscriber to be notified when the object is
+     * created and available, or if there was a problem creating the
+     * object.
+     * @param subscribe If true, the subscriber will be subscribed to the
+     * object after creation; if false, it will merely be notified of it's
+     * availability but not added as a subscriber.
+     */
+    public void createObject (Class dclass, Subscriber target,
+                              boolean subscribe);
 
-    public void subscribeToObject (int oid, Subscriber sub);
+    /**
+     * Requests that the specified subscriber be subscribed to the object
+     * identified by the supplied object id. That subscriber will be
+     * notified when the object is available or if the subscription
+     * request failed.
+     *
+     * @param oid The object id of the distributed object to which
+     * subscription is desired.
+     * @param target The subscriber to be subscribed.
+     *
+     * @see Subscriber.objectAvailable
+     * @see Subscriber.requestFailed
+     */
+    public void subscribeToObject (int oid, Subscriber target);
 
-    public void fetchObject (int oid, Subscriber sub);
+    /**
+     * Fetches an up-to-date copy of the specified distributed object and
+     * makes it available to the subscriber for a one-time access. The
+     * subscriber will not be added to the object's subscriber list and
+     * will not be notified of updates to the object and the object
+     * represents a snapshot in time which, it should be acknowledged,
+     * could be out of date by the time it reaches the subscriber. If the
+     * object cannot be fetched for some reason, the subscriber will be
+     * notified via <code>requestFailed</code>.
+     *
+     * @param oid The object id of the distributed object of which a
+     * snapshot is desired.
+     * @param target The subscriber that will receive the snapshot.
+     *
+     * @see Subscriber.objectAvailable
+     * @see Subscriber.requestFailed
+     */
+    public void fetchObject (int oid, Subscriber target);
 }

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

@@ -1,5 +1,5 @@
 //
-// $Id: Subscriber.java,v 1.1 2001/06/01 05:01:52 mdb Exp $
+// $Id: Subscriber.java,v 1.2 2001/06/01 05:17:16 mdb Exp $
 
 package com.threerings.cocktail.cher.dobj;
 
@@ -27,14 +27,14 @@ public interface Subscriber
     public void objectAvailable (DObject object);
 
     /**
-     * Called when a subscription request has failed. The nature of the
-     * failure will be communicated via the supplied
+     * Called when a subscription or fetch request has failed. The nature
+     * of the failure will be communicated via the supplied
      * <code>ObjectAccessException</code>.
      *
      * @see DObjectManager.subscribeToObject
      * @see DObjectManager.fetchObject
      */
-    public void subscriptionFailed (ObjectAccessException cause);
+    public void requestFailed (ObjectAccessException cause);
 
     /**
      * Called when an event has been dispatched on an object. The event
@@ -44,8 +44,14 @@ public interface Subscriber
      * fetching an attribute upon receiving an attribute changed event
      * will provide the new value for the attribute.
      *
+     * <p> A subscriber should return true from <code>handleEvent</code>
+     * unless they wish their subscription to be terminated.
+     *
      * @param event The event dispatched on the object.
      * @param target The object on which the event was dispatched.
+     *
+     * @return true if the subscriber wishes to remain subscribed to the
+     * target object, false if they do not.
      */
-    public void handleEvent (DEvent event, DObject target);
+    public boolean handleEvent (DEvent event, DObject target);
 }