jvm.server
Interface CommunicationHandler

All Known Implementing Classes:

LocalCommunicationHandler, DistributedCommunicationHandler

public abstract interface CommunicationHandler

The heart of the whole comunication system.

It takes care of handling the entities communication with each other. The data structure offered by the Communication Thread should be used by this plugin in order to perform the real comm stuff between the entities.

We encourage you to write your own custom communication handlers or even better versions of the current existing ones. (Local, Distribuited)

Written: Radu Sion
Version: 0.25
Source: CommunicationHandler.java

Visit Smart Software

See Also:

Entity, ConnectServerThread, CommunicationServerThread

Method Summary

boolean	addNewEntity(Entity e) Called each time inside the host's CommunicationServerThread addNewEntity() as last statement, AFTER the new entity is inserted into the Communication ServerThread's structures, BEFORE starting the entity through Entity.up() This gives the handler the oportunity to maybe change the default message handler of this entity and to perform maybe other tasks.
boolean	communicate() This method is called periodically by the CommunicationServerThread inside a loop.
boolean	dispatchMessage(Message msg) Tries to handle a message and to send it to it's destination.
java.lang.String	getCommunicationHandlerVersion() Returns a version string of this handler.
void	initCommunicationHandler() Called AFTER the host's CommunicationServerThread constructor finishes, inside that constructor, as last statement BEFORE starting the time base.
void	remove(Entity eid) Called each time the CommunicationServerThread.remove() is called, BEFORE really entering the removal procedure.
void	setBasicVars(CommunicationServerThread c, SimpleProperties rhash) This is like some sort of constructor for the communication handler and gets called right after instantiating the handler.

nbsp;

Method Detail

getCommunicationHandlerVersion

public java.lang.String getCommunicationHandlerVersion()

Returns a version string of this handler.

setBasicVars

public void setBasicVars(CommunicationServerThread c,
                         SimpleProperties rhash)

This is like some sort of constructor for the communication handler and gets called right after instantiating the handler. The main reason why we use this is the fact that we don't have (yet) a mean to instantiate a class via it's name and also call it's natural constructor WITH PARAMETERS. That is why we have to have somehow assured that this method gets called RIGHT AFTER INSTANTIATING the class.

Remember that the main ideea with this class was to load it from the home server via Class.forName() (for example) and to use it like some sort of plugin inside a certain Communication Server Thread. If you subclass this you have to call inside your setBasicVars also this method !!! That is use something like super.setBasicVars() as first line inside your subclass setBasicVars() method.
No parameter checkings are performed.

Parameters:

c - Host thread

rhash - SimpleProperties to use in setting internal resources

See Also:

CommunicationServerThread

initCommunicationHandler

public void initCommunicationHandler()

Called AFTER the host's CommunicationServerThread constructor finishes, inside that constructor, as last statement BEFORE starting the time base.

addNewEntity

public boolean addNewEntity(Entity e)
                     throws SimpleException

Called each time inside the host's CommunicationServerThread addNewEntity() as last statement, AFTER the new entity is inserted into the Communication ServerThread's structures, BEFORE starting the entity through Entity.up() This gives the handler the oportunity to maybe change the default message handler of this entity and to perform maybe other tasks.
If this returns false the host CommunicationServerThread should remove this entity as it means that it won't be able to communicate.

Parameters:

e - The just added Entity

Returns:

True if ok, false otherwise

Throws:

SimpleException - It might just throw some exception in order to say something instead of just returning false

remove

public void remove(Entity eid)

Called each time the CommunicationServerThread.remove() is called, BEFORE really entering the removal procedure. The implementation should do some final actions here.

Parameters:

eid - Entity going to be removed

communicate

public boolean communicate()

This method is called periodically by the CommunicationServerThread inside a loop. It is ment to implement the whole communication between the clients. The ideea is to manage the thread delays outside etc. You may just ignore this and subclass maybe the handler from a thread and do all the handling inside the handler but this should NOT be the case under normal circumstances.
This method also returns a status that tells the CommunicationServerThread if everything ok. If some fatal communication problem arises this returns false and the CommunicationServerThread should shut down.

Returns:

True if ok, false if shutdown required

dispatchMessage

public boolean dispatchMessage(Message msg)

Tries to handle a message and to send it to it's destination. This method should be implemented indeed fully by each communication handler and it also has to be reentrant to allow for recursive calls.

Parameters:

Message - to send

Returns:

True if succeeded to send it fully, false if some error.