BasicObject (neohabitat 0.1.0-SNAPSHOT API)

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

Fields
Modifier and Type	Field and Description
`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

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

Class BasicObject

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface org.elkoserver.json.Encodable

Field Detail

VIS_PUBLIC

VIS_PERSONAL

VIS_NONE

VIS_CONTAINER

Method Detail

baseRef

checkpoint

checkpoint

container

contents

context

contextor

createItem

getMod

holder

isClone

isContainer

isEphemeral

markAsChanged

markAsDeleted

markAsEphemeral

name

noteCodependent

objectIsComplete

position

sendObjectDescription

sendToClones

setName

setPosition

setVisibility

user

visibleTo

handleMessage

findActualTarget

ref