Package jmri.jmrit.roster

Class RosterEntry

  • All Implemented Interfaces:
    BasicRosterEntry, BeanInterface, PropertyChangeFirer, PropertyChangeProvider, RosterObject
    public class RosterEntry
extends ArbitraryBean
implements RosterObject, BasicRosterEntry
    RosterEntry represents a single element in a locomotive roster, including information on how to locate it from decoder information.

    The RosterEntry is the central place to find information about a locomotive's configuration, including CV and "programming variable" information. RosterEntry handles persistence through the LocoFile class. Creating a RosterEntry does not necessarily read the corresponding file (which might not even exist), please see readFile(), writeFile() member functions.

    All the data attributes have a content, not null. FileName, however, is special. A null value for it indicates that no physical file is (yet) associated with this entry.

    When the filePath attribute is non-null, the user has decided to organize the roster into directories.

    Each entry can have one or more "Attributes" associated with it. These are (key, value) pairs. The key has to be unique, and currently both objects have to be Strings.

    All properties, including the "Attributes", are bound.

    See Also:
    LocoFile

    • Constructor Detail

      • RosterEntry

        public RosterEntry()
        Construct a blank object.

      • RosterEntry

        public RosterEntry​(java.lang.String fileName)
        Constructor based on a given file name.
        Parameters:
        fileName - xml file name for the user's Roster entry

      • RosterEntry

        public RosterEntry​(RosterEntry pEntry,
                   java.lang.String pID)
        Constructor based on a given RosterEntry object and name/ID.
        Parameters:
        pEntry - RosterEntry object
        pID - unique name/ID for the roster entry

      • RosterEntry

        public RosterEntry​(org.jdom2.Element e)
        Construct this Entry from XML.

        This member has to remain synchronized with the detailed schema in xml/schema/locomotive-config.xsd.

        Parameters:
        e - Locomotive XML element

    • Method Detail

      • getMaxFnNumAsInt

        public int getMaxFnNumAsInt()
        Get the highest valid Fn key number for this roster entry.
        The default value (28) can be overridden by a "maxFnNum" attribute in the "model" element of a decoder definition file
        • A European standard (RCN-212) extends NMRA S9.2.1 up to F68.
        • ESU LokSound 5 already uses up to F31.
        Returns:
        the highest function number (Fn) supported by this roster entry.
        See Also:
        "http://normen.railcommunity.de/RCN-212.pdf"

      • setId

        public void setId​(java.lang.String s)
        Set the roster ID for this roster entry.
        Parameters:
        s - new ID

      • setFileName

        public void setFileName​(java.lang.String s)
        Set the file name for this roster entry.
        Parameters:
        s - the new roster entry file name

      • ensureFilenameExists

        public void ensureFilenameExists()
        Ensure the entry has a valid filename.

        If none exists, create one based on the ID string. Does _not_ enforce any particular naming; you have to check separately for "<none>" or whatever your convention is for indicating an invalid name. Does replace the space, period, colon, slash and backslash characters so that the filename will be generally usable.

      • setRoadName

        public void setRoadName​(java.lang.String s)

      • setRoadNumber

        public void setRoadNumber​(java.lang.String s)

      • setMfg

        public void setMfg​(java.lang.String s)

      • getMfg

        public java.lang.String getMfg()

      • setModel

        public void setModel​(java.lang.String s)

      • getModel

        public java.lang.String getModel()

      • setOwner

        public void setOwner​(java.lang.String s)

      • getOwner

        public java.lang.String getOwner()

      • setDccAddress

        public void setDccAddress​(java.lang.String s)

      • setComment

        public void setComment​(java.lang.String s)

      • getComment

        public java.lang.String getComment()

      • setProgrammingModes

        public void setProgrammingModes​(@CheckForNull
                                java.lang.String s)
        Set programming modes as defined in a roster entry's decoder definition.
        Parameters:
        s - a comma separated string of predefined mode elements

      • getProgrammingModes

        public java.lang.String getProgrammingModes()
        Get the modes as defined in a roster entry's decoder definition.
        Returns:
        a comma separated string of predefined mode elements

      • setMaxFnNum

        public void setMaxFnNum​(java.lang.String s)

      • setImagePath

        public void setImagePath​(java.lang.String s)

      • setIconPath

        public void setIconPath​(java.lang.String s)

      • setURL

        public void setURL​(java.lang.String s)

      • getURL

        public java.lang.String getURL()

      • setDateModified

        public void setDateModified​(@Nonnull
                            java.lang.String date)
                     throws java.text.ParseException
        Set the date modified given a string representing a date.

        Tries ISO 8601 and the current Java defaults as formats for parsing a date.

        Parameters:
        date - the string to parse into a date
        Throws:
        java.text.ParseException - if the date cannot be parsed

      • setDateUpdated

        protected void setDateUpdated​(java.lang.String s)
        Set the date last updated.
        Parameters:
        s - the string to parse into a date

      • getDateUpdated

        public java.lang.String getDateUpdated()
        Get the date this entry was last modified. Returns the value of getDateModified() in ISO 8601 format if that is not null, otherwise returns the raw value for the last modified date from the XML file for the roster entry.

        Use getDateModified() if control over formatting is required

        Returns:
        the string representation of the date last modified

      • loadFunctions

        public void loadFunctions​(org.jdom2.Element e3)
        Load function names from a JDOM element.

        Does not change values that are already present!

        Parameters:
        e3 - the XML element containing functions

      • loadFunctions

        public void loadFunctions​(org.jdom2.Element e3,
                          java.lang.String source)
        Loads function names from a JDOM element. Does not change values that are already present!
        Parameters:
        e3 - the XML element containing the functions
        source - "family" if source is the decoder definition, or "model" if source is the roster entry itself

      • loadSounds

        public void loadSounds​(org.jdom2.Element e3,
                       java.lang.String source)
        Loads sound names from a JDOM element. Does not change values that are already present!
        Parameters:
        e3 - the XML element containing sound names
        source - "family" if source is the decoder definition, or "model" if source is the roster entry itself

      • loadAttributes

        public void loadAttributes​(org.jdom2.Element e3)
        Load attribute key/value pairs from a JDOM element.
        Parameters:
        e3 - XML element containing roster entry attributes

      • setFunctionLabel

        public void setFunctionLabel​(int fn,
                             java.lang.String label)
        Set the label for a specific function.
        Parameters:
        fn - function number, starting with 0
        label - the label to use

      • getFunctionLabel

        public java.lang.String getFunctionLabel​(int fn)
        If a label has been defined for a specific function, return it, otherwise return null.
        Parameters:
        fn - function number, starting with 0
        Returns:
        function label or null if not defined

      • setSoundLabel

        public void setSoundLabel​(int fn,
                          java.lang.String label)
        Define label for a specific sound.
        Parameters:
        fn - sound number, starting with 0
        label - display label for the sound function

      • getSoundLabel

        public java.lang.String getSoundLabel​(int fn)
        If a label has been defined for a specific sound, return it, otherwise return null.
        Parameters:
        fn - sound number, starting with 0
        Returns:
        sound label or null

      • setFunctionImage

        public void setFunctionImage​(int fn,
                             java.lang.String s)

      • setFunctionLockable

        public void setFunctionLockable​(int fn,
                                boolean lockable)
        Define whether a specific function is lockable.
        Parameters:
        fn - function number, starting with 0
        lockable - true if function is continuous; false if momentary

      • getFunctionLockable

        public boolean getFunctionLockable​(int fn)
        Return the lockable/latchable state of a specific function. Defaults to true.
        Parameters:
        fn - function number, starting with 0
        Returns:
        true if function is lockable/latchable

      • setFunctionVisible

        public void setFunctionVisible​(int fn,
                               boolean visible)
        Define whether a specific function button is visible.
        Parameters:
        fn - function number, starting with 0
        visible - true if function button is visible; false to hide

      • getFunctionVisible

        public boolean getFunctionVisible​(int fn)
        Return the UI visibility of a specific function button. Defaults to true.
        Parameters:
        fn - function number, starting with 0
        Returns:
        true if function button is visible

      • getAttributes

        public java.util.Set<java.lang.String> getAttributes()
        Provide access to the set of attributes.

        This is directly backed access, so e.g. removing an item from this Set removes it from the RosterEntry too.

        Returns:
        a set of attribute keys

      • getGroups

        public java.util.List<RosterGroup> getGroups()
        List the roster groups this entry is a member of, returning existing RosterGroups from the default Roster if they exist.
        Returns:
        list of roster groups

      • getGroups

        public java.util.List<RosterGroup> getGroups​(Roster roster)
        List the roster groups this entry is a member of, returning existing RosterGroups from the specified Roster if they exist.
        Parameters:
        roster - the roster to get matching groups from
        Returns:
        list of roster groups

      • warnShortLong

        protected void warnShortLong​(java.lang.String id)
        Warn user that the roster entry needs to be resaved.
        Parameters:
        id - roster ID to warn about

      • store

        public org.jdom2.Element store()
        Create an XML element to represent this Entry.

        This member has to remain synchronized with the detailed schema in xml/schema/locomotive-config.xsd.

        Specified by:
        store in interface BasicRosterEntry
        Returns:
        Contents in a JDOM Element

      • updateFile

        public void updateFile()
        Write the contents of this RosterEntry back to a file, preserving all existing decoder CV content.

        This writes the file back in place, with the same decoder-specific content.

      • writeFile

        public void writeFile​(CvTableModel cvModel,
                      VariableTableModel variableModel)
        Write the contents of this RosterEntry to a file.

        Information on the contents is passed through the parameters, as the actual XML creation is done in the LocoFile class.

        Parameters:
        cvModel - CV contents to include in file
        variableModel - Variable contents to include in file

      • changeDateUpdated

        public void changeDateUpdated()
        Mark the date updated, e.g. from storing this roster entry.

      • loadCvModel

        public void loadCvModel​(VariableTableModel varModel,
                        CvTableModel cvModel)
        Load pre-existing Variable and CvTableModel object with the contents of this entry.
        Parameters:
        varModel - the variable model to load
        cvModel - CV contents to load

      • printEntryDetails

        public void printEntryDetails​(java.io.Writer w)
        Print the roster entry information.

        Updated to allow for multiline comment and decoder comment fields. Separate write statements for text and line feeds to work around the HardcopyWriter bug that misplaces borders.

        Parameters:
        w - the HardcopyWriter used to print

      • wrapComment

        public java.util.Vector<java.lang.String> wrapComment​(java.lang.String comment,
                                                      int textSpace)
        Line wrap a comment.
        Parameters:
        comment - the comment to wrap at word boundaries
        textSpace - the width of the space to print
        Returns:
        comment wrapped to fit given width

      • readFile

        public void readFile()
        Read a file containing the contents of this RosterEntry.

        This has to be done before a call to loadCvModel, for example.

      • fromFile

        public static RosterEntry fromFile​(@Nonnull
                                   java.io.File file)
                            throws org.jdom2.JDOMException,
                                   java.io.IOException
        Create a RosterEntry from a file.
        Parameters:
        file - The file containing the RosterEntry
        Returns:
        a new RosterEntry
        Throws:
        org.jdom2.JDOMException - if unable to parse file
        java.io.IOException - if unable to read file