org.safs.sockets

Class AbstractProtocolRunner

java.lang.Object

org.safs.sockets.AbstractProtocolRunner

All Implemented Interfaces:

java.lang.Runnable, ConnectionListener, DebugListener, NamedListener

Direct Known Subclasses:

RemoteClientRunner, SoloRemoteControlRunner

public abstract class AbstractProtocolRunner
extends java.lang.Object
implements java.lang.Runnable, ConnectionListener, DebugListener

This abstract class implements the necessary Threading of a SocketProtocol. The class provides the implementation needed by processes running on Windows, *nix, or Mac to control a remote client complying with this SocketProtocol.

Concrete subclasses must implement the abstract processProtocolMessage(String) in order to parse and process the messages received.

Currently, this server expects remote TCP services to be accepting connections on port 2410 as required by the underlying SocketProtocol.

Currently, this server uses port 2411 to contact and attempt a connection to those remote TCP services as required by the underlying SocketProtocol.

Both sides eventually need to be able to use a broader range of ports to prevent conflicts with other system resources.

There is an initial handshake or verification that occurs between this remote controller server and the on-device Service to confirm the device port owners conform to the SocketProtocol.

See Also:

SocketProtocol, SocketProtocol.MSG_PROTOCOL_VERSION_QUERY

Field Summary

Fields

Modifier and Type	Field and Description
boolean	_debugEnabled set to false to disable debug logging and improve performance.
SocketProtocol	protocolserver The underlying SocketProtocol instance performing the actual TCP communication.
protected java.util.Vector	runnerlisteners All Listeners registered with this instance--whether they be simple NamedListeners, DebugListeners, or ConnectionListeners.

Constructor Summary

Constructors

Constructor and Description
AbstractProtocolRunner() Default no-op constructor setting using all defaults.

Method Summary

Modifier and Type	Method and Description
boolean	addListener(NamedListener listener) Add any class or subclass of NamedListener to the registered Listeners list.
protected void	debug(java.lang.String text) Convenience routine to route internal debug messages to registered DebugListeners.
java.lang.String	getListenerName() NamedListener.getListenerName()
void	onReceiveConnection() Notify all registered ConnectionListeners a 2-way SocketProtocol connection has been established.
void	onReceiveDebug(java.lang.String message) Send all registered DebugListeners a Debug message received from a remote source.
void	onReceiveLocalShutdown(int cause) Notify all registered ConnectionListeners the 2-way SocketProtocol connection is shutting down on our local side.
void	onReceiveRemoteShutdown(int cause) Notify all registered ConnectionListeners the 2-way SocketProtocol connection is shutting down from the remote side.
abstract void	processProtocolMessage(java.lang.String message) Concrete implementations must insert the parsing and processing of the messages received from the underlying SocketProtocol.
boolean	removeListener(NamedListener listener) Remove a Listener from the list of registered Listeners for this instance.
void	run() Required Runnable interface for the Threaded execution of the underlying SocketProtocol.
abstract boolean	sendDispatchFile(java.lang.String filepath) Send the remote client a dispatch file message with the filepath to a file that should be readable by the remote client.
abstract boolean	sendDispatchProps(java.util.Properties trd) Send the remote client a dispatch Properties message containing a Serialized Properties object containing all the data needed for the execution of the Dispatch.
boolean	sendProtocolMessage(java.lang.String message) Send an arbitrary message through our SocketProtocol.
abstract boolean	sendShutdown() Send a shutdown command to the remote client.
void	setListenerName(java.lang.String name) NamedListener#setListenerName(String)
void	shutdownThread() Command the ProtocolRunner thread to shutdown.

Methods inherited from class java.lang.Object

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

Field Detail

_debugEnabled

public boolean _debugEnabled

set to false to disable debug logging and improve performance.

runnerlisteners

protected java.util.Vector runnerlisteners

All Listeners registered with this instance--whether they be simple NamedListeners, DebugListeners, or ConnectionListeners.

protocolserver

public SocketProtocol protocolserver

The underlying SocketProtocol instance performing the actual TCP communication.

Constructor Detail

AbstractProtocolRunner

public AbstractProtocolRunner()

Default no-op constructor setting using all defaults. This creates a default SocketProtocol instance running in local controller mode with this class added as a registered Debug and Connection Listener.

Subclass implementation should change any desired remote hostname/port settings and add any other Listeners prior to starting the Runnable thread.

See Also:

SocketProtocol.SocketProtocol(NamedListener)

Method Detail

debug

protected void debug(java.lang.String text)

Convenience routine to route internal debug messages to registered DebugListeners.

Parameters:

text -

addListener

public boolean addListener(NamedListener listener)

Add any class or subclass of NamedListener to the registered Listeners list. This allows the chaining or pass-thru of notifications from the underlying SocketProtocol object to the registered Listeners of this class.

Parameters:

listener -

Returns:

true if the Listener was successfully registered. false if the Listener was already registered.

See Also:

NamedListener, DebugListener, ConnectionListener

removeListener

public boolean removeListener(NamedListener listener)

Remove a Listener from the list of registered Listeners for this instance.

Parameters:

listener -

Returns:

true if the Listener was successfully removed. false if the Listener was not previously registered.

See Also:

NamedListener, DebugListener, ConnectionListener

run

public void run()

Required Runnable interface for the Threaded execution of the underlying SocketProtocol. This thread implements the required sequence of events for both the local controller and the remote client--both using a matching underlying SocketProtocol object--to connect through TCP Sockets and continuously monitor and exchange UTF-8 messages until a request for shutdown has been detected.

Subclasses of this abstract class would not normally change or override this method regardless of being local controllers or remote clients. This routine handles both through the SocketProtocol object.

The thread constantly loops performing the following tasks:

1. if not connected to a remote SocketProtocol, attempt to locate and connect to it.
2. check to see if the remote SocketProtocol has sent any valid content we need to dispatch.
3. if so, dispatch the content via processProtocolMessage(String)
4. if not shutdown, loop again.

When exiting the loop due to a shutdown, all registered ConnectionListeners will be notified via ConnectionListener.onReceiveLocalShutdown(int) that a "normal" shutdown has occurred. The thread will then attempt to finish by closing the SocketProtocol communication channels.

Note that sending messages from the local SocketProtocol to the remote SocketProtocol is NOT handled in this thread. Once the remote connection is made, registered ConnectionListeners are notified via ConnectionListener.onReceiveConnection(). Messages sent from the local using class to the remote SocketProtocol are sent via sendProtocolMessage(String) and usually from a different Thread. Consequently, the two-way communication should be considered asynchronous. Though it is expected the local and remote clients will attempt to maintain whatever "synchronous" communication is appropriate for their shared protocol implementation.

Specified by:

run in interface java.lang.Runnable

See Also:

sendProtocolMessage(String), SocketProtocol.closeProtocolRunners(), shutdownThread()

shutdownThread

public void shutdownThread()

Command the ProtocolRunner thread to shutdown. If the thread is running, this will ultimately null out all communication streams and close the active socket connection (if any) to the remote client.

See Also:

run()

getListenerName

public java.lang.String getListenerName()

NamedListener.getListenerName()

Specified by:

getListenerName in interface NamedListener

Returns:

name of listener. Might be null.

setListenerName

public void setListenerName(java.lang.String name)

NamedListener#setListenerName(String)

onReceiveDebug

public void onReceiveDebug(java.lang.String message)

Send all registered DebugListeners a Debug message received from a remote source. If no DebugListeners are registered, then the message may be routed to System.out. This will only happen if debug output is enabled--which it is by default.

Specified by:

onReceiveDebug in interface DebugListener

Parameters:

message -

See Also:

_debugEnabled, DebugListener.onReceiveDebug(String)

onReceiveConnection

public void onReceiveConnection()

Notify all registered ConnectionListeners a 2-way SocketProtocol connection has been established. If no ConnectionListeners are registered, then the notification may be routed to System.out.

Specified by:

onReceiveConnection in interface ConnectionListener

See Also:

ConnectionListener.onReceiveConnection()

onReceiveLocalShutdown

public void onReceiveLocalShutdown(int cause)

Notify all registered ConnectionListeners the 2-way SocketProtocol connection is shutting down on our local side. If no ConnectionListeners are registered, then the notification may be routed to System.out.

Specified by:

onReceiveLocalShutdown in interface ConnectionListener

Parameters:

caus - -- whether "normal", or not.

See Also:

ConnectionListener.onReceiveLocalShutdown(int), SocketProtocol.STATUS_SHUTDOWN_NORMAL, SocketProtocol.STATUS_SHUTDOWN_REMOTE_CLIENT

onReceiveRemoteShutdown

public void onReceiveRemoteShutdown(int cause)

Notify all registered ConnectionListeners the 2-way SocketProtocol connection is shutting down from the remote side. If no ConnectionListeners are registered, then the notification may be routed to System.out.

Specified by:

onReceiveRemoteShutdown in interface ConnectionListener

Parameters:

caus - -- whether "normal", or not.

See Also:

ConnectionListener.onReceiveRemoteShutdown(int), SocketProtocol.STATUS_SHUTDOWN_NORMAL, SocketProtocol.STATUS_SHUTDOWN_REMOTE_CLIENT

sendProtocolMessage

public boolean sendProtocolMessage(java.lang.String message)
                            throws java.io.InvalidObjectException

Send an arbitrary message through our SocketProtocol. Subclasses of AbstractProtocolRunner will usually define the message content and syntax to be appropriate for whatever the application is trying to accomplish. That is, different applications will send and receive different messages.

Parameters:

message -

Returns:

true if successfully sent

Throws:

java.io.InvalidObjectException - from the underlying SocketProtocol if no connection has yet been made.

See Also:

SocketProtocol.sendResponse(String)

processProtocolMessage

public abstract void processProtocolMessage(java.lang.String message)

Concrete implementations must insert the parsing and processing of the messages received from the underlying SocketProtocol. Subclasses of AbstractProtocolRunner will usually define the message content and syntax to be appropriate for whatever the application is trying to accomplish. That is, different applications will send and receive different messages.

Parameters:

message -

sendShutdown

public abstract boolean sendShutdown()

Send a shutdown command to the remote client. The format or syntax of this will be implementation specific.

A remote client Protocol Runner would implement this as a do-nothing method.

Returns:

true if the message was successfully sent.

sendDispatchProps

public abstract boolean sendDispatchProps(java.util.Properties trd)

Send the remote client a dispatch Properties message containing a Serialized Properties object containing all the data needed for the execution of the Dispatch. The format or syntax of this will be implementation specific.

A remote client Protocol Runner would implement this as a do-nothing method.

Parameters:

Properties - trd to send

Returns:

true if the message was sent successfully.

sendDispatchFile

public abstract boolean sendDispatchFile(java.lang.String filepath)

Send the remote client a dispatch file message with the filepath to a file that should be readable by the remote client. The format or syntax of this will be implementation specific.

A remote client Protocol Runner would implement this as a do-nothing method.

Parameters:

filepath - path to a remote client readable file.

Returns:

true if the message was successfully sent.