Class 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.
    • Field Detail

      • echo

        protected boolean echo
        True if the external hardware is not echoing messages, so we must.
      • xmtList

        protected java.util.concurrent.LinkedTransferQueue<byte[]> xmtList
        Synchronized list used as a transmit queue.
      • xmtHandler

        protected java.lang.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 java.lang.Runnable rcvHandler
        RcvHandler (a local class) object to implement the receive thread
      • istream

        public java.io.DataInputStream istream
      • ostream

        public java.io.OutputStream ostream
      • rcvThread

        protected java.lang.Thread rcvThread
      • xmtThread

        protected java.lang.Thread xmtThread
      • threadStopRequest

        protected volatile boolean threadStopRequest
        Flag that threads should terminate as soon as they can.
    • Method Detail

      • 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​(java.io.DataInputStream istream)
                                  throws java.io.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:
        java.io.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.