Context (neohabitat 0.1.0-SNAPSHOT API)

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

Methods
Modifier and Type	Method and Description
`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.

Class Context

Field Summary

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

Method Summary

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

Methods inherited from class java.lang.Object

Method Detail

baseCapacity

closeGate

forceClose

gateIsClosed

get

getStaticObject

isSemiPrivate

isRestricted

loadedFromRef

maxCapacity

openGate

registerContextShutdownWatcher

registerUserWatcher

release

retain

scheduleContextEvent

sendObjectDescription

sendToNeighbors

neighbors

toList

toListExcluding

toString

trace

userCount

userIterator

exit

context

isContainer

user

send

encode