Development Tools

• Code/Help Repository:
  • Getting the code
  • Developing with Git
  • Merging a PR
  • Git FAQs
  • Intro to GitHub Desktop
• Building Tools:
  • Ant
  • NetBeans
  • Eclipse
  • IntelliJ IDEA

Code Structure

• Introduction
• Names and Naming
• Application Structure
• Code Structure Patterns
• Swing Structure
• External Connection Structure
• Application Preferences
• Profile Files
• Threading
• Use of XML
  • XML Schema
  • XSLT Formatting
• Web Site
• Javadocs
  • Name Index
  • Packages
  • Classes

Techniques and Standards

• Recommended Practices
• Continuous Integration
• Internationalization
• Logging & Error Handling
• Unit testing with JUnit
• Documentation using Javadoc and UML
• Run the SpotBugs static analysis tool
• Providing help using JavaHelp
• Portable Filename Method
• XML Persistance

Help and Web Site

• Providing Help using JmriHelp
• The JMRI Web Site
• Updating JMRI Web and Help
• Creating Help for New Hardware
• Program Documentation Using Javadoc

How To

• Extend JMRI
• Add a New System
• Add a New Type

Functional Info

• Turnout Feedback
• Network Connections
• How the startup scripts work

Background Info

• Technology Roadmap
• Survey of JVM Capabilities
• Usage Poll, Spring 2007

Donate to JMRI.org

JMRI: Profile Directory Tutorial

This page is a tutorial on how JMRI stores and accesses preference and profile information.

Locations and contents

Settings Location (portable name = "settings:")

This is the only fixed location and is determined by the underlying operating system type and your logged-in-username. It's a known place the JMRI program can always look and find essential settings files that tell it where everything else is located.

The following files/folders are always located here:

nodeIdentity.xml

This file contains a unique nodeIdentity string that is generated the first time JMRI uses this Settings Location, doesn't change and serves to distinguish between other possible Settings Locations (such as under another username, on a different operating system partition or another computer).

profiles.xml

This file lists the name of every Profile Folder known to this instance of JMRI and its location. It also has a list of all paths you wish to search for profiles and which path is the default for newly-created profiles. "settings:" is always searched but it doesn't have to be the default.

preferences

This directory contains preferences that are retained on the computer for use in all JMRI application profiles. If it is not present, no preferences that apply to all profiles have been written.

log

This folder contains the "session.log" and "messages.log" files, plus several previous versions of these files.

DecoderProConfig3.properties

PanelProConfig2.properties

SoundProConfig2.properties

LccProConfig.properties

These files are created the first time each of the apps are run and simply contain three pieces of information:

• The name of the Profile Folder last used by this app.
• Whether you want the app to autostart with the last-used Profile Folder
• How long to display the Profile Selector box if you choose not to autostart.

Other files/folders:

The following may be present, but do not have to be:

• Various Profile Folders you have created. From V4.13.4 on, newly-created Profile Folders will have a ".jmri" extension.
• Your User Files - panels etc.
• Your "roster" folder and its (recreatable) roster.xml file.

Profile Location (portable name = "profile:")

This folder is the one chosen by the Profile Selector mechanism for the current JMRI session.

The "profile" folder at the profile: location contains the "profile.xml" and "profile.properties" files and one or more node specific folders that start with "jmri-".

The node specific folders contain local versions of "profile.xml", "profile.properties" and "user-interface.xml". The "user-interface.xml" file contains information on window size and positions, column widths, etc.

Other files/folders:

• Other specific preference folders (throttle, etc.)

The following may be present, but do not have to be:

• Your User Files - panels etc.
• Your "roster" folder and its (recreatable) roster.xml file.

User Files Location (portable name = "preference:")

This location contains:

• Your User Files - panels etc.

The following may be present, but does not have to be:

• Your "roster" folder and its (recreatable) roster.xml file.

You are free to change the User Files Location as you like (Preferences->File Locations).

Roster Location

This location contains:

• A "roster.xml" file, which is a (recreatable) index of the XML files in the "roster" folder. You should create/recreate "roster.xml" (Actions->Recreate Roster Index) if it is missing or you are experiencing roster problems.
• Your "roster" folder. This contains:
  • An XML file for each loco entry in your roster, with stored CV values, etc.
  • ".bak" files, which are backup versions of entries in your roster.
  • A "consist" folder, which stores information on consists you have created using the Consist tools in JMRI.
  • Copies of media files you have added to roster entries, throttles etc.
    (Older JMRI versions stored roster images in a "resources" folder in the User Files Location. If you have been using JMRI for a long time, you may have roster images in both locations.)

By default the Roster Location is the same as (and follows) the User Files location unless you explicitly set a different location.

You are free to change the Roster Location as you like (Preferences->Roster->Roster->Location Set/Reset). The Reset button causes the Roster Location to again follow the User Files location.

Scripts Location (portable name = "scripts:")

This location defaults to the "jython" sample scripts folder located within your JMRI Program Location. You should never store user-created files anywhere within your Program Location, they are likely to be lost in a JMRI upgrade.

If you are creating your own scripts you may wish to change the Scripts Location (Preferences->File Locations).

Program Location (portable name = "program:")

This location is set when JMRI is installed and can only be changed when installing the software. You should never store user-created files anywhere within your Program Location, they are likely to be lost in a JMRI upgrade.

User Files Location defaults and implications

Depending when you first installed JMRI on your computer, the default User Files Location will differ:

• Before the advent of Profiles (JMRI V3.8),the default User Files Location was the same as the Settings. This arrangement stayed in place with the upgrade.
• After the implementation of Profiles (JMRI V3.8),the default User Files Location for new installations is the same as the Profile Location.

Implications of User Files Location with Profiles

• If you create a new profile, User Files Location = Profile Location. This means the profile will have an initially-empty set of User Files.
• If you create a copy of a profile that has User Files Location within the Profile Location, the new profile will have a new private copy of User Files from the source profile. The two sets will be unconnected and changes to one will not affect the other.
• If you create a copy of a profile that has User Files Location anywhere on the computer outside the Profile Location, the new profile will share User Files with the source profile. So changes will be seen by both profiles.

Implications of Separating User Files Location and Roster Location

If you separate User Files Location from Roster Location (as documented above), you can implement differing sharing/separation of the two, e.g a single roster shared between two different layouts (each with its own profile).

Sharing User Files between Computers

Since User Files can be relocated completely outside of the user's JMRI file system, sharing of User Files between computers is easy:

Use of simple file sharing or using a local NAS or other file server

This approach seems appealing at first sight. However there are considerable disadvantages and risks.

• The host computer or server must always be on line when using JMRI on any computer.
• Use of JMRI on a laptop away from home or Internet access will not be possible.
• JMRI is not designed for simultaneous file access. The risk of file corruption is very high.
• Recovery from a file corruption may be difficult or impossible unless a very comprehensive incremental backup strategy is in use and even the there is likely to be some data loss.

See the link below for further information on issues with simple file sharing:

Use of a cloud-synced sharing solution

Note that in this context we are not talking about a Cloud Server approach where your files only exist on a remote server. We are talking about a service such as Dropbox, Google Drive, OneDrive where full local copies exist on each computer and each copy is kept in sync with the central Cloud copy.

There are considerable advantages with this approach.

• Only one computer needs to be switched on at a time.
• Use of JMRI on a laptop away from home or Internet access is fine. The file changes will be synced next time you are connected.
• These services generally do not usually use simultaneous file access. The risk of file corruption is much lower.
• Recovery from unintended file changes is much easier. For example Dropbox keeps every saved change you have made in the past 30 days (even if you only have one computer) and allows easy reversion.

We tend to talk about Dropbox because that is the one that seems to be most used by JMRI developers and users, some of whom have been doing so for many years. For more information and setup instructions (also applicable to competing services) see the JMRI page on Dropbox use.

Sharing Profiles between Computers

In the same way that User Files can be relocated completely outside of the user's JMRI file system and shared between computers, so can entire Profiles. In Preferences->Config Profiles->Search Paths you can add a search path in a synced/shared location and set that to be the default for newly-created profiles. It's then simply a matter of manually moving each Profile Folder from the Settings Location to your new shared folder. When you first use a shared profile on a different computer JMRI creates a node-specific folder for storing overrides of settings (see above) that are machine-specific (e.g. COM port names).

I have been using both of shared User Files (a "JMRI" folder in my Dropbox folder) for many years and a shared Profiles (a "JMRI Config Profiles" folder in my Dropbox folder) for more than a year now (and tweaked some JMRI code to improve node differentiation) across more than a dozen machines/virtual machines, running Mac, Windows and Linux.

Portable File Access in JMRI

The success of file and profile sharing in JMRI is very dependent on the use of our Portable File Access specification in XML files.

Briefly, this consists of pseudo-URL prefixes (portable names mentioned above) that replace machine-specific directory paths in file specifications with a set of prefixes relative to known JMRI and machine locations. These are expanded by the local JMRI instance to create a machine-specific file specification. The component separators are standardised as "/" and converted locally.

For more information see the FileNames page. For a full list of prefixes, see the JavaDocs for the FileUtil class.

---