Package jmri.jmrix

Class AbstractSerialPortController

java.lang.Object

jmri.jmrix.AbstractPortController

jmri.jmrix.AbstractSerialPortController

All Implemented Interfaces:

PortAdapter, SerialPortAdapter

Direct Known Subclasses:

AcelaPortController, BiDiBSerialPortController, CdBPortController, Dcc4PcPortController, DCCppSerialPortController, DCCppSimulatorPortController, DemoSerialPort, EasyDccPortController, GcPortController, IEEE802154PortController, InternalAdapter, LnPortController, MrcPortController, Mx1PortController, NcePortController, Port, PortController, PortController, QsiPortController, RfidPortController, SerialAdapter, SerialPortAdapter, SerialPortController, SerialPortController, SerialPortController, SerialPortController, SerialPortController, SerialPortController, SpeedoPortController, SprogPortController, TamsPortController, XNetSerialPortController, XNetSimulatorPortController, XpaPortController

public abstract class AbstractSerialPortController
extends AbstractPortController
implements SerialPortAdapter

Provide an abstract base for *PortController classes.

The intent is to hide, to the extent possible, all the references to the actual serial library in use within this class. Subclasses then rely on methods here to maniplate the content of the protected currentSerialPort variable/

See Also:

SerialPortAdapter

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	AbstractSerialPortController.Blocking	Enumerate the possible timeout choices
static class	AbstractSerialPortController.FlowControl	Enumerate the possible flow control choices

Nested classes/interfaces inherited from class jmri.jmrix.AbstractPortController

AbstractPortController.Option

Field Summary

Fields

Modifier and Type	Field	Description
protected SerialPort	currentSerialPort
protected java.lang.String	mBaudRate
protected java.lang.String	mPort

Fields inherited from class jmri.jmrix.AbstractPortController

allowConnectionRecovery, manufacturerName, opened, option1Name, option2Name, option3Name, option4Name, options, reconnectinterval, reconnectMaxAttempts, reconnectMaxInterval

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	AbstractSerialPortController(SystemConnectionMemo connectionMemo)

Method Summary

Modifier and Type	Method	Description
static SerialPort	activatePort(java.lang.String systemPrefix, java.lang.String portName, org.slf4j.Logger log, int stop_bits, SerialPort.Parity parity)	Do the formal opening of the port, set the port for blocking reads without timeout, set the port to 8 data bits, the indicated number of stop bits and parity, and purge the port's input stream.
protected SerialPort	activatePort(java.lang.String portName, org.slf4j.Logger log)	Do the formal opening of the port, set the port for blocking reads without timeout, set the port to 8 data bits, 1 stop bit, no parity and purge the port's input stream.
protected SerialPort	activatePort(java.lang.String portName, org.slf4j.Logger log, int stop_bits)	Do the formal opening of the port, set the port for blocking reads without timeout, set the port to 8 data bits, the indicated number of stop bits, no parity, and purge the port's input stream.
protected void	closeConnection()	Abstract class for controllers to close the connection.
protected void	closeSerialPort(SerialPort serialPort)	Cleanly close the specified port
void	configureBaudRate(java.lang.String rate)	Set the baud rate description by port speed description.
void	configureBaudRateFromIndex(int index)	Set the baud rate description by index (integer) from validBaudRates[].
void	configureBaudRateFromNumber(java.lang.String indexString)	Set the baud rate description by port speed number (as a string) from validBaudRates[].
protected void	configureLeads(SerialPort serialPort, boolean rts, boolean dtr)	Set the control leads.
protected void	configureLeadsAndFlowControl(SerialPort serialPort, int flow)	Set the flow control for jmri.jmrix.purejavacomm, while also setting RTS and DTR to active.
protected void	configureLeadsAndFlowControl(SerialPort serialPort, int flow, boolean rts, boolean dtr)	Set the control leads and flow control for jmri.jmrix.purejavacomm.
void	connect()	Open the connection.
int	currentBaudNumber(java.lang.String currentBaudRate)	Convert a baud rate I18N String to an int number, e.g. "9,600 baud" to 9600.
int	defaultBaudIndex()	Get the index of the default port speed for this adapter from the validSpeeds and validRates arrays.
static java.util.Vector<java.lang.String>	getActualPortNames()	Provide the actual serial port names.
int	getCurrentBaudIndex()
java.lang.String	getCurrentBaudNumber()	To store as XML attribute, get a string to represent current port speed.
java.lang.String	getCurrentBaudRate()
java.lang.String	getCurrentPortName()	Overridden in simulator adapter classes to return "";
protected AbstractSerialPortController.FlowControl	getFlowControl(SerialPort serialPort)	get the flow control mode back from the actual port.
java.io.DataInputStream	getInputStream()	Get the InputStream from the port.
java.io.DataOutputStream	getOutputStream()	Get the outputStream to the port.
java.lang.String	getPortSettingsString()	Get a string with the serial port settings.
java.lang.String	handlePortBusy(PortInUseException p, java.lang.String portName, org.slf4j.Logger log)	Standard error handling for jmri.jmrix.purejavacomm port-busy case.
static java.lang.String	handlePortNotFound(java.lang.String systemPrefix, java.lang.String portName, org.slf4j.Logger log, java.lang.Exception ex)	Standard error handling for the general port-not-found case.
java.lang.String	handlePortNotFound(NoSuchPortException p, java.lang.String portName, org.slf4j.Logger log)	Specific error handling for jmri.jmrix.purejavacomm port-not-found case.
boolean	isPortOpen()	Is the serial port open?
void	replacePortWithFakePort()	Replace the serial port with a fake serial port and close the old serial port.
protected void	reportPortStatus(org.slf4j.Logger log, java.lang.String portName)	Report the connection status.
protected void	resetupConnection()	Re-setup the connection.
protected void	setBaudRate(SerialPort serialPort, int baud)	Set the baud rate on the port
protected void	setComPortTimeouts(SerialPort serialPort, AbstractSerialPortController.Blocking blocking, int timeout)
protected void	setDataListener(SerialPort serialPort, SerialPortDataListener serialPortDataListener)	Add a data listener to the specified port
protected void	setFlowControl(SerialPort serialPort, AbstractSerialPortController.FlowControl flow)	Configure the flow control settings.
void	setPort(java.lang.String port)	Remember the associated port name.
int[]	validBaudNumbers()	Get an array of valid baud rate numbers; used to store/load adapter speed option.
java.lang.String[]	validBaudRates()	Get an array of valid baud rate strings; used to display valid options in Connections Preferences.

Methods inherited from class jmri.jmrix.AbstractPortController

configureOption1, configureOption2, configureOption3, configureOption4, dispose, getDisabled, getManufacturer, getOption1Name, getOption2Name, getOption3Name, getOption4Name, getOptionChoices, getOptionDisplayName, getOptions, getOptionState, getReconnectMaxAttempts, getReconnectMaxInterval, getSystemConnectionMemo, getSystemPrefix, getUserName, isDirty, isOptionAdvanced, isOptionTypePassword, isOptionTypeText, isRestartRequired, purgeStream, reconnect, reconnectFromLoop, recover, safeSleep, setClosed, setDisabled, setManufacturer, setOpened, setOptionState, setReconnectMaxAttempts, setReconnectMaxInterval, setSystemConnectionMemo, setSystemPrefix, setUserName, status

Methods inherited from class java.lang.Object

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

Methods inherited from interface jmri.jmrix.PortAdapter

dispose, getDisabled, getOption1Name, getOption2Name, getOption3Name, getOption4Name, getOptionChoices, getOptionDisplayName, getOptions, getOptionState, getReconnectMaxAttempts, getReconnectMaxInterval, getSystemConnectionMemo, getSystemPrefix, getUserName, isDirty, isOptionAdvanced, isOptionTypePassword, isOptionTypeText, isRestartRequired, recover, setDisabled, setOptionState, setReconnectMaxAttempts, setReconnectMaxInterval, setSystemConnectionMemo, setSystemPrefix, setUserName

Methods inherited from interface jmri.jmrix.SerialPortAdapter

configure, configureOption1, configureOption2, configureOption3, configureOption4, getManufacturer, getPortNames, openPort, setManufacturer, status

Field Detail

currentSerialPort

protected volatile SerialPort currentSerialPort

mPort

protected java.lang.String mPort

mBaudRate

protected java.lang.String mBaudRate

Constructor Detail

AbstractSerialPortController

protected AbstractSerialPortController(SystemConnectionMemo connectionMemo)

Method Detail

handlePortBusy

public java.lang.String handlePortBusy(PortInUseException p,
                                       java.lang.String portName,
                                       org.slf4j.Logger log)

Standard error handling for jmri.jmrix.purejavacomm port-busy case.

Parameters:

p - the exception being handled, if additional information from it is desired

portName - name of the port being accessed

log - where to log a status message

Returns:

Localized message, in case separate presentation to user is desired

handlePortNotFound

public java.lang.String handlePortNotFound(NoSuchPortException p,
                                           java.lang.String portName,
                                           org.slf4j.Logger log)

Specific error handling for jmri.jmrix.purejavacomm port-not-found case.

Parameters:

p - no such port exception.

portName - port name.

log - system log.

Returns:

human readable string with error detail.

handlePortNotFound

public static java.lang.String handlePortNotFound(java.lang.String systemPrefix,
                                                  java.lang.String portName,
                                                  org.slf4j.Logger log,
                                                  java.lang.Exception ex)

Standard error handling for the general port-not-found case.

Parameters:

systemPrefix - the system prefix

portName - port name.

log - system log, passed so logging comes from bottom level class

ex - Underlying Exception that caused this failure

Returns:

human readable string with error detail.

connect

public void connect()
             throws java.io.IOException

Open the connection.

Specified by:

connect in interface PortAdapter

Throws:

java.io.IOException - if unable to connect

activatePort

protected final SerialPort activatePort(java.lang.String portName,
                                        org.slf4j.Logger log)

Do the formal opening of the port, set the port for blocking reads without timeout, set the port to 8 data bits, 1 stop bit, no parity and purge the port's input stream.

Does not do the rest of the setup implied in the SerialPortAdapter.openPort(java.lang.String, java.lang.String) method. This is usually followed by calls to setBaudRate(jmri.jmrix.SerialPort, int), configureLeads(jmri.jmrix.SerialPort, boolean, boolean) and setFlowControl(jmri.jmrix.SerialPort, jmri.jmrix.AbstractSerialPortController.FlowControl).

Parameters:

portName - local system name for the desired port

log - Logger to use for errors, passed so that errors are logged from low-level class

Returns:

the serial port object for later use

activatePort

protected final SerialPort activatePort(java.lang.String portName,
                                        org.slf4j.Logger log,
                                        int stop_bits)

Do the formal opening of the port, set the port for blocking reads without timeout, set the port to 8 data bits, the indicated number of stop bits, no parity, and purge the port's input stream.

Does not do the rest of the setup implied in the SerialPortAdapter.openPort(java.lang.String, java.lang.String) method. This is usually followed by calls to setBaudRate(jmri.jmrix.SerialPort, int), configureLeads(jmri.jmrix.SerialPort, boolean, boolean) and setFlowControl(jmri.jmrix.SerialPort, jmri.jmrix.AbstractSerialPortController.FlowControl).

Parameters:

portName - local system name for the desired port

log - Logger to use for errors, passed so that errors are logged from low-level class'

stop_bits - The number of stop bits, either 1 or 2

Returns:

the serial port object for later use

activatePort

public static SerialPort activatePort(java.lang.String systemPrefix,
                                      java.lang.String portName,
                                      org.slf4j.Logger log,
                                      int stop_bits,
                                      SerialPort.Parity parity)

Do the formal opening of the port, set the port for blocking reads without timeout, set the port to 8 data bits, the indicated number of stop bits and parity, and purge the port's input stream.

Does not do the rest of the setup implied in the SerialPortAdapter.openPort(java.lang.String, java.lang.String) method. This is usually followed by calls to setBaudRate(jmri.jmrix.SerialPort, int), configureLeads(jmri.jmrix.SerialPort, boolean, boolean) and setFlowControl(jmri.jmrix.SerialPort, jmri.jmrix.AbstractSerialPortController.FlowControl).

Parameters:

systemPrefix - the system prefix

portName - local system name for the desired port

log - Logger to use for errors, passed so that errors are logged from low-level class'

stop_bits - The number of stop bits, either 1 or 2

parity - one of the defined parity contants

Returns:

the serial port object for later use

setComPortTimeouts

protected final void setComPortTimeouts(SerialPort serialPort,
                                        AbstractSerialPortController.Blocking blocking,
                                        int timeout)

setPort

public void setPort(java.lang.String port)

Remember the associated port name.

Specified by:

setPort in interface SerialPortAdapter

Parameters:

port - name of the port

getCurrentPortName

public java.lang.String getCurrentPortName()

Overridden in simulator adapter classes to return "";

Specified by:

getCurrentPortName in interface PortAdapter

Specified by:

getCurrentPortName in interface SerialPortAdapter

Specified by:

getCurrentPortName in class AbstractPortController

getActualPortNames

public static java.util.Vector<java.lang.String> getActualPortNames()

Provide the actual serial port names. As a public static method, this can be accessed outside the jmri.jmrix package to get the list of names for e.g. context reports.

Returns:

the port names in the form they can later be used to open the port

configureLeadsAndFlowControl

protected void configureLeadsAndFlowControl(SerialPort serialPort,
                                            int flow,
                                            boolean rts,
                                            boolean dtr)

Set the control leads and flow control for jmri.jmrix.purejavacomm. This handles any necessary ordering.

Parameters:

serialPort - Port to be updated

flow - flow control mode from (@link jmri.jmrix.purejavacomm.SerialPort}

rts - set RTS active if true

dtr - set DTR active if true

setBaudRate

protected final void setBaudRate(SerialPort serialPort,
                                 int baud)

Set the baud rate on the port

Parameters:

serialPort - Port to be updated

baud - baud rate to be set

configureLeads

protected final void configureLeads(SerialPort serialPort,
                                    boolean rts,
                                    boolean dtr)

Set the control leads.

Parameters:

serialPort - Port to be updated

rts - set RTS active if true

dtr - set DTR active if true

setFlowControl

protected final void setFlowControl(SerialPort serialPort,
                                    AbstractSerialPortController.FlowControl flow)

Configure the flow control settings. Keep this in synch with the FlowControl enum.

Parameters:

serialPort - Port to be updated

flow - set which kind of flow control to use

getFlowControl

protected final AbstractSerialPortController.FlowControl getFlowControl(SerialPort serialPort)

get the flow control mode back from the actual port.

Parameters:

serialPort - Port to be examined

Returns:

flow control setting observed in the port

setDataListener

protected final void setDataListener(SerialPort serialPort,
                                     SerialPortDataListener serialPortDataListener)

Add a data listener to the specified port

Parameters:

serialPort - Port to be updated

serialPortDataListener - the listener to add

closeSerialPort

protected final void closeSerialPort(SerialPort serialPort)

Cleanly close the specified port

Parameters:

serialPort - Port to be closed

configureLeadsAndFlowControl

protected final void configureLeadsAndFlowControl(SerialPort serialPort,
                                                  int flow)

Set the flow control for jmri.jmrix.purejavacomm, while also setting RTS and DTR to active.

Parameters:

serialPort - Port to be updated

flow - flow control mode from (@link jmri.jmrix.purejavacomm.SerialPort}

reportPortStatus

protected final void reportPortStatus(org.slf4j.Logger log,
                                      java.lang.String portName)

Report the connection status. Typically used after the connection is complete

Parameters:

log - The low-level logger to get this reported against the right class

portName - low-level name of selected port

getInputStream

public java.io.DataInputStream getInputStream()

Description copied from class: AbstractPortController

Get the InputStream from the port.

Specified by:

getInputStream in interface PortAdapter

Specified by:

getInputStream in class AbstractPortController

Returns:

the InputStream from the port

getOutputStream

public java.io.DataOutputStream getOutputStream()

Description copied from class: AbstractPortController

Get the outputStream to the port.

Specified by:

getOutputStream in interface PortAdapter

Specified by:

getOutputStream in class AbstractPortController

Returns:

the outputStream to the port

configureBaudRate

public final void configureBaudRate(java.lang.String rate)

Set the baud rate description by port speed description.

Only to be used after construction, but before the openPort call.

Specified by:

configureBaudRate in interface SerialPortAdapter

Parameters:

rate - the baud rate as I18N description, eg. "28,800 baud"

configureBaudRateFromNumber

public final void configureBaudRateFromNumber(java.lang.String indexString)

Set the baud rate description by port speed number (as a string) from validBaudRates[].

Only to be used after construction, but before the openPort call.

Specified by:

configureBaudRateFromNumber in interface SerialPortAdapter

Parameters:

indexString - the port speed as unformatted number string, eg. "28800"

configureBaudRateFromIndex

public final void configureBaudRateFromIndex(int index)

Set the baud rate description by index (integer) from validBaudRates[]. Invalid indexes are ignored.

Specified by:

configureBaudRateFromIndex in interface SerialPortAdapter

Parameters:

index - the index to select from speeds[] array

defaultBaudIndex

public int defaultBaudIndex()

Description copied from interface: SerialPortAdapter

Get the index of the default port speed for this adapter from the validSpeeds and validRates arrays.

Specified by:

defaultBaudIndex in interface SerialPortAdapter

Returns:

-1 to indicate not supported, unless overridden in adapter

getCurrentBaudRate

public java.lang.String getCurrentBaudRate()

Specified by:

getCurrentBaudRate in interface SerialPortAdapter

getCurrentBaudNumber

public final java.lang.String getCurrentBaudNumber()

To store as XML attribute, get a string to represent current port speed.

Specified by:

getCurrentBaudNumber in interface SerialPortAdapter

Returns:

speed as number string

getCurrentBaudIndex

public final int getCurrentBaudIndex()

Specified by:

getCurrentBaudIndex in interface SerialPortAdapter

validBaudRates

public java.lang.String[] validBaudRates()

Get an array of valid baud rate strings; used to display valid options in Connections Preferences.

Specified by:

validBaudRates in interface SerialPortAdapter

Returns:

array of I18N display strings of port speed settings valid for this serial adapter, must match order and values from SerialPortAdapter.validBaudNumbers()

validBaudNumbers

public int[] validBaudNumbers()

Get an array of valid baud rate numbers; used to store/load adapter speed option.

Specified by:

validBaudNumbers in interface SerialPortAdapter

Returns:

integer array of speeds, must match order and values from SerialPortAdapter.validBaudRates()

currentBaudNumber

public final int currentBaudNumber(java.lang.String currentBaudRate)

Convert a baud rate I18N String to an int number, e.g. "9,600 baud" to 9600.

Uses the validBaudNumbers() and validBaudRates() methods to do this.

Parameters:

currentBaudRate - a rate from validBaudRates()

Returns:

baudrate as integer if available and matching first digits in currentBaudRate, 0 if baudrate not supported by this adapter, -1 if no match (configuration system should prevent this)

closeConnection

protected void closeConnection()

Abstract class for controllers to close the connection. Called prior to any re-connection attempts. Each serial port adapter should handle this and it should be abstract.

Overrides:

closeConnection in class AbstractPortController

resetupConnection

protected void resetupConnection()

Re-setup the connection. Called when the physical connection has reconnected and can be linked to this connection. Each port adapter should handle this and it should be abstract.

Overrides:

resetupConnection in class AbstractPortController

isPortOpen

public boolean isPortOpen()

Is the serial port open? The LocoNet simulator uses this class but doesn't open the port.

Returns:

true if the port is open, false otherwise

replacePortWithFakePort

public void replacePortWithFakePort()

Replace the serial port with a fake serial port and close the old serial port. Note that you can only replace the port once. This call is used when you want to close the port and reopen it for some special task, for example upload firmware.

getPortSettingsString

public java.lang.String getPortSettingsString()

Get a string with the serial port settings.

Returns:

the settings as a string