stella.rmi
Class CasterTorso

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

All Implemented Interfaces:

Cloneable, Remote, EventListener, Caster, CommandLaunching, ErrorSending, ErrorCaster, ReplyDeliverer, RmiAcknowledgeListener, RmiCommandCaster, RmiDoneListener, RmiErrorCaster, AlarmHandler, ExitCleaning, Initializable, LocalizedSupplying, PropertySupplying, ResourceSupplying, RmiCaster, RmiEventListener, RmiListener, RmiPropertyBearing

Direct Known Subclasses:

CalibrationCaster, CCDCaster, DistinctCaster, EnvironmentCaster, SpectrographCaster, TelescopeCaster, TestCaster, WifsipCaster

public abstract class CasterTorso
extends AbstractRmiCasterAndListener
implements AlarmHandler, RmiAcknowledgeListener, RmiDoneListener, RmiCommandCaster, ErrorCaster, ReplyDeliverer, CommandLaunching, Initializable

The class to send commands. This class is used as a generic command event caster. Subclasses may specify the distinct types of command casters, see TelescopeCaster. It provides the following capabilities:

• Send a command with castCommand(stella.CommandEvent). This method calls the RmiCommandListener.rmiCommand(stella.CommandEvent) method of all registered listeners.
• After sending a command an Alarm is started to eventually time-out the acknowledge receiving.
• If the AcknowledgeEvent is received in time another alarm is started, its time-out depending on the completion time handed over with the acknowledge event.
• The caster does not care about the number of acknowledge events sent. Its simple contract is: Wait for an acknowledge event after the command is cast and end the cycle with a done event.
• Any time out events (i.e. on of the alarms is set off) is passed to registered error listeners. According to convention there are two distinct type of time-out errors:
  • Receiver time outs, type 801, if the first acknowledge event was not received in time.
  • Completion time outs, type 802, if the completion time submitted with the previous acknowledge event could not be met.
• If the command receiver fires an error event it is immediately passed to its error listeners. Note that the caster does not know about this process and hence relies on the receiver to send a successful done event. Any pending acknowledge events may be skipped, but the final done event is essential.
• For the -hopefully- very rare event of an unsuccessful done a done error, type 800, is passed to the error listeners.
• In cases were the chain of command-acknowledge(s)-done is broken (e.g. an acknowledge is received that does not belong to a command or a done is received without a prior acknowledge) a software error, type 809, is cast to the error listeners. This error indicates a software bug.

To properly fullfil all of the specified requirements stated above a Caster must act in a variety of ways (i.e. implement interfaces), namly:

• AcknowledgeListener
• DoneListener. All of these implementations must be fully RMI capable.
• ErrorCaster. As an error event caster this class should only cast to local listeners.
• ReplyDelivering. This interface defines the functionality a ReplySubscriber relies on in talking to his client.

Additionally a ReplySubscriber can be associated with this caster instance. All incoming replies (i.e. acknowledge and done events are checked whether they should be forwarded to the reply subscriber. The intended use for this is that some sort of a command sequencer is not necessaryly interested in all acknowledge and done events sent back to the caster, but only in some that allow the sequencer optimal timing.

See Also:

ReplySubscriber

Nested Class Summary

Nested classes/interfaces inherited from class util.PropertyResources

PropertyResources.URLResource

Field Summary

private Hashtable	active A list of all commands active.
private ThreadGroup	alarmGroup The ThreadGroup the alarms should run in.
private int	alarmNumber The numbering for the alarms.
private static char	ALARMSEPARATOR The separator char between execute-keys and alarm number.
private Hashtable	alarmTable The table mapping commands to alarms.
private Vector	commandList The registered command listeners.
private static String	COMPLETE The name for alarms waiting for done or additional acknowledges.
private boolean	crash To avoid repeating crash errors.
private static boolean	DEFBIND The default command-binding behaviour.
private static long	DEFTIMEOUT The default acknowledge time-out value, in ms.
private static String	FIRSTACKNOWLEDGE The name for alarms waiting for the first acknowledge.
private ReplySubscriber	forward The registered reply subscriber.
static String	KEY_ACKNOWLEDGECASTER The key in the properties for the acknowledge casters.
static String	KEY_ACKNOWLEDGETIMEOUT The key in the properties for the acknowledge time out.
static String	KEY_ALARMGROUP The key in the properties for the alarm thread group.
static String	KEY_BIND The key matching the default command casting binding.
static String	KEY_DONECASTER The key in the properties for the done casters.
private CommandEvent	lastCommand A copy of the last command cast.
private Vector	pattern The replies the reply subscriber is interested in.
private Hashtable	setOffAlarms The table mapping alarms that have been set off to commands.

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.RmiCommandCaster

NAMING_EXTENSION

Fields inherited from interface util.PropertySupplying

CONFIG, KEY_CLASS

Fields inherited from interface util.ResourceSupplying

KEY_URLRESOURCES, KEY_URLUSECONFIG, KEY_URLUSECURRENT, KEY_URLUSEHOME

Constructor Summary

protected

CasterTorso(Map qualify) Constructs a new caster with the specified properties.

Method Summary

void	addRmiCommandListener(RmiCommandListener ear) Registers a rmi command event listener to this property container.
void	announceInterest(ReplyEvent re) Adds a new reply event pattern to the pattern list.
void	castCommand(CommandEvent ce) The public method called to cast a command to registered listeners.
private void	checkForward(ReplyEvent re) Checks if the received reply message should be forwarded to the registered reply subscriber.
protected boolean	deregisterAtCaster(RmiCaster caster, Class service) Deregisters at the specified caster if the caster is either an RmiDoneCaster or an RmiAcknowledgeCaster
void	exit() Derigsters from the acknowledge and done casters and unbinds from the registry.
long	getAcknowledgeTimeOut() Returns the acknowledge time out, in ms.
ThreadGroup	getAlarmGroup() Returns the thread group the done and acknowledge time-out alarms should run in.
String	getClientName() Returns the name of this caster.
CommandEvent	getExitCommand() Default implementation of exit command is null.
void	init() Initializes the command caster.
boolean	isReady() Checks if all connections to registered listeners are intact.
private int	nextAlarmNumber() Returns the next available number for the alarm numbering.
void	recastCommand() Recasts the last command.
protected boolean	registerAtCaster(RmiCaster caster, Class service) Binds to an caster.
void	registerReplySubscriber(ReplySubscriber forward) Registers the reply subscriber.
void	removeRmiCommandListener(RmiCommandListener ear) Deregisters an rmi command event listener from this property container.
void	rmiGotAcknowledge(AcknowledgeEvent ae) The receiver method for acknowledge events.
void	rmiGotDone(DoneEvent de) The receiver method for done events.
void	setOff(String alarm) The method called by the internal alarms of this caster if a problem with in-time replies occured.
String	toString() Returns a short description of the receiver torso.

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, rescanned, startBinding, startBinding

Methods inherited from class util.rmi.RmiPropertyContainer

containsRemoteProperty, getRemoteProperties, getRemoteProperty, setRemoteProperty

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, 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

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

Methods inherited from interface util.rmi.RmiEventListener

getListenerName

Methods inherited from interface util.rmi.RmiListener

disconnect, isConnected

Methods inherited from interface util.rmi.RmiCaster

bindToRegistry, isValid, unbindFromRegistry

Methods inherited from interface stella.ErrorCaster

addErrorListener, removeErrorListener

Methods inherited from interface stella.CommandLaunching

getShutdownCommand, handles

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.ResourceSupplying

getResource, getResourceAsStream, getResources

Field Detail

KEY_BIND

public static final String KEY_BIND

The key matching the default command casting binding.

See Also:

Constant Field Values

KEY_ACKNOWLEDGECASTER

public static final String KEY_ACKNOWLEDGECASTER

The key in the properties for the acknowledge casters.

See Also:

Constant Field Values

KEY_DONECASTER

public static final String KEY_DONECASTER

The key in the properties for the done casters.

See Also:

Constant Field Values

KEY_ACKNOWLEDGETIMEOUT

public static final String KEY_ACKNOWLEDGETIMEOUT

The key in the properties for the acknowledge time out.

See Also:

Constant Field Values

KEY_ALARMGROUP

public static final String KEY_ALARMGROUP

The key in the properties for the alarm thread group.

See Also:

Constant Field Values

DEFTIMEOUT

private static final long DEFTIMEOUT

The default acknowledge time-out value, in ms.

See Also:

Constant Field Values

DEFBIND

private static final boolean DEFBIND

The default command-binding behaviour.

See Also:

Constant Field Values

FIRSTACKNOWLEDGE

private static final String FIRSTACKNOWLEDGE

The name for alarms waiting for the first acknowledge.

See Also:

Constant Field Values

COMPLETE

private static final String COMPLETE

The name for alarms waiting for done or additional acknowledges.

See Also:

Constant Field Values

ALARMSEPARATOR

private static final char ALARMSEPARATOR

The separator char between execute-keys and alarm number.

See Also:

Constant Field Values

lastCommand

private CommandEvent lastCommand

A copy of the last command cast. Used for recasting.

active

private Hashtable active

A list of all commands active.

commandList

private Vector commandList

The registered command listeners.

forward

private ReplySubscriber forward

The registered reply subscriber.

pattern

private Vector pattern

The replies the reply subscriber is interested in.

alarmGroup

private ThreadGroup alarmGroup

The ThreadGroup the alarms should run in.

alarmTable

private Hashtable alarmTable

The table mapping commands to alarms.

setOffAlarms

private Hashtable setOffAlarms

The table mapping alarms that have been set off to commands.

alarmNumber

private int alarmNumber

The numbering for the alarms. Allows distinct names.

crash

private boolean crash

To avoid repeating crash errors.

Constructor Detail

CasterTorso

protected CasterTorso(Map qualify)
               throws RemoteException

Constructs a new caster with the specified properties. Use of this constructor guarantees that the acknowledge time-out (see KEY_ACKNOWLEDGETIMEOUT), the thread group the alarms should run in KEY_ALARMGROUP and the caster bind name #KEY_BINDNAME is always set. Additionally the retry intervall and the maximum number of retries is set if not already given.

Parameters:

qualify - The properties of this caster

Throws:

RemoteException

Method Detail

init

public void init()

Initializes the command caster. This means scanning the properties for acknowledge and done casters using the appropriate keys. The value matched to this key must follow the following prescriptions:

• Multiple casters are combined in a comma separated list without spaces.
• The caster names must be ready for the Naming format.

This newly initialized instance of a Caster immediately register itself to all casters found.

According to the binding rules defined in AbstractRmiListener#initBinding some wait cycles may be introduced if the according caster cannot be found in the registry.

Specified by:

init in interface Initializable

Overrides:

init in class PropertyResources

exit

public void exit()

Derigsters from the acknowledge and done casters and unbinds from the registry.

Specified by:

exit in interface ExitCleaning

Overrides:

exit in class AbstractRmiCasterAndListener

toString

public String toString()

Returns a short description of the receiver torso.

Overrides:

toString in class PropertyContainer

registerAtCaster

protected boolean registerAtCaster(RmiCaster caster,
                                   Class service)

Binds to an caster. If the argumental RmiCaster is an instance of RmiDoneCaster this done listener registers to it via the RmiDoneCaster.addRmiDoneListener(stella.rmi.RmiDoneListener) method. If the argumental RmiCaster is an instance of RmiAcknowledgeCaster this acknowledge listener registers to it via the RmiAcknowledgeCaster.addRmiAcknowledgeListener(stella.rmi.RmiAcknowledgeListener) method.

If the argument is neither of these two types the method returns silently.

Specified by:

registerAtCaster in class AbstractRmiListener

Returns:

True, if this listener can register at the specified caster

See Also:

deregisterAtCaster(util.rmi.RmiCaster, java.lang.Class)

deregisterAtCaster

protected boolean deregisterAtCaster(RmiCaster caster,
                                     Class service)

Deregisters at the specified caster if the caster is either an RmiDoneCaster or an RmiAcknowledgeCaster

Specified by:

deregisterAtCaster in class AbstractRmiListener

Returns:

True, if this listener can deregister at the specified caster

See Also:

registerAtCaster(util.rmi.RmiCaster, java.lang.Class)

getExitCommand

public CommandEvent getExitCommand()

Default implementation of exit command is null.

Specified by:

getExitCommand in interface CommandLaunching

getClientName

public String getClientName()

Returns the name of this caster. The name is not necessarilly identical to the name used in binding.

Specified by:

getClientName in interface CommandLaunching

getAcknowledgeTimeOut

public long getAcknowledgeTimeOut()

Returns the acknowledge time out, in ms. Use of the standard constructor guarantees that this property is set.

getAlarmGroup

public ThreadGroup getAlarmGroup()

Returns the thread group the done and acknowledge time-out alarms should run in.

registerReplySubscriber

public void registerReplySubscriber(ReplySubscriber forward)

Registers the reply subscriber. All received reply messages are checked whether they should be forwarded to the subscriber. Call this method with a null argument to disable reply forwarding.

Specified by:

registerReplySubscriber in interface ReplyDeliverer

Parameters:

forward - The reply subscriber interested in received replies.

castCommand

public void castCommand(CommandEvent ce)

The public method called to cast a command to registered listeners. This method does:

• Notify the registered command listeners. Note that the base class does not define any command casting capabilities. This must be provided by concrete subclasses.
• Start an alarm thread with the acknowledge time-out.
• Registers the alarm on the alarm table. If the alarm table already contains an alarm linked to the key a software error is cast ( type 809).

Note that from the chain of command it is never possible that there is already an alarm mapped to the commands key. If this situation occurs nevertheless this is a software bug and is reported by casting a software error.

Specified by:

castCommand in interface CommandLaunching

recastCommand

public void recastCommand()

Recasts the last command. The last command is kept in a private copy. The only problem is to get rid of unnecessary acknowledge time outs.

Because recasting of a command is only useful if the command has not been completely received at the receiver, only a first acknowledge may be in the waiting queue.

Specified by:

recastCommand in interface CommandLaunching

nextAlarmNumber

private int nextAlarmNumber()

Returns the next available number for the alarm numbering.

rmiGotAcknowledge

public void rmiGotAcknowledge(AcknowledgeEvent ae)
                       throws RemoteException

The receiver method for acknowledge events. This method does:

• A Lookup in the alarm table whether the execute group key of this acknowledge event is present.
• If the alarm thread cannot be found a software error is cast (type 809). In this case the method returns immediately.
• The alarm asociated with the previous acknowledge event is canceled.
• The acknowledge event received is checked for forwarding to the reply subscriber.
• A new alarm is started with the completion time delivered with the acknowledge event.
• The new alarm is mapped to this acknowledge events key.

Note that from the chain of command it is never possible that there is no alarm mapped to the acknowledge key. If this situation occurs it signals a software bug and is reported by casting a software error.

Specified by:

rmiGotAcknowledge in interface RmiAcknowledgeListener

Throws:

RemoteException

rmiGotDone

public void rmiGotDone(DoneEvent de)
                throws RemoteException

The receiver method for done events. This method does:

• A lookup in the alarm table whether the execute group key of this done event is present.
• If the alarm thread cannot be found a software error is cast (type 809). In this case the method returns immediately.
• The alarm asociated with the previous acknowledge event is canceled.
• The done event received is checked for forwarding to the reply subscriber.

Note that from the chain of command it is never possible that there is no alarm mapped to the done key. If this situation occurs it signals a software bug and is reported by casting a software error.

Specified by:

rmiGotDone in interface RmiDoneListener

Throws:

RemoteException

checkForward

private void checkForward(ReplyEvent re)

Checks if the received reply message should be forwarded to the registered reply subscriber. This method scans through all stored reply event patterns and tries to find a match to the argument reply event. Due to the convention of the match method, see ReplyEvent.matches(stella.ReplyEvent) all stored reply patterns are used as arguments to the reply event under question.

If the argument is matched to one of the patterns the argument is immediately passed to the registered reply subscriber and the pattern is removed from the list.

Note that this method synchronizes on the pattern vector.

announceInterest

public void announceInterest(ReplyEvent re)

Adds a new reply event pattern to the pattern list. This method should be called by the reply subscriber prior to sending the command that will produce the appropriate reply to the caster (castCommand(stella.CommandEvent)). Otherwise timing fluctuation may cause problems.

Specified by:

announceInterest in interface ReplyDeliverer

setOff

public void setOff(String alarm)

The method called by the internal alarms of this caster if a problem with in-time replies occured. The name of the alarm is used to either generate a acknowledge time-out error or a completion time-out error. An acknowledge time-out means that the listener did not sent back the acknowledge following the command. This error probably suggests some connection problem since no other action than simply replying to the command is involved. Completion time-outs may indicate that there is a problem with the hardware involved in completing the required task.
Note that acknowledge events sent after the verry first produce completion time-outs rather than acknowledge time-outs.

Specified by:

setOff in interface AlarmHandler

addRmiCommandListener

public void addRmiCommandListener(RmiCommandListener ear)
                           throws RemoteException

Registers a rmi command event listener to this property container. This method is used for non-local listeners running in a different VM.

Specified by:

addRmiCommandListener in interface RmiCommandCaster

Throws:

RemoteException

removeRmiCommandListener

public void removeRmiCommandListener(RmiCommandListener ear)
                              throws RemoteException

Deregisters an rmi command event listener from this property container. This method is used for non-local listeners running in a different VM.

Specified by:

removeRmiCommandListener in interface RmiCommandCaster

Throws:

RemoteException

isReady

public boolean isReady()

Checks if all connections to registered listeners are intact. If no listeners are registered this method returns true.

Simply calls the RmiListener.isConnected() method, which should return true or throw a remote exception.

Specified by:

isReady in interface CommandLaunching