com.threerings.crowd.client
Class LocationDirector

java.lang.Object
  com.threerings.presents.client.BasicDirector
      com.threerings.crowd.client.LocationDirector

All Implemented Interfaces:

LocationReceiver, LocationCodes, InvocationReceiver, SessionObserver, InvocationCodes

public class LocationDirector
extends BasicDirector
implements LocationCodes, LocationReceiver

The location director provides a means by which entities on the client can request to move from place to place and can be notified if other entities have caused the client to move to a new place. It also provides a mechanism for ratifying a request to move to a new place before actually issuing the request.

Nested Class Summary

static interface

LocationDirector.FailureHandler Used to recover from a moveTo request that was accepted but resulted in a failed attempt to fetch the place object to which we were moving.

Nested classes/interfaces inherited from interface com.threerings.presents.client.InvocationReceiver

InvocationReceiver.Registration

Field Summary

protected PlaceController	_controller The place controller in effect for our current place.
protected CrowdContext	_ctx The context through which we access needed services.
protected com.samskivert.util.ObserverList.ObserverOp<LocationObserver>	_didChangeOp The operation used to inform observers that the location changed.
protected LocationDirector.FailureHandler	_failureHandler The entity that deals when we fail to subscribe to a place object.
protected long	_lastRequestTime The last time we requested a move to.
protected LocationService	_lservice Provides access to location services.
protected com.samskivert.util.ResultListener<PlaceConfig>	_moveListener A listener that wants to know if we succeeded or how we failed to move.
protected com.samskivert.util.ObserverList<LocationObserver>	_observers Our location observer list.
protected int	_pendingPlaceId The oid of the place for which we have an outstanding moveTo request, or -1 if we have no outstanding request.
protected int	_placeId The oid of the place we currently occupy.
protected PlaceObject	_plobj The place object that we currently occupy.
protected int	_previousPlaceId The oid of the place we previously occupied.
protected SafeSubscriber<PlaceObject>	_subber Used to subscribe to our place object.
protected static long	STALE_REQUEST_DURATION We require that a moveTo request be outstanding for one minute before it is declared to be stale.

Fields inherited from class com.threerings.presents.client.BasicDirector

_availableInStandalone

Fields inherited from interface com.threerings.crowd.data.LocationCodes

ALREADY_THERE, MOVE_IN_PROGRESS, NO_SUCH_PLACE

Fields inherited from interface com.threerings.presents.data.InvocationCodes

ACCESS_DENIED, E_ACCESS_DENIED, E_INTERNAL_ERROR, GLOBAL_GROUP, INTERNAL_ERROR

Constructor Summary

LocationDirector(CrowdContext ctx)
Constructs a location director which will configure itself for operation using the supplied context.

Method Summary

void	addLocationObserver(LocationObserver observer) Adds a location observer to the list.
boolean	checkRepeatMove() Called to test and set a time stamp that we use to determine if a pending moveTo request is stale.
void	clientDidLogoff(Client client) Called after the client has been logged off of the server and has disconnected.
void	clientDidLogon(Client client) Called after the client successfully connected to and authenticated with the server.
protected PlaceController	createController(PlaceConfig config) Called to create our place controller using the supplied place configuration.
void	didLeavePlace() Called when we're leaving our current location.
void	didMoveTo(int placeId, PlaceConfig config) This can be called by cooperating directors that need to coopt the moving process to extend it in some way or other.
void	failedToMoveTo(int placeId, String reason) This can be called by cooperating directors that need to coopt the moving process to extend it in some way or other.
protected void	fetchServices(Client client) Derived directors can override this method and obtain any services they'll need during their operation via calls to Client.getService(java.lang.Class).
void	forcedMove(int placeId) Used to communicate a required move notification to the client.
PlaceObject	getPlaceObject() Returns the place object for the location we currently occupy or null if we're not currently occupying any location.
protected void	gotBodyObject(BodyObject clobj)
protected void	gotPlaceObject(PlaceObject object)
protected void	handleFailure(int placeId, String reason)
boolean	leavePlace() Issues a request to leave our current location.
protected void	mayLeavePlace() Called to inform our controller that we may be leaving the current place.
boolean	mayMoveTo(int placeId, com.samskivert.util.ResultListener<PlaceConfig> rl) This can be called by cooperating directors that need to coopt the moving process to extend it in some way or other.
boolean	moveBack() Requests to move to the room that we last occupied, if such a room exists.
boolean	movePending() Returns true if there is a pending move request.
boolean	moveTo(int placeId) Requests that this client be moved to the specified place.
protected void	registerServices(Client client) If a director makes use of bootstrap invocation services which are part of a bootstrap service group, it should register interest in that group here with a call to Client.addServiceGroup(java.lang.String).
void	removeLocationObserver(LocationObserver observer) Removes a location observer from the list.
void	setFailureHandler(LocationDirector.FailureHandler handler) Sets the failure handler which will recover from place object fetching failures.

Methods inherited from class com.threerings.presents.client.BasicDirector

assertAvailable, clientObjectDidChange, clientObjectUpdated, clientWillLogon, isAvailable, isAvailableInStandalone, setAvailableInStandalone

Methods inherited from class java.lang.Object

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

Field Detail

_ctx

protected CrowdContext _ctx

The context through which we access needed services.

_lservice

protected LocationService _lservice

Provides access to location services.

_observers

protected com.samskivert.util.ObserverList<LocationObserver> _observers

Our location observer list.

_subber

protected SafeSubscriber<PlaceObject> _subber

Used to subscribe to our place object.

_placeId

protected int _placeId

The oid of the place we currently occupy.

_plobj

protected PlaceObject _plobj

The place object that we currently occupy.

_controller

protected PlaceController _controller

The place controller in effect for our current place.

_pendingPlaceId

protected int _pendingPlaceId

The oid of the place for which we have an outstanding moveTo request, or -1 if we have no outstanding request.

_previousPlaceId

protected int _previousPlaceId

The oid of the place we previously occupied.

_lastRequestTime

protected long _lastRequestTime

The last time we requested a move to.

_failureHandler

protected LocationDirector.FailureHandler _failureHandler

The entity that deals when we fail to subscribe to a place object.

_moveListener

protected com.samskivert.util.ResultListener<PlaceConfig> _moveListener

A listener that wants to know if we succeeded or how we failed to move.

_didChangeOp

protected com.samskivert.util.ObserverList.ObserverOp<LocationObserver> _didChangeOp

The operation used to inform observers that the location changed.

STALE_REQUEST_DURATION

protected static final long STALE_REQUEST_DURATION

We require that a moveTo request be outstanding for one minute before it is declared to be stale.

See Also:

Constant Field Values

Constructor Detail

LocationDirector

public LocationDirector(CrowdContext ctx)

Constructs a location director which will configure itself for operation using the supplied context.

Method Detail

addLocationObserver

public void addLocationObserver(LocationObserver observer)

Adds a location observer to the list. This observer will subsequently be notified of potential, effected and failed location changes.

removeLocationObserver

public void removeLocationObserver(LocationObserver observer)

Removes a location observer from the list.

getPlaceObject

public PlaceObject getPlaceObject()

Returns the place object for the location we currently occupy or null if we're not currently occupying any location.

movePending

public boolean movePending()

Returns true if there is a pending move request.

moveTo

public boolean moveTo(int placeId)

Requests that this client be moved to the specified place. A request will be made and when the response is received, the location observers will be notified of success or failure.

Returns:

true if the move to request was issued, false if it was rejected by a location observer or because we have another request outstanding.

moveBack

public boolean moveBack()

Requests to move to the room that we last occupied, if such a room exists.

Returns:

true if we had a previous room and we requested to move to it, false if we had no previous room.

leavePlace

public boolean leavePlace()

Issues a request to leave our current location.

Returns:

true if we were able to leave, false if we are in the middle of moving somewhere and can't yet leave.

mayMoveTo

public boolean mayMoveTo(int placeId,
                         com.samskivert.util.ResultListener<PlaceConfig> rl)

This can be called by cooperating directors that need to coopt the moving process to extend it in some way or other. In such situations, they should call this method before moving to a new location to check to be sure that all of the registered location observers are amenable to a location change.

Parameters:

placeId - the place oid of our tentative new location.

Returns:

true if everyone is happy with the move, false if it was vetoed by one of the location observers.

mayLeavePlace

protected void mayLeavePlace()

Called to inform our controller that we may be leaving the current place.

didMoveTo

public void didMoveTo(int placeId,
                      PlaceConfig config)

This can be called by cooperating directors that need to coopt the moving process to extend it in some way or other. In such situations, they will be responsible for receiving the successful move response and they should let the location director know that the move has been effected.

Parameters:

placeId - the place oid of our new location.

config - the configuration information for the new place.

didLeavePlace

public void didLeavePlace()

Called when we're leaving our current location. Informs the location's controller that we're departing, unsubscribes from the location's place object, and clears out our internal place information.

failedToMoveTo

public void failedToMoveTo(int placeId,
                           String reason)

This can be called by cooperating directors that need to coopt the moving process to extend it in some way or other. If the coopted move request fails, this failure can be propagated to the location observers if appropriate.

Parameters:

placeId - the place oid to which we failed to move.

reason - the reason code given for failure.

checkRepeatMove

public boolean checkRepeatMove()

Called to test and set a time stamp that we use to determine if a pending moveTo request is stale.

clientDidLogon

public void clientDidLogon(Client client)

Description copied from interface: SessionObserver

Called after the client successfully connected to and authenticated with the server. The entire object system is up and running by the time this method is called.

Specified by:

clientDidLogon in interface SessionObserver

Overrides:

clientDidLogon in class BasicDirector

clientDidLogoff

public void clientDidLogoff(Client client)

Description copied from interface: SessionObserver

Called after the client has been logged off of the server and has disconnected.

Specified by:

clientDidLogoff in interface SessionObserver

Overrides:

clientDidLogoff in class BasicDirector

registerServices

protected void registerServices(Client client)

Description copied from class: BasicDirector

If a director makes use of bootstrap invocation services which are part of a bootstrap service group, it should register interest in that group here with a call to Client.addServiceGroup(java.lang.String).

Overrides:

registerServices in class BasicDirector

fetchServices

protected void fetchServices(Client client)

Description copied from class: BasicDirector

Derived directors can override this method and obtain any services they'll need during their operation via calls to Client.getService(java.lang.Class). If the director is available, it will automatically be called when the client logs on or when the director is constructed if it is constructed after the client is already logged on.

Overrides:

fetchServices in class BasicDirector

gotPlaceObject

protected void gotPlaceObject(PlaceObject object)

gotBodyObject

protected void gotBodyObject(BodyObject clobj)

forcedMove

public void forcedMove(int placeId)

Description copied from interface: LocationReceiver

Used to communicate a required move notification to the client. The server will have removed the client from their existing location and the client is then responsible for generating a LocationService.moveTo(com.threerings.presents.client.Client, int, com.threerings.crowd.client.LocationService.MoveListener) request to move to the new location.

Specified by:

forcedMove in interface LocationReceiver

setFailureHandler

public void setFailureHandler(LocationDirector.FailureHandler handler)

Sets the failure handler which will recover from place object fetching failures. In the event that we are unable to fetch our place object after making a successful moveTo request, we attempt to rectify the failure by moving back to the last known working location. Because entites that cooperate with the location director may need to become involved in this failure recovery, we provide this interface whereby they can interject themseves into the failure recovery process and do their own failure recovery.

handleFailure

protected void handleFailure(int placeId,
                             String reason)

createController

protected PlaceController createController(PlaceConfig config)

Called to create our place controller using the supplied place configuration. This lives in a separate method so that derived instances can do funny class loader business if necessary to load the place controller using a sandboxed class loader.