org.elkoserver.server.context
Class BasicObject

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

All Implemented Interfaces:

DefaultDispatchTarget, DispatchTarget, MessageRetargeter, Encodable, Referenceable

Direct Known Subclasses:

Context, Item, User

public abstract class BasicObject
extends Object
implements DefaultDispatchTarget, DispatchTarget, Encodable, MessageRetargeter, Referenceable

Base class of the fundamental addressable objects in the Context Server: context, user, and item.

All such objects share many characteristics in common, hence this base class. They are all Encodable since representations of them can be sent to the client, DispatchTargets since the client can address messages to them, MessageRetargeters since they can have Mods attached and so need to be able to retarget arriving messages to those mods, and Referenceable since they can be referred to in messages.

Field Summary

static int	VIS_CONTAINER Visible according to the visibility of its container.
static int	VIS_NONE Not visible to anyone.
static int	VIS_PERSONAL Visible to user holding object but nobody else.
static int	VIS_PUBLIC Visible to everyone in the enclosing context.

Method Summary

String	baseRef() Obtain an object clone's base reference.
void	checkpoint() Checkpoint this object, its contents, and any registered codependent objects (that is, objects whose state must be kept consistent with this object and vice versa).
void	checkpoint(ArgRunnable handler) Checkpoint this object, with completion handler.
BasicObject	container() Get this objects's container.
Iterable<Item>	contents() Obtain an iterable for this object's contents.
abstract Context	context() Obtain the context in which this object is located, regardless of how deeply nested in containers it might be.
Contextor	contextor() Obtain the contextor that created this object.
Item	createItem(String name, boolean isPossibleContainer, boolean isDeletable) Create a Item directly (i.e., create it at runtime rather than loading it from the database).
DispatchTarget	findActualTarget(Class type) Find the object to handle a message for some class (either the object itself or one of its mods).
Mod	getMod(Class type) Obtain one of this object's Mods.
void	handleMessage(Deliverer from, JSONObject msg) Handle an otherwise unhandled message.
BasicObject	holder() Obtain the user or context holding this object, regardless of how deeply nested in containers it might be.
boolean	isClone() Test if this object is a clone.
boolean	isContainer() Test if this object is allowed to be used as a container.
boolean	isEphemeral() Test if this object is ephemeral.
void	markAsChanged() Mark this object as needing to be written to persistent storage.
void	markAsDeleted() Mark this object as having been deleted.
void	markAsEphemeral() Mark this object as being ephemeral.
String	name() Obtain this object's name, if it has one.
void	noteCodependent(BasicObject obj) Note another object that needs to be checkpointed when this object is checkpointed (in order to maintain data consistency).
void	objectIsComplete() Inform this object that its construction is now complete.
Position	position() Obtain this object's position with respect to its container.
String	ref() Obtain this object's reference string.
abstract void	sendObjectDescription(Deliverer to, Referenceable maker) Transmit a description of this object as a series of 'make' messages, such that the receiver will be able to construct a local presence of it.
void	sendToClones(JSONLiteral message) Send a JSON message to all other clones of this object.
void	setName(String name) Set this object's name.
void	setPosition(Position pos) Set this object's position.
void	setVisibility(int visibility) Set this object's visibility without taking any other action.
abstract User	user() Obtain the user within which this object is contained, regardless of how deeply nested in containers it might be.
boolean	visibleTo(Deliverer receiver) Test if this object is visible to a given receiver.

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.elkoserver.json.Encodable

encode

Field Detail

VIS_PUBLIC

public static final int VIS_PUBLIC

Visible to everyone in the enclosing context.

See Also:

Constant Field Values

VIS_PERSONAL

public static final int VIS_PERSONAL

Visible to user holding object but nobody else.

See Also:

Constant Field Values

VIS_NONE

public static final int VIS_NONE

Not visible to anyone.

See Also:

Constant Field Values

VIS_CONTAINER

public static final int VIS_CONTAINER

Visible according to the visibility of its container.

See Also:

Constant Field Values

Method Detail

baseRef

public String baseRef()

Obtain an object clone's base reference. This is the object reference string with the clone sub-ID stripped off.

Returns:

the base reference string for this object, if it is a clone. If it is not a clone, the reference string itself will be returned.

checkpoint

public void checkpoint()

Checkpoint this object, its contents, and any registered codependent objects (that is, objects whose state must be kept consistent with this object and vice versa). In other words, ensure that any changes to the aforementioned objects' states that have been made since the last time they were checkpointed are saved to persistent storage.

checkpoint

public void checkpoint(ArgRunnable handler)

Checkpoint this object, with completion handler. Note that the completion handler is run when the write of the object itself completes; execution of the completion handler does not indicate that the object's contents or codedependent objects have yet been written!

Parameters:

handler - Optional completion handler.

container

public BasicObject container()

Get this objects's container. For objects not currently in any container (including non-containable objects), this will be null. The base case is that the object is not containable (contexts and users are never containable, while items may be), so this base implementation will always return null.

Returns:

the object this object is currently contained by.

contents

public Iterable<Item> contents()

Obtain an iterable for this object's contents. If the object has no contents, either because it is empty or because it is not a container, the iterable returned will be empty (i.e., its iterator's hasNext() method will return false right away) but null will never be returned.

Returns:

an iterable that iterates over this object's contents.

context

public abstract Context context()

Obtain the context in which this object is located, regardless of how deeply nested in containers it might be.

Returns:

the context in which this object is located, at whatever level of container nesting, or null if it is not in any context.

contextor

public Contextor contextor()

Obtain the contextor that created this object.

Returns:

the contextor associated with this object.

createItem

public Item createItem(String name,
                       boolean isPossibleContainer,
                       boolean isDeletable)

Create a Item directly (i.e., create it at runtime rather than loading it from the database). The new item will be contained by this object and have neither any contents nor any mods.

Parameters:

name - The name for the new item, or null if the name doesn't matter.

isPossibleContainer - true if the new item may itself be used as a container, false if not.

isDeletable - true if users may delete the new item at will, false if not.

Returns:

a new Item object as described by the parameters.

getMod

public Mod getMod(Class type)

Obtain one of this object's Mods.

Parameters:

type - The type of the mod desired.

Returns:

the mod of the given type, if there is one, else null.

holder

public BasicObject holder()

Obtain the user or context holding this object, regardless of how deeply nested in containers it might be. The base case is that this object is not held.

Returns:

the user or context within which this object is contained, at whatever level of container nesting, or null if it is not held by anything.

isClone

public boolean isClone()

Test if this object is a clone.

Returns:

true if this object is a clone object, false if not.

isContainer

public boolean isContainer()

Test if this object is allowed to be used as a container.

Returns:

true if this object can contain other objects, false if not.

isEphemeral

public boolean isEphemeral()

Test if this object is ephemeral. If an object is ephemeral, its state is not persisted. An object is made ephemeral by calling the markAsEphemeral() method.

Returns:

true if the object is ephemeral, false if not.

markAsChanged

public void markAsChanged()

Mark this object as needing to be written to persistent storage. Its state and the state of any codependent objects will be written out the next time the object is checkpointed.

markAsDeleted

public void markAsDeleted()

Mark this object as having been deleted. Note that unlike markAsChanged(), there is no corresponding method to unmark deletion; this is a one-way trip.

markAsEphemeral

public void markAsEphemeral()

Mark this object as being ephemeral.

name

public String name()

Obtain this object's name, if it has one.

Returns:

this object's name, or null if it is nameless.

noteCodependent

public void noteCodependent(BasicObject obj)

Note another object that needs to be checkpointed when this object is checkpointed (in order to maintain data consistency). An object may have any number of codependents.

Parameters:

obj - The other, codependent object.

objectIsComplete

public void objectIsComplete()

Inform this object that its construction is now complete. This will in turn inform any Mods that have expressed an interest in this event so that they can do any post-creation cleanup or initialization.

Application code should not normally need to call this method, since it is called automatically when an object is loaded from persistent storage. However, certain specialized applications that synthesize objects directly will need to call this after they finish attaching any synthesized Mods.

position

public Position position()

Obtain this object's position with respect to its container.

Returns:

this object's position, or null if it has none.

sendObjectDescription

public abstract void sendObjectDescription(Deliverer to,
                                           Referenceable maker)

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

Parameters:

to - Where to send the description.

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

sendToClones

public void sendToClones(JSONLiteral message)

Send a JSON message to all other clones of this object. The message will be delivered and dispatched to each clone as if it had been received from a client (except that the 'from' parameter will be null). If this Context Server is connected to a Director, the message will be relayed to the Director that will relay it in turn to any clones of this object that reside on other Context Servers connected to that Director. Note that this can be a very expensive operation if used injudiciously. This operation is only valid for users and contexts; it does not work on items. Also, if this object is not a clone, this method will have no effect.

Parameters:

message - The message to send.

setName

public void setName(String name)

Set this object's name.

Parameters:

name - The new name for the object to have.

setPosition

public void setPosition(Position pos)

Set this object's position.

Parameters:

pos - New position for the object.

setVisibility

public void setVisibility(int visibility)

Set this object's visibility without taking any other action. This can only be done once. An object's visibility determines the circumstances under which a description of the object will be transmitted to clients as part of the description of the containing context. Four cases are supported: VIS_PUBLIC indicates that the object is visible to anyone in the context, i.e., its description will always be transmitted. VIS_PERSONAL indicates that the object's description will only be sent to the user who is holding it and not to anyone else. VIS_NONE indicates that the object's description will never be sent to anyone. VIS_CONTAINER indicates that the object inherits its visiblity from its container, i.e., its description will be transmitted to anyone to whom its container's description is transmitted. If the visibility is not set by calling this method, a default visibility rule will be applied, which is equivalent in every way to VIS_PUBLIC except that it may be modified by calling this method. Note also that users and contexts are always implicitly set to VIS_PUBLIC regardless.

Parameters:

visibility - The visibility setting. This should be one of the constants VIS_PUBLIC, VIS_PERSONAL, VIS_NONE, or VIS_CONTAINER.

user

public abstract User user()

Obtain the user within which this object is contained, regardless of how deeply nested in containers it might be.

Returns:

the user in which this object is contained, at whatever level of container nesting, or null if it is not contained by a user.

visibleTo

public boolean visibleTo(Deliverer receiver)

Test if this object is visible to a given receiver. If the receiver is a User, then this will test the visibility of the object to that particular user. If the receiver is a Context, then it will test the visibility of the object to any user in that context.

Parameters:

receiver - User or context whose sightlines are at issue.

Returns:

true if this object is visible to 'receiver', false if not.

handleMessage

public void handleMessage(Deliverer from,
                          JSONObject msg)
                   throws MessageHandlerException

Handle an otherwise unhandled message.

Specified by:

handleMessage in interface DefaultDispatchTarget

Parameters:

from - Who sent the message.

msg - The message itself.

Throws:

MessageHandlerException - if there was a problem handling the message.

findActualTarget

public DispatchTarget findActualTarget(Class type)

Find the object to handle a message for some class (either the object itself or one of its mods). This method is part of the message handling subsystem; applications will not normally have need to call it.

Specified by:

findActualTarget in interface MessageRetargeter

Parameters:

type - The class associated with the message verb.

Returns:

an object that can handle messages for class 'type', or null if this object doesn't handle messages for that class.

ref

public String ref()

Obtain this object's reference string.

Specified by:

ref in interface Referenceable

Returns:

a string that can be used to refer to this object in JSON messages, either as the message target or as a parameter value.