jmri.jmrit.roster
Class Roster

java.lang.Object
  jmri.jmrit.XmlFile
      jmri.jmrit.roster.Roster

public class Roster
extends XmlFile

Roster manages and manipulates a roster of locomotives.

It works with the "roster-config" XML DTD to load and store its information.

This is an in-memory representation of the roster xml file (see below for constants defining name and location). As such, this class is also responsible for the "dirty bit" handling to ensure it gets written. As a temporary reliability enhancement, all changes to this structure are now being written to a backup file, and a copy is made when the file is opened.

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

The only bound property is the list of RosterEntrys; a PropertyChangedEvent is fired every time that changes.

The entries are stored in an ArrayList, sorted alphabetically. That sort is done manually each time an entry is added.

The roster is stored in a "Roster Index", which can be read or written. Each individual entry (once stored) contains a filename which can be used to retreive the locomotive information for that roster entry. Note that the RosterEntry information is duplicated in both the Roster (stored in the roster.xml file) and in the specific file for the entry.

Author:

Bob Jacobsen Copyright (C) 2001, 2008, 2010, Dennis Miller Copyright 2004

See Also:

RosterEntry

Field Summary

protected List<RosterEntry>	_list List of contained RosterEntry elements.
protected ArrayList<String>	_rosterGroupList

Fields inherited from class jmri.jmrit.XmlFile

dtdLocation, xsltLocation

Constructor Summary

Roster()

Method Summary

void	addEntry(RosterEntry e) Add a RosterEntry object to the in-memory Roster.
void	addPropertyChangeListener(PropertyChangeListener l)
void	addRosterGroupList(String str)
boolean	checkEntry(int i, String roadName, String roadNumber, String dccAddress, String mfg, String decoderModel, String decoderFamily, String id) Check if an entry is consistent with specific properties.
static String	defaultRosterFilename() Return the filename String for the default roster file, including location.
void	delRosterGroupList(String str)
void	dispose()
RosterEntry	entryFromTitle(String title) Return RosterEntry from a "title" string, ala selection in matchingComboBox.
void	entryIdChanged(RosterEntry r) Notify that the ID of an entry has changed.
String	fileFromTitle(String title) Return filename from a "title" string, ala selection in matchingComboBox.
protected void	firePropertyChange(String p, Object old, Object n)
JComboBox	fullRosterComboBox() Return a JComboBox containing the entire roster, if a roster group has been selected, it will only return the entries relating to that group.
JComboBox	fullRosterComboBoxGlobal() Return a JComboBox containing the entire roster, regardless of what roster group has been selected.
Set<String>	getAllAttributeKeys()
List<RosterEntry>	getEntriesWithAttributeKey(String key)
List<RosterEntry>	getEntriesWithAttributeKeyValue(String key, String value)
RosterEntry	getEntry(int i) Return a specific entry by index
static String	getFileLocation() Absolute path to roster file location.
RosterEntry	getGroupEntry(int i)
static String	getRosterGroup()
void	getRosterGroupList(int i)
static String	getRosterGroupName()
String	getRosterGroupPrefix()
static String	getRosterGroupWP()
static void	installNullInstance() Provide a null (empty) roster instance
static Roster	instance() Locate the single instance of Roster, loading it if need be.
static String	makeValidFilename(String entry) Name a valid roster entry filename from an entry name.
JComboBox	matchingComboBox(String roadName, String roadNumber, String dccAddress, String mfg, String decoderMfgID, String decoderVersionID, String id) Get a JComboBox representing the choices that match some information.
JComboBox	matchingComboBoxGlobal(String roadName, String roadNumber, String dccAddress, String mfg, String decoderMfgID, String decoderVersionID, String id) Get a JComboBox representing the choices that match some information regardless of which roster group has been selected.
List<RosterEntry>	matchingList(String roadName, String roadNumber, String dccAddress, String mfg, String decoderMfgID, String decoderVersionID, String id) Get a List of RosterEntry objects in Roster matching some information.
int	numEntries()
int	numGroupEntries()
void	reloadRosterFile() Update the in-memory Roster to be consistent with the current roster file.
void	removeEntry(RosterEntry e) Remove a RosterEntry object from the in-memory Roster.
void	removePropertyChangeListener(PropertyChangeListener l)
static void	resetInstance()
JComboBox	rosterGroupBox()
void	rosterGroupEntryChanged() This is here so that when a roster entry is added to a group via the table entry, a propertyChangeEvent is fired off.
static void	setFileLocation(String f) Set the default location for the Roster file, and all individual locomotive files.
static void	setRosterFileName(String name)
void	setRosterGroup(String group)
void	updateComboBox(JComboBox box)
void	updateComboBoxGlobal(JComboBox box)
void	updateGroupBox(JComboBox box)
static void	writeRosterFile() Store the roster in the default place, including making a backup if needed.

Methods inherited from class jmri.jmrit.XmlFile

addDefaultInfo, backupFileName, checkFile, createFileNameWithDate, dumpElement, ensurePrefsPresent, findFile, getBuilder, getRootViaURI, getVerify, makeBackupFile, makeBackupFile, newDocument, newDocument, prefsDir, reportError1, reportError2, resourcesDir, revertBackupFile, rootFromFile, rootFromName, rootFromURL, scriptsDir, setScriptsFileLocationDefault, setUserFileLocationDefault, setVerify, userFileChooser, userFileChooser, userFileChooser, userFileChooser, userFileLocationDefault, writeXML, xmlDir

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

_list

protected List<RosterEntry> _list

List of contained RosterEntry elements.

_rosterGroupList

protected ArrayList<String> _rosterGroupList

Constructor Detail

Roster

public Roster()

Method Detail

resetInstance

public static void resetInstance()

instance

public static Roster instance()

Locate the single instance of Roster, loading it if need be.

Returns:

The valid Roster object

installNullInstance

public static void installNullInstance()

Provide a null (empty) roster instance

addEntry

public void addEntry(RosterEntry e)

Add a RosterEntry object to the in-memory Roster.

Parameters:

e - Entry to add

removeEntry

public void removeEntry(RosterEntry e)

Remove a RosterEntry object from the in-memory Roster. This does not delete the file for the RosterEntry!

Parameters:

e - Entry to remove

numEntries

public int numEntries()

Returns:

Number of entries in the Roster.

numGroupEntries

public int numGroupEntries()

Returns:

The Number of roster entries that are in the currently selected group.

fullRosterComboBox

public JComboBox fullRosterComboBox()

Return a JComboBox containing the entire roster, if a roster group has been selected, it will only return the entries relating to that group.

The JComboBox is based on a common model object, so it updates when the roster changes.

fullRosterComboBoxGlobal

public JComboBox fullRosterComboBoxGlobal()

Return a JComboBox containing the entire roster, regardless of what roster group has been selected.

The JComboBox is based on a common model object, so it updates when the roster changes.

matchingComboBox

public JComboBox matchingComboBox(String roadName,
                                  String roadNumber,
                                  String dccAddress,
                                  String mfg,
                                  String decoderMfgID,
                                  String decoderVersionID,
                                  String id)

Get a JComboBox representing the choices that match some information. If a roster group has been selected then the results will be restricted to those in the roster group.

Only entries that exactly match the given parameters will be returned. Null parameters mean to ignore that part of the match.

The JComboBox is based on a common model object, so it updates when the roster changes.

matchingComboBoxGlobal

public JComboBox matchingComboBoxGlobal(String roadName,
                                        String roadNumber,
                                        String dccAddress,
                                        String mfg,
                                        String decoderMfgID,
                                        String decoderVersionID,
                                        String id)

Get a JComboBox representing the choices that match some information regardless of which roster group has been selected.

Only entries that exactly match the given parameters will be returned. Null parameters mean to ignore that part of the match.

The JComboBox is based on a common model object, so it updates when the roster changes.

updateComboBox

public void updateComboBox(JComboBox box)

updateComboBoxGlobal

public void updateComboBoxGlobal(JComboBox box)

entryFromTitle

public RosterEntry entryFromTitle(String title)

Return RosterEntry from a "title" string, ala selection in matchingComboBox.

getEntry

public RosterEntry getEntry(int i)

Return a specific entry by index

getGroupEntry

public RosterEntry getGroupEntry(int i)

Returns:

The Number of roster entries that are in the currently selected group.

fileFromTitle

public String fileFromTitle(String title)

Return filename from a "title" string, ala selection in matchingComboBox.

Returns:

The filename matching this "title", or null if none exists

getEntriesWithAttributeKey

public List<RosterEntry> getEntriesWithAttributeKey(String key)

getEntriesWithAttributeKeyValue

public List<RosterEntry> getEntriesWithAttributeKeyValue(String key,
                                                         String value)

getAllAttributeKeys

public Set<String> getAllAttributeKeys()

matchingList

public List<RosterEntry> matchingList(String roadName,
                                      String roadNumber,
                                      String dccAddress,
                                      String mfg,
                                      String decoderMfgID,
                                      String decoderVersionID,
                                      String id)

Get a List of RosterEntry objects in Roster matching some information. The list may have null contents if there are no matches.

checkEntry

public boolean checkEntry(int i,
                          String roadName,
                          String roadNumber,
                          String dccAddress,
                          String mfg,
                          String decoderModel,
                          String decoderFamily,
                          String id)

Check if an entry is consistent with specific properties.

A null String entry always matches. Strings are used for convenience in GUI building.

makeValidFilename

public static String makeValidFilename(String entry)

Name a valid roster entry filename from an entry name.

• Replaces all problematic characters with "_".
• Append .xml suffix

Does not check for duplicates.

Parameters:

entry - the getId() entry name from the RosterEntry

Throws:

IllegalArgumentException - if called with null or empty entry name

Since:

2.1.5

See Also:

RosterEntry.ensureFilenameExists()

dispose

public void dispose()

writeRosterFile

public static void writeRosterFile()

Store the roster in the default place, including making a backup if needed.

Uses writeFile(String), a protected method that can write to a specific location.

reloadRosterFile

public void reloadRosterFile()

Update the in-memory Roster to be consistent with the current roster file. This removes any existing roster entries!

defaultRosterFilename

public static String defaultRosterFilename()

Return the filename String for the default roster file, including location. This is here to allow easy override in tests.

setFileLocation

public static void setFileLocation(String f)

Set the default location for the Roster file, and all individual locomotive files.

Parameters:

f - Absolute pathname to use. A null or "" argument flags a return to the original default in prefsdir.

getFileLocation

public static String getFileLocation()

Absolute path to roster file location.

Default is in the prefsDir, but can be set to anything.

See Also:

XmlFile.prefsDir()

setRosterFileName

public static void setRosterFileName(String name)

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener l)

firePropertyChange

protected void firePropertyChange(String p,
                                  Object old,
                                  Object n)

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener l)

entryIdChanged

public void entryIdChanged(RosterEntry r)

Notify that the ID of an entry has changed. This doesn't actually change the Roster per se, but triggers recreation.

setRosterGroup

public void setRosterGroup(String group)

getRosterGroup

public static String getRosterGroup()

getRosterGroupName

public static String getRosterGroupName()

getRosterGroupWP

public static String getRosterGroupWP()

rosterGroupEntryChanged

public void rosterGroupEntryChanged()

This is here so that when a roster entry is added to a group via the table entry, a propertyChangeEvent is fired off. Not Ideal but it works.

getRosterGroupPrefix

public String getRosterGroupPrefix()

addRosterGroupList

public void addRosterGroupList(String str)

delRosterGroupList

public void delRosterGroupList(String str)

getRosterGroupList

public void getRosterGroupList(int i)

rosterGroupBox

public JComboBox rosterGroupBox()

updateGroupBox

public void updateGroupBox(JComboBox box)