Package jmri.jmrix

Class AbstractProgrammer

java.lang.Object
jmri.beans.PropertyChangeSupport
jmri.jmrix.AbstractProgrammer
All Implemented Interfaces:
PropertyChangeFirer, PropertyChangeProvider, Disposable, Programmer
Direct Known Subclasses:
BiDiBOpsModeProgrammer, BiDiBProgrammer, CbusDccProgrammer, Dcc4PcOpsModeProgrammer, DCCppOpsModeProgrammer, DCCppProgrammer, EasyDccProgrammer, EcosProgrammer, MrcProgrammer, Mx1Programmer, NceProgrammer, OlcbProgrammer, QsiProgrammer, SlotManager, SprogProgrammer, SRCPProgrammer, TamsProgrammer, TmccProgrammer, XNetOpsModeProgrammer, XNetProgrammer
public abstract class AbstractProgrammer extends PropertyChangeSupport implements Programmer
Common implementations for the Programmer interface.

Contains two time-out handlers:

  • SHORT_TIMEOUT, the "short timer", is on operations other than reads
  • LONG_TIMEOUT, the "long timer", is for the "read from decoder" step, which can take a long time.
The duration of these can be adjusted by changing the values of those constants in subclasses.

  • Field Details

  • Constructor Details

  • Method Details

    • decodeErrorCode

      @Nonnull public String decodeErrorCode(int code)
      Specified by:
      decodeErrorCode in interface Programmer

    • writeCV

      public abstract void writeCV(String CV, int val, ProgListener p) throws ProgrammerException
      Perform a CV write in the system-specific manner, and using the specified programming mode.

      Handles a general address space through a String address. Each programmer defines the acceptable formats.

      Note that this returns before the write is complete; you have to provide a ProgListener to hear about completion. For simplicity, expect the return to be on the GUI thread.

      Exceptions will only be thrown at the start, not during the actual programming sequence. A typical exception would be due to an invalid mode (though that should be prevented earlier)

      Specified by:
      writeCV in interface Programmer
      Parameters:
      CV - the CV to write
      val - the value to write
      p - the listener that will be notified of the write
      Throws:
      ProgrammerException - if unable to communicate

    • readCV

      public abstract void readCV(String CV, ProgListener p) throws ProgrammerException
      Perform a CV read in the system-specific manner, and using the specified programming mode.

      Handles a general address space through a String address. Each programmer defines the acceptable formats.

      Note that this returns before the write is complete; you have to provide a ProgListener to hear about completion. For simplicity, expect the return to be on the GUI thread.

      Exceptions will only be thrown at the start, not during the actual programming sequence. A typical exception would be due to an invalid mode (though that should be prevented earlier)

      Specified by:
      readCV in interface Programmer
      Parameters:
      CV - the CV to read
      p - the listener that will be notified of the read
      Throws:
      ProgrammerException - if unable to communicate

    • confirmCV

      public abstract void confirmCV(String CV, int val, ProgListener p) throws ProgrammerException
      Confirm the value of a CV using the specified programming mode. On some systems, this is faster than a read.

      Handles a general address space through a String address. Each programmer defines the acceptable formats.

      Note that this returns before the write is complete; you have to provide a ProgListener to hear about completion. For simplicity, expect the return to be on the GUI thread.

      Exceptions will only be thrown at the start, not during the actual programming sequence. A typical exception would be due to an invalid mode (though that should be prevented earlier)

      Specified by:
      confirmCV in interface Programmer
      Parameters:
      CV - the CV to confirm
      val - the value to confirm
      p - the listener that will be notified of the confirmation
      Throws:
      ProgrammerException - if unable to communicate

    • getCanRead

      public boolean getCanRead()
      Checks the general read capability, regardless of mode Basic implementation. Override this to turn reading on and off globally.
      Specified by:
      getCanRead in interface Programmer
      Returns:
      true if the programmer is capable of reading; false otherwise

    • getCanRead

      public boolean getCanRead(String addr)
      Checks the general read capability, regardless of mode, for a specific address Checks using the current default programming mode
      Specified by:
      getCanRead in interface Programmer
      Parameters:
      addr - the address to read
      Returns:
      true if the address can be read; false otherwise

    • setMode

      public final void setMode(ProgrammingMode m)
      Set the programmer to a particular mode.

      Mode is a bound parameter; mode changes fire listeners.

      Only modes returned by Programmer.getSupportedModes() are supported. If an invalid mode is requested, the active mode is unchanged.

      Specified by:
      setMode in interface Programmer
      Parameters:
      m - a valid node returned by Programmer.getSupportedModes() or null; null is ignored if Programmer.getSupportedModes() is not empty

    • getBestMode

      public ProgrammingMode getBestMode()
      Define the "best" programming mode, which provides the initial setting.

      The definition of "best" is up to the specific-system developer. By default, this is the first of the available methods from getSupportedModes; override this method to change that.

      Returns:
      The recommended ProgrammingMode or null if none exists or is defined.

    • getMode

      public final ProgrammingMode getMode()
      Get the current programming mode
      Specified by:
      getMode in interface Programmer
      Returns:
      the current mode or null if none is defined and no default mode is defined

    • getSupportedModes

      @Nonnull public abstract List<ProgrammingMode> getSupportedModes()
      Description copied from interface: Programmer
      Get the list of ProgrammingMode supported by this Programmer. If the order is significant, earlier modes are better.
      Specified by:
      getSupportedModes in interface Programmer
      Returns:
      the list of supported modes or an empty list

    • getCanWrite

      public boolean getCanWrite()
      Checks the general write capability, regardless of mode Basic implementation. Override this to turn writing on and off globally.
      Specified by:
      getCanWrite in interface Programmer
      Returns:
      true if the programmer is capable of writing; false otherwise

    • getCanWrite

      public boolean getCanWrite(String addr)
      Checks the general write capability, regardless of mode, for a specific address Checks using the current default programming mode.
      Specified by:
      getCanWrite in interface Programmer
      Parameters:
      addr - the address to write to
      Returns:
      true if the address can be written to; false otherwise

    • getWriteConfirmMode

      @Nonnull public Programmer.WriteConfirmMode getWriteConfirmMode(String addr)
      Learn about whether the programmer does any kind of verification of write operations By default, say that no verification is done.
      Specified by:
      getWriteConfirmMode in interface Programmer
      Parameters:
      addr - A CV address to check (in case this varies with CV range) or null for any
      Returns:
      Always WriteConfirmMode.NotVerified

    • startShortTimer

      protected void startShortTimer()
      Internal routine to start timer to protect the mode-change.

    • startLongTimer

      protected void startLongTimer()
      Internal routine to restart timer with a long delay

    • stopTimer

      protected void stopTimer()
      Internal routine to stop timer, as all is well

    • restartTimer

      protected void restartTimer(int delay)
      Internal routine to handle timer starts and restarts.
      Parameters:
      delay - the initial delay, in milliseconds

    • registerFromCV

      public int registerFromCV(int cv) throws ProgrammerException
      Find the register number that corresponds to a specific CV number.
      Parameters:
      cv - CV number (1 through 512) for which equivalent register is desired
      Returns:
      register number corresponding to cv
      Throws:
      ProgrammerException - if the requested CV does not correspond to a register

    • timeout

      protected abstract void timeout()
      Internal routine to handle a timeout, should be synchronized!