Package jmri.jmrit.decoderdefn

Class DecoderIndexFile

java.lang.Object
jmri.jmrit.XmlFile
jmri.jmrit.decoderdefn.DecoderIndexFile
public class DecoderIndexFile extends XmlFile
DecoderIndex represents the decoderIndex.xml (decoder types) and nmra_mfg_list.xml (Manufacturer ID list) files in memory.

This allows a program to navigate to various decoder descriptions without having to manipulate files.

This class doesn't provide tools for defining the index; that's done by DecoderIndexCreateAction, which rebuilds it from the decoder files.

Multiple DecoderIndexFile objects don't make sense, so we use an "instance" member to navigate to a single one.

Previous to JMRI 4.19.1, the manufacturer information was kept in the decoderIndex.xml file. Starting with that version it's in the separate nmra_mfg_list.xml file, but still written to decoderIndex.xml when one is created.

See Also:

  • Field Details

  • Constructor Details

  • Method Details

    • numDecoders

      public int numDecoders()

    • getMfgNameList

      public List<String> getMfgNameList()

    • mfgIdFromName

      public String mfgIdFromName(String name)

    • mfgNameFromID

      public String mfgNameFromID(String idNum)
      Parameters:
      idNum - String containing the manufacturer's NMRA manufacturer ID number
      Returns:
      String containing the "friendly" name of the manufacturer

    • matchingDecoderList

      @Nonnull public List<DecoderFile> matchingDecoderList(String progMode)
      Get a List of decoders matching (only) the programming mode.
      Parameters:
      progMode - decoder programming mode as defined in a decoder's programming element
      Returns:
      a list, possibly empty, of matching decoders

    • matchingDecoderList

      @Nonnull public List<DecoderFile> matchingDecoderList(String mfg, String family, String decoderMfgID, String decoderVersionID, String decoderProductID, String model)
      Get a List of decoders matching basic characteristics.
      Parameters:
      mfg - decoder manufacturer
      family - decoder family
      decoderMfgID - NMRA decoder manufacturer ID
      decoderVersionID - decoder version ID
      decoderProductID - decoder product ID
      model - decoder model
      Returns:
      a list, possibly empty, of matching decoders

    • matchingDecoderList

      @Nonnull public List<DecoderFile> matchingDecoderList(String mfg, String family, String decoderMfgID, String decoderVersionID, String decoderProductID, String model, String developerID, String manufacturerID, String productID)
      Get a List of decoders matching basic characteristics + product ID etc.
      Parameters:
      mfg - decoder manufacturer
      family - decoder family
      decoderMfgID - NMRA decoder manufacturer ID
      decoderVersionID - decoder version ID
      decoderProductID - decoder product ID
      model - decoder model
      developerID - developer ID number
      manufacturerID - manufacturerID number
      productID - productID number
      Returns:
      a list, possibly empty, of matching decoders

    • matchingDecoderList

      @Nonnull public List<DecoderFile> matchingDecoderList(String mfg, String family, String decoderMfgID, String decoderVersionID, String decoderProductID, String model, String developerID, String manufacturerID, String productID, String progMode)
      Get a List of decoders matching basic characteristics + product ID etc. + programming mode.
      Parameters:
      mfg - decoder manufacturer
      family - decoder family
      decoderMfgID - NMRA decoder manufacturer ID
      decoderVersionID - decoder version ID
      decoderProductID - decoder product ID
      model - decoder model
      developerID - developer ID number
      manufacturerID - manufacturerID number
      productID - productID number
      progMode - programming mode as defined in a decoder's programming element
      Returns:
      a list, possibly empty, of matching decoders

    • matchingComboBox

      public JComboBox<String> matchingComboBox(String mfg, String family, String decoderMfgID, String decoderVersionID, String decoderProductID, String model)
      Get a JComboBox representing the choices that match basic characteristics.
      Parameters:
      mfg - decoder manufacturer
      family - decoder family
      decoderMfgID - NMRA decoder manufacturer ID
      decoderVersionID - decoder version ID
      decoderProductID - decoder product ID
      model - decoder model
      Returns:
      a combo box populated with matching decoders

    • jComboBoxFromList

      public static JComboBox<String> jComboBoxFromList(List<DecoderFile> l)
      Get a new JComboBox made with the titles from a list of DecoderFile.
      Parameters:
      l - list of decoders
      Returns:
      a combo box populated with the list

    • jComboBoxModelFromList

      public static ComboBoxModel<String> jComboBoxModelFromList(List<DecoderFile> l)
      Get a new ComboBoxModel made with the titles from a list of DecoderFile. entries.
      Parameters:
      l - list of decoders
      Returns:
      a combo box model populated with the list

    • fileFromTitle

      public DecoderFile fileFromTitle(String title)
      Get a DecoderFile from a "title" string, typically a selection in a matching ComboBox.
      Parameters:
      title - the decoder title
      Returns:
      the decoder file

    • checkEntry

      public boolean checkEntry(int i, String mfgName, String family, String mfgID, String decoderVersionID, String decoderProductID, String model, String developerID, String manufacturerID, String productID, String progMode)
      Check if an entry consistent with specific properties. A null String entry always matches. Strings are used for convenience in GUI building. Don't bother asking about the model number...
      Parameters:
      i - index of entry
      mfgName - decoder manufacturer
      family - decoder family
      mfgID - NMRA decoder manufacturer ID
      decoderVersionID - decoder version ID
      decoderProductID - decoder product ID
      model - decoder model
      developerID - developer ID number
      manufacturerID - manufacturer ID number
      productID - product ID number
      progMode - programming mode as defined in a decoder's programming element
      Returns:
      true if entry at i matches the other parameters; false otherwise

    • resetInstance

      public static void resetInstance()
      Replace the managed instance with a new instance.

    • updateIndexIfNeeded

      public static boolean updateIndexIfNeeded() throws org.jdom2.JDOMException, IOException
      Check whether the user's version of the decoder index file needs to be updated; if it does, then forces the update.
      Returns:
      true is the index should be reloaded because it was updated
      Throws:
      org.jdom2.JDOMException - if unable to parse decoder index
      IOException - if unable to read decoder index

    • forceCreationOfNewIndex

      public static void forceCreationOfNewIndex()
      Force creation of a new user index without incrementing version

    • forceCreationOfNewIndex

      public static void forceCreationOfNewIndex(boolean increment)
      Force creation of a new user index.
      Parameters:
      increment - true to increment the version of the decoder index

    • readFile

      void readFile(String name) throws org.jdom2.JDOMException, IOException
      Read the contents of a decoderIndex XML file into this object. Note that this does not clear any existing entries; reset the instance to do that.
      Parameters:
      name - the name of the decoder index file
      Throws:
      org.jdom2.JDOMException - if unable to parse to decoder index file
      IOException - if unable to read decoder index file

    • readMfgSection

      void readMfgSection() throws org.jdom2.JDOMException, IOException
      Throws:
      org.jdom2.JDOMException
      IOException

    • readFamilySection

      void readFamilySection(org.jdom2.Element decoderIndex)

    • readFamily

      void readFamily(org.jdom2.Element family)

    • checkInCommaDelimString

      public boolean checkInCommaDelimString(String findString, String inString)
      Check if target string is in a comma-delimited string

      Example: findString = "47" inString = "1,4,53,97" return value is 'false'

      Example: findString = "47" inString = "1,31,47,51" return value is 'true'

      Example: findString = "47" inString = "47" return value is true

      Parameters:
      findString - string to find
      inString - comma-delimited string of sub-strings
      Returns:
      true if target string is found as sub-string within comma- delimited string

    • writeFile

      public void writeFile(String name, DecoderIndexFile oldIndex, String[] files, JOptionPane pane, JProgressBar pb) throws IOException
      Build and write the decoder index file, based on a set of decoder files.

      This creates the full DOM object for the decoder index based on reading the supplied decoder xml files. It then saves the decoder index out to a new file.

      Parameters:
      name - name of the new index file
      oldIndex - old decoder index file
      files - array of files to read for new index
      pane - optional JOptionPane to check for cancellation
      pb - optional JProgressBar to update during operations
      Throws:
      IOException - for errors writing the decoder index file

    • defaultDecoderIndexFilename

      protected static String defaultDecoderIndexFilename()
      Get the filename for the default decoder index file, including location. This is here to allow easy override in tests.
      Returns:
      the complete path to the decoder index