jmri.jmrix
Class AbstractMRTrafficController

Show UML class diagram

java.lang.Object
  jmri.jmrix.AbstractMRTrafficController

Direct Known Subclasses:

AbstractCanTrafficController, AbstractMRNodeTrafficController, Dcc4PcTrafficController, EasyDccTrafficController, EcosTrafficController, JMRIClientTrafficController, MarklinTrafficController, MrcTrafficController, NceTrafficController, RfidTrafficController, SerialTrafficController, SerialTrafficController, SRCPTrafficController, TamsTrafficController, XNetTrafficController

public abstract class AbstractMRTrafficController
extends Object

Abstract base for TrafficControllers in a Message/Reply protocol.

Two threads are used for the actual communication. The "Transmit" thread handles pushing characters to the port, and also changing the mode. The "Receive" thread converts characters from the input stream into replies.

A third thread is registered by the constructor as a shutdown hook. It triggers the necessary cleanup code

"Mode" refers to the state of the command station communications.
"State" refers to the internal state machine used to control the mode, e.g. to send commands to change mode.
"Idle" is a special case, where there is no communications in process, and the port is waiting to do something.

Nested Class Summary

(package private) static class	AbstractMRTrafficController.CleanupHook Internal class to handle traffic controller cleanup.
protected static class	AbstractMRTrafficController.RcvNotifier Internal class to remember the Reply object and destination listener with a reply is received.
protected static class	AbstractMRTrafficController.XmtNotifier Internal class to remember the Message object and destination listener when a message is queued for notification.

Field Summary

protected boolean	allowUnexpectedReply
static int	AUTORETRYSTATE
protected Vector<AbstractMRListener>	cmdListeners
(package private) boolean	connectionError
AbstractPortController	controller
protected boolean	flushReceiveChars
static int	IDLESTATE
protected DataInputStream	istream
(package private) LinkedList<AbstractMRListener>	listenerQueue
(package private) static org.slf4j.Logger	log
protected int	maxRcvExceptionCount
protected int	mCurrentMode
protected int	mCurrentState
protected AbstractMRListener	mLastSender
(package private) LinkedList<AbstractMRMessage>	msgQueue Messages to be transmitted
protected int	mWaitBeforePoll
static int	NORMALMODE
static int	NOTIFIEDSTATE
static int	OKSENDMSGSTATE
protected OutputStream	ostream
static int	POLLSTATE
static int	PROGRAMINGMODE
protected boolean	rcvException
(package private) Thread	rcvThread
protected boolean	replyInDispatch
static int	WAITMSGREPLYSTATE
static int	WAITREPLYINNORMMODESTATE
static int	WAITREPLYINPROGMODESTATE
protected long	waitTimePoll
protected boolean	xmtException
protected Runnable	xmtRunnable
(package private) Thread	xmtThread

Constructor Summary

AbstractMRTrafficController()

Method Summary

protected int	addHeaderToOutput(byte[] msg, AbstractMRMessage m) Add header to the outgoing byte stream.
protected void	addListener(AbstractMRListener l)
protected void	addTrailerToOutput(byte[] msg, int offset, AbstractMRMessage m) Add trailer to the outgoing byte stream.
protected boolean	canReceive() Override in the system specific code if necessary
protected void	connectionWarn()
void	connectPort(AbstractPortController p) Make connection to existing PortController object.
void	disconnectPort(AbstractPortController p) Break connection to existing PortController object.
protected abstract boolean	endOfMessage(AbstractMRReply r)
protected abstract AbstractMRMessage	enterNormalMode()
protected abstract AbstractMRMessage	enterProgMode()
protected int	enterProgModeDelayTime()
protected void	finalize()
protected abstract void	forwardMessage(AbstractMRListener client, AbstractMRMessage m) Implement this to forward a specific message type to a protocol-specific listener interface.
protected abstract void	forwardReply(AbstractMRListener client, AbstractMRReply m)
protected void	forwardToPort(AbstractMRMessage m, AbstractMRListener reply) Actually transmits the next message to the port
AbstractMRListener	getLastSender()
String	getPortName() Get the port name for this connection
AbstractMRTrafficController	getSelfLock()
void	handleOneIncomingReply() Handle each reply when complete.
protected void	handleTimeout(AbstractMRMessage msg, AbstractMRListener l)
boolean	hasTimeouts()
protected int	lengthOfByteStream(AbstractMRMessage m) Determine how much many bytes the entire message will take, including space for header and trailer
protected void	loadChars(AbstractMRReply msg, DataInputStream istream) Get characters from the input source, and file a message.
protected AbstractMRTrafficController.RcvNotifier	newRcvNotifier(AbstractMRReply pMsg, AbstractMRListener pDest, AbstractMRTrafficController pTC)
protected abstract AbstractMRReply	newReply()
protected void	notifyMessage(AbstractMRMessage m, AbstractMRListener notMe) Forward a Message to registered listeners.
protected void	notifyReply(AbstractMRReply r, AbstractMRListener dest) Forward a "Reply" from layout to registered listeners.
protected abstract AbstractMRMessage	pollMessage() Invoked if it's appropriate to do low-priority polling of the command station, this should return the next message to send, or null if the TC should just sleep.
protected abstract AbstractMRListener	pollReplyHandler()
boolean	portReadyToSend(AbstractPortController p) Check to see if PortController object can be sent to.
protected void	portWarn(Exception e)
protected void	portWarnTCP(Exception e)
protected boolean	programmerIdle()
protected byte	readByteProtected(DataInputStream istream) Read a single byte, protecting against various timeouts, etc.
void	receiveLoop() Handle incoming characters.
protected void	removeListener(AbstractMRListener l)
protected void	reportReceiveLoopException(Exception e) Report error on receive loop.
protected void	resetTimeout(AbstractMRMessage msg)
protected void	sendMessage(AbstractMRMessage m, AbstractMRListener reply) This is invoked with messages to be forwarded to the port.
protected void	setAllowUnexpectedReply(boolean expected)
protected abstract void	setInstance()
boolean	status()
protected void	terminate()
protected void	transmitWait(int waitTime, int state, String InterruptMessage)
protected void	waitForStartOfReply(DataInputStream istream) Dummy routine, to be filled by protocols that have to skip some start-of-message characters.

Methods inherited from class java.lang.Object

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

Field Detail

cmdListeners

protected Vector<AbstractMRListener> cmdListeners

mLastSender

protected AbstractMRListener mLastSender

mCurrentMode

protected volatile int mCurrentMode

NORMALMODE

public static final int NORMALMODE

See Also:

Constant Field Values

PROGRAMINGMODE

public static final int PROGRAMINGMODE

See Also:

Constant Field Values

mCurrentState

protected volatile int mCurrentState

IDLESTATE

public static final int IDLESTATE

See Also:

Constant Field Values

NOTIFIEDSTATE

public static final int NOTIFIEDSTATE

See Also:

Constant Field Values

WAITMSGREPLYSTATE

public static final int WAITMSGREPLYSTATE

See Also:

Constant Field Values

WAITREPLYINPROGMODESTATE

public static final int WAITREPLYINPROGMODESTATE

See Also:

Constant Field Values

WAITREPLYINNORMMODESTATE

public static final int WAITREPLYINNORMMODESTATE

See Also:

Constant Field Values

OKSENDMSGSTATE

public static final int OKSENDMSGSTATE

See Also:

Constant Field Values

AUTORETRYSTATE

public static final int AUTORETRYSTATE

See Also:

Constant Field Values

POLLSTATE

public static final int POLLSTATE

See Also:

Constant Field Values

allowUnexpectedReply

protected boolean allowUnexpectedReply

msgQueue

LinkedList<AbstractMRMessage> msgQueue

Messages to be transmitted

listenerQueue

LinkedList<AbstractMRListener> listenerQueue

replyInDispatch

protected boolean replyInDispatch

flushReceiveChars

protected boolean flushReceiveChars

mWaitBeforePoll

protected int mWaitBeforePoll

waitTimePoll

protected long waitTimePoll

xmtException

protected boolean xmtException

connectionError

boolean connectionError

controller

public AbstractPortController controller

xmtThread

Thread xmtThread

xmtRunnable

protected Runnable xmtRunnable

rcvThread

Thread rcvThread

istream

protected DataInputStream istream

ostream

protected OutputStream ostream

rcvException

protected boolean rcvException

maxRcvExceptionCount

protected int maxRcvExceptionCount

log

static org.slf4j.Logger log

Constructor Detail

AbstractMRTrafficController

public AbstractMRTrafficController()

Method Detail

getSelfLock

public AbstractMRTrafficController getSelfLock()

setInstance

protected abstract void setInstance()

addListener

protected void addListener(AbstractMRListener l)

removeListener

protected void removeListener(AbstractMRListener l)

notifyMessage

protected void notifyMessage(AbstractMRMessage m,
                             AbstractMRListener notMe)

Forward a Message to registered listeners.

Parameters:

m - Message to be forwarded intact

notMe - One (optional) listener to be skipped, usually because it's the originating object.

forwardMessage

protected abstract void forwardMessage(AbstractMRListener client,
                                       AbstractMRMessage m)

Implement this to forward a specific message type to a protocol-specific listener interface. This puts the casting into the concrete class.

pollMessage

protected abstract AbstractMRMessage pollMessage()

Invoked if it's appropriate to do low-priority polling of the command station, this should return the next message to send, or null if the TC should just sleep.

pollReplyHandler

protected abstract AbstractMRListener pollReplyHandler()

enterProgMode

protected abstract AbstractMRMessage enterProgMode()

enterNormalMode

protected abstract AbstractMRMessage enterNormalMode()

programmerIdle

protected boolean programmerIdle()

enterProgModeDelayTime

protected int enterProgModeDelayTime()

setAllowUnexpectedReply

protected void setAllowUnexpectedReply(boolean expected)

notifyReply

protected void notifyReply(AbstractMRReply r,
                           AbstractMRListener dest)

Forward a "Reply" from layout to registered listeners.

Parameters:

r - Reply to be forwarded intact

dest - One (optional) listener to be skipped, usually because it's the originating object.

forwardReply

protected abstract void forwardReply(AbstractMRListener client,
                                     AbstractMRReply m)

sendMessage

protected void sendMessage(AbstractMRMessage m,
                           AbstractMRListener reply)

This is invoked with messages to be forwarded to the port. It queues them, then notifies the transmission thread.

transmitWait

protected void transmitWait(int waitTime,
                            int state,
                            String InterruptMessage)

hasTimeouts

public boolean hasTimeouts()

handleTimeout

protected void handleTimeout(AbstractMRMessage msg,
                             AbstractMRListener l)

resetTimeout

protected void resetTimeout(AbstractMRMessage msg)

addHeaderToOutput

protected int addHeaderToOutput(byte[] msg,
                                AbstractMRMessage m)

Add header to the outgoing byte stream.

Parameters:

msg - The output byte stream

Returns:

next location in the stream to fill

addTrailerToOutput

protected void addTrailerToOutput(byte[] msg,
                                  int offset,
                                  AbstractMRMessage m)

Add trailer to the outgoing byte stream.

Parameters:

msg - The output byte stream

offset - the first byte not yet used

lengthOfByteStream

protected int lengthOfByteStream(AbstractMRMessage m)

Determine how much many bytes the entire message will take, including space for header and trailer

Parameters:

m - The message to be sent

Returns:

Number of bytes

forwardToPort

protected void forwardToPort(AbstractMRMessage m,
                             AbstractMRListener reply)

Actually transmits the next message to the port

connectionWarn

protected void connectionWarn()

portWarn

protected void portWarn(Exception e)

portWarnTCP

protected void portWarnTCP(Exception e)

status

public boolean status()

connectPort

public void connectPort(AbstractPortController p)

Make connection to existing PortController object.

getPortName

public String getPortName()

Get the port name for this connection

disconnectPort

public void disconnectPort(AbstractPortController p)

Break connection to existing PortController object. Once broken, attempts to send via "message" member will fail.

portReadyToSend

public boolean portReadyToSend(AbstractPortController p)
                        throws Exception

Check to see if PortController object can be sent to. returns true if ready, false otherwise May throw an Exception.

Throws:

Exception

receiveLoop

public void receiveLoop()

Handle incoming characters. This is a permanent loop, looking for input messages in character form on the stream connected to the PortController via connectPort. Each turn of the loop is the receipt of a single message.

reportReceiveLoopException

protected void reportReceiveLoopException(Exception e)

Report error on receive loop. Separated so tests can suppress, even though message is asynchronous.

newReply

protected abstract AbstractMRReply newReply()

endOfMessage

protected abstract boolean endOfMessage(AbstractMRReply r)

waitForStartOfReply

protected void waitForStartOfReply(DataInputStream istream)
                            throws IOException

Dummy routine, to be filled by protocols that have to skip some start-of-message characters.

Throws:

IOException

readByteProtected

protected byte readByteProtected(DataInputStream istream)
                          throws IOException

Read a single byte, protecting against various timeouts, etc.

When a gnu.io port is set to have a receive timeout (via the enableReceiveTimeout() method), some will return zero bytes or an EOFException at the end of the timeout. In that case, the read should be repeated to get the next real character.

Throws:

IOException

loadChars

protected void loadChars(AbstractMRReply msg,
                         DataInputStream istream)
                  throws IOException

Get characters from the input source, and file a message.

Returns only when the message is complete.

Only used in the Receive thread.

Handles timeouts on read by ignoring zero-length reads.

Parameters:

msg - message to fill

istream - character source.

Throws:

IOException - when presented by the input source.

canReceive

protected boolean canReceive()

Override in the system specific code if necessary

Returns:

true if it is okay to buffer receive characters into a reply message. When false, discard char received

handleOneIncomingReply

public void handleOneIncomingReply()
                            throws IOException

Handle each reply when complete.

(This is public for testing purposes) Runs in the "Receive" thread.

Throws:

IOException

getLastSender

public AbstractMRListener getLastSender()

finalize

protected final void finalize()
                       throws Throwable

Overrides:

finalize in class Object

Throws:

Throwable

terminate

protected void terminate()

newRcvNotifier

protected AbstractMRTrafficController.RcvNotifier newRcvNotifier(AbstractMRReply pMsg,
                                                                 AbstractMRListener pDest,
                                                                 AbstractMRTrafficController pTC)