Package jmri.jmrix.loconet

Class LnPacketizer

java.lang.Object

jmri.jmrix.loconet.LnTrafficController

jmri.jmrix.loconet.LnPacketizer

All Implemented Interfaces:

LocoNetInterface

Direct Known Subclasses:

IBLnPacketizer, LnOverTcpPacketizer, LnPacketizerStrict, LnPr2Packetizer, LnStreamPortPacketizer, UhlenbrockPacketizer

public class LnPacketizer
extends LnTrafficController

Converts Stream-based I/O to/from LocoNet messages. The "LocoNetInterface" side sends/receives LocoNetMessage objects. The connection to a LnPortController is via a pair of *Streams, which then carry sequences of characters for transmission.

Messages come to this via the main GUI thread, and are forwarded back to listeners in that same thread. Reception and transmission are handled in dedicated threads by RcvHandler and XmtHandler objects. Those are internal classes defined here. The thread priorities are:

• RcvHandler - at highest available priority
• XmtHandler - down one, which is assumed to be above the GUI
• (everything else)

Some of the message formats used in this class are Copyright Digitrax, Inc. and used with permission as part of the JMRI project. That permission does not extend to uses in other software products. If you wish to use this code, algorithm or these message formats outside of JMRI, please contact Digitrax Inc for separate permission.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
(package private) static class	LnPacketizer.Echo
protected class	LnPacketizer.RcvHandler	Captive class to handle incoming characters.
(package private) class	LnPacketizer.XmtHandler	Captive class to handle transmission.

Field Summary

Fields

Modifier and Type	Field	Description
protected LnPortController	controller
protected boolean	echo	True if the external hardware is not echoing messages, so we must.
DataInputStream	istream
OutputStream	ostream
protected Runnable	rcvHandler	RcvHandler (a local class) object to implement the receive thread
protected Thread	rcvThread
protected boolean	threadStopRequest	Flag that threads should terminate as soon as they can.
protected Runnable	xmtHandler	XmtHandler (a local class) object to implement the transmit thread.
protected LinkedTransferQueue<byte[]>	xmtList	Synchronized list used as a transmit queue.
protected Thread	xmtThread

Fields inherited from class jmri.jmrix.loconet.LnTrafficController

listeners, memo, receivedByteCount, receivedMsgCount, transmittedMsgCount

Fields inherited from interface jmri.jmrix.loconet.LocoNetInterface

ALL, POWER, PROGRAMMING, SENSORS, SLOTINFO, TURNOUTS

Constructor Summary

Constructors

Constructor	Description
LnPacketizer(LocoNetSystemConnectionMemo m)

Method Summary

Modifier and Type	Method	Description
void	connectPort(LnPortController p)	Make connection to an existing LnPortController object.
void	disconnectPort(LnPortController p)	Break connection to an existing LnPortController object.
void	dispose()	Clean up any resources, particularly threads.
boolean	isXmtBusy()	Implement abstract method to signal if there's a backlog of information waiting to be sent.
protected void	messageTransmitted(byte[] msg)	When a message is finally transmitted, forward it to listeners if echoing is needed.
protected byte	readByteProtected(DataInputStream istream)	Read a single byte, protecting against various timeouts, etc.
void	sendLocoNetMessage(LocoNetMessage m)	Forward a preformatted LocoNetMessage to the actual interface.
void	startThreads()	Invoked at startup to start the threads needed here.
boolean	status()	Check whether an implementation is operational.
void	terminateThreads()	Terminate the receive and transmit threads.

Methods inherited from class jmri.jmrix.loconet.LnTrafficController

addLocoNetListener, getReceivedByteCount, getReceivedMsgCount, getSystemConnectionMemo, getTransmittedMsgCount, notify, removeLocoNetListener, resetStatistics, setSystemConnectionMemo

Methods inherited from class java.lang.Object

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

Field Details

echo

protected boolean echo

True if the external hardware is not echoing messages, so we must.

xmtList

protected LinkedTransferQueue<byte[]> xmtList

Synchronized list used as a transmit queue.

xmtHandler

protected Runnable xmtHandler

XmtHandler (a local class) object to implement the transmit thread.

We create this object in startThreads() as each packetizer uses different handlers. So long as the object is created before using it to sync it works.

rcvHandler

protected Runnable rcvHandler

RcvHandler (a local class) object to implement the receive thread

controller

protected LnPortController controller

istream

public DataInputStream istream

ostream

public OutputStream ostream

rcvThread

protected Thread rcvThread

xmtThread

protected Thread xmtThread

threadStopRequest

protected volatile boolean threadStopRequest

Flag that threads should terminate as soon as they can.

Constructor Details

LnPacketizer

public LnPacketizer(LocoNetSystemConnectionMemo m)

Method Details

status

public boolean status()

Check whether an implementation is operational. Returns true if operational.

Specified by:

status in interface LocoNetInterface

Specified by:

status in class LnTrafficController

Returns:

true if implementation is operational.

sendLocoNetMessage

public void sendLocoNetMessage(LocoNetMessage m)

Forward a preformatted LocoNetMessage to the actual interface.

Checksum is computed and overwritten here, then the message is converted to a byte array and queued for transmission.

Specified by:

sendLocoNetMessage in interface LocoNetInterface

Specified by:

sendLocoNetMessage in class LnTrafficController

Parameters:

m - Message to send; will be updated with CRC

isXmtBusy

public boolean isXmtBusy()

Implement abstract method to signal if there's a backlog of information waiting to be sent.

Specified by:

isXmtBusy in class LnTrafficController

Returns:

true if busy, false if nothing waiting to send

connectPort

public void connectPort(LnPortController p)

Make connection to an existing LnPortController object.

Parameters:

p - Port controller for connected. Save this for a later disconnect call

disconnectPort

public void disconnectPort(LnPortController p)

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

Parameters:

p - previously connected port

readByteProtected

protected byte readByteProtected(DataInputStream istream)
                          throws IOException

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

When a 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.

Parameters:

istream - stream to read from

Returns:

buffer of received data

Throws:

IOException - failure during stream read

messageTransmitted

protected void messageTransmitted(byte[] msg)

When a message is finally transmitted, forward it to listeners if echoing is needed.

Parameters:

msg - message sent

startThreads

public void startThreads()

Invoked at startup to start the threads needed here.

dispose

public void dispose()

Clean up any resources, particularly threads.

The object can't be used after this.

Overrides:

dispose in class LnTrafficController

terminateThreads

public void terminateThreads()

Terminate the receive and transmit threads.

This is intended to be used only by testing subclasses.