com.threerings.presents.server

Class PresentsDObjectMgr

java.lang.Object

com.threerings.presents.server.PresentsDObjectMgr

All Implemented Interfaces:

Interval.Factory, RunQueue, DObjectManager, RootDObjectManager, Executor

Direct Known Subclasses:

LocalDObjectMgr

public class PresentsDObjectMgr
extends Object
implements RootDObjectManager

The presents distributed object manager implements the DObjectManager interface, providing an object manager that runs on the server. By virtue of running on the server, it manages its objects directly rather than managing proxies of objects which is what is done on the client. Thus it simply queues up events and dispatches them to listeners.

The server object manager is meant to run on the main thread of the server application and thus provides a method to be invoked by the application main thread which won't return until the manager has been requested to shut down.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	PresentsDObjectMgr.LongRunnable Post instances of these if you know you're going to tie up the distributed object thread for a long time and don't want a spurious warning.
static class	PresentsDObjectMgr.Stats Returned by getStats(boolean).

Nested classes/interfaces inherited from interface com.samskivert.util.RunQueue

RunQueue.AsExecutor

Field Summary

Fields inherited from interface com.samskivert.util.RunQueue

AWT

Constructor Summary

Constructors

Constructor and Description
PresentsDObjectMgr(ReportManager repmgr) Creates the dobjmgr and prepares it for operation.

Method Summary

Modifier and Type	Method and Description
void	clearProxyObject(int origObjectId, DObject object) Clears a proxy object reference from our local distributed object space.
void	clearUnitProfiles() Clears the current set of unit profiles.
void	destroyObject(int oid) Requests that the specified object be destroyed.
void	dumpUnitProfiles() Dumps collected profiling information to the system log.
void	execute(Runnable command)
long	getNextEventId(boolean increment) Returns the id to be assigned to the next event posted to the event queue.
DObject	getObject(int oid) Returns the object in the object table with the specified oid or null if no object has that oid.
PresentsDObjectMgr.Stats	getStats(boolean snapshot) Returns a recent snapshot of runtime statistics tracked by the distributed object manager.
int	getUnitProfInterval() Returns the profiling sample frequency.
void	harshShutdown() Requests that the dobjmgr shut itself down directly.
boolean	isDispatchThread() Returns true if the thread invoking this method is the same thread that is doing distributed object event dispatch.
boolean	isManager(DObject object) Returns true if this distributed object manager is the authoritative manager for the specified distributed object, or false if we are only providing a proxy to the object.
boolean	isRunning() Tests if the event processing thread is still running.
Interval	newInterval(Runnable action) Creates an Interval that runs the supplied runnable.
boolean	objectAdded(DEvent event, DObject target) Called as a helper for ObjectAddedEvent events.
boolean	objectDestroyed(DEvent event, DObject target) Called as a helper for ObjectDestroyedEvent events.
boolean	objectRemoved(DEvent event, DObject target) Called as a helper for ObjectRemovedEvent events.
void	postEvent(DEvent event) Posts a distributed object event into the system.
void	postRunnable(Runnable unit) Posts a self-contained unit of code that should be run on the distributed object manager thread at the next available opportunity.
boolean	queueIsEmpty() Should not need to be called except by the invoker during shutdown to ensure that things are proceeding smoothly.
void	refuseEventThread() Ensures that the calling thread is not the distributed object event dispatch thread, throwing an IllegalStateException if it is.
<T extends DObject> T	registerObject(T object) Registers a distributed object instance of the supplied class with the system and assigns it an oid.
void	registerProxyObject(DObject object, DObjectManager omgr) Registers an object managed by another distributed object manager (probably on another server).
void	removedLastSubscriber(DObject obj, boolean deathWish) When a distributed object removes its last subscriber, it will call this function to let the object manager know.
void	requireEventThread() Ensures that the calling thread is the distributed object event dispatch thread, throwing an IllegalStateException if it is not.
void	run() Runs the dobjmgr event loop until it is requested to exit.
void	setDefaultAccessController(AccessController controller) Sets up an access controller that will be provided to any distributed objects created on the server.
void	setUnitProfInterval(int interval) Sets the frequency at which we take profiling samples.
<T extends DObject> void	subscribeToObject(int oid, Subscriber<T> target) Requests that the specified subscriber be subscribed to the object identified by the supplied object id.
<T extends DObject> void	unsubscribeFromObject(int oid, Subscriber<T> target) Requests that the specified subscriber be unsubscribed from the object identified by the supplied object id.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PresentsDObjectMgr

@Inject
public PresentsDObjectMgr(ReportManager repmgr)

Creates the dobjmgr and prepares it for operation.

Method Detail

getNextEventId

public long getNextEventId(boolean increment)

Returns the id to be assigned to the next event posted to the event queue.

Parameters:

increment - if true, the event id will be incremented so that the caller can "claim" the returned event id.

setDefaultAccessController

public void setDefaultAccessController(AccessController controller)

Sets up an access controller that will be provided to any distributed objects created on the server. The controllers can subsequently be overridden if desired, but a default controller is useful for implementing basic access control policies.

registerProxyObject

public void registerProxyObject(DObject object,
                                DObjectManager omgr)

Registers an object managed by another distributed object manager (probably on another server). The local server will assign the object a proxy oid, and any events that come in on this object will be rewritten from their proxy oid to their original id before forwarding on to the originating object manager.

clearProxyObject

public void clearProxyObject(int origObjectId,
                             DObject object)

Clears a proxy object reference from our local distributed object space. This merely removes it from our internal tables, the caller is responsible for coordinating the deregistration of the object with the proxying client.

isManager

public boolean isManager(DObject object)

Description copied from interface: DObjectManager

Returns true if this distributed object manager is the authoritative manager for the specified distributed object, or false if we are only providing a proxy to the object.

Specified by:

isManager in interface DObjectManager

subscribeToObject

public <T extends DObject> void subscribeToObject(int oid,
                                                  Subscriber<T> target)

Description copied from interface: DObjectManager

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.

Specified by:

subscribeToObject in interface DObjectManager

Parameters:

oid - The object id of the distributed object to which subscription is desired.

target - The subscriber to be subscribed.

See Also:

Subscriber.objectAvailable(T), Subscriber.requestFailed(int, com.threerings.presents.dobj.ObjectAccessException)

unsubscribeFromObject

public <T extends DObject> void unsubscribeFromObject(int oid,
                                                      Subscriber<T> target)

Description copied from interface: DObjectManager

Requests that the specified subscriber be unsubscribed from the object identified by the supplied object id.

Specified by:

unsubscribeFromObject in interface DObjectManager

Parameters:

oid - The object id of the distributed object from which unsubscription is desired.

target - The subscriber to be unsubscribed.

postEvent

public void postEvent(DEvent event)

Description copied from interface: DObjectManager

Posts a distributed object event into the system. Instead of requesting the modification of a distributed object attribute by calling the setter for that attribute on the object itself, an AttributeChangedEvent can be constructed and posted directly. This is true for all event types and is useful for situations where one doesn't have access to the object in question, but needs to affect some event.

This event will be forwarded to the ultimate manager of the object (on the client, this means it will be forwarded to the server) where it will be checked for validity and then applied to the object and dispatched to all its subscribers.

Specified by:

postEvent in interface DObjectManager

Parameters:

event - The event to be dispatched.

removedLastSubscriber

public void removedLastSubscriber(DObject obj,
                                  boolean deathWish)

Description copied from interface: DObjectManager

When a distributed object removes its last subscriber, it will call this function to let the object manager know. The manager might then choose to flush this object from the system or unregister from some upstream manager whose object it was proxying, for example.

Specified by:

removedLastSubscriber in interface DObjectManager

registerObject

public <T extends DObject> T registerObject(T object)

Description copied from interface: RootDObjectManager

Registers a distributed object instance of the supplied class with the system and assigns it an oid. When the call returns the object will be registered with the system and its oid will have been assigned.

Specified by:

registerObject in interface RootDObjectManager

Returns:

the registered object for the caller's convenience.

destroyObject

public void destroyObject(int oid)

Description copied from interface: RootDObjectManager

Requests that the specified object be destroyed. Once destroyed an object is removed from the runtime system and may no longer have events dispatched on it.

Specified by:

destroyObject in interface RootDObjectManager

Parameters:

oid - The object id of the distributed object to be destroyed.

newInterval

public Interval newInterval(Runnable action)

Description copied from interface: RootDObjectManager

Creates an Interval that runs the supplied runnable. If the root omgr is shutdown before the interval expires (or if the interval is scheduled to repeat), it will be automatically cancelled. This makes it easy to schedule fire-and-forget intervals:

 _omgr.newInterval(someRunnable).schedule(500); // one shot
 Interval ival = _omgr.newInterval(someRunnable).schedule(500, true); // repeater
 

Specified by:

newInterval in interface Interval.Factory

Specified by:

newInterval in interface RootDObjectManager

getObject

public DObject getObject(int oid)

Returns the object in the object table with the specified oid or null if no object has that oid. Be sure only to call this function from the dobjmgr thread and not to do anything funny with the object. If subscription is desired, use subscribeToObject(int, com.threerings.presents.dobj.Subscriber<T>).

Specified by:

getObject in interface RootDObjectManager

getStats

public PresentsDObjectMgr.Stats getStats(boolean snapshot)

Returns a recent snapshot of runtime statistics tracked by the distributed object manager.

Parameters:

snapshot - if true, the current stats will be snapshotted and reset and the new snapshot will be returned. If false, the previous snapshot will be returned. If no snapshot has ever been taken, the current stats that have been accumulting since the JVM start will be returned.

execute

public void execute(Runnable command)

Specified by:

execute in interface Executor

postRunnable

public void postRunnable(Runnable unit)

Posts a self-contained unit of code that should be run on the distributed object manager thread at the next available opportunity. The code will be queued up with the rest of the events and invoked in turn. Like event processing code, the code should not take long to complete and should definitely not block. From interface RunQueue

Specified by:

postRunnable in interface RunQueue

isDispatchThread

public boolean isDispatchThread()

Returns true if the thread invoking this method is the same thread that is doing distributed object event dispatch. Code that wishes to enforce that it is either always or never called on the event dispatch thread will want to make use of this method. From interface RunQueue

Specified by:

isDispatchThread in interface RunQueue

requireEventThread

public void requireEventThread()

Ensures that the calling thread is the distributed object event dispatch thread, throwing an IllegalStateException if it is not. Note: before the manager is started up, all calls to this method will succeed, as things that take place during server initialization are considered safe and only after the distributed object manager is started (and the event thread is established) will we require it.

refuseEventThread

public void refuseEventThread()

Ensures that the calling thread is not the distributed object event dispatch thread, throwing an IllegalStateException if it is.

run

public void run()

Runs the dobjmgr event loop until it is requested to exit. This should be called from the main application thread.

harshShutdown

public void harshShutdown()

Requests that the dobjmgr shut itself down directly. You may want to try using PresentsInvoker.shutdown() which will make sure that both the Invoker and DObjectMgr are empty and then shut them both down.

setUnitProfInterval

public void setUnitProfInterval(int interval)

Sets the frequency at which we take profiling samples.

getUnitProfInterval

public int getUnitProfInterval()

Returns the profiling sample frequency.

dumpUnitProfiles

public void dumpUnitProfiles()

Dumps collected profiling information to the system log.

clearUnitProfiles

public void clearUnitProfiles()

Clears the current set of unit profiles.

objectDestroyed

public boolean objectDestroyed(DEvent event,
                               DObject target)

Called as a helper for ObjectDestroyedEvent events. It removes the object from the object table.

Returns:

true if the event should be dispatched, false if it should be aborted.

objectAdded

public boolean objectAdded(DEvent event,
                           DObject target)

Called as a helper for ObjectAddedEvent events. It updates the object/oid list tracking structures.

Returns:

true if the event should be dispatched, false if it should be aborted.

objectRemoved

public boolean objectRemoved(DEvent event,
                             DObject target)

Called as a helper for ObjectRemovedEvent events. It updates the object/oid list tracking structures.

Returns:

true if the event should be dispatched, false if it should be aborted.

queueIsEmpty

public boolean queueIsEmpty()

Should not need to be called except by the invoker during shutdown to ensure that things are proceeding smoothly.

isRunning

public boolean isRunning()

Tests if the event processing thread is still running. This is required by the ConnectionManager to ensure messages posted just before or during shutdown are sent.

Specified by:

isRunning in interface RunQueue