stella.net

Class CommandReceiver

java.lang.Object

util.PropertyContainer

util.PropertyResources

util.rmi.RmiPropertyContainer

util.rmi.AbstractRmiCaster

stella.CastingContainer

stella.net.ReceiverServer

stella.net.ErrorServer

stella.net.CommandReceiver

All Implemented Interfaces:

Cloneable, Runnable, Remote, ErrorProcessing, RmiErrorCaster, CancelRunnable, ExitCleaning, Initializable, PropertySupplying, ResourceSupplying, RmiCaster, RmiPropertyBearing

Direct Known Subclasses:

TestReceiver

public abstract class CommandReceiver
extends ErrorServer

The command receiver, acting as a server. 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.

• On startup this class creates a server socket listening on the port specified in the properties of this receiver. This is part of the parent class behaviour.
• When a connection is established a helper thread is spawned. The helper thread, CommandReceiver.CommandHandler, takes over the client socket and is responsible for the entire communication ('protocol'). This helper thread is an extension to Handler.
• The main receiver class immediately retakes the listening state once the protocol thread is started.
• The CommandReceiver.CommandHandler first establishes the streams to the client (parent class functionality) and reads in the command sent by the client.
• It then calls the main class' getAcknowledgeNumber(stella.CommandEvent) with the just received command as an argument to get the number of acknowledges that constitute the whole cycle. The default implementation returns 1 always, concrete subclasses should override this method.
• The completion time required for the acknowledge event is gained via a call to the main class's getCompletionTime(stella.CommandEvent, int).
• The handler sends back an acknowledge event to the client and calls the abstract processCommand(stella.CommandEvent, int) of the main class.
• The processCommand(stella.CommandEvent, int) method returns true to indicate proper execution of the command (or of the actual subcommand in the case of macro commands). In this case, the handler thread loops between decrementing the acknowledge number, calling the getCompletionTime(stella.CommandEvent, int) and sending back acknowledge events.
• After the last return of the processCommand(stella.CommandEvent, int), i.e. as the counter decreases to zero, 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 in the sense that immediately after the error event is sent to the error listener a successful done is sent to the client, regardless of pending acknowledges. This behaviour is necessary to satisfy the command-sender acknowledge-done request chain.
• In the error case the error event is fetched via a call to the main class's getLastError() method.
• Any status messages that should be sent back must be initiated within the processCommand(stella.CommandEvent, int) method, because this is the base class's link to its concrete subclasses. These concrete subclasses in turn can rely on the receivers sendStatus(stella.ErrorEvent) method to send back a status message.
• Note that error, status, or relay messages (commands sent from the receiver to different receivers using the SCS) all use the same channel.

This class is only intended as an example class. Though the STELLA contract is to channel error messages through a dedicated socket connection to the SCS, the error casting capabilities of this class are obsolete but included for convenience in the testing phase. For an ascii-based error protocol, see ErrorReceiver.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	CommandReceiver.CommandHandler Handles the command protocol.

Nested classes/interfaces inherited from class util.PropertyResources

PropertyResources.Load, PropertyResources.URLResource

Field Summary

Fields

Modifier and Type	Field and Description
private ThreadGroup	commandgroup The thread group commands run in.
private static long	DEFAVAILABLE The default sleep interval between available queries.
private static ThreadGroup	DEFCOMMANDGROUP The default thread group commands run in.
private static long	DEFTIMEOUT The default sleep interval between available queries.
static String	KEY_AVAILABLE The key for sleep intervalls on available queries.
static String	KEY_COMMANDGROUP The key in the properties for the alarm thread group.
static String	KEY_TIMEOUT The key for join-time on cancel.
private Object	lockread A locking object to prevent simultaneous read access to socket.
private Object	lockwrite A locking object to prevent simultaneous write access to socket.
private CommandReceiver.CommandHandler	receive The command handler used for sending.

Fields inherited from class stella.net.ErrorServer

KEY_BIND, KEY_BINDNAME

Fields inherited from class stella.net.ReceiverServer

DEFSERVERPORT, handlerGroup, KEY_BUFFERSIZE, KEY_HANDLERPRIORITY, KEY_HOSTADDRESS, KEY_LOGOUT, KEY_RECEIVERNAME, KEY_SERVERPORT, KEY_SERVERPRIORITY

Fields inherited from class util.rmi.AbstractRmiCaster

ALTERNATEHOST, ALTERNATEPORT, KEY_EXPORTPORT, KEY_REGISTRYHOST, KEY_REGISTRYPORT

Fields inherited from class util.PropertyResources

KEY_NOINITONCREATE, POSTFIX_ALPHABET, POSTFIX_BYTES, POSTFIX_DIR, POSTFIX_EXT, POSTFIX_FILE, POSTFIX_LIST, POSTFIX_MODTIME, POSTFIX_URL

Fields inherited from class util.PropertyContainer

KEY_LISTSEPARATOR, KEY_MAPKEYVALUECHAR, KEY_MAPSEPARATOR

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

Constructors

Modifier	Constructor and Description
protected	CommandReceiver(Map qualify) Constructs a new receiver with the specified properties.

Method Summary

Modifier and Type	Method and Description
void	cancel() Cancels the server.
protected int	getAcknowledgeNumber(CommandEvent cmd) Returns the type of the first acknowledge event as a function of the command type.
protected abstract long	getCompletionTime(CommandEvent cmd, int acktype) Returns the completion time for the specified command.
protected ErrorEvent	getLastError() Returns the error event describing the last error that occured.
protected abstract boolean	processCommand(CommandEvent cmd, int acktype) Processes the given command.
protected void	protocol(Socket client) The method to handle the communication from the command-sending client to this receiver.
void	sendInfo(InfoEvent ie) Sends an info message to the normal command socket.
void	sendStatus(ErrorEvent ee) Sends the status event back to registered listeners.

Methods inherited from class stella.net.ErrorServer

exit, init, processError

Methods inherited from class stella.net.ReceiverServer

getAsociatedThread, getBufferSize, getHandlerPriority, getReceiverName, getServerPort, getServerPriority, initReceiverServer, maxTimeToCancel, run

Methods inherited from class stella.CastingContainer

addErrorListener, addRmiErrorListener, isValid, notifyErrorListener, removeErrorListener, removeRmiErrorListener, sendError, sendError, sendError, sendStatus, sendStatus

Methods inherited from class util.rmi.AbstractRmiCaster

bindToRegistry, bindToRegistry, bindToRegistry, bindToRegistry, bindToRegistry, bindToRegistry, casterExit, casterExit, getBindName, getBindName, unbindFromRegistry, unbindFromRegistry

Methods inherited from class util.rmi.RmiPropertyContainer

containsRemoteProperty, getRemoteProperties, getRemoteProperty, setRemoteProperty

Methods inherited from class util.PropertyResources

clone, createFrom, createFrom, createFrom, createInstance, getApplet, getAsResources, getLocate, getPropertiesToKey, getPropertiesToKey, getResource, getResourceAsStream, getResourceFromKey, getResources, hasLocalURLs, initProperties, keyCreate, keyCreate, reload, setApplet

Methods inherited from class util.PropertyContainer

augment, augment, 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, parseObject, reload, removeProperty, requires, rescanned, setObject, setProperties, setProperty, stringProperties, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface stella.rmi.RmiErrorCaster

addRmiErrorListener, removeRmiErrorListener

Methods inherited from interface util.rmi.RmiCaster

bindToRegistry, isValid, unbindFromRegistry

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

Field Detail

KEY_TIMEOUT

public static final String KEY_TIMEOUT

The key for join-time on cancel.

See Also:

Constant Field Values

KEY_AVAILABLE

public static final String KEY_AVAILABLE

The key for sleep intervalls on available queries.

See Also:

Constant Field Values

KEY_COMMANDGROUP

public static final String KEY_COMMANDGROUP

The key in the properties for the alarm thread group.

See Also:

Constant Field Values

DEFTIMEOUT

private static final long DEFTIMEOUT

The default sleep interval between available queries.

See Also:

Constant Field Values

DEFAVAILABLE

private static final long DEFAVAILABLE

The default sleep interval between available queries.

See Also:

Constant Field Values

DEFCOMMANDGROUP

private static final ThreadGroup DEFCOMMANDGROUP

The default thread group commands run in.

lockread

private final Object lockread

A locking object to prevent simultaneous read access to socket.

lockwrite

private final Object lockwrite

A locking object to prevent simultaneous write access to socket.

receive

private CommandReceiver.CommandHandler receive

The command handler used for sending. Only last instance available.

commandgroup

private final ThreadGroup commandgroup

The thread group commands run in.

Constructor Detail

CommandReceiver

protected CommandReceiver(Map qualify)

Constructs a new receiver with the specified properties. Use of this constructor ensures no additional properties to be set.
This constructor exports the newly created error receiver to the registry as an unicast object.

Method Detail

protocol

protected void protocol(Socket client)

The method to handle the communication from the command-sending client to this receiver. It takes the client socket as an argument and spawns a CommandReceiver.CommandHandler thread that implements the command-receiving protocol. The priority the handler thread should run at is defined in the base class and is querried with the ReceiverServer.getHandlerPriority() method.
As soon as the handler is started this method returns, allowing the receiver to regain its listening stage quickly.

Specified by:

protocol in class ReceiverServer

Parameters:

client - The client socket.

See Also:

CommandReceiver, ErrorReceiver

getAcknowledgeNumber

protected int getAcknowledgeNumber(CommandEvent cmd)

Returns the type of the first acknowledge event as a function of the command type. Subclasses should interfere here to reflect the correct behaviour. In the default implementation, this method returns 901.

getCompletionTime

protected abstract long getCompletionTime(CommandEvent cmd,
                                          int acktype)

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.

acktype - The type of the acknowledge that will be sent back.

processCommand

protected abstract boolean processCommand(CommandEvent cmd,
                                          int acktype)

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 ErrorEvent getLastError()

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

sendStatus

public void sendStatus(ErrorEvent ee)

Sends the status event back to registered listeners. This method should be called within concrete implementations of the processCommand(stella.CommandEvent, int) method.
Note that from the event type there is no difference between a status and an error event. This method therefore simply passes the argument to this classes ErrorServer.processError(stella.ErrorEvent) method.

Overrides:

sendStatus in class CastingContainer

sendInfo

public void sendInfo(InfoEvent ie)

Sends an info message to the normal command socket. This is meant for development only.

cancel

public void cancel()

Cancels the server. Also cancels any ongoing protocol.

Specified by:

cancel in interface CancelRunnable

Overrides:

cancel in class ReceiverServer