Package jmri.jmrix.loconet.duplexgroup.swing

Class LnDplxGrpInfoImpl

java.lang.Object
java.awt.Component
java.awt.Container
javax.swing.JComponent
jmri.jmrix.loconet.duplexgroup.swing.LnDplxGrpInfoImpl
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, EventListener, LocoNetListener
public class LnDplxGrpInfoImpl extends JComponent implements LocoNetListener
Provides a low-level interface to Digitrax Duplex Group Identity information.

Implements the following "Property Change" events, which are defined as static strings in LnDplxGrpInfoImplConstants:

  • DPLX_PC_STAT_LN_UPDATE - Indicates that a GUI status line could be updated using provided string.
  • DPLX_PC_STAT_LN_UPDATE_IF_NOT_CURRENTLY_ERROR - Indicates that a GUI status line could be updated using the provided string UNLESS the status line is currently showing an error.
  • NumberOfUr92sUpdate - Indicates that the class has counted the number of UR92 devices
  • DPLX_PC_NAME_UPDATE - Indicates that a LocoNet message has reported the Duplex Group Name
  • DPLX_PC_CHANNEL_UPDATE - Indicates that a LocoNet message has reported the Duplex Group Channel
  • DPLX_PC_PASSWORD_UPDATE - Indicates that a LocoNet message has reported the Duplex Group Password
  • DPLX_PC_ID_UPDATE - Indicates that a LocoNet message has reported the Duplex Group Id
  • DPLX_PC_NAME_VALIDITY - Indicates that the validity of GUI field showing the Duplex Group Name should be changed. NewValue() is true if a valid Duplex Group Name is available; is false if the Duplex Group Name should be considered invalid.
  • DPLX_PC_CHANNEL_VALIDITY - Indicates that the validity of GUI field showing the Duplex Group Channel should be changed. NewValue() is true if a valid Duplex Group Channel is available; is false if the Duplex Group Channel should be considered invalid.
  • DPLX_PC_PASSWORD_VALIDITY - Indicates that the validity of GUI field showing the Duplex Group Password should be changed. NewValue() is true if a valid Duplex Group Password is available; is false if the Duplex Group Password should be considered invalid.
  • DPLX_PC_ID_VALIDITY - Indicates that the validity of GUI field showing the Duplex Group Id should be changed. NewValue() is true if a valid Duplex Group Id is available; is false if the Duplex Group Id should be considered invalid.
  • DPLX_PC_RCD_DPLX_IDENTITY_QUERY - Indicates that a LocoNet message which queries the Duplex Group identity has been received.
  • DPLX_PC_RCD_DPLX_IDENTITY_REPORT - Indicates that a LocoNet message which reports the Duplex Group identity has been received.
This tool works equally well with UR92 and UR92CE devices. The UR92 and UR92CE behave identically with respect to this tool. For the purpose of clarity, only the term UR92 is used herein.
See Also:

  • Field Details

  • Constructor Details

  • Method Details

    • isPasswordLimitedToNumbers

      public static final boolean isPasswordLimitedToNumbers()
      Report whether Duplex Group Password must only be numeric, or if Password is allowed to include characters 'A', 'B', and/or 'C'.
      Returns:
      true if Password may only include digits.

    • validateGroupName

      public static final boolean validateGroupName(String sGroupName)
      Validate a Duplex Group Name.

      A valid Duplex Group Name is an 8 character string. The calling method should append spaces or truncate to give correct length if necessary.

      Parameters:
      sGroupName - string containing group name to be validated
      Returns:
      true if and only if groupName is a valid Duplex Group Name

    • validateGroupPassword

      public static final boolean validateGroupPassword(String sGroupPassword)
      Validate a Duplex Group Password.

      Note that the password must be four digits if only numeric values are allowed, or must be four characters, each of pattern [0-9A-C] if alphanumeric values are allowed. (See private field limitPasswordToNumericCharacters.)

      Parameters:
      sGroupPassword - Duplex Group Password to be validated
      Returns:
      true if and only if sGroupPassword is a valid Duplex Group Password.

    • validateGroupChannel

      public static final boolean validateGroupChannel(Integer iGroupChannel)
      Validate a Duplex Group Channel Number.
      Parameters:
      iGroupChannel - Duplex Group Channel number to be validated
      Returns:
      true if and only if iGroupChannel is a valid Duplex Group Channel.

    • validateGroupID

      public static final boolean validateGroupID(Integer iGroupId)
      Validate the parameter as a Duplex Group ID number.
      Parameters:
      iGroupId - Duplex Group ID number to be validated
      Returns:
      true if and only if iGroupId is a valid Duplex Group ID.

    • createUr92GroupIdentityQueryPacket

      public static final LocoNetMessage createUr92GroupIdentityQueryPacket()
      Create a LocoNet packet which queries UR92(s) for Duplex group identification information. The invoking method is responsible for sending the message to LocoNet.
      Returns:
      LocoNetMessage containing IPL query of UR92s

    • createSetUr92GroupNamePacket

      public static final LocoNetMessage createSetUr92GroupNamePacket(String sGroupName) throws LocoNetException
      Create a LocoNet packet to set the Duplex group name.

      Throws an exception if s provides a 0-length group name string. If s is too short, it is padded with spaces at the end of the string.

      Parameters:
      sGroupName - is the desired group name value as a string
      Returns:
      The LocoNet packet which writes the Group Name to the UR92 device(s)
      Throws:
      LocoNetException - if sGroupName is not a valid Duplex Group Name

    • createSetUr92GroupChannelPacket

      public static final LocoNetMessage createSetUr92GroupChannelPacket(Integer iChannelNumber) throws LocoNetException
      Create a LocoNet packet to set the Duplex group channel number.

      If s provides a 0-length group name, a bogus LocoNet message is returned. If s does not define an integer is too short, it is padded with spaces at the end of the string.

      Parameters:
      iChannelNumber - The desired group channel number value as an integer
      Returns:
      The packet which writes the Group Channel Number to the UR92 device(s)
      Throws:
      LocoNetException - if sGroupName is not a valid Duplex Group Name

    • createSetUr92GroupPasswordPacket

      public static final LocoNetMessage createSetUr92GroupPasswordPacket(String sGroupPassword) throws LocoNetException
      Create a LocoNet packet to set the Duplex group password.

      If s provides anything other than a 4 character length group password which uses only valid group ID characters (0-9, A-C), a bogus LocoNet message is returned.

      Parameters:
      sGroupPassword - The desired group password as a string
      Returns:
      The packet which writes the Group Password to the UR92 device(s)
      Throws:
      LocoNetException - in case of invalid sGrooupPassword

    • createSetUr92GroupIDPacket

      public static final LocoNetMessage createSetUr92GroupIDPacket(String s) throws LocoNetException
      Create a LocoNet packet to set the Duplex group ID number.

      If s provides anything other than a numeric value between 0 and 127, a LocoNetException is thrown.

      Parameters:
      s - The desired group ID number as a string
      Returns:
      The packet which writes the Group ID Number to the UR92 device(s)
      Throws:
      LocoNetException - when an invalid id is provided

    • isDuplexGroupMessage

      public static final boolean isDuplexGroupMessage(LocoNetMessage m)
      Checks message m to determine if it contains a Duplex Group Identity message, including queries, reports, and writes, for Name, Channel, Password, and ID.
      Parameters:
      m - LocoNet message to check
      Returns:
      true if message is query, report, or write of Duplex Group Name, Channel, Password or ID

    • getDuplexGroupIdentityMessageType

      public static final DuplexGroupMessageType getDuplexGroupIdentityMessageType(LocoNetMessage m)
      Classifies a LocoNet Message to see if it is a Duplex Group Identity message
      Parameters:
      m - a LocoNetMessage
      Returns:
      DuplexGroupMessageType, encoded as one of the following NOT_A_DUPLEX_GROUP_MESSAGE DUPLEX_GROUP_CHANNEL_QUERY_MESSAGE DUPLEX_GROUP_CHANNEL_REPORT_MESSAGE DUPLEX_GROUP_CHANNEL_WRITE_MESSAGE DUPLEX_GROUP_NAME_QUERY_MESSAGE DUPLEX_GROUP_NAME_ETC_REPORT_MESSAGE DUPLEX_GROUP_NAME_WRITE_MESSAGE DUPLEX_GROUP_PASSWORD_QUERY_MESSAGE DUPLEX_GROUP_PASSWORD_REPORT_MESSAGE DUPLEX_GROUP_PASSWORD_WRITE_MESSAGE DUPLEX_GROUP_ID_QUERY_MESSAGE DUPLEX_GROUP_ID_REPORT_MESSAGE DUPLEX_GROUP_ID_WRITE_MESSAGE

    • extractDuplexGroupName

      public static String extractDuplexGroupName(LocoNetMessage m)
      Checks that m is a message with a Duplex Group Name encoded inside, then extracts the Duplex Group Name. Note that the returned string is always 8 characters long.

      If m does not contain a Duplex Group Name, returns null.

      Parameters:
      m - LocoNet message from which a Duplex Group Name is to be extracted.
      Returns:
      String containing Duplex Group Name as extracted from m

    • extractDuplexGroupChannel

      public static int extractDuplexGroupChannel(LocoNetMessage m)
      Checks that m is a message with a Duplex Group Channel encoded inside, then extracts and returns the Duplex Group Channel.

      Returns -1 if the m does not contain a Duplex Group Channel.

      Parameters:
      m - LocoNet message from which a Duplex Group Channel number will be extracted
      Returns:
      Integer containing Duplex Group Name as extracted from m

    • extractDuplexGroupID

      public static int extractDuplexGroupID(LocoNetMessage m)
      Checks that m is a message with a Duplex Group ID encoded inside, then extracts and returns the Duplex Group ID.

      Returns -1 if the m does not contain a Duplex Group ID.

      Parameters:
      m - LocoNet message from which a Duplex Group ID will be extracted
      Returns:
      Integer containing Duplex Group Name as extracted from m

    • extractDuplexGroupPassword

      public static String extractDuplexGroupPassword(LocoNetMessage m)
      Checks that m is a message with a Duplex Group Password encoded inside, then extracts and returns the Duplex Group Password.

      Returns null if the m does not contain a Duplex Group Password.

      Parameters:
      m - LocoNet message to be checked for a duplex group password message
      Returns:
      String containing the Duplex Group Password as extracted from m

    • message

      public void message(LocoNetMessage m)
      Process all incoming LocoNet messages to look for Duplex Group information operations. Only pays attention to LocoNet report of Duplex Group Name/password/channel/groupID, and ignores all other LocoNet messages.

      If tool has sent a query for Duplex group information and has not yet received a Duplex group report, the method updates the GUI with the received information.

      If the tool is not currently waiting for a response to a query, then the method compares the received information against the information currently displayed in the GUI. If the received information does not match, a message is displayed on the status line in the GUI, else nothing is displayed in the GUI status line.

      Specified by:
      message in interface LocoNetListener
      Parameters:
      m - The received LocoNet message. Note that this same object may be presented to multiple users. It should not be modified here.

    • getFetchedDuplexGroupName

      public String getFetchedDuplexGroupName()
      Returns:
      String containing reported Duplex Group Name

    • getFetchedDuplexGroupChannel

      public String getFetchedDuplexGroupChannel()
      Returns:
      String containing reported Duplex Group Name

    • getFetchedDuplexGroupPassword

      public String getFetchedDuplexGroupPassword()
      Returns:
      String containing reported Duplex Group Name

    • getFetchedDuplexGroupId

      public String getFetchedDuplexGroupId()
      Returns:
      String containing reported Duplex Group Name

    • queryDuplexGroupIdentity

      public void queryDuplexGroupIdentity()
      Sends a LocoNet Message to query the Duplex Group Identity. Starts a timer to monitor completion.

    • setDuplexGroupName

      public void setDuplexGroupName(String dgn) throws LocoNetException
      Creates and sends a LocoNet message which sets the Duplex Group Name.
      Parameters:
      dgn - String containing the new Duplex Group Name
      Throws:
      LocoNetException - if dgn is not a valid Duplex Group Name.

    • setDuplexGroupChannel

      public void setDuplexGroupChannel(Integer dgc) throws LocoNetException
      Creates and sends a LocoNet message which sets the Duplex Group Channel.
      Parameters:
      dgc - Integer containing the new Duplex Group Channel
      Throws:
      LocoNetException - if dgc is not a valid Duplex Group Channel number.

    • setDuplexGroupPassword

      public void setDuplexGroupPassword(String dgp) throws LocoNetException
      Creates and sends a LocoNet message which sets the Duplex Group Password.
      Parameters:
      dgp - String containing the new Duplex Group Password
      Throws:
      LocoNetException - if dgp is not a valid Duplex Group Password.

    • setDuplexGroupId

      public void setDuplexGroupId(String dgi) throws LocoNetException
      Creates and sends a LocoNet message which sets the Duplex Group Id.
      Parameters:
      dgi - String containing the new Duplex Group Id
      Throws:
      LocoNetException - if dgi is not a valid Duplex Group Id.

    • countUr92sAndQueryDuplexIdentityInfo

      public void countUr92sAndQueryDuplexIdentityInfo()
      Begins a sequence which includes counting available UR92s and similar and, if at least one UR92/UR93/LNWI is present, reads the Duplex Group Identity Info.

    • createUr92GroupNameReportPacket

      public static final LocoNetMessage createUr92GroupNameReportPacket(String dupName, String dupPass, int dupChan, int dupId)

    • createUr92GroupChannelReportPacket

      public static final LocoNetMessage createUr92GroupChannelReportPacket(int dupChan)

    • createUr92GroupPasswordReportPacket

      public static final LocoNetMessage createUr92GroupPasswordReportPacket(String dupPass)

    • createUr92GroupIdReportPacket

      public static final LocoNetMessage createUr92GroupIdReportPacket(int dupId)

    • getNumUr92s

      public int getNumUr92s()
      Reports the number of UR92 devices which responded to the most-recent LocoNet IPL query of UR92 devices.

      Note that code should ignore the value returned by this method if isWaitingForUr92DeviceReports() is true;

      Returns:
      the number of UR92 devices which reported in response to the LocoNet IPL device query which is sent by this class.

    • isWaitingForFirstUr92IPLReport

      public boolean isWaitingForFirstUr92IPLReport()
      Reports whether this class is currently waiting for the first UR92 LocoNet IPL Device Report messages in response to a LocoNet IPL Device Query for UR92s sent by this class.
      Returns:
      true if the class is waiting for LocoNet IPL reply messages, else false.

    • getMessagesHandled

      public int getMessagesHandled()
      Reports the number of LocoNet messages handled since object construction.
      Returns:
      the number of LocoNet messages since this object was constructed.

    • isIplQueryTimerRunning

      public boolean isIplQueryTimerRunning()
      Reports whether the IPL query timer is running.
      Returns:
      true if the timer is running, else false.

    • isDuplexGroupQueryRunning

      public boolean isDuplexGroupQueryRunning()
      Reports whether the Duplex Group Info query timer is running.
      Returns:
      true if the timer is running, else false.

    • isAwaitingDuplexGroupReportMessage

      public boolean isAwaitingDuplexGroupReportMessage()
      Reports whether this object is currently waiting for Duplex Group Name, etc. Report message.
      Returns:
      true if currently waiting, else false

    • connect

      public void connect(LnTrafficController t)
      Connect this instance's LocoNetListener to the LocoNet Traffic Controller
      Parameters:
      t - LocoNet traffic controller

    • dispose

      public void dispose()
      Break connection with the LnTrafficController and stop timers.