Package jmri.configurexml

Provides an XML-based mechanism for storing and restoring configurations.

See:
Description

Interface Summary

XmlAdapter

Interface assumed during configuration operations.

Class Summary

AbstractLightManagerConfigXML	Provides the abstract base and store functionality for configuring LightManagers, working with AbstractLightManagers.
AbstractMemoryManagerConfigXML	Provides the abstract base and store functionality for configuring MemoryManagers, working with AbstractMemoryManagers.
AbstractNamedBeanManagerConfigXML	Provides services for configuring NamedBean manager storage.
AbstractReporterManagerConfigXML	Provides the abstract base and store functionality for configuring ReporterManagers, working with AbstractReporterManagers.
AbstractSensorManagerConfigXML	Provides the abstract base and store functionality for configuring SensorManagers, working with AbstractSensorManagers.
AbstractSignalHeadManagerXml	Provides the abstract base and store functionality for configuring SignalHeadManagers, working with AbstractSignalHeadManagers.
AbstractTurnoutManagerConfigXML	Provides the abstract base and store functionality for configuring TurnoutManagers, working with AbstractTurnoutManagers.
BlockManagerXml	Persistency implementation for BlockManager persistance.
ConfigXmlManager	Provides the mechanisms for storing an entire layout configuration to XML.
DccLocoAddressXml	Handle XML configuration for DccLocoAddress objects.
DccSignalHeadXml	Handle XML configuration for LsDecSignalHead objects.
DefaultConditionalManagerXml	Provides the functionality for configuring ConditionalManagers
DefaultLogixManagerXml	Provides the functionality for configuring LogixManagers
DefaultMemoryManagerXml	Persistency implementation for the default MemoryManager persistance.
DefaultRouteManagerXml	Provides the functionality for configuring RouteManagers
DoubleTurnoutSignalHeadXml	Handle XML configuration for DoubleTurnoutSignalHead objects.
GuiLafConfigPaneXml	Handle XML persistance of SwingGuiLaf default values.
LoadStoreBaseAction	Base implementation for the load and store actions.
LoadXmlConfigAction	Load configuration information from an XML file.
LoadXmlUserAction	Load configuration information from an XML file.
LocoAddressXml	Handle XML configuration for LocoAddress objects.
LsDecSignalHeadXml	Handle XML configuration for LsDecSignalHead objects.
SaveMenu	Create a "Save" menu item containing actions for storing various data (subsets).
StoreXmlAllAction	Store the entire JMRI status in an XML file.
StoreXmlConfigAction	Store the JMRI configuration information as XML.
StoreXmlUserAction	Store the JMRI user-level information as XML.
TripleTurnoutSignalHeadXml	Handle XML configuration for TripleTurnoutSignalHead objects.
TurnoutOperationManagerXml
VirtualSignalHeadXml	Handle XML configuration for VirtualSignalHead objects.

Package jmri.configurexml Description

Provides an XML-based mechanism for storing and restoring configurations.

This is intended to satisfy a number of requirements:

• No XML-specific code in the objects being loaded/stored.
• Separation at the package level between load/store code and the configured objects
• Customizable storage of complex objects
• Control over the order in which complex objects are recreated during load.

To do this:

1. The application registers relevant objects with the ConfigXmlManager class. These objects are usually the higher-level managers; since code has to be written for the actual class of these objects, you should design to have a minimal number of them. For example, a LayoutManager object of the specific LocoNetLayoutManager class might be registered.
2. The ConfigXmlManager checks that an adapter class for that object exists. The adapter class for an object of package and class "p.c" is located at runtime by searching for a class called "p.configurexml.cXml", and must implement jmri.configurexml.Adapter.
3. When a store operation is required, the ConfigXmlManager object iterates over the set of registered objects. For each, it creates an adapter object and requests a store operation, which returns a JDOM Element which is added to the output XML.
4. When a load operation is required, the input XML file is iterated through. For each top-level Element, an adapter object of the described type is created and passed the Element. Note that the adapter should register the objects it creates!

We choose to put the adapters in a separate package to encourage the reduction of coupling, and make it clear that they are separate (you can get a source tree without them from CVS easily, for example). But this means that package-level member variables are not automatically visible. For one class, you can get around this by subclassing. We'll have to see whether this is a real problem or not.

On read, the right class has to be found to handle any given top-level XML element. We do this in an ugly fashion by putting the class name in the "class" attribute. This prevents the XML output from being portable from program to program, an unfortunate loss, but for the time being it seems a reasonable compromise.

The various types do still have element names (e.g. "turnouts") so that we can have a rational DTD.

The order of loading is the order in the XML file, as written. The write order is the registration order. This constrains how certain registrations at startup are done. In particular, the layout tree has a problem: It seems it should be instantiated before the turnout managers, etc, so that it can listen as their contents are added. But if it's created first, it has no turnout manager instance to connect to yet. The solution to this seems to be support for an "InstanceListener" in the InstanceManager so that objects can learn about the creation of new basic instances.

There are four levels of information, used to ensure that prerequisites are present during a load:

• Pref
• Config
• Tool
• User

DTD management

DTDs for these files are found in the xml/DTD directory.

A rudimentary version control system is provided by DTD naming, i.e.

• layout-config.dtd - the original, not to be changed any more.
• layout-config-2-1-5.dtd - manually created when the first XML content change was made after the release of JMRI 2.1.4, this accumulates changes until 2.1.5 is released.

The first time a change is made to XML persistance after a release, the following steps are needed:

• Copy the existing DTD to one with the next version name (e.g. after 2.1.7 is released, copy layout-config-2-1-7.dtd to layout-config-2-1-8.dtd) and commit to CVS.
• Update the comment on the previous file.
• Update the references in the ConfigXmlManager code.

Related Documentation

For overviews, tutorials, examples, guides, and tool documentation, please see:

• JMRI XML persistance page
• JMRI project technical info
• JMRI project overview page