Package jmri.jmrit.decoderdefn

Class 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:
    DecoderIndexCreateAction

    • Method Detail

      • getMfgNameList

        public java.util.List<java.lang.String> getMfgNameList()

      • mfgIdFromName

        public java.lang.String mfgIdFromName​(java.lang.String name)

      • mfgNameFromID

        public java.lang.String mfgNameFromID​(java.lang.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 java.util.List<DecoderFile> matchingDecoderList​(java.lang.String mfg,
                                                       java.lang.String family,
                                                       java.lang.String decoderMfgID,
                                                       java.lang.String decoderVersionID,
                                                       java.lang.String decoderProductID,
                                                       java.lang.String model)
        Get a List of decoders matching some information.
        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 java.util.List<DecoderFile> matchingDecoderList​(java.lang.String mfg,
                                                       java.lang.String family,
                                                       java.lang.String decoderMfgID,
                                                       java.lang.String decoderVersionID,
                                                       java.lang.String decoderProductID,
                                                       java.lang.String model,
                                                       java.lang.String developerID,
                                                       java.lang.String manufacturerID,
                                                       java.lang.String productID)
        Get a List of decoders matching some information.
        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

      • matchingComboBox

        public javax.swing.JComboBox<java.lang.String> matchingComboBox​(java.lang.String mfg,
                                                                java.lang.String family,
                                                                java.lang.String decoderMfgID,
                                                                java.lang.String decoderVersionID,
                                                                java.lang.String decoderProductID,
                                                                java.lang.String model)
        Get a JComboBox representing the choices that match some information.
        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 javax.swing.JComboBox<java.lang.String> jComboBoxFromList​(java.util.List<DecoderFile> l)
        Get a JComboBox made with the titles from a list of DecoderFile entries.
        Parameters:
        l - list of decoders
        Returns:
        a combo box populated with the list

      • jComboBoxModelFromList

        public static javax.swing.ComboBoxModel<java.lang.String> jComboBoxModelFromList​(java.util.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​(java.lang.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,
                          java.lang.String mfgName,
                          java.lang.String family,
                          java.lang.String mfgID,
                          java.lang.String decoderVersionID,
                          java.lang.String decoderProductID,
                          java.lang.String model,
                          java.lang.String developerID,
                          java.lang.String manufacturerID,
                          java.lang.String productID)
        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
        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,
                                          java.io.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
        java.io.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​(java.lang.String name)
       throws org.jdom2.JDOMException,
              java.io.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
        java.io.IOException - if unable to read decoder index file

      • readMfgSection

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

      • readFamily

        void readFamily​(org.jdom2.Element family)

      • checkInCommaDelimString

        public boolean checkInCommaDelimString​(java.lang.String findString,
                                       java.lang.String inString)
        Is target string in 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​(java.lang.String name,
                      DecoderIndexFile oldIndex,
                      java.lang.String[] files,
                      javax.swing.JOptionPane pane,
                      javax.swing.JProgressBar pb)
               throws java.io.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:
        java.io.IOException - for errors writing the decoder index file

      • defaultDecoderIndexFilename

        protected static java.lang.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