com.threerings.presents.dobj
Class DEvent

java.lang.Object
  com.threerings.presents.dobj.DEvent

All Implemented Interfaces:

Streamable

Direct Known Subclasses:

CompoundEvent, InvocationNotificationEvent, InvocationRequestEvent, InvocationResponseEvent, NamedEvent, ObjectDestroyedEvent, PresentsDObjectMgr.AccessObjectEvent

public abstract class DEvent
extends Object
implements Streamable

A distributed object event is dispatched whenever any modification is made to a distributed object. It can also be dispatched purely for notification purposes, without making any modifications to the object that defines the delivery group (the object's subscribers).

Nested Class Summary

Nested classes/interfaces inherited from interface com.threerings.io.Streamable

Streamable.Closure

Field Summary

protected Transport	_actualTransport The actual transport with which the event was transmitted (null if as yet unknown).
protected int	_soid The oid of the client that generated this event.
protected int	_toid The oid of the object that is the target of this event.
protected Transport	_transport The transport parameters.
long	eventId This event's "number".
protected static DSet.Entry	UNSET_OLD_ENTRY Used to differentiate between null meaning we haven't initialized our old entry and null being the actual old entry.
protected static Object	UNSET_OLD_VALUE Used to differentiate between null meaning we haven't initialized our old value and null being the actual old value.

Constructor Summary

DEvent(int targetOid)
Constructs a new distributed object event that pertains to the specified distributed object.

Method Summary

boolean	alreadyApplied() If this event applies itself immediately to the distributed object on the server and then NOOPs later when applyToObject(com.threerings.presents.dobj.DObject) is called, it should return true from this method.
abstract boolean	applyToObject(DObject target) Applies the attribute modifications represented by this event to the specified target object.
Transport	getActualTransport() Returns the actual transport with which the event was transmitted, or null if not yet known.
int	getSourceOid() Returns the object id of the client that generated this event.
int	getTargetOid() Returns the oid of the object that is the target of this event.
Transport	getTransport() Returns the transport parameters.
boolean	isPrivate() Some events are used only internally on the server and need not be broadcast to subscribers, proxy or otherwise.
void	noteActualTransport(Transport transport) Notes the actual transport with which the event was transmitted.
protected void	notifyListener(Object listener) Events with associated listener interfaces should implement this function and notify the supplied listener if it implements their event listening interface.
void	setSourceOid(int sourceOid) Do not call this method.
void	setTargetOid(int targetOid) Do not call this method.
DEvent	setTransport(Transport transport) Sets the transport parameters.
String	toString()
protected void	toString(StringBuilder buf) This should be overridden by derived classes (which should be sure to call super.toString()) to append the derived class specific event information to the string buffer.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

eventId

public transient long eventId

This event's "number". Every event dispatched by the server is numbered in monotonically increasing fashion when the event is posted to the event dispatch queue.

_toid

protected int _toid

The oid of the object that is the target of this event.

_soid

protected transient int _soid

The oid of the client that generated this event.

_transport

protected transient Transport _transport

The transport parameters.

_actualTransport

protected transient Transport _actualTransport

The actual transport with which the event was transmitted (null if as yet unknown).

UNSET_OLD_VALUE

protected static final Object UNSET_OLD_VALUE

Used to differentiate between null meaning we haven't initialized our old value and null being the actual old value.

UNSET_OLD_ENTRY

protected static final DSet.Entry UNSET_OLD_ENTRY

Used to differentiate between null meaning we haven't initialized our old entry and null being the actual old entry.

Constructor Detail

DEvent

public DEvent(int targetOid)

Constructs a new distributed object event that pertains to the specified distributed object.

Parameters:

transport - a hint as to the type of transport desired for the event.

Method Detail

getTargetOid

public int getTargetOid()

Returns the oid of the object that is the target of this event.

isPrivate

public boolean isPrivate()

Some events are used only internally on the server and need not be broadcast to subscribers, proxy or otherwise. Such events can return true here and short-circuit the normal proxy event dispatch mechanism.

alreadyApplied

public boolean alreadyApplied()

If this event applies itself immediately to the distributed object on the server and then NOOPs later when applyToObject(com.threerings.presents.dobj.DObject) is called, it should return true from this method. If it will modify the object during its applyToObject(com.threerings.presents.dobj.DObject) call, it should return false.

applyToObject

public abstract boolean applyToObject(DObject target)
                               throws ObjectAccessException

Applies the attribute modifications represented by this event to the specified target object. This is called by the distributed object manager in the course of dispatching events and should not be called directly.

Returns:

true if the object manager should go on to notify the object's listeners of this event, false if the event should be treated silently and the listeners should not be notified.

Throws:

ObjectAccessException - thrown if there is any problem applying the event to the object (invalid attribute, etc.).

getSourceOid

public int getSourceOid()

Returns the object id of the client that generated this event. If the event was generated by the server, the value returned will be -1. This is not valid on the client, it will return -1 for all events there (it is primarily provided to allow for event-level access control).

setTargetOid

public void setTargetOid(int targetOid)

Do not call this method. Sets the oid of the object on which this event operates. It is only used when rewriting events during object proxying.

setSourceOid

public void setSourceOid(int sourceOid)

Do not call this method. Sets the source oid of the client that generated this event. It is automatically called by the client management code when a client forwards an event to the server.

setTransport

public DEvent setTransport(Transport transport)

Sets the transport parameters. For events received over the network, these indicate the mode of transport over which the event was received. When an event is sent over the network, these act as a hint as to the type of transport desired.

getTransport

public Transport getTransport()

Returns the transport parameters.

noteActualTransport

public void noteActualTransport(Transport transport)

Notes the actual transport with which the event was transmitted.

getActualTransport

public Transport getActualTransport()

Returns the actual transport with which the event was transmitted, or null if not yet known.

notifyListener

protected void notifyListener(Object listener)

Events with associated listener interfaces should implement this function and notify the supplied listener if it implements their event listening interface. For example, the AttributeChangedEvent will notify listeners that implement AttributeChangeListener.

toString

public String toString()

Overrides:

toString in class Object

toString

protected void toString(StringBuilder buf)

This should be overridden by derived classes (which should be sure to call super.toString()) to append the derived class specific event information to the string buffer.