org.elkoserver.foundation.json

Class MessageDispatcher

java.lang.Object

org.elkoserver.foundation.json.MessageDispatcher

public class MessageDispatcher
extends Object

A collection of precomputed Java reflection information that can dispatch JSON messages to methods of the appropriate classes.

Constructor Summary

Constructors

Constructor and Description
MessageDispatcher(TypeResolver resolver) Constructor.

Method Summary

Methods

Modifier and Type	Method and Description
void	addClass(Class targetClass) Perform the Java reflection operations needed to do JSON message dispatch on a given Java class.
void	dispatchMessage(Deliverer from, DispatchTarget target, JSONObject message) Dispatch a received JSON message by invoking the appropriate JSON method on the appropriate object with the parameters from the message.

Methods inherited from class java.lang.Object

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

Constructor Detail

MessageDispatcher

public MessageDispatcher(TypeResolver resolver)

Constructor. Creates an empty dispatcher.

Parameters:

resolver - Type resolver for the type tags of JSON encoded message parameter objects.

Method Detail

addClass

public void addClass(Class targetClass)

Perform the Java reflection operations needed to do JSON message dispatch on a given Java class. The class must be a JSON message handler class. Such classes have JSON message handler methods marked with the JSONMethod annotation. JSON message handler methods must have public scope, a return type of void, and a least one parameter, the first of which must have a type assignable to a variable of type Deliverer. The name of the method is the name of the JSON message verb that the method handles. The value of the attached JSONMethod annotation is an array of Strings, one for each method parameter except the initial Deliverer parameter. These strings will be the names of JSON message parameters and will be mapped one-to-one to the corresponding parameters of the method itself when it is invoked to handle a JSON message. If a method is annotated JSONMethod but does not follow these rules, no dispatch information will be recorded for that method and an error message will be logged.

Parameters:

targetClass - Class to compute method dispatch information for.

Throws:

JSONSetupError - if an annotated method breaks the rules for a JSON method.

dispatchMessage

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

Dispatch a received JSON message by invoking the appropriate JSON method on the appropriate object with the parameters from the message. This proceeds as follows: First, if 'from' is an instance of SourceRetargeter, then 'from' is replaced with result of calling its findEffectiveSource() method. Second, if 'target' is an instance of MessageRetargeter, then 'target' is replaced with the result of calling its findActualTarget() method. This step is repeated as many times as necessary until 'target' is no longer an instance of MessageRetargeter. If 'target' has a method with the same name as the message verb in 'message' and which matches the message handler signature pattern as described in the description of the addClass() method, then this method is invoked to handle the message and the message dispatch operation is complete. Note: for this to work, the 'target's class must have previously been inserted into this dispatcher using the addClass() method. If the previous step failed to located a message handler method, but 'target' is an instance of DefaultDispatchTarget, then its handleMessage() method is invoked to handle the message and the message dispatch operation is complete. Otherwise a MessageHandlerException is thrown.

Parameters:

from - The source from whom the message was allegedly received.

target - The object to which the message is addressed.

message - The message itself.

Throws:

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