Code documentation
Development Tools
Code Structure
Techniques and Standards
Help and Web Site
How To
Functional Info
Background Info

JMRI Help:

Contents Index
Glossary FAQ

Donate to JMRI.org

JMRI Code: Introduction to JMRI Library Structure

This page is the top-level introduction to how the JMRI software is organized.

Static Structure

At the highest level, we separate test source code from distributed source code by putting both in separate directories within the development directory: "java/test" and "java/src". This makes it easy to compile a version without test code, to apply different tools to the two types of code, etc.

In addition to the source code, JMRI expects to find directories within the current directory:

help/
The in-program help files
jython/
Various sample and test scripts.
lib/
Jar files and linkable libraries that JMRI relies on.
resources/
Image and sound resources used by the library, and available for user selection. These can be directly browsed.
web/
Files for JMRI's built-in web servers
xml/
XML files for decoder and programmer definitions, signal system definitions, Schema and DTDs used to validate JMRI's XML persistance, and others.

plus specific files used by the build process, to control logging, and containing the JMRI license.

Static Package and Class Structure

For interfaces in the jmri package, which might be implemented by lots of different layout hardware types, jmri.InstanceManager satisfies requests for implemented objects by providing access to a hardware-specific Manager, from which you can get the hardware-specific items that represent what you want to access on the layout.

package structure

Because we have different hardware implementations in subpackages of the jmrix package, those are also accessed via the SystemConnectionMemo classes, which provide access to generally-defined objects.

Other code should, in general, not reference those specific implementations directly.

(The help/en/package section of the in-program help files are also organized this way)

implementation structure

More specifically:

jmri
Contains interfaces and base class implementations for the common JMRI objects. This is the basic interface to the overall JMRI library and its capabilities.
Code in the jmri package should depend on no other JMRI code, though it may depend on externals (log4j, etc.) There should be no AWT or Swing code here.
jmrit
Contains commonly useful tools and extensions.
It can depend on jmri.* and externals. It must not depend on jmrix.*
jmrix
Contains code that is specific to a particular external system. This includes implementations of jmri interfaces that are specific to a system, plus system-specific tools (in the long run, those could certainly be separated).
jmrix can depend on jmri and externals, but not jmrit.
Only system-specific code should access within the jmrix subpackages.
jmris
contains all the code for the server implementation for the JMRI interfaces.
managers
Abstract and default implementations of the various JMRI type managers, e.g. the concrete classes from the InstanceManager. It's a historical accident that these have a package of their own, rather than being rolled into jmri.implementations.
implementations
Abstract and default implementations of the jmri objects; no system specific or Swing code allowed here. These are in a separate package, rather than in jmri itself, to make the jmri package simpler to understand for people who just want to use the library.
util
General service classes that are not user level tools. Should not depend on jmri.jmrit or jmri.jmrix packages. The jmri.util.swing subpackage provides Swing utilities.

This is an exception to the idea that packages should not directly reference classes across the tree: these utility classes are generally available for use.

apps
Separate from the jmri package tree, this contains application classes and base classes that can use jmri, jmrit, and jmrix classes, along with anything else. By having this here, we break the dependency between jmrix and jmrit classes (somebody has to create the general and system-specific tool objects for an application; that dependency is from the apps package)
dependencies

Although it's not always honored, the tree structure here is important: Packages should not reference across the tree. Code in jmri.jmrit is welcome to reference classes in the jmri package, but should not reference directly to classes in jmri.jmrix. Classes should reference the interfaces in jmri, not the specific details of classes in jmri.managers and jmri.implementations. It can be tempting to violate this rule in the interest of expediency, but in the long run it makes it much harder for JMRI to be maintained and improved by a large group of people. We just can't allow lots of tiny little special cases to make the code impossible to understand. We're developing ArchUnit tests for this which can be run via ./runtest.csh jmri.ArchitectureCheck as part of developer unit testing (there is also a PowerShell script available, see the developer unit testing page for more information). This will highlight many existing structure violations in addition to new ones because we haven't yet cleaned up some historical issues. There's also jmri.ArchitectureTest which is run as part of our CI tests, and catches new violations of a subset of the constraints.

Similarly, we have conventions for where to locate Swing GUI code and persistance (store/load) code that limits how embedded in them main code they become.

Example: Implementing a Turnout

Turnouts involve multiple classes:

Dynamic (Object) Structure

For many JMRI objects, once they have been created they can be accessed either by type, i.e. "The default configuration manager" via the InstanceManager, or by name, i.e. "The East Yard Entrance turnout" via a type-specific Manager. More information on how things (e.g. objects representing items on the layout) are named is available on a separate page.

The "InstanceManager" is a key central point for this navigation.

JMRI makes extensive use of the Factory pattern via objects we call "Manager" objects.

Example: Accessing a Turnout

To get a specific Turnout instance that represents something on the layout, you make a request of a TurnoutManager. This is also an interface, with a similar implementation pattern. In turn, you got that TurnoutManager from the InstanceManager.

 TurnoutManager manager = InstanceManager.getDefault(TurnoutManager.class);
 Turnout turnout = manager.getTurnout("IT12");

The generic Manager<T> class provides the basic interface. which is then extended for specifics i.e. TurnoutManager. That then has specific implementations.

In many cases, there's one underlying implementation for a manager. For example, there's one LogixManager, one MemoryManager, etc.

In other cases, you might have multiple system-specific managers: LnTurnoutManager for a LocoNet connection, NceTurnoutManager for an NCE connection, and an InternalTurnoutManager for the internal turnouts. These are handled by making them clients to a single ProxyManager, subclass i.e. ProxyTurnoutManager which uses name lookup to work with the individual managers.

Object Referencing

Code can hold a direct java reference to a specific object. In some cases, typically GUIs or persistance, you'll want to refer to an object by its name. JMRI NamedBean objects have both system names that can't change and user names that can. For example, the user name "East Yard" for a turnout might refer to "LI1" at some point and later refer to "NT12". The NamedBeanHandle class takes care of this by remembering which name is being used for an object, and keeping track of how that name might be moved from one object to another. For more information, see the description on the Patterns page.