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

Nested Classes

Modifier and Type	Class and Description
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

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

Constructors

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

Method Summary

Modifier and Type	Method and Description
void	addLocationObserver(LocationObserver observer) Adds a location observer to the list.
void	addPendingForcedMove(Runnable move)
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.
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.
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.
boolean	leavePlace() Issues a request to leave our current location.
boolean	mayMoveTo(int placeId, 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.
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

clientObjectDidChange, clientWillLogon, isAvailableInStandalone, setAvailableInStandalone

Methods inherited from class java.lang.Object

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

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,
                         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.

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

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(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.

addPendingForcedMove

public void addPendingForcedMove(Runnable move)