stella.rmi
Class ReceiverTorso

java.lang.Object
  util.PropertyContainer
      util.PropertyResources
          util.PropertyBundles
              util.rmi.RmiPropertyContainer
                  util.rmi.AbstractRmiListener
                      stella.rmi.AbstractRmiCasterAndListener
                          stella.rmi.ReceiverTorso

All Implemented Interfaces:

Cloneable, Remote, EventListener, Caster, ErrorSending, ErrorCaster, RmiAcknowledgeCaster, RmiCommandListener, RmiDoneCaster, RmiErrorCaster, ExitCleaning, Initializable, LocalizedSupplying, PropertySupplying, ResourceSupplying, RmiCaster, RmiEventListener, RmiListener, RmiPropertyBearing, StepInitializable

Direct Known Subclasses:

DeviceSimulator, GenericMaster, GenericSimulator

public abstract class ReceiverTorso
extends AbstractRmiCasterAndListener
implements RmiAcknowledgeCaster, RmiDoneCaster, ErrorCaster, RmiCommandListener, StepInitializable

The command receiver. This abstract base class comprises all the necessary methods to receive a command, send the acknowledge, process the command and send the done event. Concrete subclasses should provide their implementations of the command processor. The details of the class functionality can be described as follows.

• As the command listener receives a command within its rmiCommand(stella.CommandEvent) method, it generates a reply as an acknowledge command. To get the correct acknowledge number it calls the getAcknowledgeNumber(stella.CommandEvent) method with the command received as an argument. In the default implementation this method returns 1 which is always the number of the last acknowledge command. Concrete subclasses may interfere here if multiple acknowledge events are necessary.
• In order to feed the acknowledge event with the appropriate completion time the method getCompletionTime(stella.CommandEvent, int) with the command and the actual type number of the acknowledge event is called. This method must return fast otherwise the sending of the acknowledge event is delayed.
• After the acknowledge event has been sent, the abstract method processCommand(stella.CommandEvent, int) again with the command and the actual acknowledge type is called.
• As long as this method returns true, the type of the acknowledge is gradually decreased and a new acknowledge is sent, as described above.
• After the last return of the processCommand (called with an acknowledge type 901) a successful done event is generated and sent back.
• If a call to processCommand returns false an error has occured during the processing of the command. In this case the normal acknowledge-done chain is broken and an error event is sent back. Immediately after the error event a successful done is sent to satisfy the command-sender acknowledge-done request chain. Note that even in the case of an immediate error an acknowledge is sent back.
• In the latter case the error event is fetched via a call to the getLastError() method.
• Any status messages that should be sent back must be initiated within the processCommand method. To properly send back a status message, call the receivers AbstractRmiCasterAndListener.sendStatus(java.lang.String) with the desired status message as an argument.

To fulfill all the above requirements a receiver implements the following interfaces:

• AcknowledgeCaster
• DoneCaster
• ErrorCaster. All this interfaces must exploit their RMI-capabilities.

Nested Class Summary

protected class

ReceiverTorso.CommandHandler Handles the incomming command.

Nested classes/interfaces inherited from class util.PropertyResources

PropertyResources.URLResource

Field Summary

private List<RmiAcknowledgeListener>	acknowledgeList The Vector of the registered acknowledge listeners.
private ThreadGroup	commandGroup The thread group command handlers run in.
private static int	COUNT An internal counter for automatic naming.
private static long	DEFABORTTIME The default abort time acknowledge.
private static boolean	DEFBIND The default auto-binding as a RmiDoneCaster.
private static long	DEFERRORCOOL The default error-downcool time.
private static int	DEFINITDEPTH The default depth of the initialization process.
private List<RmiDoneListener>	doneList The Vector of the registered done listeners.
static String	KEY_BIND The key in the Map for auto-binding of the receiver.
static String	KEY_BINDNAME The binding name of this done and acknowledge caster.
static String	KEY_COMMANDCASTER The key in the properties for the default command casters.
static String	KEY_ERRORCOOL The key in the Map for error-downcool.
private List<CommandEvent>	process A vector of commands currently processed.

Fields inherited from class util.rmi.AbstractRmiListener

KEY_ALIVE, KEY_EXPORTPORT, KEY_INIT, KEY_LISTENERNAME, KEY_RETRY, KEY_RETRYSLEEP, KEY_SHUTDOWNDELAY

Fields inherited from class util.PropertyBundles

KEY_LOCALECOUNTRY, KEY_LOCALELANGUAGE, KEY_RESOURCEBUNDLES

Fields inherited from class util.PropertyResources

KEY_NOINITONCREATE, localurl, locate, POSTFIX_DIR, POSTFIX_EXT, POSTFIX_FILE, POSTFIX_LIST, POSTFIX_URL, urlset

Fields inherited from class util.PropertyContainer

KEY_LISTSEPARATOR, KEY_MAPKEYVALUECHAR, KEY_MAPSEPARATOR

Fields inherited from interface stella.rmi.RmiAcknowledgeCaster

NAMING_EXTENSION

Fields inherited from interface stella.rmi.RmiDoneCaster

NAMING_EXTENSION

Fields inherited from interface util.StepInitializable

KEY_INITDEPTH

Fields inherited from interface util.ResourceSupplying

KEY_URLRESOURCES, KEY_URLUSECONFIG, KEY_URLUSECURRENT, KEY_URLUSEHOME

Fields inherited from interface util.PropertySupplying

CONFIG, KEY_CLASS

Constructor Summary

protected

ReceiverTorso(Map<String,String> qualify) Constructs a new receiver with the specified properties.

Method Summary

void	addRmiAcknowledgeListener(RmiAcknowledgeListener ear) Registers an acknowledge listener to this command receiver.
void	addRmiDoneListener(RmiDoneListener ear) Adds a done event listener to this command receiver.
protected boolean	bindDefault() Initializes binding to all default command casters.
boolean	containsRemoteProperty(String key) Tests if this property container contains a certain property.
protected boolean	deregisterAtCaster(RmiCaster caster, Class ignored) Deregisters at the command caster.
boolean	equals(Object that) Two receiver torsos are equal, if their classes are equals.
void	exit() Exits the receiver torso.
protected abstract int	getAcknowledgeNumber(CommandEvent cmd) Returns the number of acknowledge event to be sent back as a function of the command type.
protected abstract long	getCompletionTime(CommandEvent cmd, int acknr) Returns the completion time for the specified command.
protected abstract ErrorEvent	getLastError() Returns the error event describing the last error that occured.
Map<String,Object>	getRemoteProperties() Returns the entire properties of this object as a map.
String	getRemoteProperty(String key) Returns a special property of this property container.
int	hashCode() Returns the class hash.
private void	init0() Zero-level, i.e.
private void	init3() Initializes this receiver by adding its casting capabilities to the registry if auto-binding is enabled.
void	initStep(int curdepth) The step-wise initialization.
private static int	nextCount() Gets the next available number at automatic naming.
protected void	notifyAcknowledgeListener(AcknowledgeEvent ae) Sends the acknowledge event to all registered acknowledge event listeners.This method parses through the Vector of acknowledge listeners and passes the argument to their gotAcknowledge method.
protected void	notifyDoneListener(DoneEvent de) Sends the done event to all registered done event listeners.This method parses through the Vector of done listeners and passes the argument to their gotDone method.
protected abstract boolean	processCommand(CommandEvent cmd, int acknr) Processes the given command.
protected boolean	registerAtCaster(RmiCaster caster, Class<?> service) Registers at the command caster.
void	removeRmiAcknowledgeListener(RmiAcknowledgeListener ear) Deregisters an acknowledge listener from this command receiver.
void	removeRmiDoneListener(RmiDoneListener ear) Deregisters a done event listener from this command receiver.
protected double	rescanned(String key, String old, String newval) On reload, unbind default, if command caster is affected.
void	rmiCommand(CommandEvent cmd) The command receiving method.
protected void	sendAllPrematureDone() Terminates all command currently processed except Aborting commands.
protected void	sendPrematureDone(CommandEvent cmd) Terminates the given command with a final done event.
String	setRemoteProperty(String key, String val) Sets a special property of this property container.
String	toString() Returns a short description of the receiver torso.
protected boolean	unbindDefault() Removes binding to all default command casters.

Methods inherited from class stella.rmi.AbstractRmiCasterAndListener

addErrorListener, addRmiErrorListener, bindToRegistry, getBindName, isValid, notifyErrorListener, removeErrorListener, removeRmiErrorListener, sendError, sendError, sendError, sendStatus, sendStatus, sendStatus, unbindFromRegistry

Methods inherited from class util.rmi.AbstractRmiListener

allBound, blockBinding, blockBinding, disconnect, getIP, getListenerName, isConnected, listenerName, releaseBinding, releaseBinding, startBinding, startBinding

Methods inherited from class util.PropertyBundles

clone, getLocalized, getLocalized, getLocalizedString, getLocalizedString, loadResource

Methods inherited from class util.PropertyResources

createFrom, createFrom, createFrom, getApplet, getAsResources, getLocalClassLoader, getPropertiesToKey, getPropertiesToKey, getResource, getResourceAsStream, getResourceFromKey, getResources, init, keyCreate, keyCreate, reload, setApplet

Methods inherited from class util.PropertyContainer

augment, augment, augment, defaultBoolean, defaultChar, defaultDouble, defaultFloat, defaultInt, defaultLong, defaultObject, defaultObject, defaultProperties, defaultProperty, getAsBoolean, getAsChar, getAsDouble, getAsEnums, getAsFloat, getAsInt, getAsList, getAsLong, getAsMap, getAsMap, getAsObject, getAsObject, getProperties, getProperty, has, isNew, parseObject, reload, removeProperty, setObject, setProperties, setProperty, stringProperties

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface util.rmi.RmiCaster

bindToRegistry, isValid, unbindFromRegistry

Methods inherited from interface stella.ErrorCaster

addErrorListener, removeErrorListener

Methods inherited from interface stella.rmi.RmiCommandListener

accepts

Methods inherited from interface util.rmi.RmiEventListener

getListenerName

Methods inherited from interface util.rmi.RmiListener

disconnect, isConnected

Methods inherited from interface util.ResourceSupplying

getResource, getResourceAsStream, getResources

Methods inherited from interface util.PropertySupplying

defaultBoolean, defaultChar, defaultDouble, defaultFloat, defaultInt, defaultLong, defaultObject, defaultObject, defaultProperties, defaultProperty, getAsBoolean, getAsChar, getAsDouble, getAsFloat, getAsInt, getAsList, getAsLong, getAsMap, getAsObject, getAsObject, getProperties, getProperty, has, parseObject, removeProperty, setObject, setProperty, stringProperties

Methods inherited from interface util.Initializable

init

Field Detail

KEY_COMMANDCASTER

public static final String KEY_COMMANDCASTER

The key in the properties for the default command casters.

See Also:

Constant Field Values

KEY_BINDNAME

public static final String KEY_BINDNAME

The binding name of this done and acknowledge caster.

See Also:

Constant Field Values

KEY_BIND

public static final String KEY_BIND

The key in the Map for auto-binding of the receiver.

See Also:

Constant Field Values

KEY_ERRORCOOL

public static final String KEY_ERRORCOOL

The key in the Map for error-downcool.

See Also:

Constant Field Values

DEFINITDEPTH

private static final int DEFINITDEPTH

The default depth of the initialization process.

See Also:

Constant Field Values

DEFBIND

private static final boolean DEFBIND

The default auto-binding as a RmiDoneCaster.

See Also:

Constant Field Values

DEFERRORCOOL

private static final long DEFERRORCOOL

The default error-downcool time.

See Also:

Constant Field Values

DEFABORTTIME

private static final long DEFABORTTIME

The default abort time acknowledge.

See Also:

Constant Field Values

COUNT

private static int COUNT

An internal counter for automatic naming.

process

private List<CommandEvent> process

A vector of commands currently processed.

commandGroup

private ThreadGroup commandGroup

The thread group command handlers run in.

acknowledgeList

private List<RmiAcknowledgeListener> acknowledgeList

The Vector of the registered acknowledge listeners.

doneList

private List<RmiDoneListener> doneList

The Vector of the registered done listeners.

Constructor Detail

ReceiverTorso

protected ReceiverTorso(Map<String,String> qualify)

Constructs a new receiver with the specified properties. Use of this constructor ensures that auto-binding of its caster abilities is always sepecified. Per default, all binidings are enabled.
Note that this constructor also sets a name for this receiver if none is specified in the properties. The use of the default behaviour is strongly discouraged because of confusions in the naming-based binding process that may follow out of the default naming method. Note that the PropertyResources.init() method should be called after construction.

Method Detail

nextCount

private static int nextCount()

Gets the next available number at automatic naming.

initStep

public void initStep(int curdepth)

The step-wise initialization. If curdepth

Specified by:

initStep in interface StepInitializable

Parameters:

curdepth - The current initialization depth.

init0

private void init0()

Zero-level, i.e. first init.

init3

private void init3()

Initializes this receiver by adding its casting capabilities to the registry if auto-binding is enabled. Tries to bind to the command caster(s).

exit

public void exit()

Exits the receiver torso. Unregisters from the command caster and removes its registry binding.

Specified by:

exit in interface ExitCleaning

Overrides:

exit in class AbstractRmiCasterAndListener

rescanned

protected double rescanned(String key,
                           String old,
                           String newval)

On reload, unbind default, if command caster is affected.

Overrides:

rescanned in class AbstractRmiListener

bindDefault

protected boolean bindDefault()

Initializes binding to all default command casters. Default command casters are given with their binding name in the key KEY_COMMANDCASTER.

unbindDefault

protected boolean unbindDefault()

Removes binding to all default command casters. Default command casters are given with their binding name in the key KEY_COMMANDCASTER.

registerAtCaster

protected boolean registerAtCaster(RmiCaster caster,
                                   Class<?> service)

Registers at the command caster. Does nothing if the handed reference is not of an RmiCommandCaster instance.

Specified by:

registerAtCaster in class AbstractRmiListener

Returns:

True, if this listener can register at the specified caster

deregisterAtCaster

protected boolean deregisterAtCaster(RmiCaster caster,
                                     Class ignored)

Deregisters at the command caster. Does nothing if the handed reference is not of an RmiCommandCaster instance.

Specified by:

deregisterAtCaster in class AbstractRmiListener

Returns:

True, if this listener can deregister at the specified caster

rmiCommand

public void rmiCommand(CommandEvent cmd)
                throws RemoteException

The command receiving method. Note that this class does not implement any command listener but merely provides the necessary method. This allows subclasses of receiver to implement the desired interface without caring about providing an implementation for the command method.

This method returns fast, i.e. it spawns a new thread that takes care of handling the command. This is done by instantaning a helper class ReceiverTorso.CommandHandler which is a inner class of the Receiver. It is constructed with the specified command as a parameter therefore multiple calls to this method oppose no problem.

Specified by:

rmiCommand in interface RmiCommandListener

Parameters:

cmd - The command to process.

Throws:

RemoteException

addRmiAcknowledgeListener

public void addRmiAcknowledgeListener(RmiAcknowledgeListener ear)
                               throws RemoteException

Registers an acknowledge listener to this command receiver.

Specified by:

addRmiAcknowledgeListener in interface RmiAcknowledgeCaster

Throws:

RemoteException

removeRmiAcknowledgeListener

public void removeRmiAcknowledgeListener(RmiAcknowledgeListener ear)
                                  throws RemoteException

Deregisters an acknowledge listener from this command receiver.

Specified by:

removeRmiAcknowledgeListener in interface RmiAcknowledgeCaster

Throws:

RemoteException

addRmiDoneListener

public void addRmiDoneListener(RmiDoneListener ear)
                        throws RemoteException

Adds a done event listener to this command receiver.

Specified by:

addRmiDoneListener in interface RmiDoneCaster

Throws:

RemoteException

removeRmiDoneListener

public void removeRmiDoneListener(RmiDoneListener ear)
                           throws RemoteException

Deregisters a done event listener from this command receiver.

Specified by:

removeRmiDoneListener in interface RmiDoneCaster

Throws:

RemoteException

getRemoteProperties

public Map<String,Object> getRemoteProperties()
                                       throws RemoteException

Returns the entire properties of this object as a map. Calls PropertyContainer.getProperties().

Specified by:

getRemoteProperties in interface RmiPropertyBearing

Overrides:

getRemoteProperties in class RmiPropertyContainer

Throws:

RemoteException

getRemoteProperty

public String getRemoteProperty(String key)
                         throws RemoteException

Returns a special property of this property container. Calls PropertyContainer.getProperty(java.lang.String).

Specified by:

getRemoteProperty in interface RmiPropertyBearing

Overrides:

getRemoteProperty in class RmiPropertyContainer

Parameters:

key - The key for the Map object.

Returns:

The value of the PropertyContainer.getProperty(java.lang.String) call.

Throws:

RemoteException

setRemoteProperty

public String setRemoteProperty(String key,
                                String val)

Sets a special property of this property container. Calls PropertyContainer.setProperty(java.lang.String, java.lang.String).

Specified by:

setRemoteProperty in interface RmiPropertyBearing

Overrides:

setRemoteProperty in class RmiPropertyContainer

Parameters:

key - The key for this Property.

value - The value of this Property.

containsRemoteProperty

public boolean containsRemoteProperty(String key)
                               throws RemoteException

Tests if this property container contains a certain property. Calls PropertyContainer.has(java.lang.String).

Specified by:

containsRemoteProperty in interface RmiPropertyBearing

Overrides:

containsRemoteProperty in class RmiPropertyContainer

Throws:

RemoteException

toString

public String toString()

Returns a short description of the receiver torso.

Overrides:

toString in class PropertyContainer

equals

public boolean equals(Object that)

Two receiver torsos are equal, if their classes are equals.

Overrides:

equals in class Object

hashCode

public int hashCode()

Returns the class hash.

Overrides:

hashCode in class Object

sendPrematureDone

protected void sendPrematureDone(CommandEvent cmd)

Terminates the given command with a final done event. Any acknowledge events still missing are skipped. The done event generated is a successful one. If the command is not found in the list of actually processed commands, nothing happens.

sendAllPrematureDone

protected void sendAllPrematureDone()

Terminates all command currently processed except Aborting commands.

getAcknowledgeNumber

protected abstract int getAcknowledgeNumber(CommandEvent cmd)

Returns the number of acknowledge event to be sent back as a function of the command type. Subclasses should interfere here to reflect the correct behaviour. In the default implementation, this method returns 1.

getCompletionTime

protected abstract long getCompletionTime(CommandEvent cmd,
                                          int acknr)

Returns the completion time for the specified command. If the command triggers multiple acknowledge events this method returns the completion time for the current subtask. The subtask can be derived from the acknowledge type handed over with the command. The type of the acknowledge is the one the completion time is requested for.

Parameters:

cmd - The command to process.

acknr - The number of the acknowledge that will be sent back.

processCommand

protected abstract boolean processCommand(CommandEvent cmd,
                                          int acknr)

Processes the given command. If the command consists of multiple subtasks this method processes only the current subtask. The subtask can be derived from the acknowledge type handed over with the command. The type of the acknowledge is the type of the acknowledge that has been sent immediately before this method was called.

The method returns true if the (sub)task was executed without an error. If it returns false the appropriate error event must be ready for retrival using the getLastError() method.

getLastError

protected abstract ErrorEvent getLastError()

Returns the error event describing the last error that occured. Subclasses should interfere here. The default implementation returns null.

notifyAcknowledgeListener

protected void notifyAcknowledgeListener(AcknowledgeEvent ae)

Sends the acknowledge event to all registered acknowledge event listeners.This method parses through the Vector of acknowledge listeners and passes the argument to their gotAcknowledge method.

Parameters:

ae - The AcknowledgeEvent to pass to the Listeners.

notifyDoneListener

protected void notifyDoneListener(DoneEvent de)

Sends the done event to all registered done event listeners.This method parses through the Vector of done listeners and passes the argument to their gotDone method.

Parameters:

de - The DoneEvent to pass to the Listeners.