org.elkoserver.foundation.actor
Class RefTable

java.lang.Object
  org.elkoserver.foundation.actor.RefTable

All Implemented Interfaces:

Iterable<DispatchTarget>

Direct Known Subclasses:

Contextor, Workshop

public class RefTable
extends Object
implements Iterable<DispatchTarget>

A mapping from object reference strings (as they would be used in JSON message parameters) to the objects they refer to. This mapping may be modified at any time by adding or removing objects. The class also supports the direct invocation (from JSON messages) of JSON methods on the mapped objects.

By convention, the object references mapped by this table take the form:

type-ref

where: 'type' designates the kind of object being referred to, while 'ref' designates a specific object of that type. The 'ref' and accompanying hyphen separator are optional (actually, you are not required to follow this convention at all, but various classes provide convenience methods that are helpful if you do). The specific forms of 'type' and 'ref' themselves are unconstrained (other than the use of a hyphen as separator).

Constructor Summary

RefTable(TypeResolver resolver)
Constructor.

Method Summary

void	addClass(Class targetClass) Add JSON method dispatch information for a Java class to the table's message dispatcher, independent of any particular object instance.
void	addRef(Referenceable target) Add an object to the table, using the reference string it knows for itself.
void	addRef(String ref, DispatchTarget target) Add an object to the table, explicitly specifying its reference string.
List<DispatchTarget>	clones(String ref) Get a list of all objects in the table that have a common root reference string.
void	dispatchMessage(Deliverer from, DispatchTarget target, JSONObject message) Dispatch a JSON message directly to the appropriate method of a given object.
void	dispatchMessage(Deliverer from, JSONObject message) Dispatch a JSON message to the appropriate method on the object that the message says it is addressed to.
DispatchTarget	get(String ref) Look up an object by reference string.
Iterator<DispatchTarget>	iterator() Support iteration over all objects in the table.
void	remove(Referenceable object) Remove an object from the table, using the reference string it knows for itself.
void	remove(String ref) Remove an object from the table, explicitly specifying its reference string.
static String	rootRef(String ref) Extract the root from a reference string.

Methods inherited from class java.lang.Object

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

Constructor Detail

RefTable

public RefTable(TypeResolver resolver)

Constructor. Creates an empty reference table.

Parameters:

resolver - Type resolver for the type tags of JSON encoded object descriptors.

Method Detail

addClass

public void addClass(Class targetClass)

Add JSON method dispatch information for a Java class to the table's message dispatcher, independent of any particular object instance.

Parameters:

targetClass - Java class whose JSON methods are to be added.

addRef

public void addRef(String ref,
                   DispatchTarget target)

Add an object to the table, explicitly specifying its reference string.

Parameters:

ref - The reference string for the object.

target - The object referenced by the reference string.

addRef

public void addRef(Referenceable target)

Add an object to the table, using the reference string it knows for itself.

Parameters:

target - The object referenced by the reference string.

clones

public List<DispatchTarget> clones(String ref)

Get a list of all objects in the table that have a common root reference string.

Parameters:

ref - Reference string designating the object(s) of interest.

Returns:

a list of all objects in the table denoted by 'ref'. If 'ref' is the root reference of a clone group, returns a list of all the clones with that root reference. If 'ref' designates a non-clone object, returns a single element list containing that unique object. If there are no objects corresponding to 'ref', an empty list is returned.

dispatchMessage

public void dispatchMessage(Deliverer from,
                            DispatchTarget target,
                            JSONObject message)
                     throws MessageHandlerException

Dispatch a JSON message directly to the appropriate method of a given object.

Parameters:

from - Alleged sender of the message.

target - The object to which the message is being sent.

message - The message itself.

Throws:

MessageHandlerException - if there was some kind of problem handling the message.

dispatchMessage

public void dispatchMessage(Deliverer from,
                            JSONObject message)
                     throws MessageHandlerException

Dispatch a JSON message to the appropriate method on the object that the message says it is addressed to.

Parameters:

from - Alleged sender of the message.

message - The message itself.

Throws:

MessageHandlerException - if there was some kind of problem handling the message.

get

public DispatchTarget get(String ref)

Look up an object by reference string.

Parameters:

ref - Reference string denoting the object sought.

Returns:

the object designated by 'ref', or null if there is no such object.

iterator

public Iterator<DispatchTarget> iterator()

Support iteration over all objects in the table.

Specified by:

iterator in interface Iterable<DispatchTarget>

Returns:

an Iterator over all the objects.

remove

public void remove(String ref)

Remove an object from the table, explicitly specifying its reference string. It is permissible to specify a reference string that isn't actually there.

Parameters:

ref - Reference string for the object to be removed.

remove

public void remove(Referenceable object)

Remove an object from the table, using the reference string it knows for itself. It is permissible to remove an object that isn't actually there.

Parameters:

object - The object to be removed.

rootRef

public static String rootRef(String ref)

Extract the root from a reference string. This is everything before the second '-' character, or the whole string if there are fewer than two '-' characters in it. This is used in the addressing of clone objects.

Parameters:

ref - The reference string whose root is sought.

Returns:

the root reference string extracted from 'ref'.