Presents Distributed Object System

• Distributed Objects
• Event Listeners
• Distributed Collections
• Invocation Services
• Ant Tasks

A note to the reader: the Presents system is a complex one and though a great deal of code is provided in explaining the services it provides, it is not the intent that one should start from only these examples and build a working system. A better approach is to read through this documentation to come to an understanding of the concepts and mechanisms that define the system and then take a look at some working sample code which is provided in the tests directory of this distribution.

Distributed Objects

Clients cannot modify their proxy distributed objects directly, instead they make use of setter methods which package up the requested change into an event and send that event to the server for processing. After performing access control checks, the server will apply the event to the primary distributed object instance and then dispatch that event to all subscribed clients. Those clients (including the original change requesting client) then apply the event to their proxy copy of the object and in this way all clients maintain an up to date copy of the object's data.

Defining an object

    public class CageObject extends DObject
    {
        /** The number of monkeys in the cage. */
        public int monkeys;

        /** The name of the owner of this cage. */
        public String owner;
    }

We then run our class definition through a post-processor which turns it into the following:

    public class CageObject extends DObject
    {
        // AUTO-GENERATED: FIELDS START
        /** The field name of the monkeys field. */
        public static final String MONKEYS = "monkeys";

        /** The field name of the owner field. */
        public static final String OWNER = "owner";
        // AUTO-GENERATED: FIELDS END

        /** The number of monkeys in the cage. */
        public int monkeys;

        /** The name of the owner of this cage. */
        public String owner;

        // AUTO-GENERATED: METHODS START
        /**
         * Requests that the monkeys field be set to the
         * specified value. The local value will be updated immediately and an
         * event will be propagated through the system to notify all listeners
         * that the attribute did change. Proxied copies of this object (on
         * clients) will apply the value change when they received the
         * attribute changed notification.
         */
        public void setMonkeys (int value)
        {
            int ovalue = this.monkeys;
            requestAttributeChange(
                EVEN_BASE, new Integer(value), new Integer(ovalue));
            this.monkeys = value;
        }

        /**
         * Requests that the owner field be set to the
         * specified value. The local value will be updated immediately and an
         * event will be propagated through the system to notify all listeners
         * that the attribute did change. Proxied copies of this object (on
         * clients) will apply the value change when they received the
         * attribute changed notification.
         */
        public void setOwner (String value)
        {
            String ovalue = this.owner;
            requestAttributeChange(
                ODD_BASE, value, ovalue);
            this.owner = value;
        }
        // AUTO-GENERATED: METHODS END
    }

One may also notice that attribute change requests result in the new value of the attribute being immediately written to the local copy of the object. This is a convention that was decided upon after repeatedly running into trouble when users of the system would set a value in an object and immediately assume it held the new value rather than realizing that an event would have to propagate back from the server before the value was in fact updated. By setting the value immediately, these problems are avoided and the opposite assumption is almost never made. This is further justified by the fact that, in general, attribute changes never originate on a client but instead originate on the server after processing a request from the client (via the below documented invocation services) to do something application-specific that results in one or more attribute changes taking place.

See the section on Ant Tasks for information on how to configure and run this post-processor.

Creating an object

    public class ServerEntity implements Subscriber {
        public void init (DObjectManager omgr) {
            omgr.createObject(CageObject.class, this);
        }

        // inherited from interface Subscriber
        public void objectAvailable (DObject object) {
            // yay! we created our object
            _object = (CageObject)object;
        }

        // inherited from interface Subscriber
        public void requestFailed (int oid, ObjectAccessException cause) {
            // oh the humanity, we failed to create our object; in
            // general this would only happen if we did something silly like
            // passed in a DObject class that didn't extend DObject
        }

        protected CageObject _object;
    }

Subscribing to an object

The client obtains a proxy of the object by a process called subscription, which is accomplished via {@link com.threerings.presents.dobj.DObjectManager}.subscribeToObject():

    public class ObjectUser implements Subscriber {
        public void init (Client client, int objectId) {
            client.getDObjectManager().subscribeToObject(objectId, this);
        }

        // inherited from interface Subscriber
        public void objectAvailable (DObject object) {
            // yay! we got our object
            _object = (CageObject)object;
        }

        // inherited from interface Subscriber
        public void requestFailed (int oid, ObjectAccessException cause) {
            // oh the humanity, we failed to subscribe
        }

        protected CageObject _object;
    }

Later a client would relinquish its subscription to the object using a similar mechanism:

    public class ObjectUser implements Subscriber {
        // ...
        public void shutdown (Client client) {
            client.getDObjectManager().unsubscribeFromObject(
                _object.getOid(), this);
            _object = null;
        }
        // ...
    }

    public class ObjectUser implements Subscriber {
        public void init (Client client, int objectId) {
            _safesub = new SafeSubscriber(objectId, this);
            _safesub.subcribe(client.getDObjectManager());
        }

        // inherited from interface Subscriber
        public void objectAvailable (DObject object) {
            // yay! we got our object
            _object = (CageObject)object;
        }

        // inherited from interface Subscriber
        public void requestFailed (int oid, ObjectAccessException cause) {
            // oh the humanity, we failed to subscribe
        }

        public void shutdown (Client client) {
            _safesub.unsubscribe(client.getDObjectManager());
            _object = null;
        }

        protected SafeSubscriber _safesub;
        protected CageObject _object;
    }

Event Listeners

The basic listener is the {@link com.threerings.presents.dobj.AttributeChangeListener} which is informed of all simple attribute changes (setting a primitive field to a new value is called an attribute change). We return to our trusty example:

    public class ObjectUser
        implements Subscriber, AttributeChangeListener {
        // ...
        public void init (Client client, int objectId) {
            _safesub = new SafeSubscriber(_subscriber, objectId);
            _safesub.subcribe(client.getDObjectManager());
        }

        // inherited from interface Subscriber
        public void objectAvailable (DObject object) {
            // yay! we got our object
            _object = (CageObject)object;
            _object.addListener(this);
        }

        // inherited from interface Subscriber
        public void requestFailed (int oid, ObjectAccessException cause) {
            // oh the humanity, we failed to subscribe
        }

        // inherited from interface AttributeChangeListener
        public void attributeChanged (AttributeChangedEvent event)
        {
            System.out.println("Wow! The " + event.getName() +
                               " field changed to " + event.getValue() + ".");
        }

        public void shutdown (Client client) {
            _safesub.unsubscribe(client.getDObjectManager());
            if (_object != null) {
                 // removing our listener not necessary as we are
                 // unsubscribing, but it's a good habit to develop as
                 // frequently listeners will come and go during the
                 // lifetime of an object subscription
                _object.removeListener(this);
                _object = null;
            }
        }

        protected SafeSubscriber _safesub;
        protected CageObject _object;
    }

It is useful to note that listeners are notified of a changed attribute after the change has been applied to the object. The previous value of the attribute is available through the {@link com.threerings.presents.dobj.AttributeChangedEvent#getOldValue} method, though in spite of many years of experience using this system in a variety of circumstances, we have rarely found that we cared to know the previous value.

Distributed collections

Distributed Arrays
Arrays of primitive types can be used in a distributed object and the system will detect their use and provide a mechanism for updating the entire array and an additional mechanism for updating a single element at a time:

    public class ChessObject extends DObject
    {
        // AUTO-GENERATED: FIELDS START
        /** The field name of the state field. */
        public static final String STATE = "state";
        // AUTO-GENERATED: FIELDS END

        /** Used to track our board state. */
        public int[] state;

        // AUTO-GENERATED: METHODS START
        /**
         * Requests that the state field be set to the
         * specified value. The local value will be updated immediately and an
         * event will be propagated through the system to notify all listeners
         * that the attribute did change. Proxied copies of this object (on
         * clients) will apply the value change when they received the
         * attribute changed notification.
         */
        public void setState (int[] value)
        {
            int[] ovalue = this.state;
            requestAttributeChange(
                STATE, value, ovalue);
            this.state = (value == null) ? null : (int[])value.clone();
        }

        /**
         * Requests that the indexth element of
         * state field be set to the specified value.
         * The local value will be updated immediately and an event will be
         * propagated through the system to notify all listeners that the
         * attribute did change. Proxied copies of this object (on clients)
         * will apply the value change when they received the attribute
         * changed notification.
         */
        public void setStateAt (int value, int index)
        {
            int ovalue = this.state[index];
            requestElementUpdate(
                STATE, index, new Integer(value), new Integer(ovalue));
            this.state[index] = value;
        }
        // AUTO-GENERATED: METHODS END
    }

Note that distributed arrays are not automatically resized. If a request is made to update the element at index 9 of an array, the array must be of at least size 10 or an array index out of bounds exception will be thrown (as should be evident from inspecting the code above). For more dynamic collections of objects, see the documentation below about distributed sets.

This mechanism is not actually limited to arrays of primitive types. It also works for arrays of objects that implement the {@link com.threerings.io.Streamable} interface which is documented next.

Streamable and its good friend SimpleStreamableObject
The {@link com.threerings.io.Streamable} interface is used to mark objects that can be sent over the network by using them in distributed object fields by using arrays of such objects as a field. This interface functions in much the same way that {@link java.io.Serializable} does in that it simply marks the class and an underlying mechanism uses reflection to actually marshall and unmarshall the object on the network. In fact, all non-transient fields of a streamable object are included during the marhsalling process. Here's an example:

    public class Player implements Streamable
    {
        /** This player's name. */
        public String name;

        /** This player's rating. */
        public int rating;
    }

    public class ChessObject extends DObject
    {
        /** A record for each player in the game. */
        public Player[] players;
    }

It should be pointed out that streamable objects sent over the network are sent in their entirety. No mechanism is provided for updating just a single field in a streamable instance both because that would increase the complexity of the system tremendously and because it is generally not very useful. If conservation of bandwidth is of extreme importance, special {@link com.threerings.presents.dobj.DEvent} derived classes can be created to transmit precisely what is desired and nothing more. Doing so is beyond the scope of this introduction, but will hopefully be covered in an additional tutorial.

The {@link com.threerings.io.SimpleStreamableObject} class is a convenient way to create a simple record like the Player record above that implements Streamable and provides a default implementation of toString() that uses reflection to print out the actual values of the fields in the object (a boon when logging and debugging).

Distributed Sets
In developing a distributed system, one frequently encounters situations where one wants distributed collection of objects where order is generally not important but the ability to fluidly add and remove elements is. For such occasions we provide the distributed set or {@link com.threerings.presents.dobj.DSet}.

A DSet contains entries (called entries rather than elements to avoid confusion with array "element updating") which must implement the {@link com.threerings.presents.dobj.DSet.Entry} interface. This automatically makes them {@link com.threerings.io.Streamable} and requires that they provide a {@link java.lang.Comparable} key which is used to distinguish them from other entries in the set (and look them up via an efficient binary search).

When using a DSet one is provided with three new operations: addToFoo(), updateFoo() and removeFromFoo(). Once again an example is in order:

    public class Monkey implements DSet.Entry
    {
        /** The monkey's name. */
        public String name;

        /** The monkey's age. */
        public int age;

        // documentation inherited from interface DSet.Entry
        public Comparable getKey ()
        {
            return name;
        }
    }

    public class CageObject extends DObject
    {
        // AUTO-GENERATED: FIELDS START
        /** The field name of the monkeys field. */
        public static final String MONKEYS = "monkeys";
        // AUTO-GENERATED: FIELDS END

        /** A collection of monkeys. */
        public DSet monkeys;

        // AUTO-GENERATED: METHODS START
        /**
         * Requests that the specified entry be added to the
         * monkeys set.
         */
        public void addToMonkeys (DSet.Entry elem)
        {
            requestEntryAdd(MONKEYS, monkeys, elem);
        }

        /**
         * Requests that the entry matching the supplied key be removed from
         * the monkeys set.
         */
        public void removeFromMonkeys (Comparable key)
        {
            requestEntryRemove(MONKEYS, monkeys, key);
        }

        /**
         * Requests that the specified entry be updated in the
         * monkeys set.
         */
        public void updateMonkeys (DSet.Entry elem)
        {
            requestEntryUpdate(MONKEYS, monkeys, elem);
        }

        /**
         * Requests that the monkeys field be set to the
         * specified value.
         */
        public void setMonkeys (DSet value)
        {
            requestAttributeChange(MONKEYS, value, this.monkeys);
            this.monkeys = (value == null) ? null : (DSet)value.clone();
        }
        // AUTO-GENERATED: METHODS END
    }

In conjunction with the DSet there exists the {@link com.threerings.presents.dobj.SetListener} which is notified when changes are made to a distributed set. This functions in the same was as the previously documented listeners, so I will refrain from boring you with yet more sample code.

Invocation Services

Ant Tasks