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/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);
 }