com.threerings.crowd.server
Class PlaceManager

java.lang.Object
  com.threerings.crowd.server.PlaceManager

All Implemented Interfaces:

SpeakHandler.SpeakerValidator, ChangeListener, MessageListener

public class PlaceManager
extends Object
implements MessageListener, SpeakHandler.SpeakerValidator

The place manager is the server-side entity that handles all place-related interaction. It subscribes to the place object and reacts to message and other events. Behavior specific to a place (or class of places) should live in the place manager. An intelligently constructed hierarchy of place manager classes working in concert with invocation services should provide the majority of the server-side functionality of an application built on the Presents platform.

The base place manager class takes care of the necessary interactions with the place registry to manage place registration. It handles the place-related component of chatting. It also provides the basis for place-based access control.

A derived class is expected to handle initialization, cleanup and operational functionality via the calldown functions didInit(), didStartup(), and didShutdown() as well as through event listeners.

Nested Class Summary

static class	PlaceManager.DelegateOp Used to call methods on this place manager's delegates.
static interface	PlaceManager.MessageHandler Deprecated. Use dynamically bound methods instead. See DynamicListener.

Field Summary

protected SetAdapter<OccupantInfo>	_bodyUpdater Listens for occupant updates.
protected PlaceConfig	_config A reference to the configuration for our place.
protected ObjectDeathListener	_deathListener Listens for death of our place object.
protected List<PlaceManagerDelegate>	_delegates A list of the delegates in use by this manager.
protected DynamicListener<?>	_dispatcher Used to do method lookup magic when we receive message events.
protected static Map<Class<?>,MethodFinder>	_dispatcherFinders Maps from a PlaceManager subclass to a MethodFinder for it.
protected com.google.inject.Injector	_injector We use this to inject dependencies into our access controller.
protected InvocationManager	_invmgr The invocation manager with whom we register our game invocation services.
protected BodyLocator	_locator Used to look up body objects by name.
protected List<InvocationMarshaller<?>>	_marshallers A list of services registered with addProvider(com.threerings.presents.server.InvocationProvider, java.lang.Class) which will be automatically cleared when this manager shuts down.
protected Map<String,PlaceManager.MessageHandler>	_msghandlers Message handlers are used to process message events.
protected HashIntMap<OccupantInfo>	_occInfo Used to keep a canonical copy of the occupant info records.
protected OidListListener	_occListener Listens for body entry and departure.
protected RootDObjectManager	_omgr A distributed object manager for doing dobj stuff.
protected PlaceObject	_plobj A reference to the place object that we manage.
protected PlaceRegistry	_registry A reference to the place registry with which we're registered.
protected Interval	_shutdownInterval The interval currently registered to shut this place down after a certain period of idility, or null if no interval is currently registered.

Constructor Summary

PlaceManager()

Method Summary

void	addDelegate(PlaceManagerDelegate delegate) Adds the supplied delegate to the list for this manager.
protected <T extends InvocationMarshaller<?>> T	addDispatcher(InvocationDispatcher<T> disp) Registers an invocation dispatcher and notes the registration such that it will be automatically cleared when this manager shuts down.
protected void	addOccupantInfo(BodyObject body, OccupantInfo info) Adds this occupant's info to the PlaceObject.
protected <T extends InvocationMarshaller<?>> T	addProvider(InvocationProvider prov, Class<T> mclass) Registers an invocation provider and notes the registration such that it will be automatically cleared when this manager shuts down.
void	applyToDelegates(PlaceManager.DelegateOp op) Applies the supplied operation to this manager's registered delegates.
void	applyToOccupants(OccupantOp op) Applies the supplied occupant operation to each occupant currently present in this place.
protected void	bodyEntered(int bodyOid) Called when a body object enters this place.
protected void	bodyLeft(int bodyOid) Called when a body object leaves this place.
protected void	bodyUpdated(OccupantInfo info) Called when a body's occupant info is updated.
void	bodyWillEnter(BodyObject body) This is called to inform the manager that a body is on the way in.
void	bodyWillLeave(BodyObject body) Called to inform a manager that a body is about to leave this place.
protected void	cancelShutdowner() Cancels any registered shutdown interval.
String	checkPermissions() Provides an opportunity for place managers to ratify the creation of a place based on whatever criterion they may require (based on information available to the manager at this post-init() but pre-startup() phase of initialization).
protected void	checkShutdownInterval() Called on startup and when the place is empty.
protected PlaceObject	createPlaceObject() Derived classes will generally override this method to create a custom PlaceObject derivation that contains extra information.
protected SpeakHandler	createSpeakHandler(PlaceObject plobj) Creates the speak handler for this place.
protected void	didInit() Called after this place manager has been initialized with its configuration information but before it has been started up with its place object reference.
protected void	didShutdown() Called when this place has been destroyed and the place manager has shut down (via a call to shutdown()).
protected void	didStartup() Derived classes should override this (and be sure to call super.didStartup()) to perform any startup time initialization.
protected AccessController	getAccessController() Creates an access controller for this place's distributed object, which by default is CrowdObjectAccess.PlaceAccessController.
PlaceConfig	getConfig() Returns a reference to our place configuration object.
Place	getLocation() Returns a Place instance that identifies this place.
PlaceObject	getPlaceObject() Returns the place object managed by this place manager.
protected Class<? extends PlaceObject>	getPlaceObjectClass() Deprecated. Use createPlaceObject().
protected long	idleUnloadPeriod() Returns the period (in milliseconds) of emptiness after which this place manager will unload itself and shutdown.
void	init(PlaceRegistry registry, InvocationManager invmgr, RootDObjectManager omgr, BodyLocator locator, PlaceConfig config) Called by the place registry after creating this place manager.
boolean	isValidSpeaker(DObject speakObj, ClientObject speaker, byte mode) Should return true if the supplied speaker is allowed to speak via the speak provider with which this validator was registered.
void	messageReceived(MessageEvent event) Called when an message event has been dispatched on an object.
protected void	permissionsFailed() Called if the permissions check failed, to give place managers a chance to do any cleanup that might be necessary due to their early initialization or permissions checking code.
protected void	placeBecameEmpty() Called when we transition from having bodies in the place to not having any bodies in the place.
String	ratifyBodyEntry(BodyObject body) Provides an opportunity for the place manager to prevent bodies from entering.
void	registerMessageHandler(String name, PlaceManager.MessageHandler handler) Deprecated. Use dynamically bound methods instead. See DynamicListener.
protected boolean	shouldCreateSpeakService()
protected boolean	shouldDeclareEmpty(OccupantInfo leaver) Returns whether the location should be marked as empty and potentially shutdown.
void	shutdown() Causes the place object being managed by this place manager to be destroyed and the place manager to shut down.
void	startup(PlaceObject plobj) Called by the place manager after the place object has been successfully created.
String	toString() Generates a string representation of this manager.
protected void	toString(StringBuilder buf) An extensible way to add to the string representation of this class.
<T extends OccupantInfo> boolean	updateOccupantInfo(int bodyOid, OccupantInfo.Updater<T> updater) Calls the supplied updater on the canonical occupant info record for the specified body (which must be an occupant of this place) and broadcasts the update to all other occupants.
String	where() Returns a string that can be used in log messages to identify the place as sensibly as possible to the developer who has to puzzle over log output trying to figure out what's going on.

Methods inherited from class java.lang.Object

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

Field Detail

_bodyUpdater

protected SetAdapter<OccupantInfo> _bodyUpdater

Listens for occupant updates.

_occListener

protected OidListListener _occListener

Listens for body entry and departure.

_deathListener

protected ObjectDeathListener _deathListener

Listens for death of our place object.

_injector

@Inject
protected com.google.inject.Injector _injector

We use this to inject dependencies into our access controller.

_registry

protected PlaceRegistry _registry

A reference to the place registry with which we're registered.

_invmgr

protected InvocationManager _invmgr

The invocation manager with whom we register our game invocation services.

_omgr

protected RootDObjectManager _omgr

A distributed object manager for doing dobj stuff.

_locator

protected BodyLocator _locator

Used to look up body objects by name.

_plobj

protected PlaceObject _plobj

A reference to the place object that we manage.

_config

protected PlaceConfig _config

A reference to the configuration for our place.

_msghandlers

protected Map<String,PlaceManager.MessageHandler> _msghandlers

Message handlers are used to process message events.

_delegates

protected List<PlaceManagerDelegate> _delegates

A list of the delegates in use by this manager.

_marshallers

protected List<InvocationMarshaller<?>> _marshallers

A list of services registered with addProvider(com.threerings.presents.server.InvocationProvider, java.lang.Class) which will be automatically cleared when this manager shuts down.

_occInfo

protected HashIntMap<OccupantInfo> _occInfo

Used to keep a canonical copy of the occupant info records.

_shutdownInterval

protected Interval _shutdownInterval

The interval currently registered to shut this place down after a certain period of idility, or null if no interval is currently registered.

_dispatcher

protected DynamicListener<?> _dispatcher

Used to do method lookup magic when we receive message events.

_dispatcherFinders

protected static Map<Class<?>,MethodFinder> _dispatcherFinders

Maps from a PlaceManager subclass to a MethodFinder for it. When there are many many instances of a PlaceManager in existence, having a MethodFinder instance for each gets quite expensive.

Constructor Detail

PlaceManager

public PlaceManager()

Method Detail

getConfig

public PlaceConfig getConfig()

Returns a reference to our place configuration object.

getLocation

public Place getLocation()

Returns a Place instance that identifies this place.

getPlaceObject

public PlaceObject getPlaceObject()

Returns the place object managed by this place manager.

applyToOccupants

public void applyToOccupants(OccupantOp op)

Applies the supplied occupant operation to each occupant currently present in this place.

updateOccupantInfo

public <T extends OccupantInfo> boolean updateOccupantInfo(int bodyOid,
                                                           OccupantInfo.Updater<T> updater)

Calls the supplied updater on the canonical occupant info record for the specified body (which must be an occupant of this place) and broadcasts the update to all other occupants.

Returns:

true if the updater was called and the update sent, false if the body could not be located (was not an occupant of this place) or the updater made no modifications.

Throws:

ClassCastException - thrown if the type of the supplied updater does not match the type of OccupantInfo record used for the occupant. Caveat utilitor.

init

public void init(PlaceRegistry registry,
                 InvocationManager invmgr,
                 RootDObjectManager omgr,
                 BodyLocator locator,
                 PlaceConfig config)

Called by the place registry after creating this place manager.

addDelegate

public void addDelegate(PlaceManagerDelegate delegate)

Adds the supplied delegate to the list for this manager.

applyToDelegates

public void applyToDelegates(PlaceManager.DelegateOp op)

Applies the supplied operation to this manager's registered delegates.

checkPermissions

public String checkPermissions()

Provides an opportunity for place managers to ratify the creation of a place based on whatever criterion they may require (based on information available to the manager at this post-init() but pre-startup() phase of initialization).

Returns:

If a permissions check is to fail, the manager should return a translatable string explaining the failure. null should be returned if initialization is to be allowed to proceed.

startup

public void startup(PlaceObject plobj)

Called by the place manager after the place object has been successfully created.

shutdown

public void shutdown()

Causes the place object being managed by this place manager to be destroyed and the place manager to shut down.

ratifyBodyEntry

public String ratifyBodyEntry(BodyObject body)

Provides an opportunity for the place manager to prevent bodies from entering.

Returns:

null if the body can enter, otherwise a translatable message explaining the reason the body is blocked from entering

bodyWillEnter

public void bodyWillEnter(BodyObject body)

This is called to inform the manager that a body is on the way in. This is called at the very beginning of the entry process before the client is informed that it is allowed to enter. This will be followed by a call to bodyEntered(int) once all events relating to body entry have been processed.

bodyWillLeave

public void bodyWillLeave(BodyObject body)

Called to inform a manager that a body is about to leave this place. This will be followed by a call to bodyLeft(int) once all events relating to body entry have been processed.

registerMessageHandler

@Deprecated
public void registerMessageHandler(String name,
                                              PlaceManager.MessageHandler handler)

Deprecated. Use dynamically bound methods instead. See DynamicListener.

Registers a particular message handler instance to be used when processing message events with the specified name.

Parameters:

name - the message name of the message events that should be handled by this handler.

handler - the handler to be registered.

messageReceived

public void messageReceived(MessageEvent event)

Description copied from interface: MessageListener

Called when an message event has been dispatched on an object.

Specified by:

messageReceived in interface MessageListener

Parameters:

event - The event that was dispatched on the object.

isValidSpeaker

public boolean isValidSpeaker(DObject speakObj,
                              ClientObject speaker,
                              byte mode)

Description copied from interface: SpeakHandler.SpeakerValidator

Should return true if the supplied speaker is allowed to speak via the speak provider with which this validator was registered.

Specified by:

isValidSpeaker in interface SpeakHandler.SpeakerValidator

where

public String where()

Returns a string that can be used in log messages to identify the place as sensibly as possible to the developer who has to puzzle over log output trying to figure out what's going on. Derived place managers can override this and augment the default value (which is simply the place object id) with useful identifying information.

toString

public String toString()

Generates a string representation of this manager. Does so in a way that makes it easier for derived classes to add to the string representation.

Overrides:

toString in class Object

See Also:

toString(StringBuilder)

createPlaceObject

protected PlaceObject createPlaceObject()

Derived classes will generally override this method to create a custom PlaceObject derivation that contains extra information.

getPlaceObjectClass

@Deprecated
protected Class<? extends PlaceObject> getPlaceObjectClass()

Deprecated. Use createPlaceObject().

didInit

protected void didInit()

Called after this place manager has been initialized with its configuration information but before it has been started up with its place object reference. Derived classes can override this function and perform any basic initialization that they desire. They should of course be sure to call super.didInit().

permissionsFailed

protected void permissionsFailed()

Called if the permissions check failed, to give place managers a chance to do any cleanup that might be necessary due to their early initialization or permissions checking code.

shouldCreateSpeakService

protected boolean shouldCreateSpeakService()

Returns:

true if we should create a speaker service for our place object so that clients can use it to speak in this place.

getAccessController

protected AccessController getAccessController()

Creates an access controller for this place's distributed object, which by default is CrowdObjectAccess.PlaceAccessController.

didStartup

protected void didStartup()

Derived classes should override this (and be sure to call super.didStartup()) to perform any startup time initialization. The place object will be available by the time this method is executed.

didShutdown

protected void didShutdown()

Called when this place has been destroyed and the place manager has shut down (via a call to shutdown()). Derived classes can override this method and perform any necessary shutdown time processing.

addProvider

protected <T extends InvocationMarshaller<?>> T addProvider(InvocationProvider prov,
                                                            Class<T> mclass)

Registers an invocation provider and notes the registration such that it will be automatically cleared when this manager shuts down.

addDispatcher

protected <T extends InvocationMarshaller<?>> T addDispatcher(InvocationDispatcher<T> disp)

Registers an invocation dispatcher and notes the registration such that it will be automatically cleared when this manager shuts down.

bodyEntered

protected void bodyEntered(int bodyOid)

Called when a body object enters this place.

bodyLeft

protected void bodyLeft(int bodyOid)

Called when a body object leaves this place.

addOccupantInfo

protected void addOccupantInfo(BodyObject body,
                               OccupantInfo info)

Adds this occupant's info to the PlaceObject. This is called in a transaction on the place object so if a derived class needs to add additional information for an occupant it should override this method. It may opt to add the information before calling super if it wishes to rely on its information being configured when bodyEntered(int) is called.

shouldDeclareEmpty

protected boolean shouldDeclareEmpty(OccupantInfo leaver)

Returns whether the location should be marked as empty and potentially shutdown.

bodyUpdated

protected void bodyUpdated(OccupantInfo info)

Called when a body's occupant info is updated.

placeBecameEmpty

protected void placeBecameEmpty()

Called when we transition from having bodies in the place to not having any bodies in the place. Some places may take this as a sign to pack it in, others may wish to stick around. In any case, they can override this method to do their thing.

checkShutdownInterval

protected void checkShutdownInterval()

Called on startup and when the place is empty.

cancelShutdowner

protected void cancelShutdowner()

Cancels any registered shutdown interval.

idleUnloadPeriod

protected long idleUnloadPeriod()

Returns the period (in milliseconds) of emptiness after which this place manager will unload itself and shutdown. Returning 0 indicates that the place should never be shutdown.

toString

protected void toString(StringBuilder buf)

An extensible way to add to the string representation of this class. Override this (being sure to call super) and append your info to the buffer.

createSpeakHandler

protected SpeakHandler createSpeakHandler(PlaceObject plobj)

Creates the speak handler for this place. Derived classes can customize the speak handler if they so desire.