Package jmri.jmrix

Class AbstractPortController

java.lang.Object

jmri.jmrix.AbstractPortController

All Implemented Interfaces:

PortAdapter

Direct Known Subclasses:

AbstractNetworkPortController, AbstractSerialPortController, AbstractStreamPortController, IpocsPortController, RaspberryPiAdapter, UsbPortAdapter, XBeeIOStream

public abstract class AbstractPortController
extends Object
implements PortAdapter

Provide an abstract base for *PortController classes.

This is complicated by the lack of multiple inheritance. SerialPortAdapter is an Interface, and its implementing classes also inherit from various PortController types. But we want some common behaviors for those, so we put them here.

See Also:

• SerialPortAdapter

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
protected static class	AbstractPortController.Option

Field Summary

Fields

Modifier and Type	Field	Description
protected boolean	allowConnectionRecovery
protected String	manufacturerName
protected boolean	opened
protected String	option1Name
protected String	option2Name
protected String	option3Name
protected String	option4Name
protected HashMap<String,AbstractPortController.Option>	options
protected int	reconnectinterval	Initial interval between reconnection attempts.
protected int	reconnectMaxAttempts	Maximum reconnection attempts that the port should make.
protected int	reconnectMaxInterval	Maximum interval between reconnection attempts in seconds.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	AbstractPortController(SystemConnectionMemo connectionMemo)

Method Summary

Modifier and Type	Method	Description
protected void	closeConnection()	Abstract class for controllers to close the connection.
void	configureOption1(String value)	Set the first port option.
void	configureOption2(String value)	Set the second port option.
void	configureOption3(String value)	Set the third port option.
void	configureOption4(String value)	Set the fourth port option.
void	dispose()	Clean up before removal.
abstract String	getCurrentPortName()
boolean	getDisabled()	Return the disabled state of the adapter.
abstract DataInputStream	getInputStream()	Get the InputStream from the port.
String	getManufacturer()	Get the system manufacturer's name.
String	getOption1Name()
String	getOption2Name()
String	getOption3Name()
String	getOption4Name()
String[]	getOptionChoices(String option)	Get a list of the various choices allowed with a given option.
String	getOptionDisplayName(String option)
String[]	getOptions()	Get a list of all the options configured against this adapter.
String	getOptionState(String option)	Get the string value of a specific option.
abstract DataOutputStream	getOutputStream()	Get the outputStream to the port.
int	getReconnectMaxAttempts()	Get the maximum number of reconnection attempts which should be made.
int	getReconnectMaxInterval()	Get the maximum interval between reconnection attempts.
SystemConnectionMemo	getSystemConnectionMemo()	Get the SystemConnectionMemo associated with this object.
String	getSystemPrefix()	Get the system prefix for this adapter.
String	getUserName()	Get the user name for this adapter.
boolean	isDirty()	Determine if configuration needs to be written to disk.
boolean	isOptionAdvanced(String option)
boolean	isOptionTypePassword(String option)	Should this option be represented by a password field
boolean	isOptionTypeText(String option)	Should this option be represented by a text field (as opposed to a JCombobox)
boolean	isRestartRequired()	Determine if application needs to be restarted for configuration changes to be applied.
static void	purgeStream(InputStream serialStream)	Service method to purge a stream of initial contents while opening the connection.
protected void	reconnect()	Attempts to reconnect to a failed port.
protected void	reconnectFromLoop(int retryNum)	Abstract class for ports to attempt a single re-connection attempt.
void	recover()	This is called when a connection is initially lost.
protected void	resetupConnection()	Abstract class for controllers to re-setup a connection.
protected static void	safeSleep(long milliseconds, String s)
protected void	setClosed()
void	setDisabled(boolean disabled)	Set the connection disabled or enabled.
void	setManufacturer(String manufacturer)	Set the system manufacturer's name.
protected void	setOpened()
void	setOptionState(String option, String value)	Set the value of an option.
void	setReconnectMaxAttempts(int maxAttempts)	Set the maximum number of reconnection attempts
void	setReconnectMaxInterval(int maxInterval)	Set the maximum interval between reconnection attempts.
void	setSystemConnectionMemo(SystemConnectionMemo connectionMemo)	Set the SystemConnectionMemo associated with this object.
void	setSystemPrefix(String systemPrefix)	Set the system prefix for this adapter.
void	setUserName(String userName)	Set the user name for this adapter.
boolean	status()	Query the status of this connection.

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

configure, connect

Field Details

manufacturerName

protected String manufacturerName

opened

protected boolean opened

option1Name

protected String option1Name

option2Name

protected String option2Name

option3Name

protected String option3Name

option4Name

protected String option4Name

options

protected HashMap<String,AbstractPortController.Option> options

allowConnectionRecovery

protected boolean allowConnectionRecovery

reconnectinterval

protected int reconnectinterval

Initial interval between reconnection attempts. Default 1 second.

reconnectMaxAttempts

protected int reconnectMaxAttempts

Maximum reconnection attempts that the port should make. Default 100 attempts. A value of -1 indicates unlimited attempts.

reconnectMaxInterval

protected int reconnectMaxInterval

Maximum interval between reconnection attempts in seconds. Default 120 seconds.

Constructor Details

AbstractPortController

protected AbstractPortController(SystemConnectionMemo connectionMemo)

Method Details

getInputStream

public abstract DataInputStream getInputStream()

Get the InputStream from the port.

Specified by:

getInputStream in interface PortAdapter

Returns:

the InputStream from the port

getOutputStream

public abstract DataOutputStream getOutputStream()

Get the outputStream to the port.

Specified by:

getOutputStream in interface PortAdapter

Returns:

the outputStream to the port

dispose

@OverridingMethodsMustInvokeSuper
public void dispose()

Clean up before removal. Overriding methods must call super.dispose() or document why they are not calling the overridden implementation. In most cases, failure to call the overridden implementation will cause user-visible error.

Specified by:

dispose in interface PortAdapter

status

public boolean status()

Query the status of this connection. This is a question of configuration, not transient hardware status.

Specified by:

status in interface PortAdapter

Returns:

true if OK, at least as far as known

setOpened

protected void setOpened()

setClosed

protected void setClosed()

getCurrentPortName

public abstract String getCurrentPortName()

Specified by:

getCurrentPortName in interface PortAdapter

configureOption1

public void configureOption1(String value)

Description copied from interface: PortAdapter

Set the first port option. Only to be used after construction, but before the openPort call.

Specified by:

configureOption1 in interface PortAdapter

Parameters:

value - to set the option to

configureOption2

public void configureOption2(String value)

Description copied from interface: PortAdapter

Set the second port option. Only to be used after construction, but before the openPort call.

Specified by:

configureOption2 in interface PortAdapter

Parameters:

value - to set the option to

configureOption3

public void configureOption3(String value)

Description copied from interface: PortAdapter

Set the third port option. Only to be used after construction, but before the openPort call.

Specified by:

configureOption3 in interface PortAdapter

Parameters:

value - to set the option to

configureOption4

public void configureOption4(String value)

Description copied from interface: PortAdapter

Set the fourth port option. Only to be used after construction, but before the openPort call.

Specified by:

configureOption4 in interface PortAdapter

Parameters:

value - to set the option to

getOption1Name

public String getOption1Name()

Specified by:

getOption1Name in interface PortAdapter

getOption2Name

public String getOption2Name()

Specified by:

getOption2Name in interface PortAdapter

getOption3Name

public String getOption3Name()

Specified by:

getOption3Name in interface PortAdapter

getOption4Name

public String getOption4Name()

Specified by:

getOption4Name in interface PortAdapter

getOptions

public String[] getOptions()

Get a list of all the options configured against this adapter.

Specified by:

getOptions in interface PortAdapter

Returns:

Array of option identifier strings

setOptionState

public void setOptionState(String option,
 String value)

Set the value of an option.

Specified by:

setOptionState in interface PortAdapter

Parameters:

option - the name string of the option

value - the string value to set the option to

getOptionState

public String getOptionState(String option)

Get the string value of a specific option.

Specified by:

getOptionState in interface PortAdapter

Parameters:

option - the name of the option to query

Returns:

the option value

getOptionChoices

public String[] getOptionChoices(String option)

Get a list of the various choices allowed with a given option.

Specified by:

getOptionChoices in interface PortAdapter

Parameters:

option - the name of the option to query

Returns:

list of valid values for the option, null if none are available

isOptionTypeText

public boolean isOptionTypeText(String option)

Description copied from interface: PortAdapter

Should this option be represented by a text field (as opposed to a JCombobox)

Specified by:

isOptionTypeText in interface PortAdapter

Parameters:

option - Name of the option to check

Returns:

true for text representation preferred

isOptionTypePassword

public boolean isOptionTypePassword(String option)

Description copied from interface: PortAdapter

Should this option be represented by a password field

Specified by:

isOptionTypePassword in interface PortAdapter

Parameters:

option - Name of the option to check

Returns:

true for text representation preferred

getOptionDisplayName

public String getOptionDisplayName(String option)

Specified by:

getOptionDisplayName in interface PortAdapter

isOptionAdvanced

public boolean isOptionAdvanced(String option)

Specified by:

isOptionAdvanced in interface PortAdapter

getManufacturer

public String getManufacturer()

Description copied from interface: PortAdapter

Get the system manufacturer's name.

Specified by:

getManufacturer in interface PortAdapter

Returns:

manufacturer's name

setManufacturer

public void setManufacturer(String manufacturer)

Description copied from interface: PortAdapter

Set the system manufacturer's name.

Specified by:

setManufacturer in interface PortAdapter

Parameters:

manufacturer - the manufacturer's name

getDisabled

public boolean getDisabled()

Description copied from interface: PortAdapter

Return the disabled state of the adapter.

Specified by:

getDisabled in interface PortAdapter

Returns:

true if disabled

setDisabled

public void setDisabled(boolean disabled)

Set the connection disabled or enabled. By default connections are enabled. If the implementing class does not use a SystemConnectionMemo, this method must be overridden. Overriding methods must call super.setDisabled(boolean) to ensure the configuration change state is correctly set.

Specified by:

setDisabled in interface PortAdapter

Parameters:

disabled - true if connection should be disabled

getSystemPrefix

public String getSystemPrefix()

Description copied from interface: PortAdapter

Get the system prefix for this adapter.

Specified by:

getSystemPrefix in interface PortAdapter

Returns:

the system prefix or null

setSystemPrefix

public void setSystemPrefix(String systemPrefix)

Description copied from interface: PortAdapter

Set the system prefix for this adapter.

Specified by:

setSystemPrefix in interface PortAdapter

Parameters:

systemPrefix - the new system prefix

getUserName

public String getUserName()

Description copied from interface: PortAdapter

Get the user name for this adapter.

Specified by:

getUserName in interface PortAdapter

Returns:

the username or null

setUserName

public void setUserName(String userName)

Description copied from interface: PortAdapter

Set the user name for this adapter.

Specified by:

setUserName in interface PortAdapter

Parameters:

userName - the new user name

recover

public void recover()

This is called when a connection is initially lost. After checking the allowConnectionRecovery flag, closes the connection, resets the open flag and attempts a reconnection.

Specified by:

recover in interface PortAdapter

closeConnection

protected void closeConnection()

Abstract class for controllers to close the connection. Called prior to any re-connection attempts.

reconnect

protected void reconnect()

Attempts to reconnect to a failed port. Starts a reconnect thread

resetupConnection

protected void resetupConnection()

Abstract class for controllers to re-setup a connection. Called on connection reconnect success.

reconnectFromLoop

protected void reconnectFromLoop(int retryNum)

Abstract class for ports to attempt a single re-connection attempt. Called from within main reconnect thread.

Parameters:

retryNum - Reconnection attempt number.

setReconnectMaxInterval

public void setReconnectMaxInterval(int maxInterval)

Set the maximum interval between reconnection attempts.

Specified by:

setReconnectMaxInterval in interface PortAdapter

Parameters:

maxInterval - in seconds.

setReconnectMaxAttempts

public void setReconnectMaxAttempts(int maxAttempts)

Set the maximum number of reconnection attempts. -1 will set an infinite number of attempts.

Specified by:

setReconnectMaxAttempts in interface PortAdapter

Parameters:

maxAttempts - total maximum reconnection attempts.

getReconnectMaxInterval

public int getReconnectMaxInterval()

Get the maximum interval between reconnection attempts.

Specified by:

getReconnectMaxInterval in interface PortAdapter

Returns:

maximum interval in seconds.

getReconnectMaxAttempts

public int getReconnectMaxAttempts()

Get the maximum number of reconnection attempts which should be made. A value of -1 means no maximum value, i.e. infinite attempts.

Specified by:

getReconnectMaxAttempts in interface PortAdapter

Returns:

total number of attempts which should be made.

safeSleep

protected static void safeSleep(long milliseconds,
 String s)

isDirty

public boolean isDirty()

Description copied from interface: PortAdapter

Determine if configuration needs to be written to disk.

Specified by:

isDirty in interface PortAdapter

Returns:

true if configuration needs to be saved, false otherwise

isRestartRequired

public boolean isRestartRequired()

Description copied from interface: PortAdapter

Determine if application needs to be restarted for configuration changes to be applied.

Specified by:

isRestartRequired in interface PortAdapter

Returns:

true if application needs to restart, false otherwise

purgeStream

public static void purgeStream(@Nonnull
 InputStream serialStream)
                        throws IOException

Service method to purge a stream of initial contents while opening the connection.

Parameters:

serialStream - input data

Throws:

IOException - if the stream is e.g. closed due to failure to open the port completely

getSystemConnectionMemo

public SystemConnectionMemo getSystemConnectionMemo()

Get the SystemConnectionMemo associated with this object.

This method should only be overridden to ensure that a specific subclass of SystemConnectionMemo is returned. The recommended pattern is: public MySystemConnectionMemo getSystemConnectionMemo() { return (MySystemConnectionMemo) super.getSystemConnectionMemo(); }

Specified by:

getSystemConnectionMemo in interface PortAdapter

Returns:

the currently associated SystemConnectionMemo

setSystemConnectionMemo

@OverridingMethodsMustInvokeSuper
public void setSystemConnectionMemo(@Nonnull
 SystemConnectionMemo connectionMemo)

Set the SystemConnectionMemo associated with this object.

Overriding implementations must call super.setSystemConnectionMemo(memo) at some point to ensure the SystemConnectionMemo gets set.

Specified by:

setSystemConnectionMemo in interface PortAdapter

Parameters:

connectionMemo - the SystemConnectionMemo to associate with this PortController