org.elkoserver.server.context
Class Context

java.lang.Object
  org.elkoserver.server.context.BasicObject
      org.elkoserver.server.context.Context

All Implemented Interfaces:

DefaultDispatchTarget, Deliverer, DispatchTarget, MessageRetargeter, Encodable, Referenceable

public class Context
extends BasicObject
implements Deliverer

A Context is a place for interaction between connected users. It is one of the three basic object types (along with User and Item).

Field Summary

Fields inherited from class org.elkoserver.server.context.BasicObject

VIS_CONTAINER, VIS_NONE, VIS_PERSONAL, VIS_PUBLIC

Method Summary

int	baseCapacity() Obtain the number of users who may enter (a clone of) this context before another clone must be created.
void	closeGate(String reason) Close this context's gate, blocking new users from entering.
Context	context() Obtain the context this object is associated with.
JSONLiteral	encode(EncodeControl control) Encode this context for transmission or persistence.
void	exit(Deliverer from) Handle the 'exit' verb.
void	forceClose() Close this context, even if it has been retained by one or more calls to the retain() method, and even if there are still users in it (this means kicking those users off).
boolean	gateIsClosed() Test if this context's gate is closed.
BasicObject	get(String ref) Look up an object in this context's namespace.
Object	getStaticObject(String ref) Look up one of this server's static objects.
boolean	isContainer() Test if this object is a container.
boolean	isRestricted() Test if this context is restricted, that is, whether it is closed to entry without an internally requested reservation.
boolean	isSemiPrivate() Test if this context is semi-private.
String	loadedFromRef() Obtain the ref of the context descriptor from which this context was loaded.
int	maxCapacity() Obtain the number of users who may enter before no more are allowed in.
Deliverer	neighbors(Deliverer exclude) Obtain a Deliverer that will deliver to all of a user's neighbors in this context.
void	openGate() Open this context's gate, allowing new users in if the context is not full.
void	registerContextShutdownWatcher(ContextShutdownWatcher watcher) Register a callback to be invoked when the context is shut down.
void	registerUserWatcher(UserWatcher watcher) Register a callback to be invoked when a user enters or exits the context.
void	release() Release an earlier call to retain().
void	retain() Keep this context open even if all users exit (normally a context will be shut down automatically after the last user leaves).
void	scheduleContextEvent(long millis, Runnable thunk) Schedule a timer event associated with this context.
void	send(JSONLiteral message) Send a message to everyone in this context.
void	sendObjectDescription(Deliverer to, Referenceable maker) Transmit a description of this context as a series of 'make' messages, such that the receiver will be able to construct a local presence of it.
void	sendToNeighbors(Deliverer exclude, JSONLiteral message) Send a message to everyone in this context save one.
static Deliverer	toList(List<BasicObject> toList) Obtain a Deliverer that will deliver to an arbitrary list of users.
static Deliverer	toListExcluding(List<BasicObject> toList, Deliverer exclude) Obtain a Deliverer that will deliver to an arbitrary list of users except for one distinguished user.
String	toString() Obtain a printable string representation of this context.
Trace	trace() Obtain a trace object for logging.
User	user() Obtain the user this object is currently contained by.
int	userCount() Get the number of users in this context.
Iterator<User>	userIterator() Obtain an iterator over the users currently in this context.

Methods inherited from class org.elkoserver.server.context.BasicObject

baseRef, checkpoint, checkpoint, container, contents, contextor, createItem, findActualTarget, getMod, handleMessage, holder, isClone, isEphemeral, markAsChanged, markAsDeleted, markAsEphemeral, name, noteCodependent, objectIsComplete, position, ref, sendToClones, setName, setPosition, setVisibility, visibleTo

Methods inherited from class java.lang.Object

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

Method Detail

baseCapacity

public int baseCapacity()

Obtain the number of users who may enter (a clone of) this context before another clone must be created. When the user count of the context reaches this number, users may still enter this specific clone if they specify its cloned context ID explicitly (and as long as maxCapacity() is not exceeded), but users who request entry to the context by specifying its generic context ID (that is, its ID before cloning) will be directed to a different clone.

Returns:

the number of users who may enter before the context clones.

closeGate

public void closeGate(String reason)

Close this context's gate, blocking new users from entering.

Parameters:

reason - String describing why this is being done.

forceClose

public void forceClose()

Close this context, even if it has been retained by one or more calls to the retain() method, and even if there are still users in it (this means kicking those users off).

gateIsClosed

public boolean gateIsClosed()

Test if this context's gate is closed. If the gate is closed, new users may not enter, even if the context is not full.

Returns:

true iff this context's gate is closed.

get

public BasicObject get(String ref)

Look up an object in this context's namespace. Note that the context's namespace is not the context's contents but the namespace of object identifiers that the context uses for resolving object references. This may be (indeed, normally is) shared with other active contexts on the same server.

Parameters:

ref - Reference string denoting the object desired.

Returns:

the object corresponding to 'ref', or null if there is no such object in the context's namespace.

getStaticObject

public Object getStaticObject(String ref)

Look up one of this server's static objects.

Parameters:

ref - Reference string denoting the object of interest.

Returns:

the static object corresponding to 'ref', or null if there is no such object in the server's static object table.

isSemiPrivate

public boolean isSemiPrivate()

Test if this context is semi-private. In a semi-private context, users appear to be in the context by themselves. They don't see each other come or go, and the 'push' and 'say' messages do not fan to the entire context. If mods wish to comply with the semi-private context concept (most won't), they need to use this test.

Returns:

the state of this context's semi-private flag.

isRestricted

public boolean isRestricted()

Test if this context is restricted, that is, whether it is closed to entry without an internally requested reservation.

Returns:

true iff this is a restricted context.

loadedFromRef

public String loadedFromRef()

Obtain the ref of the context descriptor from which this context was loaded.

maxCapacity

public int maxCapacity()

Obtain the number of users who may enter before no more are allowed in.

Returns:

the number of users who may enter before the context becomes full.

openGate

public void openGate()

Open this context's gate, allowing new users in if the context is not full.

registerContextShutdownWatcher

public void registerContextShutdownWatcher(ContextShutdownWatcher watcher)

Register a callback to be invoked when the context is shut down. Any number of such callbacks may be registered. The callback will be invoked after all users have gone but immediately before the context is checkpointed. In particular, shutdown watchers may make changes to the persistable state that will be checkpointed when the context is finally shut down.

Parameters:

watcher - An object to notify when the context is shut down.

registerUserWatcher

public void registerUserWatcher(UserWatcher watcher)

Register a callback to be invoked when a user enters or exits the context. Any number of such callbacks may be registered.

Parameters:

watcher - An object to notify when a user arrives.

release

public void release()

Release an earlier call to retain(). When release() has been called the same number of times as retain() has been, the context is free to shut down when empty. If the context is already empty, it will be shut down immediately. Calls to this method in excess of the number of calls to retain() will be ignored.

retain

public void retain()

Keep this context open even if all users exit (normally a context will be shut down automatically after the last user leaves). Each call to retain() must be matched by a corresponding call to release() in order for the context to be permitted to close normally (though it can still be closed by called forceClose()).

scheduleContextEvent

public void scheduleContextEvent(long millis,
                                 Runnable thunk)

Schedule a timer event associated with this context. This is different from scheduling a timer event directly using the Timer class in two significant ways: first, it ensures that the context is retained until after the event happens; second, it executes the event handler thunk on the server's run queue instead of in the Timer thread, so that we won't get reentrancy. Another notable difference is that unlike direct Timer events, there is no explicit cancellation mechanism. However, since the Timer's cancellation mechanism is not really as useful as it might at first appear, this is not as signficant.

Parameters:

millis - How long to wait until timing out.

thunk - Thunk to be run when the timeout happens.

sendObjectDescription

public void sendObjectDescription(Deliverer to,
                                  Referenceable maker)

Transmit a description of this context as a series of 'make' messages, such that the receiver will be able to construct a local presence of it.

Specified by:

sendObjectDescription in class BasicObject

Parameters:

to - Where to send the description.

maker - Maker object to address the message(s) to.

sendToNeighbors

public void sendToNeighbors(Deliverer exclude,
                            JSONLiteral message)

Send a message to everyone in this context save one. This message will be delivered to every client whose user is currently in the context except the one specified by the 'exclude' parameter.

Parameters:

exclude - Who to exclude from the send operation.

message - The message to send.

neighbors

public Deliverer neighbors(Deliverer exclude)

Obtain a Deliverer that will deliver to all of a user's neighbors in this context.

Parameters:

exclude - Who to exclude from the send operation.

Returns:

a Deliverer that wraps Context.sendToNeighbors

toList

public static Deliverer toList(List<BasicObject> toList)

Obtain a Deliverer that will deliver to an arbitrary list of users.

Parameters:

toList - List of users to deliver to

Returns:

a Deliverer that wraps toList

toListExcluding

public static Deliverer toListExcluding(List<BasicObject> toList,
                                        Deliverer exclude)

Obtain a Deliverer that will deliver to an arbitrary list of users except for one distinguished user.

Parameters:

toList - List of users to deliver to

exclude - The one to exclude

Returns:

a Deliverer that wraps toList, taking note to exclude the one odd user out

toString

public String toString()

Obtain a printable string representation of this context.

Overrides:

toString in class Object

Returns:

a printable representation of this context.

trace

public Trace trace()

Obtain a trace object for logging.

Returns:

a trace object for generating log messages from this context.

userCount

public int userCount()

Get the number of users in this context.

Returns:

the number of users currently in this context.

userIterator

public Iterator<User> userIterator()

Obtain an iterator over the users currently in this context. Note that this iterator is only valid within a single turn.

Returns:

an @{link java.util.Iterator} over this context's current users.

exit

@JSONMethod
public void exit(Deliverer from)
          throws MessageHandlerException

Handle the 'exit' verb. Exit the context and disconnect the user who sent it.

Throws:

MessageHandlerException

context

public Context context()

Obtain the context this object is associated with.

Specified by:

context in class BasicObject

Returns:

the context itself.

isContainer

public boolean isContainer()

Test if this object is a container. (Note: in this case, it is.)

Overrides:

isContainer in class BasicObject

Returns:

true -- all contexts are containers.

user

public User user()

Obtain the user this object is currently contained by.

Specified by:

user in class BasicObject

Returns:

null, since a context is never contained by a user.

send

public void send(JSONLiteral message)

Send a message to everyone in this context. The message will be delivered to every client whose user is currently in the context.

Specified by:

send in interface Deliverer

Parameters:

message - The message to send.

encode

public JSONLiteral encode(EncodeControl control)

Encode this context for transmission or persistence.

Specified by:

encode in interface Encodable

Parameters:

control - Encode control determining what flavor of encoding should be done.

Returns:

a JSON literal representing this context.