jmri.configurexml
Class ConfigXmlManager

java.lang.Object
  jmri.jmrit.XmlFile
      jmri.configurexml.ConfigXmlManager

All Implemented Interfaces:

ConfigureManager

public class ConfigXmlManager
extends XmlFile
implements ConfigureManager

Provides the mechanisms for storing an entire layout configuration to XML. "Layout" refers to the hardware: Specific communcation systems, etc.

Author:

Bob Jacobsen Copyright (c) 2002, 2008

See Also:

Package summary for details of the overall structure

Field Summary

static String

schemaVersion Define the current DTD version string for the layout-config DTD.

Fields inherited from class jmri.jmrit.XmlFile

dtdLocation, xsltLocation

Constructor Summary

ConfigXmlManager()

Method Summary

static String	adapterName(Object o) Find the name of the adapter class for an object.
protected void	addConfigStore(Element root)
protected void	addPrefsStore(Element root)
protected void	addToolsStore(Element root)
protected void	addUserPrefsStore(Element root)
protected void	addUserStore(Element root)
static void	creationErrorEncountered(XmlAdapter adapter, String operation, Level level, String description, String systemName, String userName, Throwable exception) Invoke common handling of errors that happen during the "load" process.
void	deregister(Object o)
static Element	elementFromObject(Object o)
protected void	finalStore(Element root, File file)
File	find(String f) Find a file by looking in xml/layout/ in the preferences directory, if that exists in xml/layout/ in the application directory, if that exists in xml/ in the preferences directory, if that exists in xml/ in the application directory, if that exists at top level in the application directory
Object	findInstance(Class<?> c, int index) Find the ith instance of an object of particular class that's been registered for storage.
ArrayList<Object>	getInstanceList(Class<?> c) Returns a list of instances stored for a given class.
protected void	includeHistory(Element root)
protected Element	initStore()
boolean	load(File fi) Load a file.
boolean	load(File fi, boolean registerDeferred) Load a file.
boolean	loadDeferred(File fi) Create the objects defined in a particular configuration file that have been deferred until after basic GUI construction completed
boolean	makeBackup(File file) Make a backup file.
void	registerConfig(Object o)
void	registerConfig(Object o, int x)
void	registerPref(Object o)
void	registerTool(Object o)
void	registerUser(Object o) Register an object whose state is to be tracked.
void	registerUserPrefs(Object o)
void	removePrefItems() Remove the registered preference items.
static void	setErrorHandler(ErrorHandler handler)
void	setPrefsLocation(File prefsFile) Set location for preferences file.
void	storeAll(File file) Writes config, tools and user to a file.
void	storeConfig(File file) Writes prefs to a file.
void	storePrefs() Writes prefs to a predefined File location.
void	storePrefs(File file) Stores just preferences information.
void	storeUser(File file) Writes user and config info to a file.
void	storeUserPrefs(File file) Stores just user preferences information.

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

schemaVersion

public static final String schemaVersion

Define the current DTD version string for the layout-config DTD. See the DTD versioning discussion

See Also:

Constant Field Values

Constructor Detail

ConfigXmlManager

public ConfigXmlManager()

Method Detail

registerConfig

public void registerConfig(Object o)

Specified by:

registerConfig in interface ConfigureManager

registerPref

public void registerPref(Object o)

Specified by:

registerPref in interface ConfigureManager

removePrefItems

public void removePrefItems()

Remove the registered preference items. This is used e.g. when a GUI wants to replace the preferences with new values.

Specified by:

removePrefItems in interface ConfigureManager

findInstance

public Object findInstance(Class<?> c,
                           int index)

Description copied from interface: ConfigureManager

Find the ith instance of an object of particular class that's been registered for storage.

Note that the index of an object can change when other objects are stored or removed. The index is for indexing over the objects stored at a moment, not for use as an identification number.

There may be synchronization issues associated with this, although they are expected to be rare in practice.

Specified by:

findInstance in interface ConfigureManager

Parameters:

c - Class of the desired objects

index - a 1-based index of the object to return

Returns:

an object of class c or null

getInstanceList

public ArrayList<Object> getInstanceList(Class<?> c)

Description copied from interface: ConfigureManager

Returns a list of instances stored for a given class.

Specified by:

getInstanceList in interface ConfigureManager

Parameters:

c - Class of the desired objects

Returns:

an ArrayList of objects of class c or null

registerConfig

public void registerConfig(Object o,
                           int x)

Specified by:

registerConfig in interface ConfigureManager

registerTool

public void registerTool(Object o)

Specified by:

registerTool in interface ConfigureManager

registerUser

public void registerUser(Object o)

Register an object whose state is to be tracked. It is not an error if the original object was already registered.

Specified by:

registerUser in interface ConfigureManager

Parameters:

o - The object, which must have an associated adapter class.

registerUserPrefs

public void registerUserPrefs(Object o)

Specified by:

registerUserPrefs in interface ConfigureManager

deregister

public void deregister(Object o)

Specified by:

deregister in interface ConfigureManager

adapterName

public static String adapterName(Object o)

Find the name of the adapter class for an object.

Parameters:

o - object of a configurable type

Returns:

class name of adapter

initStore

protected Element initStore()

addPrefsStore

protected void addPrefsStore(Element root)

addConfigStore

protected void addConfigStore(Element root)

addToolsStore

protected void addToolsStore(Element root)

addUserStore

protected void addUserStore(Element root)

addUserPrefsStore

protected void addUserPrefsStore(Element root)

includeHistory

protected void includeHistory(Element root)

finalStore

protected void finalStore(Element root,
                          File file)

storeAll

public void storeAll(File file)

Writes config, tools and user to a file.

Specified by:

storeAll in interface ConfigureManager

Parameters:

file -

storePrefs

public void storePrefs()

Writes prefs to a predefined File location.

Specified by:

storePrefs in interface ConfigureManager

storePrefs

public void storePrefs(File file)

Description copied from interface: ConfigureManager

Stores just preferences information.

Specified by:

storePrefs in interface ConfigureManager

storeUserPrefs

public void storeUserPrefs(File file)

Description copied from interface: ConfigureManager

Stores just user preferences information.

Specified by:

storeUserPrefs in interface ConfigureManager

setPrefsLocation

public void setPrefsLocation(File prefsFile)

Set location for preferences file.

File need not exist, but location must be writable when storePrefs() called.

storeConfig

public void storeConfig(File file)

Writes prefs to a file.

Specified by:

storeConfig in interface ConfigureManager

Parameters:

file -

storeUser

public void storeUser(File file)

Writes user and config info to a file.

Config is included here because it doesnt hurt to read it again, and the user data (typically a panel) requires it to be present first.

Specified by:

storeUser in interface ConfigureManager

Parameters:

file -

makeBackup

public boolean makeBackup(File file)

Description copied from interface: ConfigureManager

Make a backup file.

Specified by:

makeBackup in interface ConfigureManager

Parameters:

file - to be backed up

Returns:

true if successful

elementFromObject

public static Element elementFromObject(Object o)

load

public boolean load(File fi)
             throws JmriConfigureXmlException

Load a file.

Handles problems locally to the extent that it can, by routing them to the creationErrorEncountered method.

Specified by:

load in interface ConfigureManager

Parameters:

fi - Input file

Returns:

true if no problems during the load

Throws:

JmriConfigureXmlException

load

public boolean load(File fi,
                    boolean registerDeferred)
             throws JmriConfigureXmlException

Load a file.

Handles problems locally to the extent that it can, by routing them to the creationErrorEncountered method.

Specified by:

load in interface ConfigureManager

Parameters:

fi - file to load

registerDeferred - true to register objects to defer

Returns:

true if no problems during the load

Throws:

JmriConfigureXmlException

Since:

2.11.2

See Also:

XmlAdapter.loadDeferred()

loadDeferred

public boolean loadDeferred(File fi)

Description copied from interface: ConfigureManager

Create the objects defined in a particular configuration file that have been deferred until after basic GUI construction completed

Specified by:

loadDeferred in interface ConfigureManager

Parameters:

fi - Input file

Returns:

true if succeeded

See Also:

XmlAdapter.loadDeferred()

find

public File find(String f)

Find a file by looking

• in xml/layout/ in the preferences directory, if that exists
• in xml/layout/ in the application directory, if that exists
• in xml/ in the preferences directory, if that exists
• in xml/ in the application directory, if that exists
• at top level in the application directory

Specified by:

find in interface ConfigureManager

Parameters:

f - Local filename, perhaps without path information

Returns:

Corresponding File object

creationErrorEncountered

public static void creationErrorEncountered(XmlAdapter adapter,
                                            String operation,
                                            Level level,
                                            String description,
                                            String systemName,
                                            String userName,
                                            Throwable exception)

Invoke common handling of errors that happen during the "load" process.

Generally, this is invoked by XmlAdapter implementations of their creationErrorEncountered() method (note different arguemments, though). The standard implemenation of that is in AbstractXmlAdapter.

Exceptions passed into this are absorbed.

Parameters:

adapter - Object that encountered the error (for reporting), may be null

operation - description of the operation being attempted, may be null

description - description of error encountered

systemName - System name of bean being handled, may be null

userName - used name of the bean being handled, may be null

exception - Any exception being handled in the processing, may be null

setErrorHandler

public static void setErrorHandler(ErrorHandler handler)