More progress on the basic distributed object facilities.

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

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

@@ -1,23 +1,130 @@
 //
-// $Id: DObject.java,v 1.4 2001/05/30 23:58:31 mdb Exp $
+// $Id: DObject.java,v 1.5 2001/06/01 05:01:52 mdb Exp $
 
 package com.threerings.cocktail.cher.dobj;
 
-import java.io.IOException;
-import java.io.DataInputStream;
-import java.io.DataOutputStream;
+import java.util.ArrayList;
 
+/**
+ * The distributed object forms the foundation of the cocktail system. All
+ * information shared among users of the system is done via distributed
+ * objects. A distributed object has a set of subscribers. These
+ * subscribers have access to the object or a proxy of the object and
+ * therefore have access to the data stored in the object's members at all
+ * times.
+ *
+ * <p> When there is any change to that data, initiated by one of the
+ * subscribers, an event is generated which is dispatched to all
+ * subscribers of the object, notifying them of that change and affecting
+ * that change to the copy of the object maintained at each client. In
+ * this way, both a respository of shared information and a mechanism for
+ * asynchronous notification are made available as a fundamental
+ * application building blocks.
+ *
+ * <p> To define what information is shared, an application creates a
+ * distributed object declaration which is much like a class declaration
+ * except that it is transformed into a proper derived class of
+ * <code>DObject</code> by a script. A declaration looks something like
+ * this:
+ *
+ * <pre>
+ * public dclass RoomObject
+ * {
+ *     public String description;
+ *     public int[] occupants;
+ * }
+ * </pre>
+ *
+ * which is converted into an actual Java class that looks like this:
+ *
+ * <pre>
+ * public class RoomObject extends DObject
+ * {
+ *     public String getDescription ()
+ *     {
+ *         // ...
+ *     }
+ *
+ *     public void setDescription (String description)
+ *     {
+ *         // ...
+ *     }
+ *
+ *     public int[] getOccupants ()
+ *     {
+ *         // ...
+ *     }
+ *
+ *     public void setOccupants (int[] occupants)
+ *     {
+ *         // ...
+ *     }
+ *
+ *     public void setOccupantsAt (int index, int value)
+ *     {
+ *         // ...
+ *     }
+ * }
+ * </pre>
+ *
+ * These method calls on the actual distributed object will result in the
+ * proper attribute change events being generated and dispatched.
+ */
 public class DObject
 {
-    public void writeTo (DataOutputStream out)
-        throws IOException
+    /**
+     * Constructs a new distributed object with the supplied object id.
+     * This should not be called directly, rather objects should be
+     * created via the distributed object manager.
+     *
+     * @see DObjectManager.createObject
+     */
+    public DObject (int oid)
     {
-        // nothing doing!
+        _oid = oid;
+        _subscribers = new ArrayList();
     }
 
-    public void readFrom (DataInputStream in)
-        throws IOException
+    /**
+     * Returns the object id of this object. All objects in the system
+     * have a unique object id.
+     */
+    public int getOid ()
     {
-        // nothing doing!
+        return _oid;
     }
+
+    /**
+     * Adds the supplied subscriber to the subscriber list for this
+     * object. This is done automatically when an object is requested for
+     * subscription by the distributed object manager, thus this function
+     * should not be called directly except in circumstances where one
+     * subscriber has already obtained a subscription to an object and
+     * wishes to include a subordinate subscriber in on the fun.
+     *
+     * <p> If the specified subscriber is already subscribed to this
+     * object, they will not be added to the list a second time.
+     */
+    public void addSubscriber (Subscriber subscriber)
+    {
+        if (!_subscribers.contains(subscriber)) {
+            _subscribers.add(subscriber);
+        }
+    }
+
+    /**
+     * Removes the specified subscriber from the subscriber list for this
+     * object. This is done automatically when a subscriber returns false
+     * from <code>handleEvent</code>, but can also be done directly
+     * through a call to <code>removeSubscriber</code>. If the specified
+     * subscriber is not currently on the list of subscribers for this
+     * object, nothing happens.
+     */
+    public void removeSubscriber (Subscriber subscriber)
+    {
+        _subscribers.remove(subscriber);
+    }
+
+    protected int _oid;
+    protected ArrayList _subscribers;
 }